@cueplusplus/ui 0.13.0

package/manifest/components/timeline.json

@@ -0,0 +1,131 @@
+{
+  "name": "Timeline",
+  "slug": "timeline",
+  "group": "layout",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "A vertical run of events on one rail: a run log, a cue history, a deploy\ntrail.\n\nStatic markup — no `\"use client\"`.",
+  "props": [],
+  "typeReferences": [],
+  "subcomponents": [
+    "Root",
+    "Item",
+    "Marker",
+    "Content"
+  ],
+  "parts": [
+    {
+      "name": "Root",
+      "usage": "Timeline.Root",
+      "description": "The list of events. A real `<ol>` — a timeline is ordered by definition, and\na screen reader should say \"list, 4 items\" rather than read four loose divs.",
+      "props": [],
+      "typeReferences": [
+        "React.ComponentPropsWithoutRef<\"ol\">"
+      ]
+    },
+    {
+      "name": "Item",
+      "usage": "Timeline.Item",
+      "description": "One event: marker on the rail, content beside it.\n\nThe rail is a pseudo-element on the item rather than a line drawn by the\nroot, so it stops exactly where the last entry begins — a full-height rule\nwould hang below the final marker with nothing under it. Its offset is\ncomputed from `--cue-icon-sm`, the same token the marker is sized from, so\nthe line stays centred under the dot at every density.",
+      "props": [],
+      "typeReferences": [
+        "React.ComponentPropsWithoutRef<\"li\">"
+      ]
+    },
+    {
+      "name": "Marker",
+      "usage": "Timeline.Marker",
+      "description": "The dot on the rail.\n\nA `StatusDot` in a ground-coloured disc: the disc punches the rail out behind\nthe marker so the line reads as *interrupted by* the event rather than as\npassing through it. Tones are the shared status vocabulary, and `StatusDot`\nalways emits its own `sr-only` label — the state is never colour-only.",
+      "props": [
+        {
+          "name": "tone",
+          "type": "\"danger\" | \"idle\" | \"busy\" | \"ok\" | \"warn\"",
+          "required": true,
+          "defaultValue": null,
+          "description": "Which state this event is in. The shared `StatusDot` vocabulary.",
+          "control": {
+            "kind": "enum",
+            "members": [
+              "danger",
+              "idle",
+              "busy",
+              "ok",
+              "warn"
+            ]
+          }
+        },
+        {
+          "name": "label",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Screen-reader text for the dot. Defaults to the tone name.",
+          "control": {
+            "kind": "string"
+          }
+        },
+        {
+          "name": "pulse",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": null,
+          "description": "Pulse the dot for an event still in progress.",
+          "control": {
+            "kind": "boolean"
+          }
+        }
+      ],
+      "typeReferences": [
+        "Omit<React.ComponentPropsWithoutRef<\"span\">, \"children\">"
+      ]
+    },
+    {
+      "name": "Content",
+      "usage": "Timeline.Content",
+      "description": "What happened: a line of text, a timestamp, a nested panel.",
+      "props": [],
+      "typeReferences": [
+        "React.ComponentPropsWithoutRef<\"div\">"
+      ]
+    }
+  ],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-bg",
+    "--cue-border",
+    "--cue-fg",
+    "--cue-font-mono",
+    "--cue-icon-sm",
+    "--cue-space-1",
+    "--cue-space-4",
+    "--cue-space-5",
+    "--cue-text-ui"
+  ],
+  "summary": "A vertical run of events on one rail: a run log, a cue history, a deploy trail.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Timeline.Root>\n  <Timeline.Item>\n    <Timeline.Marker tone=\"ok\" label=\"Patched\" />\n    <Timeline.Content>Patched universe 1</Timeline.Content>\n  </Timeline.Item>\n  <Timeline.Item>\n    <Timeline.Marker tone=\"busy\" label=\"Focusing\" pulse />\n    <Timeline.Content>Focusing front truss</Timeline.Content>\n  </Timeline.Item>\n</Timeline.Root>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/timeline",
+  "mdUrl": "/docs/components/timeline.md",
+  "jsonUrl": "/r/components/timeline.json",
+  "specimens": [
+    {
+      "title": "Timeline",
+      "group": "layout",
+      "components": [
+        "Timeline"
+      ],
+      "code": "<Timeline.Root className=\"w-full max-w-[36rem]\">\n  {CUES.slice(0, 4).map((cue, index) => (\n    <Timeline.Item key={cue.id}>\n      <Timeline.Marker\n        tone={index === 0 ? \"ok\" : index === 1 ? \"busy\" : index === 2 ? \"warn\" : \"idle\"}\n        pulse={index === 1}\n        label={index === 1 ? \"Running\" : undefined}\n      />\n      <Timeline.Content>\n        <span className=\"font-mono text-(length:--cue-text-ui) text-fg\">{cue.label}</span>\n        <span className=\"font-mono text-(length:--cue-text-micro) text-fg-subtle\">\n          {cue.time} fade\n        </span>\n      </Timeline.Content>\n    </Timeline.Item>\n  ))}\n</Timeline.Root>",
+      "note": "An ordered list with tone markers taken from `StatusDot`, so a timeline and a status row agree on what amber means.",
+      "interaction": "none. A timeline is a record."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/title-bar.json

@@ -0,0 +1,97 @@
+{
+  "name": "TitleBar",
+  "slug": "title-bar",
+  "group": "chrome",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "The window's own bar: app mark left, document name centred, controls right.",
+  "props": [
+    {
+      "name": "platformDrag",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Make the bar a window drag handle.\n\nEmits `data-tauri-drag-region` (Tauri reads the attribute) *and* the\n`app-region: drag` CSS property (Electron and Chromium read that), because\nthe same component ships into both shells and neither one recognises the\nother's contract. The interactive clusters are carved back out with\n`app-region: no-drag`, or the buttons in the bar would only ever move the\nwindow instead of firing. Both halves of that contract live in\n`./_drag.ts`, which `AppShell.Bar` emits from as well — the two bars are\ndraggable the same way or they are not draggable the same way.\n\nDouble-click-to-maximise is not wired here. Tauri's own injected script\nalready provides it on any drag region, cancel-by-dragging-away on macOS\nincluded; Electron provides nothing, and an Electron app has to listen for\n`dblclick` and toggle the window itself. Neither is a decision a component\nin a design system can make on the window's behalf.\n\nDefaults to `false`.",
+      "control": {
+        "kind": "boolean"
+      }
+    },
+    {
+      "name": "center",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "Centre slot: the document name. Absolutely centred on the *bar*, not\nbetween the two clusters, so it does not shift sideways when a button\nappears on one side. `pointer-events-none`, so the dead space around a\nshort title stays draggable.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    },
+    {
+      "name": "actions",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "Trailing slot: window controls, connection state, an overflow menu.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    },
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "Leading slot: the app mark, a back button, the file menu.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    }
+  ],
+  "typeReferences": [
+    "React.ComponentPropsWithoutRef<\"div\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-border",
+    "--cue-chrome-titlebar",
+    "--cue-fg-muted",
+    "--cue-font-mono",
+    "--cue-pad-row-x",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-surface-1",
+    "--cue-text-label"
+  ],
+  "summary": "The window's own bar: app mark left, document name centred, controls right.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<TitleBar platformDrag center=\"untitled.cue\" actions={<WindowControls />}>\n  <Eyebrow>CUE++</Eyebrow>\n</TitleBar>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/title-bar",
+  "mdUrl": "/docs/components/title-bar.md",
+  "jsonUrl": "/r/components/title-bar.json",
+  "specimens": [
+    {
+      "title": "TitleBar",
+      "group": "chrome",
+      "components": [
+        "TitleBar"
+      ],
+      "code": "<div className=\"w-full overflow-hidden rounded-(--radius-surface) border border-border\">\n  <TitleBar center=\"dmxhub — universe 1\" actions={<Chip tone=\"ok\">connected</Chip>}>\n    <Eyebrow>cue++</Eyebrow>\n  </TitleBar>\n</div>",
+      "note": "Window furniture, sized from the chrome rung rather than the control ladder.",
+      "interaction": "the drag region is inert in a browser; `platformDrag` turns it on for Electron and Tauri."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/toast.json

@@ -0,0 +1,140 @@
+{
+  "name": "Toast",
+  "slug": "toast",
+  "group": "overlays",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "Transient confirmations and failures: \"patched\", \"export finished\",\n\"Art-Net node went away\".\n\nWraps Base UI's `Toast`, which owns the queue, the auto-dismiss timers, the\nlive-region announcements, swipe-to-dismiss and the F6 focus hotkey. This\nlayer supplies the surface, the tone rail and the portal theme stamp.",
+  "props": [],
+  "typeReferences": [],
+  "subcomponents": [
+    "Provider",
+    "Viewport"
+  ],
+  "parts": [
+    {
+      "name": "Provider",
+      "usage": "Toast.Provider",
+      "description": "Holds the toast queue. Mount it once, high in the tree, around everything\nthat might raise a toast — and render exactly one {@link ToastViewport}\ninside it.\n\n`limit` defaults to `3`: beyond that the oldest toasts are marked\n`data-limited` and hidden rather than dropped, so they reappear as the stack\ndrains.",
+      "props": [],
+      "typeReferences": [
+        "BaseToast.Provider.Props"
+      ]
+    },
+    {
+      "name": "Viewport",
+      "usage": "Toast.Viewport",
+      "description": "Where the stack appears: bottom-right, newest nearest the corner.\n\nPortalled through {@link useCuePortalProps} so the cards render in the app's\ntheme and density regardless of which subtree raised them. Render exactly one\nper {@link ToastProvider}.",
+      "props": [
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the viewport (move the corner, change the width).",
+          "control": {
+            "kind": "string"
+          }
+        },
+        {
+          "name": "toastClassName",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for every toast card.",
+          "control": {
+            "kind": "string"
+          }
+        },
+        {
+          "name": "closeLabel",
+          "type": "string",
+          "required": false,
+          "defaultValue": "Dismiss",
+          "description": "Accessible name for each card's close affordance. Defaults to `\"Dismiss\"`.",
+          "control": {
+            "kind": "string"
+          }
+        }
+      ],
+      "typeReferences": []
+    }
+  ],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-soft",
+    "--cue-border",
+    "--cue-border-overlay",
+    "--cue-border-strong",
+    "--cue-busy",
+    "--cue-control-sm",
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-icon-md",
+    "--cue-icon-sm",
+    "--cue-info",
+    "--cue-leading-ui",
+    "--cue-ok",
+    "--cue-radius-control",
+    "--cue-radius-overlay",
+    "--cue-scrim",
+    "--cue-space-1",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-space-4",
+    "--cue-space-6",
+    "--cue-surface-2",
+    "--cue-text-emphasis",
+    "--cue-text-label",
+    "--cue-text-ui",
+    "--cue-warn"
+  ],
+  "summary": "A short, dismissible note about something that just happened.",
+  "examples": [
+    {
+      "title": "Raising one",
+      "code": "const { add } = useToast();\n\nadd({\n  title: \"Patch saved\",\n  description: \"12 fixtures written to universe 1.\",\n  tone: \"ok\",\n  actionProps: { children: \"Undo\", onClick: undo },\n});",
+      "language": "tsx"
+    },
+    {
+      "title": "Usage",
+      "code": "<Toast.Provider>\n  <App />\n  <Toast.Viewport />\n</Toast.Provider>",
+      "language": "tsx"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/toast",
+  "mdUrl": "/docs/components/toast.md",
+  "jsonUrl": "/r/components/toast.json",
+  "whenToUse": [
+    "Confirming an action that finished away from the user's attention, or reporting a failure with nowhere inline to put it.",
+    "One `Toast.Provider` high in the tree, with exactly one `Toast.Viewport` inside it."
+  ],
+  "whenNotToUse": [
+    "Validating a field the user is editing. Use `FieldError`, which stays with the control.",
+    "Anything that must be acknowledged before continuing. Use `AlertDialog`.",
+    "Long text. A toast leaves on its own."
+  ],
+  "commonMistakes": [
+    "Mounting a second viewport, which splits the queue across two corners of the screen.",
+    "Raising one toast per item in a batch. Reuse the id and call `update`, so the count changes in place."
+  ],
+  "specimens": [
+    {
+      "title": "Toast",
+      "group": "overlays",
+      "components": [
+        "Toast"
+      ],
+      "code": "<Toast.Provider>\n  <ToastBench />\n</Toast.Provider>",
+      "note": "Seven tones and an optional action, in a viewport that stacks from the corner.",
+      "interaction": "a hovered stack stops its timers; Escape moves focus into the stack so a toast action is reachable."
+    }
+  ]
+}

package/manifest/components/todo-list.json

@@ -0,0 +1,76 @@
+{
+  "name": "TodoList",
+  "slug": "todo-list",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "The agent's own working list, rewritten mid-run as it discovers what else is needed.",
+  "props": [
+    {
+      "name": "items",
+      "type": "readonly TodoItem[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "The list as it stands right now. Each item carries its own status, so the agent\ncan add, reorder, and complete items in any order between renders.",
+      "control": {
+        "kind": "array",
+        "fixture": "agent.todos"
+      }
+    },
+    {
+      "name": "revision",
+      "type": "number",
+      "required": false,
+      "defaultValue": null,
+      "description": "Which rewrite of the list this is. Omit to show a plain done/total count instead.",
+      "control": {
+        "kind": "number"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<ComponentProps<\"div\">, \"children\" | \"items\" | \"revision\"> & {\n  /**\n   * The list as it stands right now. Each item carries its own status, so the agent\n   * can add, reorder, and complete items in any order between renders.\n   */\n  items: readonly TodoItem[];\n  /** Which rewrite of the list this is. Omit to show a plain done/total count instead. */\n  revision?: number;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-border-strong",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-radius-control",
+    "--cue-stream",
+    "--cue-surface-2",
+    "--cue-text-body"
+  ],
+  "summary": "The agent's own working list, rewritten mid-run as it discovers what else is needed.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { TodoList } from \"@cueplusplus/ui/elements\";\n\n<TodoList\n  items={[\n    { id: \"read\", text: \"Read the failing test\", status: \"done\" },\n    { id: \"fix\", text: \"Fix the converter\", status: \"active\" },\n    { id: \"verify\", text: \"Re-run the suite\", status: \"pending\" },\n  ]}\n  revision={2}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/todo-list",
+  "mdUrl": "/docs/components/todo-list.md",
+  "jsonUrl": "/r/components/todo-list.json",
+  "specimens": [
+    {
+      "title": "TodoList",
+      "group": "elements",
+      "components": [
+        "TodoList"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"rev 3\" wide>\n    <TodoList items={TODOS} revision={3} />\n  </Specimen>\n  <Specimen label=\"no revision\" wide>\n    <TodoList items={TODOS.slice(0, 3)} />\n  </Specimen>\n</Specimens>",
+      "note": "The agent's own working list, which is not the plan: it is rewritten mid-run as the job turns out to be bigger. Items carry their own status, so more than one can be active, and `revision` is what makes a rewrite legible rather than alarming.",
+      "interaction": "none, and deliberately: a reader who could tick these off would be editing the agent's mind."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/toggle-group.json

@@ -0,0 +1,134 @@
+{
+  "name": "ToggleGroup",
+  "slug": "toggle-group",
+  "group": "forms",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A cluster of {@link Toggle }s sharing one pressed state.\n\nThe difference from {@link SegmentedControl } is not cosmetic: a toggle group\ncan be **empty**. Pressing the pressed item unpresses it, so \"no filter\" is a\nreachable state — which is what a filter bar needs and what a view switcher\nmust never offer. Reach for `SegmentedControl` when the answer is always one\nof N, and for this when the answer may be none, or several (`multiple`).\n\nArrow-key roving focus and the pressed-state ARIA come from Base UI; this\nlayer supplies the density rung (published to the children through context)\nand the flat frame-less layout — a group of toggles is a row of controls, not\na boxed widget.",
+  "props": [
+    {
+      "name": "defaultValue",
+      "type": "readonly string[]",
+      "required": false,
+      "defaultValue": null,
+      "description": "The initially pressed values when uncontrolled.",
+      "control": {
+        "kind": "array",
+        "fixture": "agent.transcript"
+      }
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes for the group frame.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": true,
+      "defaultValue": null,
+      "description": "The {@link Toggle }s, each carrying a `value`.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    },
+    {
+      "name": "size",
+      "type": "\"sm\" | \"md\" | \"lg\"",
+      "required": false,
+      "defaultValue": "md",
+      "description": "Rung of the control ladder for every toggle inside. Defaults to `\"md\"`.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "sm",
+          "md",
+          "lg"
+        ]
+      }
+    },
+    {
+      "name": "value",
+      "type": "readonly string[]",
+      "required": false,
+      "defaultValue": null,
+      "description": "The pressed values when controlled. Pass with `onValueChange`.",
+      "control": {
+        "kind": "array",
+        "fixture": "agent.transcript"
+      }
+    },
+    {
+      "name": "onValueChange",
+      "type": "((value: string[]) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with every pressed value, in the order the toggles are declared.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n    BaseToggleGroup.Props,\n    \"className\" | \"value\" | \"defaultValue\" | \"onValueChange\" | \"children\"\n  >"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-border",
+    "--cue-border-strong",
+    "--cue-control-lg",
+    "--cue-control-md",
+    "--cue-control-sm",
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-fg-subtle",
+    "--cue-focus",
+    "--cue-font-mono",
+    "--cue-radius-control",
+    "--cue-space-1",
+    "--cue-space-3",
+    "--cue-space-4",
+    "--cue-space-5",
+    "--cue-sunken",
+    "--cue-text-body",
+    "--cue-text-label",
+    "--cue-text-ui"
+  ],
+  "summary": "A cluster of {@link Toggle }s sharing one pressed state.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<ToggleGroup aria-label=\"Layers\" multiple value={layers} onValueChange={setLayers}>\n  <Toggle value=\"beams\">Beams</Toggle>\n  <Toggle value=\"haze\">Haze</Toggle>\n</ToggleGroup>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/toggle-group",
+  "mdUrl": "/docs/components/toggle-group.md",
+  "jsonUrl": "/r/components/toggle-group.json",
+  "specimens": [
+    {
+      "title": "Toggle / ToggleGroup",
+      "group": "forms",
+      "components": [
+        "Toggle",
+        "ToggleGroup"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"off\">\n    <Toggle aria-label=\"Highlight\" icon={Lightbulb} />\n  </Specimen>\n  <Specimen label=\"on\">\n    <Toggle aria-label=\"Highlight, on\" icon={Lightbulb} defaultPressed />\n  </Specimen>\n  <Specimen label=\"with label\">\n    <Toggle icon={Lightbulb}>Highlight</Toggle>\n  </Specimen>\n  <Specimen label=\"disabled\">\n    <Toggle aria-label=\"Highlight, disabled\" icon={Lightbulb} disabled />\n  </Specimen>\n  <Specimen label=\"group\">\n    <ToggleGroup aria-label=\"Text style\" defaultValue={[\"bold\"]}>\n      <Toggle value=\"bold\" aria-label=\"Bold\" icon={Bold} />\n      <Toggle value=\"italic\" aria-label=\"Italic\" icon={Italic} />\n      <Toggle value=\"underline\" aria-label=\"Underline\" icon={Underline} />\n    </ToggleGroup>\n  </Specimen>\n</Specimens>",
+      "note": "A button that stays pressed, and a set of them. `aria-pressed` carries the state.",
+      "interaction": "hover tints the ground; pressed is accent-soft, on the same ruling as the active tab."
+    }
+  ],
+  "todo": true
+}