@cueplusplus/ui 0.2.0 → 0.5.0

package/manifest/components/popover.json

@@ -0,0 +1,193 @@
+{
+  "name": "Popover",
+  "slug": "popover",
+  "group": "overlays",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A small floating surface anchored to a control — a filter form, an inspector,\na colour picker.\n\nWraps Base UI's `Popover`, so anchoring, collision flipping, Escape and\noutside-press dismissal are the primitive's. This layer adds the token skin,\nthe portal theme stamp and the canvas-safe wheel dismissal.",
+  "props": [],
+  "typeReferences": [],
+  "subcomponents": [
+    "Root",
+    "Trigger",
+    "Content",
+    "Title",
+    "Description",
+    "Close"
+  ],
+  "parts": [
+    {
+      "name": "Root",
+      "usage": "Popover.Root",
+      "description": "Groups the parts of a popover and owns its open state. Renders no element.",
+      "props": [
+        {
+          "name": "closeOnWheel",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "true",
+          "description": "Close the popover when the viewport moves under it — a wheel anywhere\noutside the popup, or a window resize. Defaults to `true`.\n\nAn anchored popup is positioned from its trigger's rect. A canvas that pans\nby mutating a CSS transform fires no `scroll` event, so without this the\npopup silently detaches from the thing it belongs to. Set `false` when the\npopover must survive page scrolling (a pinned inspector, say)."
+        }
+      ],
+      "typeReferences": [
+        "BasePopover.Root.Props"
+      ]
+    },
+    {
+      "name": "Trigger",
+      "usage": "Popover.Trigger",
+      "description": "The control the popover is anchored to. Unstyled — pass\n`render={<Button />}` or `render={<IconButton …/>}` so the button's own\nvariant classes stay the last word on how it looks.",
+      "props": [],
+      "typeReferences": [
+        "BasePopover.Trigger.Props"
+      ]
+    },
+    {
+      "name": "Content",
+      "usage": "Popover.Content",
+      "description": "The popover's portal, positioner and popup.\n\nPortalled through {@link useCuePortalProps}, so the surface carries the\ncaller's theme, density and mode even though it mounts at the end of\n`<body>`. Flipping and shifting to stay on screen is Base UI's; the wheel\ndismissal is ours (see {@link PopoverRootProps.closeOnWheel}).",
+      "props": [
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the popup surface."
+        },
+        {
+          "name": "align",
+          "type": "\"center\" | \"end\" | \"start\"",
+          "required": false,
+          "defaultValue": null,
+          "description": "Alignment along that side. Defaults to `\"center\"`."
+        },
+        {
+          "name": "keepMounted",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": null,
+          "description": "Keep the popup mounted while closed."
+        },
+        {
+          "name": "positionerClassName",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the positioner that places the popup."
+        },
+        {
+          "name": "sideOffset",
+          "type": "number | OffsetFunction",
+          "required": false,
+          "defaultValue": "4",
+          "description": "Gap in px between trigger and popup. Defaults to `4`."
+        },
+        {
+          "name": "side",
+          "type": "\"left\" | \"right\" | \"bottom\" | \"top\" | \"inline-end\" | \"inline-start\"",
+          "required": false,
+          "defaultValue": null,
+          "description": "Preferred side of the trigger. Defaults to `\"bottom\"`."
+        },
+        {
+          "name": "alignOffset",
+          "type": "number | OffsetFunction",
+          "required": false,
+          "defaultValue": null,
+          "description": "Nudge along the alignment axis, in px."
+        }
+      ],
+      "typeReferences": [
+        "Omit<BasePopover.Popup.Props, \"className\">"
+      ]
+    },
+    {
+      "name": "Title",
+      "usage": "Popover.Title",
+      "description": "The popover's heading, wired to the popup's `aria-labelledby`.",
+      "props": [],
+      "typeReferences": [
+        "BasePopover.Title.Props"
+      ]
+    },
+    {
+      "name": "Description",
+      "usage": "Popover.Description",
+      "description": "The supporting line under the title, published as `aria-describedby`.",
+      "props": [],
+      "typeReferences": [
+        "BasePopover.Description.Props"
+      ]
+    },
+    {
+      "name": "Close",
+      "usage": "Popover.Close",
+      "description": "A control that closes the popover. Unstyled — wrap it in a `Button`.",
+      "props": [],
+      "typeReferences": [
+        "BasePopover.Close.Props"
+      ]
+    }
+  ],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent-soft",
+    "--cue-border",
+    "--cue-border-overlay",
+    "--cue-control-sm",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-radius-control",
+    "--cue-radius-overlay",
+    "--cue-scrim",
+    "--cue-space-1",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-space-4",
+    "--cue-surface-2",
+    "--cue-text-emphasis",
+    "--cue-text-label",
+    "--cue-text-ui"
+  ],
+  "summary": "A panel anchored to the control that opened it.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Popover.Root>\n  <Popover.Trigger render={<IconButton aria-label=\"Filter\" icon={Filter} />} />\n  <Popover.Content side=\"bottom\" align=\"end\">\n    <Popover.Title>Filter cues</Popover.Title>\n    <SearchInput aria-label=\"Query\" />\n  </Popover.Content>\n</Popover.Root>",
+      "language": "tsx"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/popover",
+  "mdUrl": "/docs/components/popover.md",
+  "jsonUrl": "/r/components/popover.json",
+  "whenToUse": [
+    "Secondary controls that belong to one trigger: a filter set, a colour picker, a row's properties.",
+    "When the page behind has to stay readable while the panel is open."
+  ],
+  "whenNotToUse": [
+    "A list of commands. Use `DropdownMenu`, which brings roving focus, typeahead and the menu roles.",
+    "Text that only describes the trigger. Use `Tooltip`, or `InfoTip` for the question-mark affordance.",
+    "Anything that must be answered before the user moves on. Use `Dialog`."
+  ],
+  "commonMistakes": [
+    "Turning `closeOnWheel` off on a canvas that pans by CSS transform. No scroll event fires there, so the popup silently detaches from its trigger.",
+    "Filling it with a form whose first control cannot take focus, which strands keyboard users on the trigger."
+  ],
+  "specimens": [
+    {
+      "title": "Popover",
+      "group": "overlays",
+      "components": [
+        "Popover"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"default\">\n    <Popover.Root>\n      <Popover.Trigger render={<Button>Fixture</Button>} />\n      <Popover.Content>\n        <Popover.Title>Source Four 26°</Popover.Title>\n        <Popover.Description>Universe 1, channels 12 to 19.</Popover.Description>\n        <Popover.Close render={<Button size=\"sm\">Close</Button>} />\n      </Popover.Content>\n    </Popover.Root>\n  </Specimen>\n  <Specimen label=\"side right\">\n    <Popover.Root>\n      <Popover.Trigger render={<Button>Right</Button>} />\n      <Popover.Content side=\"right\" align=\"start\">\n        <Popover.Title>Anchored right</Popover.Title>\n        <Popover.Description>Flips when there is no room.</Popover.Description>\n      </Popover.Content>\n    </Popover.Root>\n  </Specimen>\n</Specimens>",
+      "note": "An anchored surface with a title, a description and arbitrary content.",
+      "interaction": "closes on outside mousedown, on scroll, on wheel and on Escape. The wheel case is the one a canvas that pans by CSS transform needs."
+    }
+  ]
+}

