@cueplusplus/ui 0.2.0 → 0.5.0

package/manifest/components/file-tree.json

@@ -0,0 +1,83 @@
+{
+  "name": "FileTree",
+  "slug": "file-tree",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "Everything a run touched, as a tree, with the churn spelled out per file.",
+  "props": [
+    {
+      "name": "nodes",
+      "type": "readonly FileTreeNode[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Flat list in display order. Nesting comes from each node's depth, not from\nchildren arrays."
+    },
+    {
+      "name": "visibleCount",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "How many nodes have landed. Raise it as the run touches more files."
+    },
+    {
+      "name": "totalAdditions",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "Added lines across the whole change."
+    },
+    {
+      "name": "totalDeletions",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "Removed lines across the whole change."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  \"children\" | \"nodes\" | \"visibleCount\" | \"totalAdditions\" | \"totalDeletions\"\n> & {\n  /**\n   * Flat list in display order. Nesting comes from each node's depth, not from\n   * children arrays.\n   */\n  nodes: readonly FileTreeNode[];\n  /** How many nodes have landed. Raise it as the run touches more files. */\n  visibleCount: number;\n  /** Added lines across the whole change. */\n  totalAdditions: number;\n  /** Removed lines across the whole change. */\n  totalDeletions: number;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-danger",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-ok",
+    "--cue-radius-overlay",
+    "--cue-radius-surface",
+    "--cue-surface-1",
+    "--cue-text-body"
+  ],
+  "summary": "Everything a run touched, as a tree, with the churn spelled out per file.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { FileTree } from \"@cueplusplus/ui/elements\";\n\n<FileTree\n  nodes={nodes}\n  visibleCount={nodes.length}\n  totalAdditions={78}\n  totalDeletions={9}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/file-tree",
+  "mdUrl": "/docs/components/file-tree.md",
+  "jsonUrl": "/r/components/file-tree.json",
+  "specimens": [
+    {
+      "title": "FileTree",
+      "group": "elements",
+      "components": [
+        "FileTree"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"mid-run\" wide>\n    <FileTree nodes={TOUCHED} visibleCount={3} totalAdditions={12} totalDeletions={4} />\n  </Specimen>\n  <Specimen label=\"complete\" wide>\n    <FileTree\n      nodes={TOUCHED}\n      visibleCount={TOUCHED.length}\n      totalAdditions={60}\n      totalDeletions={6}\n    />\n  </Specimen>\n</Specimens>",
+      "note": "Everything a run touched, with the churn per file. The list is flat and the nesting is `depth`, which is what lets a row appear the moment the agent reports it rather than after its folder is complete.",
+      "interaction": "rows highlight on hover to keep the eye on one line; nothing here is clickable, because the tree reports rather than navigates."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/file-upload.json

@@ -0,0 +1,159 @@
+{
+  "name": "FileUpload",
+  "slug": "file-upload",
+  "group": "forms",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A drop zone with a file list under it.\n\nThe zone is a real `<button>`, not a div with a drop handler: dropping is the\nmouse affordance, and pressing Enter on a focused button to open the file\ndialog is the keyboard one. A zone that only accepts drops is unusable\nwithout a pointer (WCAG 2.1.1), and it is the single most common defect in\nhand-rolled uploaders.\n\nState is the caller's. This component turns drops into `File[]` (plus\nreasoned rejections, via {@link partitionFiles}) and renders whatever rows it\nis handed — it never holds an upload queue, because the transport, the\nretries and the progress belong to the app.",
+  "props": [
+    {
+      "name": "label",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": "Drop files",
+      "description": "The zone's own copy, and its accessible name. Defaults to `\"Drop files\"`."
+    },
+    {
+      "name": "hint",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "A second line under the label — the rules, in plain words."
+    },
+    {
+      "name": "accept",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "`accept` string forwarded to the input and used for rejection."
+    },
+    {
+      "name": "multiple",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Allow more than one file per drop."
+    },
+    {
+      "name": "maxSize",
+      "type": "number",
+      "required": false,
+      "defaultValue": null,
+      "description": "Largest accepted file, in bytes."
+    },
+    {
+      "name": "maxFiles",
+      "type": "number",
+      "required": false,
+      "defaultValue": null,
+      "description": "How many files may be accepted per drop."
+    },
+    {
+      "name": "disabled",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Refuse drops and grey the zone out."
+    },
+    {
+      "name": "files",
+      "type": "readonly UploadFile[]",
+      "required": false,
+      "defaultValue": null,
+      "description": "Rows to render under the zone. The caller owns upload state."
+    },
+    {
+      "name": "onFilesAccepted",
+      "type": "((files: File[]) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with the files that passed the rules."
+    },
+    {
+      "name": "onFilesRejected",
+      "type": "((rejections: FileRejection[]) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with the files that did not, each with its reason."
+    },
+    {
+      "name": "onRemove",
+      "type": "((id: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with a row's `id` when its remove control is pressed."
+    },
+    {
+      "name": "removeLabel",
+      "type": "((file: UploadFile) => string)",
+      "required": false,
+      "defaultValue": "(file) => `Remove ${file.name}`",
+      "description": "Spoken name of a row's remove control. Defaults to `Remove <name>`."
+    },
+    {
+      "name": "zoneClassName",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes for the drop zone."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"onDrop\" | \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-soft",
+    "--cue-border",
+    "--cue-border-strong",
+    "--cue-control-sm",
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-icon-sm",
+    "--cue-ok",
+    "--cue-radius-control",
+    "--cue-space-1",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-space-4",
+    "--cue-space-5",
+    "--cue-sunken",
+    "--cue-surface-2",
+    "--cue-surface-3",
+    "--cue-text-label",
+    "--cue-text-ui"
+  ],
+  "summary": "A drop zone with a file list under it.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<FileUpload\n  label=\"Drop show files\"\n  hint=\"CSV or QLab bundle, up to 20 MB\"\n  accept=\".csv,.qlab\"\n  maxSize={20_000_000}\n  files={rows}\n  onFilesAccepted={enqueue}\n  onFilesRejected={explain}\n  onRemove={cancel}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/file-upload",
+  "mdUrl": "/docs/components/file-upload.md",
+  "jsonUrl": "/r/components/file-upload.json",
+  "specimens": [
+    {
+      "title": "FileUpload",
+      "group": "forms",
+      "components": [
+        "FileUpload"
+      ],
+      "code": "<div className=\"grid w-full gap-(--cue-space-5) lg:grid-cols-2\">\n  <FileUpload\n    label=\"Drop a show file\"\n    hint=\"One .cue file, up to 5 MB.\"\n    accept=\".cue\"\n    maxSize={5_000_000}\n    files={uploads.map((file) => ({ ...file, status: \"done\" as const, progress: 100 }))}\n    onRemove={(id) => setUploads((current) => current.filter((file) => file.id !== id))}\n  />\n  <FileUpload\n    label=\"Drop fixture profiles\"\n    hint=\"Several .gdtf files.\"\n    multiple\n    files={[\n      { id: \"a\", name: \"mac-viper.gdtf\", size: 240_000, status: \"uploading\", progress: 62 },\n      { id: \"b\", name: \"sharpy.gdtf\", size: 180_000, status: \"error\", error: \"Unsupported revision\" },\n    ]}\n  />\n</div>",
+      "note": "A drop zone that is also a button, so a keyboard can reach it. Rejections say which rule they broke.",
+      "interaction": "the zone lights on drag-over; Enter or Space opens the file dialog."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/flow-background.json

@@ -0,0 +1,50 @@
+{
+  "name": "FlowBackground",
+  "slug": "flow-background",
+  "group": "flow",
+  "importPath": "@cueplusplus/ui/flow",
+  "peerDependencies": [
+    "@xyflow/react"
+  ],
+  "clientOnly": true,
+  "description": "The canvas grid: dots one rung off the ground, at the system's own spacing.\n\nLeave `color` unset. It writes `--xy-background-pattern-color-props`, which\noutranks the theme map — passing a colour is how you opt *out* of theming, not\nhow you theme it.",
+  "props": [],
+  "typeReferences": [
+    "React.ComponentProps<typeof Background>"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-border-overlay",
+    "--cue-radius-overlay"
+  ],
+  "summary": "The canvas grid: dots one rung off the ground, at the system's own spacing.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<ReactFlow …><FlowBackground /></ReactFlow>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/flow-background",
+  "mdUrl": "/docs/components/flow-background.md",
+  "jsonUrl": "/r/components/flow-background.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/flow-controls.json

@@ -0,0 +1,50 @@
+{
+  "name": "FlowControls",
+  "slug": "flow-controls",
+  "group": "flow",
+  "importPath": "@cueplusplus/ui/flow",
+  "peerDependencies": [
+    "@xyflow/react"
+  ],
+  "clientOnly": true,
+  "description": "The zoom / fit / lock capsule, restyled as an overlay surface.\n\nShape is inline for the same reason the colours are: `border-radius` and\n`overflow` have no `--xy-*` hook, and the library's own rule would otherwise\nwin. `overflow: hidden` is what makes the first and last buttons take the\ncapsule's corners instead of squaring them off.",
+  "props": [],
+  "typeReferences": [
+    "React.ComponentProps<typeof Controls>"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-border-overlay",
+    "--cue-radius-overlay"
+  ],
+  "summary": "The zoom / fit / lock capsule, restyled as an overlay surface.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<ReactFlow …><FlowControls /></ReactFlow>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/flow-controls",
+  "mdUrl": "/docs/components/flow-controls.md",
+  "jsonUrl": "/r/components/flow-controls.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/flow-graph.json

@@ -0,0 +1,75 @@
+{
+  "name": "FlowGraph",
+  "slug": "flow-graph",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "Work as a graph rather than a list: branches that fan out and rejoin.",
+  "props": [
+    {
+      "name": "nodes",
+      "type": "readonly FlowNode[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Every node with its grid position. Layout is explicit; the element runs no solver."
+    },
+    {
+      "name": "edges",
+      "type": "readonly FlowEdge[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Connections by node id. An edge dims until both of its ends are visible."
+    },
+    {
+      "name": "visibleCount",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "How many nodes have been reached so far."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  \"children\" | \"nodes\" | \"edges\" | \"visibleCount\"\n> & {\n  /** Every node with its grid position. Layout is explicit; the element runs no solver. */\n  nodes: readonly FlowNode[];\n  /** Connections by node id. An edge dims until both of its ends are visible. */\n  edges: readonly FlowEdge[];\n  /** How many nodes have been reached so far. */\n  visibleCount: number;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-border",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-radius-overlay",
+    "--cue-radius-surface",
+    "--cue-stream",
+    "--cue-surface-1",
+    "--cue-text-ui"
+  ],
+  "summary": "Work as a graph rather than a list: branches that fan out and rejoin.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { FlowGraph } from \"@cueplusplus/ui/elements\";\n\n<FlowGraph nodes={nodes} edges={edges} visibleCount={nodes.length} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/flow-graph",
+  "mdUrl": "/docs/components/flow-graph.md",
+  "jsonUrl": "/r/components/flow-graph.json",
+  "specimens": [
+    {
+      "title": "FlowGraph",
+      "group": "elements-agents",
+      "components": [
+        "FlowGraph"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"partway\" wide>\n    <FlowGraph nodes={FLOW_NODES} edges={FLOW_EDGES} visibleCount={4} />\n  </Specimen>\n  <Specimen label=\"the whole graph\" wide>\n    <FlowGraph\n      nodes={FLOW_NODES.map((node) => ({ ...node, state: \"done\" as const }))}\n      edges={FLOW_EDGES}\n      visibleCount={FLOW_NODES.length}\n    />\n  </Specimen>\n</Specimens>",
+      "note": "Work as a graph rather than a list, for the runs that fan out and rejoin — here the two trusses are patched in parallel and the render waits for both. Layout is explicit: every node carries its own column and row and the element runs no solver, which is what keeps a re-render from rearranging a diagram somebody was reading.",
+      "interaction": "none. `visibleCount` is what makes the graph arrive a node at a time, and an edge stays dim until both of its ends have been reached."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/folder-icon.json

@@ -0,0 +1,52 @@
+{
+  "name": "FolderIcon",
+  "slug": "folder-icon",
+  "group": "icons",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "A folder somebody made: a shelf of bookmarks, filed by hand.\n\nThe tab is the whole glyph. A plain rounded box in this library is a panel,\na card or a dialog, and the one thing a folder has to say is that a person\nput these here on purpose rather than a query having returned them.",
+  "props": [],
+  "typeReferences": [
+    "React.SVGProps<SVGSVGElement>"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-icon-",
+    "--cue-icon-md",
+    "--cue-icon-sm"
+  ],
+  "summary": "A folder somebody made: a shelf of bookmarks, filed by hand.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/folder-icon",
+  "mdUrl": "/docs/components/folder-icon.md",
+  "jsonUrl": "/r/components/folder-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/footer.json

@@ -0,0 +1,112 @@
+{
+  "name": "Footer",
+  "slug": "footer",
+  "group": "chrome",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "The `contentinfo` landmark at the bottom of a document: a hairline, a\nmeasure, and room for whatever a page ends with.\n\nDeliberately **not** a link-list component. A \"complex footer\" in this system\nis `Grid` + `Stack` + `Link` inside this one — components that already exist\nand already carry the density ladder — and a `Grid` with `minItemWidth` fills\nthe row with as many columns as fit, so the footer is responsive without a\nbreakpoint and without a prop for how many columns to draw. What is left over\nis what a footer actually needs and nothing else has: the landmark, the rule\nthat separates it from the page, the measure that lines it up with the page,\nand the second rule above the fine print.\n\nThe band is full-bleed and the column inside it is centred, which is why the\nhairline runs edge to edge while the links stop at the measure. The column is\nset in the bar's register — mono, at the UI size — because a footer is\nfurniture. It paints no ground of its own: a footer is the end of the page,\nnot a bar, and the seam is the hairline. Give it `className=\"bg-surface-1\"`\nwhere a distinct band is wanted.\n\nInside `AppShell` this is a child of `AppShell.Scroller`, at the end of the\ncontent column — so it scrolls with the page and its full bleed is the\ncontent column's width, not the window's. A footer placed *beside* the\nnavigation column instead (after `AppShell.Body`) runs under the navigation\nand reads as chrome it is not. It coexists with `StatusBar`, which is the\nopposite object: a strip of the frame, always on screen, never scrolled.\n\nStatic markup — no `\"use client\"`.",
+  "props": [
+    {
+      "name": "width",
+      "type": "\"narrow\" | \"wide\" | \"broad\" | \"full\"",
+      "required": false,
+      "defaultValue": "broad",
+      "description": "Which measure the footer's column takes. Defaults to `\"broad\"`.\n\nThe same four rungs `Container` and `PageShell` offer, so a footer lines up\nwith the page above it by naming the same width — `broad` rather than\n`narrow` by default because a footer is usually the widest thing on a page,\nand a row of columns inside a 42rem reading measure is four squeezed lists."
+    },
+    {
+      "name": "meta",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "The fine print, under a hairline of its own: copyright, a licence, a build\nnumber.\n\nA slot rather than a component, because that row is a sentence and a couple\nof links — but it is a *separated* sentence, and hand-rolling the rule and\nthe space above it in every app is exactly the kind of repetition this\ncomponent exists to end."
+    },
+    {
+      "name": "columnClassName",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes for the centred column inside the landmark."
+    },
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "The footer's body — normally a `Grid` of `Stack`s of `Link`s."
+    }
+  ],
+  "typeReferences": [
+    "React.ComponentPropsWithoutRef<\"footer\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-border",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-space-3",
+    "--cue-space-5",
+    "--cue-space-6",
+    "--cue-space-7",
+    "--cue-text-label",
+    "--cue-text-ui"
+  ],
+  "summary": "The contentinfo landmark at the bottom of a document: a full-bleed hairline, a centred measure, and a fine-print row under a rule of its own.",
+  "examples": [
+    {
+      "title": "A complex footer is components you already have",
+      "code": "<Footer\n  width=\"broad\"\n  meta={\n    <>\n      <span>© 2026 CUE++</span>\n      <Link href=\"/legal\">Legal</Link>\n    </>\n  }\n>\n  <Grid minItemWidth=\"12rem\" gap={5}>\n    <Stack gap={2}>\n      <Eyebrow>Docs</Eyebrow>\n      <Link href=\"/docs\">Getting started</Link>\n      <Link href=\"/docs/theming\">Theming</Link>\n    </Stack>\n    <Stack gap={2}>\n      <Eyebrow>Surfaces</Eyebrow>\n      <Link href=\"/kitchen-sink\">Kitchen sink</Link>\n      <Link href=\"/gallery\">Gallery</Link>\n    </Stack>\n  </Grid>\n</Footer>",
+      "language": "tsx"
+    },
+    {
+      "title": "Wiring it once",
+      "code": "<div className=\"flex min-h-dvh flex-col\">\n  <SiteHeader />\n  <main className=\"min-w-0 flex-1\">{children}</main>\n  <SiteFooter />\n</div>",
+      "language": "tsx"
+    },
+    {
+      "title": "Inside `AppShell`: the content column, never the frame",
+      "code": "<AppShell.Content>\n  <AppShell.Scroller padded={false} className=\"flex flex-col\">\n    <div className=\"flex-1\">{children}</div>\n    <Footer meta={…}>…</Footer>\n  </AppShell.Scroller>\n</AppShell.Content>",
+      "language": "tsx"
+    },
+    {
+      "title": "Usage",
+      "code": "<Footer meta={<><span>© 2026 CUE++</span><Link href=\"/legal\">Legal</Link></>}>\n  <Grid minItemWidth=\"12rem\" gap={5}>\n    <Stack gap={2}>\n      <Eyebrow>Docs</Eyebrow>\n      <Link href=\"/docs\">Getting started</Link>\n      <Link href=\"/docs/theming\">Theming</Link>\n    </Stack>\n    <Stack gap={2}>\n      <Eyebrow>Surfaces</Eyebrow>\n      <Link href=\"/kitchen-sink\">Kitchen sink</Link>\n    </Stack>\n  </Grid>\n</Footer>",
+      "language": "tsx"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/footer",
+  "mdUrl": "/docs/components/footer.md",
+  "jsonUrl": "/r/components/footer.json",
+  "whenToUse": [
+    "The end of any document that scrolls: a site, a documentation page, a marketing page, the signed-out half of a console.",
+    "Whenever a page ends with a hand-rolled `<footer>` carrying its own `border-t`, its own `max-w-*` and its own gutters. Those three are the component.",
+    "As the frame for a complex footer — a row of link columns, a status line, a licence — with `Grid` and `Stack` doing the layout inside it."
+  ],
+  "whenNotToUse": [
+    "As the bottom strip of a console. That is `StatusBar`: one chrome rung tall, always on screen, tone-inked readouts. A footer scrolls away, and should. The two can coexist — see below.",
+    "As a sibling of the navigation column. Inside a shell a footer belongs to the content scroller; one placed beside `AppShell.Sidebar`, or after `AppShell.Body`, stretches under the navigation and pretends to be part of the frame.",
+    "As a place to put a link list component. There isn't one, and there does not need to be — see below."
+  ],
+  "commonMistakes": [
+    "Reaching for a column count. Use `Grid` with `minItemWidth`: it fills the row with as many columns as fit, so the footer is responsive with no breakpoint and no prop for how many columns to draw.",
+    "Setting a width that disagrees with the page above it. `Footer` takes the same four measures as `Container` and `PageShell` — name the same rung and the columns line up with the content.",
+    "Hand-rolling the fine-print rule. That is what `meta` is: it draws the hairline and the space above it so every app does not.",
+    "Painting a ground on it by reflex. A footer is the end of the page, not a bar; the seam is the hairline. Pass `className=\"bg-surface-1\"` only when a distinct band is actually wanted."
+  ],
+  "specimens": [
+    {
+      "title": "Footer",
+      "group": "chrome",
+      "components": [
+        "Footer"
+      ],
+      "code": "<div className=\"w-full overflow-hidden rounded-(--radius-surface) border border-border bg-bg\">\n  <Footer\n    width=\"wide\"\n    meta={\n      <>\n        <span>© 2026 CUE++</span>\n        <Link href=\"#legal\">Legal</Link>\n      </>\n    }\n  >\n    <Grid minItemWidth=\"9rem\" gap={5}>\n      <Stack gap={2}>\n        <Eyebrow>Docs</Eyebrow>\n        <Link href=\"#getting-started\">Getting started</Link>\n        <Link href=\"#theming\">Theming</Link>\n      </Stack>\n      <Stack gap={2}>\n        <Eyebrow>Surfaces</Eyebrow>\n        <Link href=\"#kitchen-sink\">Kitchen sink</Link>\n        <Link href=\"#gallery\">Gallery</Link>\n      </Stack>\n      <Stack gap={2}>\n        <Eyebrow>Elsewhere</Eyebrow>\n        <Link external href=\"https://skills.cueplusplus.com\">\n          Skills\n        </Link>\n      </Stack>\n    </Grid>\n  </Footer>\n</div>",
+      "note": "The contentinfo landmark: a full-bleed hairline, a centred measure off the same ladder Container and PageShell use, and a fine-print row under a rule of its own. The columns are Grid + Stack + Link — there is no link-list component here, because none is needed.",
+      "interaction": "none; the links inside are ordinary links."
+    }
+  ]
+}

package/manifest/components/frac.json

@@ -0,0 +1,59 @@
+{
+  "name": "Frac",
+  "slug": "frac",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A fraction inside an expression — numerator, rule, denominator — set inline and\naligned to the middle.",
+  "props": [
+    {
+      "name": "over",
+      "type": "ReactNode",
+      "required": true,
+      "defaultValue": null,
+      "description": "Numerator."
+    },
+    {
+      "name": "under",
+      "type": "ReactNode",
+      "required": true,
+      "defaultValue": null,
+      "description": "Denominator."
+    }
+  ],
+  "typeReferences": [],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-border-strong",
+    "--cue-fg",
+    "--cue-fg-subtle",
+    "--cue-radius-overlay",
+    "--cue-text-emphasis"
+  ],
+  "summary": "A fraction inside an expression — numerator, rule, denominator — set inline and aligned to the middle.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/frac",
+  "mdUrl": "/docs/components/frac.md",
+  "jsonUrl": "/r/components/frac.json",
+  "specimens": [
+    {
+      "title": "MathBlock",
+      "group": "elements-knowledge",
+      "components": [
+        "MathBlock",
+        "Frac",
+        "Sub",
+        "Sup"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"worked through\" wide>\n    <MathBlock label=\"illuminance at the deck\" steps={MATH} visibleSteps={MATH.length} />\n  </Specimen>\n  <Specimen label=\"first step only\" wide>\n    <MathBlock steps={MATH} visibleSteps={1} />\n  </Specimen>\n</Specimens>",
+      "note": "Maths with the working shown, a step at a time. The expressions are nodes rather than a string, so there is no parser and no KaTeX in the bundle — `Frac` stacks a numerator over a rule, `Sup` and `Sub` set an index upright inside the serif italic, and anything else is text.",
+      "interaction": "none. Each step's note says what justified it, which is what turns three lines of algebra into an explanation."
+    }
+  ],
+  "todo": true
+}