@cueplusplus/ui 0.13.0

package/manifest/components/delegation-card.json

@@ -0,0 +1,196 @@
+{
+  "name": "DelegationCard",
+  "slug": "delegation-card",
+  "group": "chat",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "One delegation, folded into a card.\n\nA multi-agent run is a tree, and rendering it flat is what turns a transcript\ninto noise: the reader loses which turns belong to which sub-agent and how\ndeep they are. This is the fold — a one-line header naming who was asked and\nwhat for, a live status line under it, and the sub-agent's own transcript\nbehind a disclosure, railed in that agent's colour so nesting is legible at a\nglance.\n\nThe body is mounted and unmounted rather than height-animated. A delegation's\ntranscript grows while it is open, and animating the height of something that\nchanges size on its own is how a panel ends up permanently mid-transition.\n\nDirection matters to the sentence. From the caller's lane the card reads\n\"asked researcher — …\"; in the delegate's own lane it reads \"chief asked\n— …\", which is the same fact from the other side.",
+  "props": [
+    {
+      "name": "agent",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Slug of the agent on the other end of the delegation.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "rootAgent",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Slug of the orchestrator, so its lane takes the theme accent.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "direction",
+      "type": "\"outbound\" | \"inbound\"",
+      "required": false,
+      "defaultValue": "outbound",
+      "description": "`outbound` (we asked them) or `inbound` (they asked us). Defaults to `\"outbound\"`.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "outbound",
+          "inbound"
+        ]
+      }
+    },
+    {
+      "name": "task",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "What the delegate was asked to do — one line, already summarised.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    },
+    {
+      "name": "status",
+      "type": "\"done\" | \"working\" | \"failed\" | \"idle\"",
+      "required": false,
+      "defaultValue": null,
+      "description": "Where the work has got to. Omit to draw no status line at all.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "done",
+          "working",
+          "failed",
+          "idle"
+        ]
+      }
+    },
+    {
+      "name": "activity",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "What the delegate is doing right now. Shown beside the spinner while `working`.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    },
+    {
+      "name": "open",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": null,
+      "description": "Open state when controlled. Pass with `onOpenChange`.",
+      "control": {
+        "kind": "boolean"
+      }
+    },
+    {
+      "name": "defaultOpen",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": null,
+      "description": "Initial open state. Defaults to open for an inbound card, shut for an outbound one.",
+      "control": {
+        "kind": "boolean"
+      }
+    },
+    {
+      "name": "onOpenChange",
+      "type": "((open: boolean) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with the state the card is asking to move to.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    },
+    {
+      "name": "doneLabel",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": "Completed",
+      "description": "What a finished delegation says. Defaults to `\"Completed\"`.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    },
+    {
+      "name": "failedLabel",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": "Failed",
+      "description": "What a failed delegation says. Defaults to `\"Failed\"`.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    },
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "The nested transcript.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"title\" | \"onToggle\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-border",
+    "--cue-danger",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-icon-sm",
+    "--cue-ok",
+    "--cue-radius-control",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-space-4",
+    "--cue-space-5",
+    "--cue-text-micro",
+    "--cue-text-ui"
+  ],
+  "summary": "One delegation, folded into a card.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<DelegationCard agent=\"researcher\" task=\"find three references\" status=\"working\">\n  {turns}\n</DelegationCard>\n<DelegationCard agent=\"chief\" direction=\"inbound\" task=\"draft the brief\">{turns}</DelegationCard>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/delegation-card",
+  "mdUrl": "/docs/components/delegation-card.md",
+  "jsonUrl": "/r/components/delegation-card.json",
+  "specimens": [
+    {
+      "title": "DelegationCard",
+      "group": "chat",
+      "components": [
+        "DelegationCard"
+      ],
+      "code": "<div className=\"grid w-full gap-(--cue-space-5) lg:grid-cols-2\">\n  <DelegationCard\n    agent=\"patcher\"\n    rootAgent=\"orchestrator\"\n    task=\"Patch the front truss\"\n    status=\"working\"\n    activity=\"Resolving GDTF profiles\"\n    defaultOpen\n  >\n    <Message role=\"agent\" agent=\"patcher\" author=\"Patcher\">\n      6 fixtures matched to Source Four 26°.\n    </Message>\n  </DelegationCard>\n  <DelegationCard\n    agent=\"reviewer\"\n    direction=\"inbound\"\n    task=\"Check the patch against the plot\"\n    status=\"done\"\n  >\n    <Message role=\"agent\" agent=\"reviewer\" author=\"Reviewer\">\n      No conflicts.\n    </Message>\n  </DelegationCard>\n  <DelegationCard agent=\"renderer\" task=\"Render the preview\" status=\"failed\" />\n  <DelegationCard agent=\"archivist\" task=\"Capture universes\" status=\"idle\" />\n</div>",
+      "note": "A nested transcript with a per-agent left rail in that agent's colour. Collapsible, because a delegation is usually a detail.",
+      "interaction": "the header row is the toggle; the status is spelled out as well as tinted."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/density.json

@@ -0,0 +1,93 @@
+{
+  "name": "Density",
+  "slug": "density",
+  "group": "system",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "Re-scope any subtree to a different density level.\n\nRenders a plain `<div data-density=\"…\" data-cue-theme=\"…\">`: the geometry\ncustom properties are re-declared by the attribute selector and inherit\ndown, so nesting is free and needs no JS. The matching React context is\npublished alongside for the rare JS reads (`useDensity()`,\n`useControlHeight()`, portal stamping) — the DOM attributes, not the\ncontext, are what actually restyle the tree.\n\n`data-cue-theme` carries the nearest `<ThemeProvider>`'s name, or is\nomitted where there is none. It is read by nothing this island does —\ntheme and mode are deliberately *not* re-scoped here; density was for a long\ntime the only axis an island could override (spec §6), and a named\n`styleSet` is the second and last — it exists so a theme's own\ngenerated CSS can address exactly this island regardless of how many\n*other* themed providers sit between it and the one it belongs to. A CSS\nancestor selector can only ask \"does some ancestor carry theme `x`\", never\n\"is `x` the *nearest* one\"; this stamp answers that question the way\n`useContext` already does, at render time, and hands the answer to CSS as\nan attribute rather than leaving it unanswerable there.\n\n`data-style` joins them when — and only when — a `styleSet` is named. Absence\nis how the axis inherits: custom properties inherit down the DOM, so an island\nthat stamped the ambient set would be restating an answer it already had, and\nan island that stamped a *default* set would silently re-point the rhythm of\nevery page that nested one.",
+  "props": [
+    {
+      "name": "density",
+      "type": "\"normal\" | \"large\" | \"compact\" | \"ultra-compact\" | \"ultra-large\"",
+      "required": true,
+      "defaultValue": null,
+      "description": "Level to apply to this subtree: `ultra-compact`, `compact`, `normal`,\n`large` or `ultra-large`.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "normal",
+          "large",
+          "compact",
+          "ultra-compact",
+          "ultra-large"
+        ]
+      }
+    },
+    {
+      "name": "styleSet",
+      "type": "\"console\" | \"editorial\" | \"marketing\"",
+      "required": false,
+      "defaultValue": null,
+      "description": "A style set for this subtree: `console`, `editorial` or `marketing`.\n\nOptional, and **absent means inherit** — an island that names none stamps no\n`data-style` and passes the ambient set straight through, exactly as a bare\n`<Density>` does today. Naming one is what makes this the library's island\nform of the fourth axis, and there are two reasons to reach for it:\n\n- `console` inside a page that is not console. That is the whole job of the\n  default set: it restates the `:root` defaults, so a subtree stamped with\n  it renders the ordinary look inside an editorial or marketing page.\n- Moving the band rhythm with the rung. `--cue-band-y` is\n  `calc(var(--cue-space-7) * 2)` declared on the `[data-style]` element, and\n  a custom property's `var()` references are substituted where they are\n  declared — so a nested density island moves `--cue-space-*` but inherits\n  the rhythm already resolved above it. Restating the set here re-resolves\n  it against this island's rung, which is how a denser island gets a\n  proportionally tighter band instead of the outer one's.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "console",
+          "editorial",
+          "marketing"
+        ]
+      }
+    },
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": true,
+      "defaultValue": null,
+      "description": "Subtree that should render at `density`.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes for the island element. It is an ordinary `<div>` — style it like one.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "style",
+      "type": "CSSProperties",
+      "required": false,
+      "defaultValue": null,
+      "description": "Inline styles for the island element.",
+      "control": {
+        "kind": "opaque"
+      }
+    }
+  ],
+  "typeReferences": [],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [],
+  "summary": "Re-scope any subtree to a different density level.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Density density=\"ultra-compact\">\n  <Toolbar />\n</Density>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/density",
+  "mdUrl": "/docs/components/density.md",
+  "jsonUrl": "/r/components/density.json",
+  "todo": true
+}