package/manifest/components/preset-section.json

@@ -0,0 +1,73 @@
+{
+  "name": "PresetSection",
+  "slug": "preset-section",
+  "group": "configurator",
+  "importPath": "@cueplusplus/ui/configurator",
+  "peerDependencies": [
+    "react-aria-components"
+  ],
+  "clientOnly": true,
+  "description": "Section 1 — the four choices that are not token edits at all.\n\nPreset, mode and density are *provider* state: picking one restamps the\ndocument and every portal under it, which is why they live here rather than\nin the colour list. Text scale and zoom are the two relief valves the spec\npairs with the density ladder — one scales the type ramp inside the layout,\nthe other scales the finished layout itself.",
+  "props": [
+    {
+      "name": "edits",
+      "type": "TokenEdits",
+      "required": true,
+      "defaultValue": null,
+      "description": "The panel's edit surface."
+    },
+    {
+      "name": "zoom",
+      "type": "ZoomValve",
+      "required": true,
+      "defaultValue": null,
+      "description": "The root zoom valve the panel owns."
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes for the section."
+    }
+  ],
+  "typeReferences": [],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-border",
+    "--cue-border-strong",
+    "--cue-density",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-font-pairing-mono",
+    "--cue-font-sans",
+    "--cue-font-scale",
+    "--cue-font-theme-mono",
+    "--cue-radius-control",
+    "--cue-radius-scale",
+    "--cue-space-1",
+    "--cue-space-2",
+    "--cue-space-4",
+    "--cue-text-label",
+    "--cue-text-micro"
+  ],
+  "summary": "Section 1 — the four choices that are not token edits at all.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<PresetSection edits={edits} zoom={zoom} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/preset-section",
+  "mdUrl": "/docs/components/preset-section.md",
+  "jsonUrl": "/r/components/preset-section.json",
+  "todo": true
+}

