@cueplusplus/ui 0.18.2 → 0.20.0

package/manifest/components/sheet.json

@@ -166,7 +166,6 @@
     "--cue-control-sm",
     "--cue-fg",
     "--cue-fg-muted",
-    "--cue-fg-subtle",
     "--cue-font-mono",
     "--cue-leading-ui",
     "--cue-paint-rim-width",
@@ -195,6 +194,7 @@
     "--cue-style-body-size",
     "--cue-style-body-weight",
     "--cue-style-control-face",
+    "--cue-style-control-radius",
     "--cue-style-display-variation",
     "--cue-style-group-label-ink",
     "--cue-style-group-label-pad",

package/manifest/components/sidebar.json

@@ -223,6 +223,7 @@
     "--cue-style-label-weight",
     "--cue-style-nav-active-ground",
     "--cue-style-nav-ink",
+    "--cue-style-rail-counter-content",
     "--cue-style-selected-ground",
     "--cue-style-selected-ink",
     "--cue-style-selected-weight",

package/manifest/components/skeleton.json

@@ -17,6 +17,7 @@
   "tokensUsed": [
     "--cue-radius-control",
     "--cue-radius-scale",
+    "--cue-style-control-radius",
     "--cue-style-skeleton-radius",
     "--cue-surface-2"
   ],

package/manifest/components/spectrum-visualizer.json

@@ -113,10 +113,20 @@
   "defaultVariants": {},
   "tokensUsed": [
     "--cue-border",
+    "--cue-border-strong",
+    "--cue-danger",
     "--cue-data-ground",
     "--cue-font-mono",
     "--cue-radius-control",
+    "--cue-radius-scale",
     "--cue-space-1",
+    "--cue-space-3",
+    "--cue-space-4",
+    "--cue-space-5",
+    "--cue-style-control-radius",
+    "--cue-style-field-hover-edge",
+    "--cue-style-field-pad",
+    "--cue-style-field-radius",
     "--cue-text-micro"
   ],
   "summary": "The FFT, drawn: one bar per frequency band, or one line across all of them.",

package/manifest/components/stack.json

