@cueplusplus/ui 0.13.0

package/manifest/components/sidebar.json

@@ -0,0 +1,245 @@
+{
+  "name": "Sidebar",
+  "slug": "sidebar",
+  "group": "layout",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "The console's navigation column: sections of items, a scroller of its own,\nand a rail that collapses the whole thing to icons.",
+  "props": [],
+  "typeReferences": [],
+  "subcomponents": [
+    "Root",
+    "Section",
+    "Item",
+    "Rail"
+  ],
+  "parts": [
+    {
+      "name": "Root",
+      "usage": "Sidebar.Root",
+      "description": "The navigation column: a `<nav>` on a hairline, with a collapse valve and a\nscroller of its own.\n\nWidth is an inline length rather than a class, because it is the one piece of\nconsole geometry a user is expected to change and persist; the transition\nbetween the two widths is CSS and switches off under `prefers-reduced-motion`.\n\n**The column scrolls, the rail does not.** Thirty rows of navigation is an\nordinary amount for a documentation site or a settings screen, and a column\nthat cannot scroll simply loses the last of them off the bottom of the frame.\nSo the sections go in an inner scroller and the root keeps the height — which\nis also what saves {@link SidebarRail}: it is `absolute inset-y-0`, its\ncontaining block is the root rather than the scroller, and an absolutely\npositioned box whose containing block is outside a scroll container neither\nscrolls with it nor is clipped by it. Put the scroller on the root instead\nand the collapse rail slides away with the third screenful.",
+      "props": [
+        {
+          "name": "landmark",
+          "type": "\"complementary\" | \"navigation\"",
+          "required": false,
+          "defaultValue": "navigation",
+          "description": "Which landmark the column is. Defaults to `\"navigation\"`, rendering\n`<nav>`; `\"complementary\"` renders `<aside>` instead.\n\nA column of `Sidebar.Item`s is a list of destinations, one of which carries\n`aria-current=\"page\"` — that is primary navigation, and announcing it as\ncomplementary tells a screen-reader user the site's main map is an aside.\n`\"complementary\"` is there for the column that genuinely is one: a filter\nrail, an inspector, a related-links strip.",
+          "control": {
+            "kind": "enum",
+            "members": [
+              "complementary",
+              "navigation"
+            ]
+          }
+        },
+        {
+          "name": "collapsed",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": null,
+          "description": "Collapsed state when controlled. Pass with `onCollapsedChange`.",
+          "control": {
+            "kind": "boolean"
+          }
+        },
+        {
+          "name": "defaultCollapsed",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "false",
+          "description": "Initial collapsed state when uncontrolled. Defaults to `false`.",
+          "control": {
+            "kind": "boolean"
+          }
+        },
+        {
+          "name": "onCollapsedChange",
+          "type": "((collapsed: boolean) => void)",
+          "required": false,
+          "defaultValue": null,
+          "description": "Called with the new collapsed state whenever the rail is pressed.",
+          "control": {
+            "kind": "callback",
+            "fixture": "callback.log"
+          }
+        },
+        {
+          "name": "width",
+          "type": "string",
+          "required": false,
+          "defaultValue": "14rem",
+          "description": "Width while expanded. Any CSS length. Defaults to `\"14rem\"`.",
+          "control": {
+            "kind": "string"
+          }
+        },
+        {
+          "name": "collapsedWidth",
+          "type": "string",
+          "required": false,
+          "defaultValue": "3rem",
+          "description": "Width while collapsed. Any CSS length. Defaults to `\"3rem\"`.",
+          "control": {
+            "kind": "string"
+          }
+        }
+      ],
+      "typeReferences": [
+        "React.ComponentPropsWithoutRef<\"aside\">"
+      ]
+    },
+    {
+      "name": "Section",
+      "usage": "Sidebar.Section",
+      "description": "One group of items, under an optional caption.",
+      "props": [
+        {
+          "name": "label",
+          "type": "ReactNode",
+          "required": false,
+          "defaultValue": null,
+          "description": "The group caption, in the mono micro idiom. Dropped entirely while the\nsidebar is collapsed — at rail width a caption has nothing left to caption.",
+          "control": {
+            "kind": "node",
+            "fixture": "children.text"
+          }
+        }
+      ],
+      "typeReferences": [
+        "React.ComponentPropsWithoutRef<\"div\">"
+      ]
+    },
+    {
+      "name": "Item",
+      "usage": "Sidebar.Item",
+      "description": "One navigation destination.\n\nActive is a tint (`accent-soft` ground, accent ink), not a solid fill: a\nfilled accent bar in a column of eight items reads as a button someone left\npressed. Same ruling as the segmented control and the active tab.\n\nWhile collapsed the label goes `sr-only` rather than being unmounted — it is\nthe item's accessible name, and an icon-only button with no name is a\nWCAG 4.1.2 failure.",
+      "props": [
+        {
+          "name": "icon",
+          "type": "ElementType<any, keyof IntrinsicElements>",
+          "required": false,
+          "defaultValue": null,
+          "description": "Optional leading icon component (e.g. a lucide icon), drawn `aria-hidden`.",
+          "control": {
+            "kind": "opaque",
+            "fixture": "icon.play"
+          }
+        },
+        {
+          "name": "active",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "false",
+          "description": "Mark this item as the current destination.",
+          "control": {
+            "kind": "boolean"
+          }
+        },
+        {
+          "name": "badge",
+          "type": "ReactNode",
+          "required": false,
+          "defaultValue": null,
+          "description": "Trailing slot: a count, a status dot. Hidden while collapsed.",
+          "control": {
+            "kind": "node",
+            "fixture": "children.text"
+          }
+        },
+        {
+          "name": "render",
+          "type": "RenderProp<Record<string, unknown>>",
+          "required": false,
+          "defaultValue": null,
+          "description": "Replace the rendered element (Base UI render prop) — normally a router\nlink: `render={<NextLink href=\"/patch\" />}`.",
+          "control": {
+            "kind": "opaque"
+          }
+        }
+      ],
+      "typeReferences": [
+        "React.ComponentPropsWithoutRef<\"button\">"
+      ]
+    },
+    {
+      "name": "Rail",
+      "usage": "Sidebar.Rail",
+      "description": "The hairline-wide hit strip along the sidebar's edge that toggles it.\n\nA 4px target straddling the rim, invisible until hovered — the collapse\ncontrol should cost no chrome, because a dedicated button for it is a\npermanent 24px reminder of a thing most people set once.\n\nPass it as a child of {@link SidebarRoot} like any other. It is `absolute`\nagainst the root rather than against the root's inner scroller, so it spans\nthe whole column and holds its edge however far the sections are scrolled.",
+      "props": [
+        {
+          "name": "collapseLabel",
+          "type": "string",
+          "required": false,
+          "defaultValue": "Collapse sidebar",
+          "description": "Accessible name while expanded. Defaults to `\"Collapse sidebar\"`.",
+          "control": {
+            "kind": "string"
+          }
+        },
+        {
+          "name": "expandLabel",
+          "type": "string",
+          "required": false,
+          "defaultValue": "Expand sidebar",
+          "description": "Accessible name while collapsed. Defaults to `\"Expand sidebar\"`.",
+          "control": {
+            "kind": "string"
+          }
+        }
+      ],
+      "typeReferences": [
+        "Omit<React.ComponentPropsWithoutRef<\"button\">, \"children\">"
+      ]
+    }
+  ],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-soft",
+    "--cue-border",
+    "--cue-control-md",
+    "--cue-control-sm",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-icon-md",
+    "--cue-radius-control",
+    "--cue-space-1",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-space-4",
+    "--cue-surface-1",
+    "--cue-surface-2",
+    "--cue-text-label",
+    "--cue-text-ui"
+  ],
+  "summary": "The console's navigation column: sections of items, a scroller of its own, and a rail that collapses the whole thing to icons.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Sidebar.Root defaultCollapsed aria-label=\"Main\">\n  <Sidebar.Section label=\"Console\">\n    <Sidebar.Item render={<NextLink href=\"/patch\" />} active>Patch</Sidebar.Item>\n  </Sidebar.Section>\n  <Sidebar.Rail />\n</Sidebar.Root>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/sidebar",
+  "mdUrl": "/docs/components/sidebar.md",
+  "jsonUrl": "/r/components/sidebar.json",
+  "specimens": [
+    {
+      "title": "Sidebar",
+      "group": "layout",
+      "components": [
+        "Sidebar"
+      ],
+      "code": "<div className=\"flex h-[14rem] w-full max-w-[36rem] overflow-hidden rounded-(--radius-surface) border border-border\">\n  <Sidebar.Root aria-label=\"Console sections\">\n    <Sidebar.Section label=\"Console\">\n      <Sidebar.Item icon={Sliders} active>\n        Patch\n      </Sidebar.Item>\n      <Sidebar.Item icon={List} badge={<Chip tone=\"accent\">12</Chip>}>\n        Cues\n      </Sidebar.Item>\n      <Sidebar.Item icon={Settings}>Setup</Sidebar.Item>\n    </Sidebar.Section>\n    <Sidebar.Rail />\n  </Sidebar.Root>\n  <div className=\"flex-1 p-(--cue-space-5) font-mono text-(length:--cue-text-ui) text-fg-muted\">\n    Content beside the column.\n  </div>\n</div>",
+      "note": "Sections of items and a 4px rail that collapses the column to icons. The label goes `sr-only` while collapsed rather than being unmounted, because an icon-only button with no name is a WCAG 4.1.2 failure.",
+      "interaction": "the rail is invisible until hovered, and is a real button with an `aria-expanded` state."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/signal-edge.json

@@ -0,0 +1,56 @@
+{
+  "name": "SignalEdge",
+  "slug": "signal-edge",
+  "group": "flow",
+  "importPath": "@cueplusplus/ui/flow",
+  "peerDependencies": [
+    "@xyflow/react"
+  ],
+  "clientOnly": false,
+  "description": "A wire between two nodes, drawn as three paths.\n\n1. **The wire.** A bezier in the tone's colour, thin and half-lit at rest.\n2. **The hit path.** Sixteen invisible pixels of it, because nobody can click\n   1.6px. `BaseEdge` draws this one, and the edge label, for free.\n3. **The pulse.** Only while `data.live` — a pale dashed overlay of the same\n   colour, marching along the wire. This is the only animation in the group,\n   it carries no information the opacity does not, and `flow.css` stops it\n   dead under `prefers-reduced-motion`.\n\nState is read from props rather than from a store on purpose: an edge that\nsubscribed to \"is this route live\" would re-render on every frame of a 40Hz\ntelemetry feed, times the number of edges. The host decides when the answer\nchanged; this component only draws it. It also means the component is a pure\nfunction of its props — no hooks, no context, no canvas needed to test it.\n\nSelection outranks everything, including the pulse: two loud treatments on one\nwire read as neither.",
+  "props": [],
+  "typeReferences": [
+    "EdgeProps<SignalEdgeType>"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-busy",
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-fg-subtle",
+    "--cue-info",
+    "--cue-ok",
+    "--cue-warn"
+  ],
+  "summary": "A wire between two nodes, drawn as three paths.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "const edges = [{ id: \"r1\", source: \"s1\", target: \"m1\", type: \"signal\", data: { live: true } }];\n<ReactFlow edges={edges} edgeTypes={theme.edgeTypes} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/signal-edge",
+  "mdUrl": "/docs/components/signal-edge.md",
+  "jsonUrl": "/r/components/signal-edge.json",
+  "specimens": [
+    {
+      "title": "useFlowTheme / FlowControls / FlowBackground / SignalEdge",
+      "group": "flow",
+      "components": [
+        "FlowControls",
+        "FlowBackground",
+        "SignalEdge"
+      ],
+      "code": "<div className=\"h-[24rem] w-full overflow-hidden rounded-(--radius-surface) border border-border\">\n  <ReactFlow\n    nodes={NODES}\n    edges={EDGES}\n    nodeTypes={NODE_TYPES}\n    edgeTypes={theme.edgeTypes}\n    defaultEdgeOptions={theme.defaultEdgeOptions}\n    colorMode={theme.colorMode}\n    style={theme.style}\n    fitView\n    proOptions={{ hideAttribution: true }}\n  >\n    <FlowBackground />\n    <FlowControls />\n  </ReactFlow>\n</div>",
+      "note": "The hook returns the `--xy-*` token map plus stable `edgeTypes` and `defaultEdgeOptions` identities. Every part also publishes the map on its own root, so the group is correct before flow.css is imported and correct again after.",
+      "interaction": "the controls capsule is an overlay surface; a live wire animates its dash overlay and stops under prefers-reduced-motion."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/skeleton.json

@@ -0,0 +1,46 @@
+{
+  "name": "Skeleton",
+  "slug": "skeleton",
+  "group": "primitives",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "A loading placeholder block.\n\nCarries no intrinsic size — give it one with `className` (`h-4 w-24`) so the\nskeleton matches the shape of whatever is arriving. `aria-hidden` by default:\na screen reader should hear the surrounding live region say \"loading\", not a\nfleet of empty boxes. The pulse stills under `prefers-reduced-motion`.\n\nStatic markup — no `\"use client\"`.",
+  "props": [],
+  "typeReferences": [
+    "React.ComponentPropsWithoutRef<\"div\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-radius-control",
+    "--cue-surface-2"
+  ],
+  "summary": "A loading placeholder block.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Skeleton className=\"h-4 w-32\" />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/skeleton",
+  "mdUrl": "/docs/components/skeleton.md",
+  "jsonUrl": "/r/components/skeleton.json",
+  "specimens": [
+    {
+      "title": "Skeleton",
+      "group": "primitives",
+      "components": [
+        "Skeleton"
+      ],
+      "code": "<div className=\"flex w-full max-w-[28rem] flex-col gap-(--cue-space-3)\">\n  <Skeleton className=\"h-4 w-[12rem]\" />\n  <Skeleton className=\"h-4 w-[20rem]\" />\n  <Skeleton className=\"h-4 w-[16rem]\" />\n  <div className=\"flex items-center gap-(--cue-space-3)\">\n    <Skeleton className=\"size-8 rounded-full\" />\n    <Skeleton className=\"h-4 flex-1\" />\n    <Chip tone=\"busy\" variant=\"outline\">\n      <Copy aria-hidden=\"true\" className=\"size-icon-sm\" /> loading\n    </Chip>\n  </div>\n</div>",
+      "note": "The shape of content that has not arrived. Sized by the caller, because only the caller knows the shape.",
+      "interaction": "the shimmer stills under prefers-reduced-motion."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/skill-icon.json

@@ -0,0 +1,46 @@
+{
+  "name": "SkillIcon",
+  "slug": "skill-icon",
+  "group": "icons",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "A skill: the thing every other container in this set holds.\n\nOne mark, and a spark rather than a document, because what is being filed is\na capability. The file it happens to be written in is an implementation\ndetail of how it travels, and a page glyph would have made the catalogue look\nlike a folder of documents rather than a list of things an agent can now do.",
+  "props": [],
+  "typeReferences": [
+    "React.SVGProps<SVGSVGElement>"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [],
+  "summary": "A skill: the thing every other container in this set holds.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/skill-icon",
+  "mdUrl": "/docs/components/skill-icon.md",
+  "jsonUrl": "/r/components/skill-icon.json",
+  "specimens": [
+    {
+      "title": "The container icon set",
+      "group": "icons",
+      "components": [
+        "CatalogueIcon",
+        "StackIcon",
+        "StacksMatrixIcon",
+        "AudienceIcon",
+        "ChannelReleasedIcon",
+        "ChannelBetaIcon",
+        "FolderIcon",
+        "McpServerIcon",
+        "CliToolIcon",
+        "SkillIcon"
+      ],
+      "code": "<Specimens>\n  {CONTAINERS.map(([label, name, Icon]) => (\n    <Specimen key={name} label={label}>\n      <Icon className=\"size-icon-md text-fg\" />\n    </Specimen>\n  ))}\n</Specimens>\n<Specimens>\n  <Specimen label=\"icon-sm\">\n    <SkillIcon className=\"size-icon-sm text-fg\" />\n  </Specimen>\n  <Specimen label=\"icon-md\">\n    <SkillIcon className=\"size-icon-md text-fg\" />\n  </Specimen>\n  <Specimen label=\"inherited\">\n    <SkillIcon className=\"size-icon-md\" />\n  </Specimen>\n  <Specimen label=\"muted\">\n    <SkillIcon className=\"size-icon-md text-fg-muted\" />\n  </Specimen>\n  <Specimen label=\"accent\">\n    <SkillIcon className=\"size-icon-md text-accent\" />\n  </Specimen>\n  <Specimen label=\"danger\">\n    <SkillIcon className=\"size-icon-md text-danger\" />\n  </Specimen>\n</Specimens>\n<Specimens>\n  <Specimen label=\"in a row\" wide>\n    <span className=\"inline-flex items-center gap-(--cue-space-2) font-mono text-(length:--cue-text-ui) text-fg-muted\">\n      <ChannelReleasedIcon className=\"size-icon-md shrink-0\" />\n      Our skills · released\n    </span>\n  </Specimen>\n  <Specimen label=\"current row\" wide>\n    <span className=\"inline-flex items-center gap-(--cue-space-2) font-mono text-(length:--cue-text-ui) text-fg\">\n      <ChannelBetaIcon className=\"size-icon-md shrink-0\" />\n      Our skills · beta\n    </span>\n  </Specimen>\n</Specimens>",
+      "note": "One grid and one weight across all ten, at size-icon-md — the size a navigation row draws them at. Each is a plain <svg> that takes every SVG prop.",
+      "interaction": "none. They are decorative by default: aria-hidden, announced by nothing, because the row they mark already carries its name."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/slider.json

@@ -0,0 +1,106 @@
+{
+  "name": "Slider",
+  "slug": "slider",
+  "group": "forms",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A continuous value control: one thumb, or several for a range.\n\nDrawn as a 2px rail rather than the chunky default — at console density a\nslider is a readout first and a grab target second, and the thumb supplies the\naffordance. The filled portion uses the theme accent so the slider agrees with\nevery other \"this much\" indicator on screen.\n\nThe important part of the API is {@link SliderProps.onCommit}: the\nchange/commit split is what lets a host app coalesce a whole drag into one\nundo entry instead of hundreds.",
+  "props": [
+    {
+      "name": "label",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "Visible label above the track.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes, merged over the root defaults.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "aria-label",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Accessible name for the thumb. With several thumbs each is suffixed with its\n1-based index, so a range slider announces \"Window 1\" and \"Window 2\".",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "onCommit",
+      "type": "((value: number | number[]) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Fired once when a gesture *ends*: pointer-up after a drag, key-up after a\nstep, or a track press. `onValueChange` fires on every intermediate value —\na drag emits dozens — so an undo stack, a network write or a persisted\nsetting must hang off this, not off `onValueChange`, or it will record every\nframe of the drag as a separate edit.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    },
+    {
+      "name": "showValue",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Show the live formatted value opposite the label.",
+      "control": {
+        "kind": "boolean"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<BaseSlider.Root.Props, \"className\" | \"onValueCommitted\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-border",
+    "--cue-control-sm",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-font-mono",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-text-label"
+  ],
+  "summary": "A continuous value control: one thumb, or several for a range.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Slider aria-label=\"Intensity\" value={level} onValueChange={setLevel} onCommit={pushUndo} />\n<Slider label=\"Window\" showValue defaultValue={[20, 60]} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/slider",
+  "mdUrl": "/docs/components/slider.md",
+  "jsonUrl": "/r/components/slider.json",
+  "specimens": [
+    {
+      "title": "Slider / RangeSlider",
+      "group": "forms",
+      "components": [
+        "Slider"
+      ],
+      "code": "<div className=\"grid w-full gap-(--cue-space-6) lg:grid-cols-2\">\n  <Slider aria-label=\"Master level\" defaultValue={62} label=\"Master\" showValue />\n  <Slider\n    aria-label=\"Level window\"\n    defaultValue={[20, 80]}\n    label=\"Level window\"\n    showValue\n  />\n  <Slider aria-label=\"Locked level\" defaultValue={40} label=\"Locked\" disabled showValue />\n  <Slider aria-label=\"Stepped level\" defaultValue={50} step={10} label=\"Steps of 10\" showValue />\n</div>",
+      "note": "One thumb or two. `onCommit` fires once at the end of a drag, which is the undo-coalescing contract the consoles need.",
+      "interaction": "the thumb grows while dragging; arrow keys step, Page Up and Page Down jump."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/sources.json

@@ -0,0 +1,97 @@
+{
+  "name": "Sources",
+  "slug": "sources",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "Citations collapsed into a pill, expanding into scannable source cards.",
+  "props": [
+    {
+      "name": "sources",
+      "type": "readonly Source[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Citation cards revealed when the sources pill expands.",
+      "control": {
+        "kind": "array",
+        "fixture": "knowledge.sources"
+      }
+    },
+    {
+      "name": "open",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "Whether the source list is expanded under the pill.",
+      "control": {
+        "kind": "boolean"
+      }
+    },
+    {
+      "name": "onOpenChange",
+      "type": "(open: boolean) => void",
+      "required": true,
+      "defaultValue": null,
+      "description": "Called when the user expands or collapses the sources.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes merged onto the root.",
+      "control": {
+        "kind": "string"
+      }
+    }
+  ],
+  "typeReferences": [],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-radius-control",
+    "--cue-radius-overlay",
+    "--cue-surface-2",
+    "--cue-text-body",
+    "--cue-text-micro",
+    "--cue-text-ui"
+  ],
+  "summary": "Citations collapsed into a pill, expanding into scannable source cards.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { Sources } from \"@cueplusplus/ui/elements\";\n\n<Sources\n  sources={[{ domain: \"docs.example.com\", title: \"Composer guide\" }]}\n  open\n  onOpenChange={setOpen}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/sources",
+  "mdUrl": "/docs/components/sources.md",
+  "jsonUrl": "/r/components/sources.json",
+  "specimens": [
+    {
+      "title": "Sources",
+      "group": "elements-knowledge",
+      "components": [
+        "Sources"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"open\" wide>\n    <Sources sources={SOURCES} open={sourcesOpen} onOpenChange={setSourcesOpen} />\n  </Specimen>\n  <Specimen label=\"collapsed\" wide>\n    <Sources sources={SOURCES} open={false} onOpenChange={() => undefined} />\n  </Specimen>\n</Specimens>",
+      "note": "Citations folded into a pill until somebody wants them. Collapsed it is a count — four sources, no argument; open it is a scannable grid of cards, one per site, each lifting a pixel under the pointer. The count is the whole affordance: it says provenance exists without spending a paragraph on it.",
+      "interaction": "the pill is the trigger and takes cue's focus ring; the chevron turns with the panel, which animates its own height through Base UI rather than a max-height guess."
+    }
+  ],
+  "todo": true
+}