JobStatus

Usage

<JobStatus
  jobId="inspection-job-1"
  label="Flag equipment for inspection"
  state="running"
  progress={{ completed: 2, total: 5 }}
  requestPending={cancelPending ? "cancel" : null}
  onCancelRequest={requestCancellation}
/>

Supplied outcomes and requests

state is one of queued, running, cancel-requested, canceled, complete, partial, or failed. The application owns these states. Calling either request callback leaves the supplied outcome unchanged. The callback receives the exact jobId.

Cancellation is offered only for queued/running jobs with onCancelRequest. Retry is offered only for failed/partial/canceled jobs with onRetryRequest. Supply requestPending while delivering a request to disable duplicate actions; clear it only when the application has reconciled that request. Use requestError for delivery feedback without replacing the job outcome. A failed request delivery may leave the remote outcome unknown.

cancel-requested does not establish cancellation. Work may finish first, so a later supplied complete state remains valid. Retrying requires application support and a new request identity; the application must choose eligible failed work and avoid resending successful items. disabled blocks actions while retaining job details.

Progress

Counts are nonnegative safe integers. For a known total, completed must not exceed total. Invalid counts produce a readable error without a progress bar. A null total produces indeterminate progress. A zero total displays zero items without a percentage. Counts describe processed items, which may include failed or skipped work; they never establish success or force a lifecycle transition.

Progress ticks stay outside the polite lifecycle announcement. The forwarded HTMLDivElement ref identifies the named, focusable job region. When a focused action disappears or becomes disabled, focus returns to that region if it would otherwise be lost.

Props

Accessibility

• Job state and request feedback remain readable without color.
• Progress has an accessible name and a determinate value only when supported by valid counts.
• Buttons support keyboard activation, disabled semantics, visible focus, and narrow wrapping.
• A pending request is announced once, through a live region that is on the page before the request is made. The sentence is written just after focus has moved to the job region, so announcing that move does not cut it off. The explanation under cancel-requested is announced together with the state.
• The job ID, counts, messages and errors wrap, and a long identifier breaks instead of running out of the job.
• Native attributes such as id, data-* and aria-describedby reach the job region. Its role and name come from label.
• Progress uses the existing reduced-motion policy.

Manifest entry

<JobStatus jobId="import-1" label="Import equipment" state="cancel-requested" progress={{completed:2,total:5}} />

{
  "description": "Application-supplied job state and validated item progress with explicit cancellation/retry requests. Requests never establish a job outcome. A pending request is announced through a live region that is always present; native attributes reach the job region; long text wraps.",
  "props": {
    "jobId": {
      "type": "string",
      "required": true
    },
    "label": {
      "type": "string",
      "required": true
    },
    "state": {
      "type": "enum",
      "values": [
        "queued",
        "running",
        "cancel-requested",
        "canceled",
        "complete",
        "partial",
        "failed"
      ],
      "required": true
    },
    "message": {
      "type": "string"
    },
    "progress": {
      "type": "node",
      "description": "{ completed: number; total: number | null }. Nonnegative safe integers; completed cannot exceed a known total. Null total is indeterminate; zero shows zero items without a percentage."
    },
    "requestPending": {
      "type": "enum",
      "values": [
        "cancel",
        "retry"
      ],
      "description": "Pending request kind, or null. Prevents duplicate requests without changing the supplied state."
    },
    "requestError": {
      "type": "string",
      "description": "Request-delivery feedback supplied independently of the job outcome."
    },
    "onCancelRequest": {
      "type": "function",
      "description": "(jobId) => void. Offered only while queued or running. Does not establish cancellation."
    },
    "onRetryRequest": {
      "type": "function",
      "description": "(jobId) => void. Offered only for failed, partial, or canceled jobs. The application chooses eligible work and request identity."
    },
    "disabled": {
      "type": "boolean",
      "default": false
    },
    "className": {
      "type": "string"
    }
  },
  "composable_with": [
    "ActionStatus",
    "Progress",
    "Button",
    "BulkResults"
  ],
  "never_inside": [
    "Button"
  ],
  "example": "<JobStatus jobId=\"import-1\" label=\"Import equipment\" state=\"cancel-requested\" progress={{completed:2,total:5}} />"
}