Realtime jobs

Preview Available in release assets

Show durable job state with bounded realtime updates and native cancellation.

Server contract

Use .thin-realtime-jobs on a stable identified region. Datastar 1.0.2 may request server fragments; the application owns permissions, validation, idempotency, persistence, and reconciliation.

Server-rendered content, real links, native controls, and ordinary submitted forms preserve the complete workflow without Datastar or JavaScript.

Realtime jobs primary example

<section class="thin-realtime-jobs" id="job-import-42" aria-labelledby="job-title">
  <h2 id="job-title">Catalog import</h2>
  <p role="status" aria-live="polite">Running — 42 of 100 records</p>
  <progress value="42" max="100">42%</progress>
  <form action="/api/advanced/dashboard?view=job" method="post">
    <input type="hidden" name="job" value="import-42">
    <button name="action" value="cancel">Cancel job</button>
  </form>
</section>

Show code

<section class="thin-realtime-jobs" id="job-import-42" aria-labelledby="job-title">
  <h2 id="job-title">Catalog import</h2>
  <p role="status" aria-live="polite">Running — 42 of 100 records</p>
  <progress value="42" max="100">42%</progress>
  <form action="/api/advanced/dashboard?view=job" method="post">
    <input type="hidden" name="job" value="import-42">
    <button name="action" value="cancel">Cancel job</button>
  </form>
</section>

Anatomy

Stable server-owned region
Heading and current status
Native links or form controls
Server result and error text

Variants and sizes

Finite progress
Indeterminate progress

Gallery coverage: No structured variant fixtures are published yet; the primary example above is the only verified production markup.

States and difficult content

Rendered fixtures exercise authored content and constrained layouts with the same production assets.

Idle
Pending
Empty
Partial success
Error
Forbidden
Long content
Narrow container
Reconnect

Structured state fixtures are not published for this item yet.

Interaction and keyboard behavior

SSE patches the stable job region after reconnect using server state. Cancellation is a normal form; completion, failure, and retry remain durable server states.

Accessibility

Use semantic headings, native controls, explicit labels, selected counts, text status/error messages, and predictable focus. Announce completed server changes, not every intermediate client event; preserve source and focus order across patches.

Contract

LIVE

Basis

Native forms, links, file inputs, status regions, and action buttons; async semantics must be chosen per update

Evidence

tests/unit/library/dashboard-recipes.test.ts

API

Use .thin-realtime-jobs on a stable identified region. Datastar 1.0.2 may request server fragments; the application owns permissions, validation, idempotency, persistence, and reconciliation.

Behavior tier: datastar-required

Structured host, property, and example tables are not authored for this item yet. Use the summary above and the primary example.

Fallback

Server-rendered content, real links, native controls, and ordinary submitted forms preserve the complete workflow without Datastar or JavaScript.

Assets and dependencies

/components.css

Dependencies: datastar@1.0.2

Source: packages/ui/src/items/dashboard/style.ts