@@ -23,7 +23,7 @@
     },
     {
       "name": "gap",
-      "type": "0 | 4 | 8 | 1 | 2 | 3 | 5 | 6 | 7",
+      "type": "0 | 1 | 2 | 4 | 8 | 3 | 5 | 6 | 7",
       "required": false,
       "defaultValue": "4",
       "description": "Which rung of the density space ladder to spend between children. Defaults to `4`.",
@@ -31,14 +31,14 @@
         "kind": "enum",
         "members": [
           0,
-          4,
-          8,
           1,
           2,
           3,
+          4,
           5,
           6,
-          7
+          7,
+          8
         ],
         "min": 0,
         "max": 8

package/manifest/components/stat-band.json

@@ -0,0 +1,68 @@
+{
+  "name": "StatBand",
+  "slug": "stat-band",
+  "group": "chrome",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "A row of named figures: the KPI band under a report's title.\n\nBuilt from `Stat`, so each figure keeps its caption-over-reading voice and its\ntabular numerals. The style set decides the band's look: `style-stat-divider`\ndraws a rule between figures, and `Stat` reads `style-stat-numeral-ink` for the\nreading's colour. Unset, there is no rule and the reading keeps its ink. A\nwrapped row's first figure draws no rule, so a narrow screen never shows a\ndivider hanging off the left edge.\n\nStatic markup — no `\"use client\"`.",
+  "props": [
+    {
+      "name": "stats",
+      "type": "readonly StatBandStat[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "The figures, in reading order. One to six sit in one row; more wrap.",
+      "control": {
+        "kind": "array",
+        "fixture": "sample.stats"
+      }
+    }
+  ],
+  "typeReferences": [
+    "React.ComponentPropsWithoutRef<\"div\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-space-5",
+    "--cue-style-stat-divider"
+  ],
+  "summary": "A row of named figures, each a `Stat`: the KPI band under a report's title.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<StatBand stats={[{ label: \"SKUs\", value: \"1,091\" }, { label: \"Brands\", value: \"148\" }]} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/stat-band",
+  "mdUrl": "/docs/components/stat-band.md",
+  "jsonUrl": "/r/components/stat-band.json",
+  "whenToUse": [
+    "Three to six headline figures under a report or dashboard title.",
+    "Inside `Hero`'s `stats` slot, where the inverse card draws them on its dark ground."
+  ],
+  "whenNotToUse": [
+    "A table of figures to compare. Use `Table` or `DataTable`.",
+    "One figure on its own. Use `Stat`."
+  ],
+  "commonMistakes": [
+    "Drawing dividers by hand. The style set's `style-stat-divider` decides whether figures are ruled, and a wrapped row's first figure drops its rule."
+  ],
+  "specimens": [
+    {
+      "title": "StatBand",
+      "group": "chrome",
+      "components": [
+        "StatBand"
+      ],
+      "code": "<StatBand\n  className=\"w-full\"\n  stats={Array.from({ length: 7 }, (_, index) => ({\n    label: [\"Lines\", \"Brands\", \"Stores\", \"Weeks\", \"Cases\", \"Suppliers\", \"Regions\"][index]!,\n    value: [\"1,091\", \"148\", \"812\", \"52\", \"4.2m\", \"63\", \"9\"][index]!,\n  }))}\n/>",
+      "note": "A row of named figures, built from Stat. The set draws the rule between them and picks the reading's ink; a wrapped row's first figure never hangs a rule off the edge.",
+      "interaction": "none. Narrow the window: seven figures wrap without a stray divider."
+    }
+  ]
+}

package/manifest/components/stat.json

@@ -73,7 +73,6 @@
     "--cue-danger",
     "--cue-fg",
     "--cue-fg-muted",
-    "--cue-fg-subtle",
     "--cue-font-mono",
     "--cue-info",
     "--cue-ok",
@@ -90,6 +89,7 @@
     "--cue-style-stat-detail-size",
     "--cue-style-stat-gap",
     "--cue-style-stat-leading",
+    "--cue-style-stat-numeral-ink",
     "--cue-style-stat-size",
     "--cue-style-stat-tracking",
     "--cue-style-stat-weight",

package/manifest/components/still-provider.json

@@ -0,0 +1,60 @@
+{
+  "name": "StillProvider",
+  "slug": "still-provider",
+  "group": "system",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "Hold a subtree still (see {@link useStill}). A gallery frame mounts one with\n`still` when it is a thumbnail.",
+  "props": [
+    {
+      "name": "still",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "`true` holds everything under it still. Nested providers can only add stillness, never remove it.",
+      "control": {
+        "kind": "boolean"
+      }
+    },
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "What it holds still. Optional, as `ThemeProvider`'s is: an empty provider renders nothing.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    }
+  ],
+  "typeReferences": [],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [],
+  "summary": "Holds a subtree still: no motif animates, no replay plays, no live readout loops.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<StillProvider still><Page /></StillProvider>",
+      "language": "tsx"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/still-provider",
+  "mdUrl": "/docs/components/still-provider.md",
+  "jsonUrl": "/r/components/still-provider.json",
+  "whenToUse": [
+    "A gallery thumbnail or any preview that must cost nothing at rest.",
+    "A screenshot or print view."
+  ],
+  "whenNotToUse": [
+    "Reduced motion for a reader. `useStill` already folds in `prefers-reduced-motion`; the provider is for previews."
+  ],
+  "commonMistakes": [
+    "Expecting a nested `still={false}` to undo an outer one. Stillness only adds."
+  ]
+}

package/manifest/components/switch.json

@@ -62,7 +62,6 @@
     "--cue-danger-fg",
     "--cue-fg",
     "--cue-fg-muted",
-    "--cue-fg-subtle",
     "--cue-focus",
     "--cue-focus-ring",
     "--cue-font-mono",

package/manifest/components/table.json

@@ -104,16 +104,16 @@
         },
         {
           "name": "headingLevel",
-          "type": "4 | 2 | 3 | 5 | 6",
+          "type": "2 | 4 | 3 | 5 | 6",
           "required": false,
           "defaultValue": null,
           "description": "Make the label slot a real heading element. Defaults to `undefined` — no\nheading, and the label stays the `<span>` it has always been.\n\n**Set this rather than passing a heading as `label`.** The label slot wraps\nwhatever it is given, so an `<h2>` handed in as `label` lands *inside* a\n`<span>` — which renders, and exposes the heading, and does not validate: a\n`<span>` is phrasing content and may not contain a heading. With this prop\nthe wrapper *is* the heading (`<h2 data-slot=\"table-group-label\">`), so\nthere is nothing to nest.\n\nA heading inside a `<th>` is valid — `<th>` takes flow content — and it is\nuseful: a screen-reader user navigates a long grouped table by heading, and\nwithout one the group names are reachable only by walking the rows. The\n`scope=\"rowgroup\"` association is untouched either way; this adds the\ndivider to the document outline, it does not change what the cell heads.\n\nLevels run `2`–`6` because the outline has to describe the real nesting of\nthe page the table sits in, not the table's own idea of itself — the same\nruling as {@link LedgerTierProps.headingLevel }. There is no `1`: a group\ndivider is never the title of the document.",
           "control": {
             "kind": "enum",
             "members": [
-              4,
               2,
               3,
+              4,
               5,
               6
             ],

package/manifest/components/tabs.json

@@ -120,6 +120,7 @@
     "--cue-space-4",
     "--cue-space-5",
     "--cue-style-control-face",
+    "--cue-style-control-radius",
     "--cue-style-focus-width",
     "--cue-style-group-gap",
     "--cue-style-segment-edge",

package/manifest/components/tags-input.json

@@ -261,6 +261,7 @@
     "--cue-style-chip-size",
     "--cue-style-chip-tracking",
     "--cue-style-control-face",
+    "--cue-style-control-radius",
     "--cue-style-control-step-size",
     "--cue-style-disabled-edge",
     "--cue-style-disabled-fill",
@@ -270,6 +271,7 @@
     "--cue-style-field-focus-offset",
     "--cue-style-field-hover-edge",
     "--cue-style-field-pad",
+    "--cue-style-field-radius",
     "--cue-style-focus-edge",
     "--cue-style-focus-width",
     "--cue-style-glyph-ink",

package/manifest/components/text-scramble.json

@@ -0,0 +1,90 @@
+{
+  "name": "TextScramble",
+  "slug": "text-scramble",
+  "group": "brand",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A line that cycles through phrases, scrambling each one in — cueplusplus.com's\n\"what we do\" cycler, ported verbatim (`what-we-do.tsx`; spec\n2026-10-04-cue-site-verbatim §4.2).\n\nEach frame, every character not yet locked shows a random glyph from the\neffect's set; spaces are never scrambled; characters lock left to right. A\nphrase holds for 1.8s once it has revealed, so a long phrase and a slow effect\nstill finish before the next begins: the next starts after\n`length × revealEvery × speed + 1800ms`.\n\n**Reduced motion** shows each phrase whole, one every 2.6s, as the site does.\n**Held still** (a gallery thumbnail, under a still `StillProvider`) shows the\nfirst phrase and schedules nothing, which is this library's departure from the\nsource: a thumbnail costs nothing at rest. The text is written straight into\nthe DOM node, as the source does, so thirty-five frames a second never\nre-render React.",
+  "props": [
+    {
+      "name": "phrases",
+      "type": "readonly string[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "The phrases to cycle through, in order, looping. The first is what renders before any script runs.",
+      "control": {
+        "kind": "array",
+        "fixture": "agent.transcript"
+      }
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "What assistive technology reads instead of the animation: one sentence that\nnames the whole cycle. The animated text is hidden from it, because a\nscramble read aloud is noise.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "effect",
+      "type": "\"matrix\" | \"flap\"",
+      "required": false,
+      "defaultValue": "matrix",
+      "description": "`matrix` (the default): letters, digits and symbols at 28ms a frame, one\ncharacter locking per frame. `flap`: upper-cased, a departure board's\nletters at 55ms a frame, one character locking every two frames.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "matrix",
+          "flap"
+        ]
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"p\">, \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [],
+  "summary": "A line that cycles through phrases, scrambling each one in — matrix glyphs at 28ms a frame, or a departure board's flap — with one sentence for assistive technology.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<TextScramble phrases={[\"we build software\", \"we design stages\"]} label=\"We build software and design stages.\" />",
+      "language": "tsx"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/text-scramble",
+  "mdUrl": "/docs/components/text-scramble.md",
+  "jsonUrl": "/r/components/text-scramble.json",
+  "whenToUse": [
+    "A hero's rotating value line: what you do, said several ways, under the headline.",
+    "A short status that changes on a slow cycle, where the change itself is part of the voice."
+  ],
+  "whenNotToUse": [
+    "Anything a reader must read at a given moment, such as an error, a price or a count: the text is unreadable while it scrambles.",
+    "Long sentences. A phrase holds for 1.8s after it settles, so a long one spends most of its turn scrambling."
+  ],
+  "commonMistakes": [
+    "Leaving `label` as one of the phrases. Assistive technology reads `label` instead of the animation, so it should name the whole cycle in one sentence.",
+    "Expecting it to scramble under reduced motion. Each phrase is shown whole, one every 2.6s; held still, the first phrase stays."
+  ],
+  "specimens": [
+    {
+      "title": "TextScramble",
+      "group": "brand",
+      "components": [
+        "TextScramble"
+      ],
+      "code": "<TextScramble\n  phrases={[\"we build software // and run on it ourselves\", \"we design stages // in 3D, before they're real\"]}\n  label=\"We build software and design stages.\"\n  className=\"font-mono text-(length:--cue-text-ui) text-fg-muted\"\n/>",
+      "note": "A line that cycles through phrases, scrambling each one in: matrix glyphs at 28ms a frame, or a departure board's flap. Assistive technology reads the label instead.",
+      "interaction": "none. Prefer reduced motion and each phrase is shown whole; held still, the first phrase stays."
+    }
+  ]
+}

package/manifest/components/textarea.json

@@ -80,11 +80,13 @@
     "--cue-paint-stroke-to",
     "--cue-paint-stroke-width",
     "--cue-radius-control",
+    "--cue-radius-scale",
     "--cue-space-3",
     "--cue-space-4",
     "--cue-space-5",
     "--cue-style-body-weight",
     "--cue-style-check-edge",
+    "--cue-style-control-radius",
     "--cue-style-control-step-size",
     "--cue-style-disabled-edge",
     "--cue-style-disabled-fill",
@@ -93,6 +95,7 @@
     "--cue-style-field-focus-offset",
     "--cue-style-field-hover-edge",
     "--cue-style-field-pad",
+    "--cue-style-field-radius",
     "--cue-style-focus-edge",
     "--cue-style-focus-width",
     "--cue-style-input-face",

package/manifest/components/theme-configurator.json

@@ -155,6 +155,7 @@
     "--cue-style-body-size",
     "--cue-style-body-weight",
     "--cue-style-control-face",
+    "--cue-style-control-radius",
     "--cue-style-display-variation",
     "--cue-style-group-label-ink",
     "--cue-style-group-label-pad",

package/manifest/components/theme-provider.json

@@ -61,7 +61,7 @@
     },
     {
       "name": "font",
-      "type": "\"source\" | \"system\" | \"geist\" | \"geist-mono\" | \"inter\" | \"plex\" | \"roboto\" | \"apple\" | \"office\" | \"inter-source\" | \"dm\" | \"calsans\"",
+      "type": "\"source\" | \"system\" | \"geist\" | \"geist-mono\" | \"inter\" | \"plex\" | \"roboto\" | \"apple\" | \"office\" | \"inter-source\" | \"dm\" | \"calsans\" | \"fraunces-mono\" | \"jetbrains-mono\"",
       "required": false,
       "defaultValue": null,
       "description": "Initial font pairing.\n\nDefaults to the pairing the active theme's manifest names in\n`fontPairings.default` — §5's rule, the density prop's rule one axis over\n— and to `\"system\"` when it names none: the platform's own faces, nothing\ndownloaded, and the theme keeps whatever monospace it authored.\n\nA pairing that needs delivering is a set of *names*: this library ships no\nfont files, and a pairing nobody delivers falls through its stack to the\nplatform rather than failing. See `FONT_PAIRINGS[font].faces` for the\ncustom properties an app assigns to make one resolve.\n\n**Root-level only.** There is no font island: a nested provider forwards\nthis axis to the root, ignores this prop, and its `setFont` drives the root.\nA page that changed face halfway down is a page with a bug, and a specimen\nthat genuinely wants one — a picker row, a docs page showing all twelve —\nneeds nothing from this library but `data-font` on a `<div>`.",
@@ -79,19 +79,22 @@
           "office",
           "inter-source",
           "dm",
-          "calsans"
+          "calsans",
+          "fraunces-mono",
+          "jetbrains-mono"
         ]
       }
     },
     {
       "name": "styleSet",
-      "type": "\"console\" | \"editorial\" | \"marketing\" | \"graphite\" | \"tender\" | \"zine\" | \"kiln\" | \"porcelain\"",
+      "type": "\"command\" | \"console\" | \"editorial\" | \"marketing\" | \"graphite\" | \"tender\" | \"zine\" | \"kiln\" | \"porcelain\" | \"ledger\" | \"monolith\" | \"prism\"",
       "required": false,
       "defaultValue": null,
       "description": "Page composition for this subtree: `console`, `editorial`, `marketing` or\n`graphite`.\n\n**`styleSet`, not `style`.** This interface already has a\n`style?: React.CSSProperties` a few lines below, applied to the provider\nroot, and a second meaning for that name would be the one collision every\nconsumer of this component would have to think about. The DOM attribute is\n`data-style`, matching the four public axes — `data-cue-*` is this tree's\nprefix for *internal* attributes (`data-cue-theme`, `data-cue-fidelity`), and\na public axis wearing the internal prefix would be the more confusing of the\ntwo mistakes.\n\nUnset, **no attribute is stamped at all**, and that is the promise: an\napplication that has never heard of this axis renders the markup it rendered\nbefore it existed and stores the preference object it stored before it\nexisted. A style set is opt-in page composition, not a fourth thing every\npage has.\n\nLike the other three axes this is an *initial* value the provider then holds\nas state, so `setStyleSet` can drive it; a changed prop is adopted after\nmount. Unlike the font pairing it has an island form, so a nested provider\nthat names a set holds its own rather than handing the axis up to the root.\n\nA nested provider that names **none** holds none: the set around it\ninherits through its element, and `useTheme().styleSet` inside it reports\nthat set **live** — a stored set the root restores after mount, or a later\n`setStyleSet` at the root, reaches it and its portals. If it names a\n`theme` or a `mode`, it also restates that set as `data-style` on its\nelement — still the page's set, followed live, never its own — because a\nset's block declares values that read the theme (a band's rule and\nground), and a custom property resolves where it is declared: restated,\nthey resolve against this island's theme instead of the page's.",
       "control": {
         "kind": "enum",
         "members": [
+          "command",
           "console",
           "editorial",
           "marketing",
@@ -99,7 +102,10 @@
           "tender",
           "zine",
           "kiln",
-          "porcelain"
+          "porcelain",
+          "ledger",
+          "monolith",
+          "prism"
         ]
       }
     },