package/manifest/components/progress.json

@@ -0,0 +1,95 @@
+{
+  "name": "Progress",
+  "slug": "progress",
+  "group": "instruments",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "Determinate work, drawn as a filling rule.\n\nWraps Base UI's `Progress`, so `role=\"progressbar\"`, the value formatting and\nthe completion status are the primitive's; this layer adds the console skin:\na sunk `surface-3` track, an accent fill and a 120ms linear width transition\n— linear because a progress bar that eases is lying about its rate.\n\nPassing `value={null}` makes it indeterminate: the fill collapses and the\ntrack pulses instead, which says \"working, size unknown\" without inventing a\nnumber. The pulse stills under `prefers-reduced-motion`.\n\nUse `Meter` instead for a *level* (how full something is); a progress bar is\nfor a *task* (how far along something is).\n\nStatic markup — no `\"use client\"`.",
+  "props": [
+    {
+      "name": "label",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "Caption above the bar. Rendered as Base UI's `Progress.Label`, so it also\nbecomes the bar's accessible name — pass one, or an `aria-label`."
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes for the frame that holds the header and the track."
+    },
+    {
+      "name": "height",
+      "type": "number",
+      "required": false,
+      "defaultValue": "5",
+      "description": "Track height in px at the 16px root, emitted as `rem`. Defaults to `5`."
+    },
+    {
+      "name": "showValue",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Show the formatted value opposite the label. Defaults to `false`."
+    },
+    {
+      "name": "trackClassName",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes for the track."
+    },
+    {
+      "name": "indicatorClassName",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes for the fill."
+    }
+  ],
+  "typeReferences": [
+    "Omit<BaseProgress.Root.Props, \"className\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-surface-3",
+    "--cue-text-label"
+  ],
+  "summary": "Determinate work, drawn as a filling rule.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Progress value={40} label=\"Rendering\" showValue />\n<Progress value={null} aria-label=\"Connecting\" />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/progress",
+  "mdUrl": "/docs/components/progress.md",
+  "jsonUrl": "/r/components/progress.json",
+  "specimens": [
+    {
+      "title": "Progress",
+      "group": "instruments",
+      "components": [
+        "Progress"
+      ],
+      "code": "<div className=\"flex w-full max-w-[36rem] flex-col gap-(--cue-space-5)\">\n  <Progress label=\"Rendering preview\" value={62} showValue />\n  <Progress label={COPY.loading.title} value={null} />\n  <Progress label=\"Tall\" value={30} height={8} showValue />\n</div>",
+      "note": "Determinate and indeterminate, with an optional printed value.",
+      "interaction": "the indeterminate track stills under prefers-reduced-motion."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/prompt-library.json

@@ -0,0 +1,99 @@
+{
+  "name": "PromptLibrary",
+  "slug": "prompt-library",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "Prompts you saved, searchable, with their variables shown before you insert one.",
+  "props": [
+    {
+      "name": "prompts",
+      "type": "readonly SavedPrompt[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Everything saved. Filtering happens inside against the name."
+    },
+    {
+      "name": "query",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Current search text."
+    },
+    {
+      "name": "selectedId",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Which prompt is previewed below the list."
+    },
+    {
+      "name": "onQueryChange",
+      "type": "((query: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called as the search is typed."
+    },
+    {
+      "name": "onSelect",
+      "type": "((id: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when a prompt is highlighted."
+    },
+    {
+      "name": "onInsert",
+      "type": "((id: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called on double click, to drop the prompt into the composer."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  | \"children\"\n  | \"prompts\"\n  | \"query\"\n  | \"selectedId\"\n  | \"onQueryChange\"\n  | \"onSelect\"\n  | \"onInsert\"\n> & {\n  /** Everything saved. Filtering happens inside against the name. */\n  prompts: readonly SavedPrompt[];\n  /** Current search text. */\n  query: string;\n  /** Which prompt is previewed below the list. */\n  selectedId: string;\n  /** Called as the search is typed. */\n  onQueryChange?: (query: string) => void;\n  /** Called when a prompt is highlighted. */\n  onSelect?: (id: string) => void;\n  /** Called on double click, to drop the prompt into the composer. */\n  onInsert?: (id: string) => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-bg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-radius-control",
+    "--cue-radius-overlay",
+    "--cue-radius-surface",
+    "--cue-surface-1",
+    "--cue-text-body",
+    "--cue-text-ui"
+  ],
+  "summary": "Prompts you saved, searchable, with their variables shown before you insert one.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { PromptLibrary } from \"@cueplusplus/ui/elements\";\n\n<PromptLibrary\n  prompts={prompts}\n  query={query}\n  selectedId={selectedId}\n  onQueryChange={setQuery}\n  onSelect={setSelectedId}\n  onInsert={insert}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/prompt-library",
+  "mdUrl": "/docs/components/prompt-library.md",
+  "jsonUrl": "/r/components/prompt-library.json",
+  "specimens": [
+    {
+      "title": "PromptLibrary",
+      "group": "elements-composer",
+      "components": [
+        "PromptLibrary"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"browsing\" wide>\n    <PromptLibrary\n      prompts={PROMPTS}\n      query={promptQuery}\n      selectedId={promptId}\n      onQueryChange={setPromptQuery}\n      onSelect={setPromptId}\n      onInsert={setPromptId}\n    />\n  </Specimen>\n  <Specimen label=\"nothing matches\" wide>\n    <PromptLibrary prompts={PROMPTS} query=\"haze\" selectedId=\"\" />\n  </Specimen>\n</Specimens>",
+      "note": "Prompts somebody saved, searchable, with the holes in them counted before you insert one — `3 vars` is the difference between a prompt you can send and a template you still have to fill. The preview underneath is the whole body, because a prompt library that hides the prompt is a list of file names.",
+      "interaction": "arrows walk the list and Enter inserts; a row also inserts on double-click, so the mouse has the same two gestures the keyboard does. An empty result says what it found nothing for rather than showing an empty box."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/queue-dock.json

@@ -0,0 +1,110 @@
+{
+  "name": "QueueDock",
+  "slug": "queue-dock",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "What you typed while it was still working, stacked and still yours to change.\n\nThe dock over the composer, and one of the two elements the teardown found\nmissing everywhere. Its whole reason to exist is the three things you can do\nto a queued turn *before* it sends: rewrite it now that you have seen what\nthe run did, jump it to the front, or drop it. A queue you can only watch is\na queue you will let send something you no longer mean.\n\nIt folds. Four queued turns above a composer is a wall, so the collapsed\nstate is one line — `4 queued messages` — and the entries come back on a\nclick. Open state is a prop like everything else in this family, so a\nscripted replay of the dock is arithmetic rather than a component with a mind\nof its own.\n\nAn empty queue draws **nothing**: no line, no empty state, no rule. Every\nproduct in the study does the same, and it is the right answer — a dock that\nannounces it has nothing in it is a permanent strip of chrome apologising for\nitself.",
+  "props": [
+    {
+      "name": "messages",
+      "type": "readonly QueuedFollowUp[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "The turns waiting to send, in the order they will drain. Ordering is the\ncaller's: Cursor lets a person drag one up the list, and a component that\nsorted the array it was given could not be dragged."
+    },
+    {
+      "name": "open",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "Whether the entries are showing, or only the summary line."
+    },
+    {
+      "name": "onOpenChange",
+      "type": "((open: boolean) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when the dock is expanded or collapsed."
+    },
+    {
+      "name": "onEdit",
+      "type": "((id: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Put this turn back in the composer to be rewritten. The control exists\nonly when this is given."
+    },
+    {
+      "name": "onSendNow",
+      "type": "((id: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Send this turn now rather than waiting for the run to finish — Cursor's\n`Send now`, Zed's steer button. The control exists only when this is given."
+    },
+    {
+      "name": "onRemove",
+      "type": "((id: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Drop this turn before it ever sends. The control exists only when this is\ngiven."
+    },
+    {
+      "name": "summary",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "The summary line, replacing the one {@link formatQueueSummary} would build\n— for a dock that counts something else: `2 follow-ups`, `3 steps queued`."
+    },
+    {
+      "name": "labels",
+      "type": "Partial<QueueLabels>",
+      "required": false,
+      "defaultValue": null,
+      "description": "Copy for the five controls, merged over `QUEUE_LABELS`. Partial: overriding\n`sendNow` does not cost you the other four."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-radius-control",
+    "--cue-radius-overlay",
+    "--cue-surface-2",
+    "--cue-text-ui"
+  ],
+  "summary": "What you typed while it was still working, stacked and still yours to change.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { QueueDock } from \"@cueplusplus/ui/elements\";\n\n<QueueDock\n  messages={queued}\n  open={open}\n  onOpenChange={setOpen}\n  onEdit={(id) => lift(id)}\n  onSendNow={(id) => steer(id)}\n  onRemove={(id) => drop(id)}\n/>\n// Read-only: the same dock in a shared transcript, with nothing to press.\n<QueueDock messages={queued} open />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/queue-dock",
+  "mdUrl": "/docs/components/queue-dock.md",
+  "jsonUrl": "/r/components/queue-dock.json",
+  "specimens": [
+    {
+      "title": "QueueDock",
+      "group": "elements-agents",
+      "components": [
+        "QueueDock"
+      ],
+      "code": "<Specimens>\n  <Specimen label={queueOpen ? \"three waiting\" : \"folded\"} wide>\n    <div className=\"w-full max-w-md\">\n      <QueueDock\n        messages={queued}\n        open={queueOpen}\n        onOpenChange={setQueueOpen}\n        onEdit={drain}\n        onSendNow={drain}\n        onRemove={drain}\n      />\n    </div>\n  </Specimen>\n  <Specimen label=\"read-only, in a shared transcript\" wide>\n    <div className=\"w-full max-w-md\">\n      <QueueDock messages={FOLLOW_UPS.slice(0, 2)} open />\n    </div>\n  </Specimen>\n</Specimens>",
+      "note": "What you typed while it was still working — and the three things you can still do about it. Cursor, opencode, Cline, Roo and Zed all ship this dock and assistant-ui's catalogue has nothing like it; the vendored MessageQueue two files along is the strip without the verbs. It folds to one line, because four queued turns above a composer is a wall, and an empty queue draws nothing at all rather than a strip of chrome apologising for itself.",
+      "interaction": "the summary line is the trigger and carries its own aria-expanded; each entry's three controls are named after the turn they belong to (`Send now: Then export the whole show to the desk`), so a screen reader hears which one it is about to jump. Press any of them here and the entry drains — the bench refills when the last one goes."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/quota-banner.json

@@ -0,0 +1,94 @@
+{
+  "name": "QuotaBanner",
+  "slug": "quota-banner",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "How much is left, when it comes back, and the way to get more.",
+  "props": [
+    {
+      "name": "used",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "How much has been consumed."
+    },
+    {
+      "name": "limit",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "The allowance. The banner turns amber at 90 percent."
+    },
+    {
+      "name": "unit",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "What is being counted: messages, runs, credits."
+    },
+    {
+      "name": "resetsIn",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Pre-formatted time until the window rolls over."
+    },
+    {
+      "name": "upgradeLabel",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Label for the way out."
+    },
+    {
+      "name": "onUpgrade",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called from the upgrade action."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  | \"children\"\n  | \"used\"\n  | \"limit\"\n  | \"unit\"\n  | \"resetsIn\"\n  | \"upgradeLabel\"\n  | \"onUpgrade\"\n> & {\n  /** How much has been consumed. */\n  used: number;\n  /** The allowance. The banner turns amber at 90 percent. */\n  limit: number;\n  /** What is being counted: messages, runs, credits. */\n  unit: string;\n  /** Pre-formatted time until the window rolls over. */\n  resetsIn: string;\n  /** Label for the way out. */\n  upgradeLabel: string;\n  /** Called from the upgrade action. */\n  onUpgrade?: () => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-fg-subtle",
+    "--cue-radius-overlay",
+    "--cue-surface-2",
+    "--cue-surface-3",
+    "--cue-text-body",
+    "--cue-text-ui",
+    "--cue-warn"
+  ],
+  "summary": "How much is left, when it comes back, and the way to get more.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { QuotaBanner } from \"@cueplusplus/ui/elements\";\n\n<QuotaBanner used={47} limit={50} unit=\"messages\" resetsIn=\"3h 12m\" upgradeLabel=\"Upgrade\" />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/quota-banner",
+  "mdUrl": "/docs/components/quota-banner.md",
+  "jsonUrl": "/r/components/quota-banner.json",
+  "specimens": [
+    {
+      "title": "QuotaBanner",
+      "group": "elements-agents",
+      "components": [
+        "QuotaBanner"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"comfortable\" wide>\n    <QuotaBanner\n      used={140}\n      limit={500}\n      unit=\"agent runs\"\n      resetsIn=\"12 days\"\n      upgradeLabel=\"Raise the limit\"\n      onUpgrade={() => undefined}\n    />\n  </Specimen>\n  <Specimen label=\"nearly out\" wide>\n    <QuotaBanner\n      used={472}\n      limit={500}\n      unit=\"agent runs\"\n      resetsIn=\"3 days\"\n      upgradeLabel=\"Raise the limit\"\n      onUpgrade={() => undefined}\n    />\n  </Specimen>\n</Specimens>",
+      "note": "How much is left, when it comes back, and the way to get more — in that order, which is the order the question is actually asked in. It turns warn at nine tenths rather than at the wall, so the warning arrives while there is still something to do about it.",
+      "interaction": "the upgrade action is an ink button with the label the caller passes; nothing here is a link, so the destination is entirely the host app's business."
+    }
+  ],
+  "todo": true
+}