{
  "schemaVersion": 1,
  "target": "react",
  "name": "queue",
  "version": "0.1.0",
  "category": "ai-elements",
  "title": "Queue",
  "description": "An agent's todo list split into collapsible To do and Done sections with counts, where items glide to their new place when their status changes.",
  "tags": [
    "ai",
    "agent",
    "todo",
    "tasks",
    "queue",
    "checklist",
    "collapsible"
  ],
  "requires": {
    "projectTypes": [
      "next",
      "vite-react"
    ],
    "styling": "tailwind-v4"
  },
  "npmDependencies": {
    "@base-ui/react": "^1.9.0"
  },
  "registryDependencies": [
    {
      "name": "agent-state",
      "version": "0.1.0"
    },
    {
      "name": "step-list",
      "version": "0.3.0"
    }
  ],
  "docsPath": "/components/queue",
  "props": [
    {
      "name": "items",
      "type": "{ id, label, status, detail?, meta?, activity? }[]",
      "description": "status is pending, active (being worked on, shown with a live mark), or done."
    },
    {
      "name": "onStatusChange",
      "type": "(id, done) => void",
      "description": "Renders a checkbox on each row so the reader can tick items off or reopen them. Without it only the agent moves items."
    },
    {
      "name": "title",
      "type": "ReactNode",
      "description": "Heading above both sections."
    },
    {
      "name": "todoLabel / doneLabel",
      "type": "ReactNode",
      "default": "\"To do\" / \"Done\"",
      "description": "Section names."
    },
    {
      "name": "defaultOpen",
      "type": "(\"todo\" | \"done\")[]",
      "default": "[\"todo\", \"done\"]",
      "description": "Sections that start open."
    },
    {
      "name": "emptyLabel",
      "type": "ReactNode",
      "default": "\"Nothing left to do\"",
      "description": "Shown in an empty To do section."
    }
  ],
  "accessibility": [
    "Each section header is a Base UI Collapsible trigger with aria-expanded, showing its name and count in text.",
    "Checkboxes are Base UI Checkbox (role=\"checkbox\", Space toggles) labeled by the row text. When a ticked row moves to the other section, keyboard focus moves with it to its checkbox.",
    "Without checkboxes, each row has a screen-reader status (to do, in progress, done); glyphs and marks are decorative.",
    "Rows move with a transform only (FLIP via the Web Animations API), measured relative to the list; with reduced motion they jump to their new place."
  ],
  "states": [
    "pending",
    "active",
    "done",
    "empty"
  ],
  "files": [
    {
      "path": "agent/queue.tsx",
      "content": "\"use client\";\n\nimport { Checkbox } from \"@base-ui/react/checkbox\";\nimport { Collapsible } from \"@base-ui/react/collapsible\";\nimport { type ComponentProps, type ReactNode, useId, useLayoutEffect, useRef } from \"react\";\nimport { type AgentActivity, AgentMark } from \"./agent-state\";\nimport { StatusGlyph } from \"./step-list\";\n\nfunction cx(...classes: Array<string | false | null | undefined>) {\n  return classes.filter(Boolean).join(\" \");\n}\n\nconst ease = \"ease-[cubic-bezier(0.23,1,0.32,1)]\";\n\nexport type QueueItemStatus = \"pending\" | \"active\" | \"done\";\n\nexport interface QueueItem {\n  id: string;\n  label: ReactNode;\n  /** pending waits in \"To do\", active is being worked on now, done moves to \"Done\". */\n  status: QueueItemStatus;\n  /** A secondary line, such as the file or the result. */\n  detail?: ReactNode;\n  /** Right-aligned metadata, for example a duration. */\n  meta?: ReactNode;\n  /** Which Agent State mark moves while the item is active. @default \"working\" */\n  activity?: AgentActivity;\n}\n\nexport interface QueueProps extends Omit<ComponentProps<\"section\">, \"children\" | \"title\"> {\n  items: QueueItem[];\n  /** Heading above both sections. Leave it out when the surrounding panel already names the list. */\n  title?: ReactNode;\n  /**\n   * Renders a checkbox on each row so the reader can tick items off or reopen them. Without it\n   * the rows show status glyphs and only the agent moves items.\n   */\n  onStatusChange?: (id: string, done: boolean) => void;\n  /** @default \"To do\" */\n  todoLabel?: ReactNode;\n  /** @default \"Done\" */\n  doneLabel?: ReactNode;\n  /** Which sections start open. @default [\"todo\", \"done\"] */\n  defaultOpen?: Array<\"todo\" | \"done\">;\n  /** Shown in an empty \"To do\" section. @default \"Nothing left to do\" */\n  emptyLabel?: ReactNode;\n}\n\n/**\n * The agent's todo list in two collapsible sections, \"To do\" and \"Done\", each with a count.\n * When an item changes status it glides from its old row to its new one, and the rows around\n * it close the gap, so the eye can follow what moved. Instant with reduced motion.\n */\nexport function Queue({\n  items,\n  title,\n  onStatusChange,\n  todoLabel = \"To do\",\n  doneLabel = \"Done\",\n  defaultOpen = [\"todo\", \"done\"],\n  emptyLabel = \"Nothing left to do\",\n  className,\n  ...props\n}: QueueProps) {\n  const todo = items.filter((item) => item.status !== \"done\");\n  const done = items.filter((item) => item.status === \"done\");\n  const root = useRef<HTMLElement>(null);\n  const rows = useRef(new Map<string, HTMLElement>());\n  const titleId = useId();\n\n  useFlip(root, rows, items);\n\n  // A ticked row remounts in the other section; keep keyboard focus on its checkbox there.\n  const refocus = useRef<string | null>(null);\n  useLayoutEffect(() => {\n    const id = refocus.current;\n    refocus.current = null;\n    if (!id) return;\n    rows.current.get(id)?.querySelector<HTMLElement>(\"[role=checkbox]\")?.focus({ preventScroll: true });\n  }, [items]);\n  const handleStatusChange = onStatusChange\n    ? (id: string, done: boolean) => {\n        if (rows.current.get(id)?.contains(document.activeElement)) refocus.current = id;\n        onStatusChange(id, done);\n      }\n    : undefined;\n\n  const register = (id: string) => (node: HTMLElement | null) => {\n    if (node) rows.current.set(id, node);\n    else rows.current.delete(id);\n  };\n\n  return (\n    <section\n      ref={root}\n      aria-labelledby={title != null ? titleId : undefined}\n      aria-label={title == null ? \"Queue\" : undefined}\n      className={cx(\n        \"w-full overflow-hidden rounded-xl border border-zinc-950/10 bg-white text-zinc-950 shadow-[0_1px_2px_rgb(0_0_0/0.04)]\",\n        \"dark:border-white/10 dark:bg-black dark:text-white dark:shadow-[inset_0_1px_0_rgb(255_255_255/0.06)]\",\n        className,\n      )}\n      {...props}\n    >\n      {title != null ? (\n        <h3 id={titleId} className=\"border-b border-zinc-950/[0.07] px-4 py-3 text-sm font-semibold dark:border-white/[0.08]\">\n          {title}\n        </h3>\n      ) : null}\n      <QueueSection label={todoLabel} count={todo.length} defaultOpen={defaultOpen.includes(\"todo\")}>\n        {todo.length ? (\n          todo.map((item) => <QueueRow key={item.id} ref={register(item.id)} item={item} onStatusChange={handleStatusChange} />)\n        ) : (\n          <li className=\"px-2.5 py-2 text-sm text-zinc-500\">{emptyLabel}</li>\n        )}\n      </QueueSection>\n      <QueueSection label={doneLabel} count={done.length} defaultOpen={defaultOpen.includes(\"done\")} divided>\n        {done.map((item) => (\n          <QueueRow key={item.id} ref={register(item.id)} item={item} onStatusChange={handleStatusChange} />\n        ))}\n      </QueueSection>\n    </section>\n  );\n}\n\nfunction QueueSection({\n  label,\n  count,\n  defaultOpen,\n  divided = false,\n  children,\n}: {\n  label: ReactNode;\n  count: number;\n  defaultOpen: boolean;\n  divided?: boolean;\n  children: ReactNode;\n}) {\n  return (\n    <Collapsible.Root defaultOpen={defaultOpen} className={divided ? \"border-t border-zinc-950/[0.07] dark:border-white/[0.08]\" : undefined}>\n      <Collapsible.Trigger\n        className={cx(\n          \"group flex h-10 w-full cursor-pointer items-center gap-1.5 px-2.5 text-left text-xs font-medium select-none\",\n          \"text-zinc-500 transition-[background-color,color] duration-150 ease-out motion-reduce:transition-none\",\n          \"hover:bg-zinc-950/[0.03] hover:text-zinc-950 dark:hover:bg-white/[0.04] dark:hover:text-white\",\n          \"focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-sky-500\",\n        )}\n      >\n        <svg\n          aria-hidden=\"true\"\n          viewBox=\"0 0 16 16\"\n          fill=\"none\"\n          className={`size-4 shrink-0 text-zinc-400 transition-[rotate,color] duration-220 ${ease} group-hover:text-current group-data-[panel-open]:rotate-90 motion-reduce:transition-none dark:text-zinc-500`}\n        >\n          <path d=\"m6.25 4.5 3.5 3.5-3.5 3.5\" stroke=\"currentColor\" strokeWidth=\"1.5\" strokeLinecap=\"round\" strokeLinejoin=\"round\" />\n        </svg>\n        <span className=\"text-zinc-950 dark:text-white\">{label}</span>\n        <span\n          key={count}\n          className={`font-mono tabular-nums transition-[opacity,translate] duration-200 ${ease} starting:-translate-y-0.5 starting:opacity-0 motion-reduce:transition-none`}\n        >\n          {count}\n        </span>\n      </Collapsible.Trigger>\n      <Collapsible.Panel\n        data-queue-panel=\"\"\n        className={cx(\n          \"h-(--collapsible-panel-height) overflow-hidden\",\n          `transition-[height,opacity] duration-220 ${ease} motion-reduce:transition-none`,\n          \"data-[starting-style]:h-0 data-[starting-style]:opacity-0\",\n          \"data-[ending-style]:h-0 data-[ending-style]:opacity-0 data-[ending-style]:duration-180\",\n        )}\n      >\n        <ul className=\"grid px-1.5 pb-1.5\">{children}</ul>\n      </Collapsible.Panel>\n    </Collapsible.Root>\n  );\n}\n\nfunction QueueRow({\n  ref,\n  item,\n  onStatusChange,\n}: {\n  ref: (node: HTMLElement | null) => void;\n  item: QueueItem;\n  onStatusChange?: (id: string, done: boolean) => void;\n}) {\n  const done = item.status === \"done\";\n  const active = item.status === \"active\";\n  const labelId = useId();\n\n  return (\n    <li\n      ref={ref}\n      data-status={item.status}\n      className={cx(\n        \"relative grid grid-cols-[1rem_minmax(0,1fr)_auto] items-start gap-x-2.5 rounded-lg px-2.5 py-2\",\n        \"transition-[background-color] duration-200 motion-reduce:transition-none\",\n        active ? \"bg-zinc-950/[0.04] dark:bg-white/[0.06]\" : \"\",\n      )}\n    >\n      <span className=\"flex h-5 items-center justify-center\">\n        {onStatusChange ? (\n          <Checkbox.Root\n            checked={done}\n            onCheckedChange={(checked) => onStatusChange(item.id, checked)}\n            aria-labelledby={labelId}\n            className={cx(\n              \"flex size-4 cursor-pointer items-center justify-center rounded-[5px] border\",\n              \"border-zinc-950/25 bg-white text-white transition-[background-color,border-color] duration-150 ease-out motion-reduce:transition-none\",\n              \"hover:border-zinc-950/40 data-[checked]:border-zinc-950 data-[checked]:bg-zinc-950\",\n              \"dark:border-white/25 dark:bg-black dark:text-black dark:hover:border-white/40 dark:data-[checked]:border-white dark:data-[checked]:bg-white\",\n              \"focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-sky-500\",\n            )}\n          >\n            <Checkbox.Indicator keepMounted className=\"flex data-[unchecked]:hidden\">\n              <svg aria-hidden=\"true\" viewBox=\"0 0 16 16\" fill=\"none\" stroke=\"currentColor\" strokeWidth={2} strokeLinecap=\"round\" strokeLinejoin=\"round\" className=\"size-3\">\n                <path\n                  d=\"m3.75 8.25 2.75 2.75 5.75-6\"\n                  pathLength={1}\n                  strokeDasharray=\"1\"\n                  className={`[stroke-dashoffset:0] transition-[stroke-dashoffset] duration-200 ${ease} starting:[stroke-dashoffset:1] motion-reduce:transition-none`}\n                />\n              </svg>\n            </Checkbox.Indicator>\n          </Checkbox.Root>\n        ) : active ? (\n          <AgentMark aria-hidden=\"true\" activity={item.activity ?? \"working\"} size={16} className=\"text-zinc-950 dark:text-white\" />\n        ) : (\n          <StatusGlyph key={item.status} kind={done ? \"success\" : \"queued\"} />\n        )}\n      </span>\n      <div className=\"min-w-0\">\n        <p\n          id={labelId}\n          className={cx(\n            \"text-sm leading-5 break-words transition-colors duration-200 motion-reduce:transition-none\",\n            done ? \"text-zinc-500 line-through decoration-zinc-500/50\" : active ? \"font-medium text-zinc-950 dark:text-white\" : \"text-zinc-950 dark:text-white\",\n          )}\n        >\n          {item.label}\n          {!onStatusChange || active ? <span className=\"sr-only\">, {done ? \"done\" : active ? \"in progress\" : \"to do\"}</span> : null}\n        </p>\n        {item.detail != null ? <p className=\"mt-0.5 text-xs text-zinc-500\">{item.detail}</p> : null}\n      </div>\n      {item.meta != null ? <span className=\"pt-0.5 font-mono text-[11px] leading-5 text-zinc-500 tabular-nums\">{item.meta}</span> : <span />}\n    </li>\n  );\n}\n\n/**\n * Moves each row from where it was to where it is now with a transform, after React has\n * placed it. Positions are measured relative to the list itself, so scrolling the page between\n * updates does not cause a jump. Rows that were hidden in a closed section simply appear.\n */\nfunction useFlip(root: { current: HTMLElement | null }, rows: { current: Map<string, HTMLElement> }, items: QueueItem[]) {\n  const last = useRef(new Map<string, { x: number; y: number }>());\n  const previousItems = useRef(items);\n\n  // Snapshot where every row is before React applies the new order.\n  if (previousItems.current !== items && root.current) {\n    last.current = measure(root.current, rows.current);\n  }\n  previousItems.current = items;\n\n  useLayoutEffect(() => {\n    const container = root.current;\n    if (!container) return;\n    const next = measure(container, rows.current);\n    const reduce = window.matchMedia(\"(prefers-reduced-motion: reduce)\").matches;\n    if (!reduce) {\n      for (const [id, to] of next) {\n        const from = last.current.get(id);\n        const node = rows.current.get(id);\n        if (!from || !node) continue;\n        const dx = from.x - to.x;\n        const dy = from.y - to.y;\n        if (Math.abs(dx) < 1 && Math.abs(dy) < 1) continue;\n        // A row crossing from one section to the other must not be clipped by its panel on the way.\n        const panel = node.closest<HTMLElement>(\"[data-queue-panel]\");\n        if (panel) {\n          lifted.set(panel, (lifted.get(panel) ?? 0) + 1);\n          panel.style.overflow = \"visible\";\n        }\n        const animation = node.animate([{ transform: `translate(${dx}px, ${dy}px)` }, { transform: \"translate(0, 0)\" }], {\n          duration: Math.min(480, 260 + Math.abs(dy) * 0.4),\n          easing: \"cubic-bezier(0.23, 1, 0.32, 1)\",\n        });\n        const settle = () => {\n          if (!panel) return;\n          const left = (lifted.get(panel) ?? 1) - 1;\n          lifted.set(panel, left);\n          if (left <= 0) panel.style.overflow = \"\";\n        };\n        animation.addEventListener(\"finish\", settle, { once: true });\n        animation.addEventListener(\"cancel\", settle, { once: true });\n      }\n    }\n    last.current = next;\n  }, [items, root, rows]);\n}\n\n/** Panels whose clipping is lifted, with the number of row animations still running in each. */\nconst lifted = new WeakMap<HTMLElement, number>();\n\nfunction measure(container: HTMLElement, rows: Map<string, HTMLElement>) {\n  const origin = container.getBoundingClientRect();\n  const positions = new Map<string, { x: number; y: number }>();\n  for (const [id, node] of rows) {\n    const rect = node.getBoundingClientRect();\n    // Rows inside a closed or closing section have no box; they should not fly in from it.\n    if (!rect.height || (node.checkVisibility && !node.checkVisibility({ visibilityProperty: true }))) continue;\n    positions.set(id, { x: rect.left - origin.left, y: rect.top - origin.top });\n  }\n  return positions;\n}\n"
    }
  ],
  "example": {
    "content": "import { Queue } from \"@/components/shaken/agent/queue\";\n\nexport default function QueueExample() {\n  return (\n    <Queue\n      className=\"max-w-sm\"\n      title=\"Tasks\"\n      items={[\n        { id: \"1\", label: \"Add a retry to the payment webhook\", status: \"active\", detail: \"api/webhooks/payment.ts\" },\n        { id: \"2\", label: \"Write tests for duplicate events\", status: \"pending\" },\n        { id: \"3\", label: \"Update the runbook\", status: \"pending\" },\n        { id: \"4\", label: \"Reproduce the duplicate charge\", status: \"done\", meta: \"2m 10s\" },\n        { id: \"5\", label: \"Find where events are deduplicated\", status: \"done\", meta: \"48s\" },\n      ]}\n    />\n  );\n}\n"
  }
}
