@cueplusplus/ui 0.13.0

package/manifest/components/otp-field.json

@@ -0,0 +1,163 @@
+{
+  "name": "OTPField",
+  "slug": "otp-field",
+  "group": "forms",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A one-time code, one character per box.\n\nThe boxes are not decoration: they tell the user how long the code is before\nthey start typing, which is the whole reason this pattern beats a plain text\ninput. Paste, arrow keys, Backspace across slot boundaries and the\n`one-time-code` autofill hint all come from Base UI.\n\nSlots ride the recessed chassis — sunken fill, hairline rim — so a code field\nreads as \"type here\" like every other input in the system, just squared off.",
+  "props": [
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes for the row.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "id",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Id of the first slot. Generated when omitted, so the hidden label can target it.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "aria-label",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Accessible name for the field. Names the group *and*, through a visually\nhidden `<label>`, the first slot — the ARIA pattern for a code field. Leave\nit off inside a {@link Field }, which supplies a real label.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "separator",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": "–",
+      "description": "What sits between groups. Defaults to `\"–\"`. Always `aria-hidden`.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    },
+    {
+      "name": "size",
+      "type": "\"sm\" | \"md\" | \"lg\"",
+      "required": false,
+      "defaultValue": "md",
+      "description": "Rung of the control ladder. Defaults to `\"md\"`.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "sm",
+          "md",
+          "lg"
+        ]
+      }
+    },
+    {
+      "name": "length",
+      "type": "number",
+      "required": false,
+      "defaultValue": "6",
+      "description": "How many characters the code has. Defaults to `6`.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "name": "groupSize",
+      "type": "number",
+      "required": false,
+      "defaultValue": null,
+      "description": "Insert a separator after every `groupSize` slots — `groupSize={3}` renders a\nsix-character code as `123 456`, which is how people read one off a screen.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "name": "slotLabel",
+      "type": "((index: number, length: number) => string)",
+      "required": false,
+      "defaultValue": "(index, total) => `Character ${index + 1} of ${total}`",
+      "description": "Accessible name for slot `index` (1-based here, since slot 0 is named by the\nfield label) of `length`. Defaults to\n``(index, length) => `Character ${index + 1} of ${length}` ``.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    },
+    {
+      "name": "slotClassName",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes for every slot.",
+      "control": {
+        "kind": "string"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<BaseOTPField.Root.Props, \"className\" | \"children\" | \"length\">"
+  ],
+  "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-2",
+    "--cue-space-3",
+    "--cue-space-4",
+    "--cue-space-5",
+    "--cue-sunken",
+    "--cue-text-body",
+    "--cue-text-emphasis",
+    "--cue-text-label",
+    "--cue-text-ui"
+  ],
+  "summary": "A one-time code, one character per box.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<OTPField aria-label=\"Verification code\" onValueComplete={submit} />\n<OTPField aria-label=\"Recovery code\" length={8} groupSize={4} validationType=\"alphanumeric\" />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/otp-field",
+  "mdUrl": "/docs/components/otp-field.md",
+  "jsonUrl": "/r/components/otp-field.json",
+  "specimens": [
+    {
+      "title": "OTPField",
+      "group": "forms",
+      "components": [
+        "OTPField"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"empty\">\n    <OTPField aria-label=\"Pairing code\" />\n  </Specimen>\n  <Specimen label=\"filled\">\n    <OTPField aria-label=\"Pairing code, filled\" defaultValue=\"428170\" />\n  </Specimen>\n  <Specimen label=\"4 digits, sm\">\n    <OTPField aria-label=\"Short code\" length={4} groupSize={4} size=\"sm\" />\n  </Specimen>\n  <Specimen label=\"disabled\">\n    <OTPField aria-label=\"Code, disabled\" defaultValue=\"428170\" disabled />\n  </Specimen>\n</Specimens>",
+      "note": "Six slots in two groups. One value, six boxes: paste fills all of them.",
+      "interaction": "Backspace walks back through the slots; arrow keys move without deleting."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/page-shell.json

@@ -0,0 +1,129 @@
+{
+  "name": "PageShell",
+  "slug": "page-shell",
+  "group": "chrome",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "A centred content column with a standard page header.\n\nThe header is emitted only when something fills it, so a shell used purely\nfor its measure adds no empty box and no stray vertical rhythm.\n\nRenders a plain `<div>` rather than a `<main>`: a page can hold more than one\nshell (a split view), and only one element per document may be `<main>`. Wrap\nit yourself where the semantics apply.\n\nStatic markup — no `\"use client\"`.",
+  "props": [
+    {
+      "name": "width",
+      "type": "\"narrow\" | \"wide\" | \"broad\" | \"full\"",
+      "required": false,
+      "defaultValue": "narrow",
+      "description": "Which measure the content column takes. Defaults to `\"narrow\"`.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "narrow",
+          "wide",
+          "broad",
+          "full"
+        ]
+      }
+    },
+    {
+      "name": "title",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "The page heading. Rendered as the `<h1>`.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    },
+    {
+      "name": "subtitle",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "One supporting line under the title.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    },
+    {
+      "name": "eyebrow",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "Accent kicker above the title — normally an `<Eyebrow>`.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    },
+    {
+      "name": "actions",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "Page-level actions, aligned with the title.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    },
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "The page body.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"title\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-font-mono",
+    "--cue-leading-ui",
+    "--cue-measure-broad",
+    "--cue-measure-narrow",
+    "--cue-measure-wide",
+    "--cue-space-2",
+    "--cue-space-4",
+    "--cue-space-6",
+    "--cue-space-7",
+    "--cue-text-title",
+    "--cue-text-ui"
+  ],
+  "summary": "A centred content column with a standard page header.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<PageShell title=\"Patch\" subtitle=\"512 channels\" eyebrow={<Eyebrow>Console</Eyebrow>}>\n  <Panel>…</Panel>\n</PageShell>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/page-shell",
+  "mdUrl": "/docs/components/page-shell.md",
+  "jsonUrl": "/r/components/page-shell.json",
+  "specimens": [
+    {
+      "title": "PageShell",
+      "group": "chrome",
+      "components": [
+        "PageShell"
+      ],
+      "code": "<div className=\"w-full rounded-(--radius-surface) border border-border bg-bg py-(--cue-space-5)\">\n  <PageShell\n    width=\"narrow\"\n    eyebrow={<Eyebrow>show file</Eyebrow>}\n    title=\"Ada, act 2\"\n    subtitle=\"12 cues, 48 fixtures, 4 universes.\"\n    actions={<Button variant=\"primary\">Save</Button>}\n  >\n    <Panel className=\"p-(--cue-space-5) font-mono text-(length:--cue-text-ui) text-fg-muted\">\n      Page body.\n    </Panel>\n  </PageShell>\n</div>",
+      "note": "The page measure: eyebrow, title, subtitle, actions and a body at one of four widths — 42rem, 54rem, 84rem, or uncapped.",
+      "interaction": "none."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/pagination.json

@@ -0,0 +1,108 @@
+{
+  "name": "Pagination",
+  "slug": "pagination",
+  "group": "layout",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "The pager: previous, a window of page numbers, next.\n\nRenders nothing at all when there is a single page — a control offering no\nchoice is chrome that says \"there is more here\" when there is not.\n\nEvery page number is a real button with a spoken name (\"Page 3\"), because the\nbare numeral is meaningless read aloud out of context; the ellipses are\n`aria-hidden` for the same reason breadcrumb separators are.",
+  "props": [
+    {
+      "name": "page",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "The current page, 1-based.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "name": "pageCount",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "How many pages there are in total.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "name": "onPageChange",
+      "type": "(page: number) => void",
+      "required": true,
+      "defaultValue": null,
+      "description": "Called with the page a control asked for. Always within `1..pageCount`.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    },
+    {
+      "name": "siblingCount",
+      "type": "number",
+      "required": false,
+      "defaultValue": "1",
+      "description": "How many pages to show either side of the current one. Defaults to `1`.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "required": false,
+      "defaultValue": "Pagination",
+      "description": "The nav's accessible name. Defaults to `\"Pagination\"`.",
+      "control": {
+        "kind": "string"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"nav\">, \"onChange\" | \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-soft",
+    "--cue-control-sm",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-radius-control",
+    "--cue-space-1",
+    "--cue-space-2",
+    "--cue-surface-2",
+    "--cue-text-ui"
+  ],
+  "summary": "The pager: previous, a window of page numbers, next.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Pagination page={page} pageCount={12} onPageChange={setPage} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/pagination",
+  "mdUrl": "/docs/components/pagination.md",
+  "jsonUrl": "/r/components/pagination.json",
+  "specimens": [
+    {
+      "title": "Pagination",
+      "group": "layout",
+      "components": [
+        "Pagination"
+      ],
+      "code": "<div className=\"flex w-full flex-col gap-(--cue-space-4)\">\n  <Pagination page={page} pageCount={12} onPageChange={setPage} />\n  <Pagination page={1} pageCount={3} onPageChange={() => {}} />\n</div>",
+      "note": "A windowed pager with gaps, generated by the exported `paginationRange`.",
+      "interaction": "the current page is accent-soft and carries `aria-current`; the ends disable rather than disappear."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/panel-header.json

@@ -0,0 +1,89 @@
+{
+  "name": "PanelHeader",
+  "slug": "panel-header",
+  "group": "chrome",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "The top bar of a {@link Panel}: title left, actions right, hairline under.\n\nPadded with the density row tokens rather than its own values, so the header\nlines up horizontally with the rows beneath it at every density level.\n\nStatic markup — no `\"use client\"`.",
+  "props": [
+    {
+      "name": "title",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "The header's label. Rendered one type rung above body text — the panel's\nown name, not a page heading.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    },
+    {
+      "name": "actions",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "Right-hand slot: the controls that act on the whole panel (a menu, a\nrefresh button, a count chip).",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    },
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra content in the leading cluster, after the title.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"title\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-border",
+    "--cue-fg",
+    "--cue-font-mono",
+    "--cue-pad-row-x",
+    "--cue-pad-row-y",
+    "--cue-radius-surface",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-surface-1",
+    "--cue-text-emphasis"
+  ],
+  "summary": "The top bar of a {@link Panel}: title left, actions right, hairline under.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<PanelHeader title=\"Universes\" actions={<Chip tone=\"ok\">live</Chip>} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/panel-header",
+  "mdUrl": "/docs/components/panel-header.md",
+  "jsonUrl": "/r/components/panel-header.json",
+  "specimens": [
+    {
+      "title": "Panel / PanelHeader",
+      "group": "chrome",
+      "components": [
+        "Panel",
+        "PanelHeader"
+      ],
+      "code": "<div className=\"grid w-full gap-(--cue-space-5) lg:grid-cols-2\">\n  <Panel>\n    <PanelHeader title=\"Output\" actions={<Chip tone=\"ok\">live</Chip>} />\n    {CUES.slice(0, 3).map((cue) => (\n      <Row key={cue.id}>\n        <span className=\"w-[2rem] shrink-0 font-mono tabular-nums\">{cue.id}</span>\n        <span className=\"flex-1 truncate\">{cue.label}</span>\n        <span className=\"font-mono tabular-nums text-fg-muted\">{cue.time}</span>\n      </Row>\n    ))}\n  </Panel>\n  <Panel className=\"p-(--cue-space-5)\">\n    <PanelHeader>\n      <Eyebrow>free-form header</Eyebrow>\n    </PanelHeader>\n    <p className=\"pt-(--cue-space-4) font-mono text-(length:--cue-text-ui) text-fg-muted\">\n      A panel with body padding instead of rows, for prose and forms.\n    </p>\n  </Panel>\n</div>",
+      "note": "The universal container: one hairline rim, no shadow, and a header that owns its own rule.",
+      "interaction": "none. A panel is a box."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/panel.json

@@ -0,0 +1,71 @@
+{
+  "name": "Panel",
+  "slug": "panel",
+  "group": "chrome",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "The universal container: one hairline rim, one raised surface, one radius.\n\nEverything in a console lives in a panel — a cue list, a patch table, a\nsettings group — so the shape is defined once here rather than re-typed as\nfour utilities at every call site. `overflow-hidden` is part of the recipe,\nnot an extra: it clips the first and last `Row`'s square edges back to the\npanel's radius, which is what makes a stack of hairline rows read as one\nobject.\n\nDeliberately flat: no shadow. In this system only a floating surface (a\ndialog, a menu, a toast) is allowed one — see `overlays/_surface.ts`.\n\nStatic markup — no `\"use client\"`.",
+  "props": [],
+  "typeReferences": [
+    "React.ComponentPropsWithoutRef<\"div\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-border",
+    "--cue-fg",
+    "--cue-font-mono",
+    "--cue-pad-row-x",
+    "--cue-pad-row-y",
+    "--cue-radius-surface",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-surface-1",
+    "--cue-text-emphasis"
+  ],
+  "summary": "The universal container: one hairline rim, one raised surface, one radius.",
+  "examples": [
+    {
+      "title": "A panel of rows",
+      "code": "<Panel>\n  <PanelHeader title=\"Cue stack\" actions={<Chip tone=\"ok\">live</Chip>} />\n  <Row interactive>Cue 1 — house up</Row>\n  <Row interactive>Cue 2 — blackout</Row>\n</Panel>",
+      "language": "tsx"
+    },
+    {
+      "title": "Usage",
+      "code": "<Panel>\n  <PanelHeader title=\"Cue stack\" actions={<IconButton aria-label=\"Add\" icon={Plus} />} />\n  <Row>Cue 1</Row>\n  <Row>Cue 2</Row>\n</Panel>",
+      "language": "tsx"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/panel",
+  "mdUrl": "/docs/components/panel.md",
+  "jsonUrl": "/r/components/panel.json",
+  "whenToUse": [
+    "Any grouped region of a console: a cue list, a table, a settings block.",
+    "As the parent of a `Row` stack, whose square corners it clips back to the panel radius."
+  ],
+  "whenNotToUse": [
+    "Page-level structure. Use `PageShell` for a titled page, `Container` for a width bound.",
+    "Anything that floats. Menus, dialogs and toasts wear the overlay surface, which owns the only shadows in the system."
+  ],
+  "commonMistakes": [
+    "Adding a shadow. A panel is flat by design; a shadow here reads as a bug in the theme.",
+    "Padding the panel and then padding its rows, which doubles the gutter the row tokens already set."
+  ],
+  "specimens": [
+    {
+      "title": "Panel / PanelHeader",
+      "group": "chrome",
+      "components": [
+        "Panel",
+        "PanelHeader"
+      ],
+      "code": "<div className=\"grid w-full gap-(--cue-space-5) lg:grid-cols-2\">\n  <Panel>\n    <PanelHeader title=\"Output\" actions={<Chip tone=\"ok\">live</Chip>} />\n    {CUES.slice(0, 3).map((cue) => (\n      <Row key={cue.id}>\n        <span className=\"w-[2rem] shrink-0 font-mono tabular-nums\">{cue.id}</span>\n        <span className=\"flex-1 truncate\">{cue.label}</span>\n        <span className=\"font-mono tabular-nums text-fg-muted\">{cue.time}</span>\n      </Row>\n    ))}\n  </Panel>\n  <Panel className=\"p-(--cue-space-5)\">\n    <PanelHeader>\n      <Eyebrow>free-form header</Eyebrow>\n    </PanelHeader>\n    <p className=\"pt-(--cue-space-4) font-mono text-(length:--cue-text-ui) text-fg-muted\">\n      A panel with body padding instead of rows, for prose and forms.\n    </p>\n  </Panel>\n</div>",
+      "note": "The universal container: one hairline rim, no shadow, and a header that owns its own rule.",
+      "interaction": "none. A panel is a box."
+    }
+  ]
+}