Document progress queue

Preview

Install

First time? Get started sets up the registry and theme. Or with shadcn directly: npx shadcn@latest add @candor/document-progress-queue

Brings in: bidi, button, format-elapsed, heading-level, heading-scope, locale, locked, progress, status, status-dot, tokens, utils · npm: lucide-react@^1.67.0

Usage

"use client"

import * as React from "react"
import { DocumentProgressQueue, type DocumentProgress } from "@/components/candor/document-progress-queue"

const at = (s: number) => new Date(Date.UTC(2026, 10, 10, 9, 0, s)).toISOString()

/* What the app's pipeline reports for each document. A stage's bar appears only where the pipeline counted pages. */
const batch: DocumentProgress[] = [
  { id: "d-1", name: "March statement.pdf", state: "done", result: "18 fields extracted", startedAt: at(0), finishedAt: at(42) },
  { id: "d-2", name: "Invoice INV-2207.pdf", state: "done", result: "11 fields extracted, 2 to check", startedAt: at(3), finishedAt: at(31) },
  { id: "d-3", name: "Invoice INV-2211.pdf", state: "working", stage: "Reading pages", progress: { done: 3, total: 12 } },
  { id: "d-4", name: "Supplier contract.pdf", state: "working", stage: "Extracting fields" },
  { id: "d-5", name: "Receipt 88.png", state: "failed", error: "The scan is too blurry to read." },
  { id: "d-6", name: "Invoice INV-2190.pdf", state: "failed", error: "The file is password-protected." },
  { id: "d-7", name: "Invoice INV-2215.pdf", state: "queued" },
  { id: "d-8", name: "Invoice INV-2219.pdf", state: "queued" },
]

export default function Example() {
  const [documents, setDocuments] = React.useState(batch)
  const [retrying, setRetrying] = React.useState<string[]>([])
  return (
    <DocumentProgressQueue
      title="Invoices from the March upload"
      className="max-w-2xl"
      documents={documents}
      retrying={retrying}
      onRetry={(ids) => {
        setRetrying((r) => [...r, ...ids])
        // Your app asks its pipeline to run them again; they come back queued.
        window.setTimeout(() => {
          setDocuments((ds) => ds.map((d) => (ids.includes(d.id) ? { id: d.id, name: d.name, state: "queued" } : d)))
          setRetrying((r) => r.filter((id) => !ids.includes(id)))
        }, 800)
      }}
      onOpen={() => {}}
    />
  )
}

<DocumentProgressQueue>

Strings

Types

DocumentProgressState

Where one document is: waiting its turn, being worked on, finished, or stopped by a failure.

"queued" | "working" | "done" | "failed"

DocumentProgress

One document in the batch, as the app's pipeline reports it.

{ /** Stable for this document in the batch. */ id: string; /** The document's name, as the app shows it ("March statement.pdf"). */ name: string; state: DocumentProgressState; /** What is happening to it now, in the app's words ("Reading pages", "Extracting fields"). Shown while working. */ stage?: string | undefined; /** * How far the current stage is, as the pipeline measured it: 3 of 12 pages. Shown as a bar while working. Left out, * there is no bar and no percentage: nothing is estimated. */ progress?: { done: number; total: number; } | undefined; /** Why it failed, in the app's words. Shown on a failed document; without it, it says no reason was given. */ error?: string | undefined; /** What it came to, in the app's words ("18 fields extracted"). Shown on a done document. */ result?: string | undefined; /** When work on it started (ISO). With `finishedAt`, a finished document says how long it took. */ startedAt?: string | undefined; /** When it finished, done or failed (ISO). */ finishedAt?: string | undefined; /** Why it can't be retried, when it can't (a file that can't be read again). Locks its Retry with the reason. */ cannotRetry?: string | undefined; }

Types from other items

The props above take these. Each is defined by another item; import it from the path shown.

HeadingLevel from @/lib/candor/heading-level

A heading's level in the page's outline: `1` is `<h1>`, `6` is `<h6>`. Every Candor item that draws a heading takes its `headingLevel` as this type; the level is where the heading sits in the outline, never how large it looks.

1 | 2 | 3 | 4 | 5 | 6