package/manifest/components/description-list.json

@@ -0,0 +1,91 @@
+{
+  "name": "DescriptionList",
+  "slug": "description-list",
+  "group": "layout",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "The `<dl>` family: {@link DescriptionListRoot}, `Term` and `Detail`.",
+  "props": [],
+  "typeReferences": [],
+  "subcomponents": [
+    "Root",
+    "Term",
+    "Detail"
+  ],
+  "parts": [
+    {
+      "name": "Root",
+      "usage": "DescriptionList.Root",
+      "description": "A key/value block: the honest `<dl>`, styled for a console.\n\nTerms are set in the mono micro caption idiom shared with `SectionHeader` and\nmenu group labels, so a metadata block reads as annotation rather than as\ncompeting body text.\n\nStatic markup — no `\"use client\"`.",
+      "props": [
+        {
+          "name": "layout",
+          "type": "\"inline\" | \"stacked\"",
+          "required": false,
+          "defaultValue": "inline",
+          "description": "`\"inline\"` (default) puts the detail beside its term in a two-column grid;\n`\"stacked\"` puts it underneath. Stack when the details are long enough to\nwrap, which turns the aligned column into ragged text anyway.",
+          "control": {
+            "kind": "enum",
+            "members": [
+              "inline",
+              "stacked"
+            ]
+          }
+        }
+      ],
+      "typeReferences": [
+        "React.ComponentPropsWithoutRef<\"dl\">"
+      ]
+    },
+    {
+      "name": "Term",
+      "usage": "DescriptionList.Term",
+      "description": "One key. Mono, uppercase, widely tracked — annotation, not body text.",
+      "props": [],
+      "typeReferences": [
+        "React.ComponentPropsWithoutRef<\"dt\">"
+      ]
+    },
+    {
+      "name": "Detail",
+      "usage": "DescriptionList.Detail",
+      "description": "One value. `m-0` resets the browser's inherited `<dd>` indent, which would\notherwise push every detail 40px right of the grid column it belongs to.",
+      "props": [],
+      "typeReferences": [
+        "React.ComponentPropsWithoutRef<\"dd\">"
+      ]
+    }
+  ],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-fg",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-space-5",
+    "--cue-text-label",
+    "--cue-text-ui"
+  ],
+  "summary": "The `<dl>` family: {@link DescriptionListRoot}, `Term` and `Detail`.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/description-list",
+  "mdUrl": "/docs/components/description-list.md",
+  "jsonUrl": "/r/components/description-list.json",
+  "specimens": [
+    {
+      "title": "DescriptionList",
+      "group": "layout",
+      "components": [
+        "DescriptionList"
+      ],
+      "code": "<div className=\"grid w-full gap-(--cue-space-5) lg:grid-cols-2\">\n  <Panel className=\"p-(--cue-space-5)\">\n    <DescriptionList.Root>\n      <DescriptionList.Term>Protocol</DescriptionList.Term>\n      <DescriptionList.Detail>Art-Net</DescriptionList.Detail>\n      <DescriptionList.Term>Host</DescriptionList.Term>\n      <DescriptionList.Detail>10.0.0.42</DescriptionList.Detail>\n      <DescriptionList.Term>Rate</DescriptionList.Term>\n      <DescriptionList.Detail>\n        <span className=\"flex items-center gap-(--cue-space-2)\">\n          44 Hz <StatusDot tone=\"ok\" label=\"Nominal\" />\n        </span>\n      </DescriptionList.Detail>\n    </DescriptionList.Root>\n  </Panel>\n  <Panel className=\"p-(--cue-space-5)\">\n    <DescriptionList.Root layout=\"stacked\">\n      <DescriptionList.Term>Protocol</DescriptionList.Term>\n      <DescriptionList.Detail>Art-Net</DescriptionList.Detail>\n      <DescriptionList.Term>Host</DescriptionList.Term>\n      <DescriptionList.Detail>10.0.0.42</DescriptionList.Detail>\n    </DescriptionList.Root>\n  </Panel>\n</div>",
+      "note": "Two layouts: inline pairs for a sidebar, stacked for a page.",
+      "interaction": "none."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/diagram.json

@@ -0,0 +1,126 @@
+{
+  "name": "Diagram",
+  "slug": "diagram",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "A drawn answer with zoom, reset, and a full-bleed view; you hand it the rendered\ngraphic.",
+  "props": [
+    {
+      "name": "title",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "What the diagram shows.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "zoom",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "Scale factor applied to the content. 1 is fit; the header prints it as a percentage.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": true,
+      "defaultValue": null,
+      "description": "The rendered graphic. The element owns the frame and never parses or injects\nmarkup itself, so whatever renders your chart stays your choice.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    },
+    {
+      "name": "onZoomIn",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called from the zoom-in control. Clamp the range yourself.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    },
+    {
+      "name": "onZoomOut",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called from the zoom-out control.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    },
+    {
+      "name": "onReset",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called to return to the default view.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    },
+    {
+      "name": "onExpand",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called to open the diagram full screen.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  | \"title\"\n  | \"zoom\"\n  | \"children\"\n  | \"onZoomIn\"\n  | \"onZoomOut\"\n  | \"onReset\"\n  | \"onExpand\"\n> & {\n  /** What the diagram shows. */\n  title: string;\n  /** Scale factor applied to the content. 1 is fit; the header prints it as a percentage. */\n  zoom: number;\n  /**\n   * The rendered graphic. The element owns the frame and never parses or injects\n   * markup itself, so whatever renders your chart stays your choice.\n   */\n  children: React.ReactNode;\n  /** Called from the zoom-in control. Clamp the range yourself. */\n  onZoomIn?: () => void;\n  /** Called from the zoom-out control. */\n  onZoomOut?: () => void;\n  /** Called to return to the default view. */\n  onReset?: () => void;\n  /** Called to open the diagram full screen. */\n  onExpand?: () => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-border",
+    "--cue-fg-subtle",
+    "--cue-radius-overlay",
+    "--cue-text-body"
+  ],
+  "summary": "A drawn answer with zoom, reset, and a full-bleed view; you hand it the rendered graphic.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { Diagram } from \"@cueplusplus/ui/elements\";\n\n<Diagram title=\"message flow\" zoom={zoom} onZoomIn={zoomIn} onReset={reset}>\n  <MermaidSvg chart={chart} />\n</Diagram>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/diagram",
+  "mdUrl": "/docs/components/diagram.md",
+  "jsonUrl": "/r/components/diagram.json",
+  "specimens": [
+    {
+      "title": "Diagram",
+      "group": "elements-knowledge",
+      "components": [
+        "Diagram"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"the front truss, zoomable\" wide>\n    <Diagram\n      title=\"Front truss — 6 fixtures on 3.2 m centres\"\n      zoom={zoom}\n      onZoomIn={() => setZoom((current) => Math.min(1.6, current + 0.2))}\n      onZoomOut={() => setZoom((current) => Math.max(0.6, current - 0.2))}\n      onReset={() => setZoom(1)}\n    >\n      <svg\n        viewBox=\"0 0 200 60\"\n        width=\"200\"\n        height=\"60\"\n        role=\"img\"\n        aria-label=\"Six fixtures hung along one truss\"\n      >\n        <line x1=\"6\" y1=\"20\" x2=\"194\" y2=\"20\" className=\"stroke-fg-subtle\" strokeWidth=\"2\" />\n        {[16, 51, 86, 121, 156, 186].map((x) => (\n          <rect key={x} x={x - 6} y=\"26\" width=\"12\" height=\"16\" rx=\"2\" className=\"fill-stream\" />\n        ))}\n      </svg>\n    </Diagram>\n  </Specimen>\n  <Specimen label=\"zoomed out, nothing to expand to\" wide>\n    <Diagram title=\"Front truss\" zoom={0.7}>\n      <svg viewBox=\"0 0 200 40\" width=\"200\" height=\"40\" role=\"img\" aria-label=\"One truss\">\n        <line x1=\"6\" y1=\"20\" x2=\"194\" y2=\"20\" className=\"stroke-fg-subtle\" strokeWidth=\"2\" />\n      </svg>\n    </Diagram>\n  </Specimen>\n</Specimens>",
+      "note": "A drawn answer with a viewport around it: zoom, reset, full-bleed. The graphic is yours — the element supplies the frame, the percentage readout and the transform, and never parses or renders anything itself.",
+      "interaction": "four named icon buttons; expand disables itself when no handler is given, which is the honest state for a bench with nowhere to expand to. The scale transition stops under reduced motion."
+    }
+  ],
+  "todo": true
+}