package/manifest/components/time-field.json

@@ -67,12 +67,14 @@
     "--cue-paint-stroke-to",
     "--cue-paint-stroke-width",
     "--cue-radius-control",
+    "--cue-radius-scale",
     "--cue-space-1",
     "--cue-space-3",
     "--cue-space-4",
     "--cue-space-5",
     "--cue-style-body-weight",
     "--cue-style-check-edge",
+    "--cue-style-control-radius",
     "--cue-style-control-step-size",
     "--cue-style-disabled-edge",
     "--cue-style-disabled-fill",
@@ -81,6 +83,7 @@
     "--cue-style-field-focus-offset",
     "--cue-style-field-hover-edge",
     "--cue-style-field-pad",
+    "--cue-style-field-radius",
     "--cue-style-focus-edge",
     "--cue-style-focus-width",
     "--cue-style-input-face",

package/manifest/components/toast.json

@@ -109,6 +109,7 @@
     "--cue-style-body-size",
     "--cue-style-body-weight",
     "--cue-style-control-face",
+    "--cue-style-control-radius",
     "--cue-style-display-variation",
     "--cue-style-focus-width",
     "--cue-style-group-label-ink",

package/manifest/components/tooltip.json

@@ -145,7 +145,6 @@
     "--cue-control-sm",
     "--cue-fg",
     "--cue-fg-muted",
-    "--cue-fg-subtle",
     "--cue-font-mono",
     "--cue-leading-ui",
     "--cue-paint-rim-width",
@@ -172,6 +171,7 @@
     "--cue-style-body-size",
     "--cue-style-body-weight",
     "--cue-style-control-face",
+    "--cue-style-control-radius",
     "--cue-style-display-variation",
     "--cue-style-group-label-ink",
     "--cue-style-group-label-pad",

package/manifest/fixtures.json

@@ -37,6 +37,16 @@
       "kind": "node",
       "label": "Three toggles"
     },
+    {
+      "id": "media.motif",
+      "kind": "node",
+      "label": "A seeded motif"
+    },
+    {
+      "id": "media.stats",
+      "kind": "node",
+      "label": "A band of four figures"
+    },
     {
       "id": "bento.tiles",
       "kind": "node",
@@ -119,6 +129,14 @@
       "kind": "array",
       "label": "5 cue rows"
     },
+    {
+      "id": "sample.stats",
+      "kind": "array",
+      "label": "4 named figures",
+      "accepts": [
+        "readonly StatBandStat[]"
+      ]
+    },
     {
       "id": "sample.blend-modes",
       "kind": "array",