@cueplusplus/ui 0.3.0 → 0.6.0

package/dist/forms/_chassis.d.ts

@@ -20,10 +20,84 @@ type FormControlSize = "sm" | "md" | "lg";
  * raising them off it, which is the portfolio-wide convention for anything the
  * user types into.
  *
+ * **Focus is one signal, not two.** The rim walks one rung up the border ladder
+ * on `:focus` — `border-border` to `border-border-strong` — and `:focus-visible`
+ * adds a single 2px outline, pulled back over that rim with
+ * `-outline-offset-1` so it sits flush against the control instead of floating
+ * a pixel clear of it. The recipe this replaced painted a saturated accent rim
+ * *and* an offset accent ring simultaneously, which in a dark, dense console
+ * reads as an error or a selection rather than as "the caret is here". No
+ * shipping system draws both: Carbon and Radix each draw one flush ring, and
+ * shadcn moved off the offset-ring default it used to ship.
+ *
+ * Flush is also the cheap way to stay correct. WCAG 2.4.13 accepts a 2px
+ * perimeter only when it touches the component's own outer edge; an indicator
+ * inset further, floating on a gap, has to be 3px thick to cover the same area.
+ * And because an outline is painted outside the layout box, none of this moves
+ * a control by a pixel or reflows the row it sits in.
+ *
+ * There is no quieter pointer path to fall back on, which is why the single
+ * treatment has to be quiet itself: every engine puts typing surfaces on the
+ * `:focus-visible` allowlist, so a text input matches it on a mouse click just
+ * as it does on Tab. Only the non-typing controls that ride this chassis — the
+ * `Select` trigger, the date triggers — actually distinguish the two.
+ *
+ * `--cue-focus`, not `--cue-accent`. Every theme ships both roles, and keeping
+ * them separable is what WCAG 1.4.11 needs: one role whose job is "read at 3:1
+ * against the surface behind the ring", independent of the role whose job is
+ * "look like the brand". Seventeen of the twenty theme blocks still set the two
+ * to the same value, so there the separation costs nothing on screen — but three
+ * light presets can no longer afford it. luma.light, venu.light and hivehub.light
+ * each read below 3:1 against surfaces a field actually sits on (luma.light as
+ * low as 2.45, and against four of its five grounds), so each now carries its
+ * own ring — the accent's hue stepped darker — while the accent itself stays
+ * put. Measured across all five grounds a field can land on — the sunken fill,
+ * the page background and the three surface rungs — every preset now clears
+ * 3:1, the thinnest being signal.light's 3.27. Pointing the ring at the focus
+ * role is what made that retune possible without repainting every accent
+ * surface in the theme.
+ *
+ * (Named in prose rather than as `--cue-*` on purpose: `tokensUsed` in the
+ * published manifest is scanned out of this file's text, so spelling the other
+ * four grounds as tokens would have every control on this chassis claim it
+ * paints a surface it never touches.)
+ *
+ * `--cue-danger` carries the same obligation on an invalid field, where it is
+ * the ring rather than only the rim — a 1.4.11 surface, not purely a semantic
+ * colour. It needed no retune: the red already clears 3:1 on all five grounds in
+ * every preset, thinnest at terminal.dark's 3.13. Both floors are held by
+ * `test/theming/contrast.test.ts`, which measures every block on every ground —
+ * the guard that was missing when these three shipped a ring nobody could see.
+ *
+ * The ring is an `outline` and never a `box-shadow`: `forced-colors: active`
+ * discards box shadows outright and repaints outlines in the user's own
+ * highlight colour, so an outline is the only indicator that survives
+ * high-contrast mode.
+ *
+ * **Invalid and focused: the ring turns red, it does not sit beside the rim.**
+ * `data-[invalid]:border-danger` does win the cascade over the focus rim, but
+ * winning it changes nothing on screen: an outline's band runs from
+ * `border-edge + offset` outward by its own width, so a 2px ring at
+ * `-outline-offset-1` spans from one pixel inside the border box to one pixel
+ * outside it — the whole 1px rim — and outlines paint after borders. Measured
+ * in both engines: an invalid control paints 456 danger pixels at rest and zero
+ * while focused. Pushing the ring off the rim would mean either floating it on
+ * a gap (WCAG 2.4.13 then wants 3px, and the halo is back) or insetting it
+ * further (which buries it deeper). So the ring takes the danger colour instead
+ * — `data-[invalid]:focus-visible:outline-danger` — which is the ruling shadcn
+ * and Radix both reached: the border stays danger, the ring communicates focus,
+ * and red communicates invalid whichever of the two is painting.
+ *
+ * The compound modifier outranks the plain one on specificity — an attribute
+ * selector and a pseudo-class against one pseudo-class — so its position in
+ * Tailwind's utility order cannot decide it. `focus-visible:outline-solid` and
+ * `focus-visible:outline-2` still supply the style and the width in both cases,
+ * which is why only the colour is restated.
+ *
  * `focus-visible:outline-solid` re-declares the outline style the sibling
  * `outline-none` switched off — see the note on `buttonChassis`.
  */
-declare const controlSurface = "w-full rounded-(--radius-control) border border-border bg-sunken font-mono text-fg placeholder:text-fg-subtle outline-none focus:border-accent focus-visible:outline-2 focus-visible:outline-solid focus-visible:outline-offset-1 focus-visible:outline-accent disabled:opacity-40 data-[disabled]:opacity-40 data-[invalid]:border-danger";
+declare const controlSurface = "w-full rounded-(--radius-control) border border-border bg-sunken font-mono text-fg placeholder:text-fg-subtle outline-none focus:border-border-strong focus-visible:outline-2 focus-visible:outline-solid focus-visible:-outline-offset-1 focus-visible:outline-(--cue-focus) disabled:opacity-40 data-[disabled]:opacity-40 data-[invalid]:border-danger data-[invalid]:focus-visible:outline-danger";
 /**
  * The full recessed-control recipe, one variant per rung of the control ladder.
  *
@@ -56,9 +130,35 @@ declare const controlClasses: string;
 declare const bareControlClasses = "min-w-0 flex-1 border-0 bg-transparent p-0 font-mono text-[length:inherit] text-fg placeholder:text-fg-subtle outline-none disabled:opacity-40";
 /**
  * Focus feedback for a wrapper that owns the rim on behalf of an inner control.
- * A `<div>` never matches `:focus-visible`, so the group has to watch its
- * descendants instead.
+ *
+ * A `<div>` never matches `:focus-visible` itself, so a group has to read the
+ * state off its descendants — and the two halves of {@link controlSurface}'s
+ * treatment want two different questions asked of them.
+ *
+ * The rim follows plain `:focus-within`: anything focused inside strengthens the
+ * border. That is the quiet half, and it is the right answer however the focus
+ * arrived. The ring follows `:has(:focus-visible)`, so it paints only when the
+ * descendant that has focus is itself showing a focus ring. Using
+ * `:focus-within` for *both* — the recipe this replaced — is what made a mouse
+ * click inside a `SearchInput` or a `NumberField` light the whole cluster up
+ * with a saturated block, the single loudest thing in a console form.
+ *
+ * `:has()` is Baseline — Chrome 105, Safari 15.4, Firefox 121 — so no
+ * `:focus-within` fallback layer is needed at the floor this library supports.
+ *
+ * Geometry matches {@link controlSurface} exactly, down to the negative offset:
+ * a grouped field and a plain one are the same control, and a rim that differed
+ * by a pixel between them would say otherwise. The inner control stays ringless
+ * — see {@link bareControlClasses} — because two concentric rings on one field
+ * is the halo this treatment exists to remove.
+ *
+ * The invalid ruling comes with the geometry, for the same reason: at
+ * `-outline-offset-1` the ring covers the rim it is drawn over, so an invalid
+ * group in focus recolours the ring rather than pretending the red under it is
+ * still visible. `data-invalid` is read off the wrapper, which is where Base
+ * UI's `Field` stamps it and where the group already takes
+ * `data-[invalid]:border-danger` from {@link controlVariants}.
  */
-declare const controlGroupFocusClasses = "focus-within:border-accent focus-within:outline-2 focus-within:outline-solid focus-within:outline-offset-1 focus-within:outline-accent";
+declare const controlGroupFocusClasses = "focus-within:border-border-strong has-focus-visible:outline-2 has-focus-visible:outline-solid has-focus-visible:-outline-offset-1 has-focus-visible:outline-(--cue-focus) data-[invalid]:has-focus-visible:outline-danger";
 //#endregion
 export { ControlVariantProps, FormControlSize, bareControlClasses, controlClasses, controlGroupFocusClasses, controlSurface, controlVariants };

package/dist/forms/_chassis.js

@@ -12,10 +12,84 @@ import { cva } from "../lib/cva.js";
 * raising them off it, which is the portfolio-wide convention for anything the
 * user types into.
 *
+* **Focus is one signal, not two.** The rim walks one rung up the border ladder
+* on `:focus` — `border-border` to `border-border-strong` — and `:focus-visible`
+* adds a single 2px outline, pulled back over that rim with
+* `-outline-offset-1` so it sits flush against the control instead of floating
+* a pixel clear of it. The recipe this replaced painted a saturated accent rim
+* *and* an offset accent ring simultaneously, which in a dark, dense console
+* reads as an error or a selection rather than as "the caret is here". No
+* shipping system draws both: Carbon and Radix each draw one flush ring, and
+* shadcn moved off the offset-ring default it used to ship.
+*
+* Flush is also the cheap way to stay correct. WCAG 2.4.13 accepts a 2px
+* perimeter only when it touches the component's own outer edge; an indicator
+* inset further, floating on a gap, has to be 3px thick to cover the same area.
+* And because an outline is painted outside the layout box, none of this moves
+* a control by a pixel or reflows the row it sits in.
+*
+* There is no quieter pointer path to fall back on, which is why the single
+* treatment has to be quiet itself: every engine puts typing surfaces on the
+* `:focus-visible` allowlist, so a text input matches it on a mouse click just
+* as it does on Tab. Only the non-typing controls that ride this chassis — the
+* `Select` trigger, the date triggers — actually distinguish the two.
+*
+* `--cue-focus`, not `--cue-accent`. Every theme ships both roles, and keeping
+* them separable is what WCAG 1.4.11 needs: one role whose job is "read at 3:1
+* against the surface behind the ring", independent of the role whose job is
+* "look like the brand". Seventeen of the twenty theme blocks still set the two
+* to the same value, so there the separation costs nothing on screen — but three
+* light presets can no longer afford it. luma.light, venu.light and hivehub.light
+* each read below 3:1 against surfaces a field actually sits on (luma.light as
+* low as 2.45, and against four of its five grounds), so each now carries its
+* own ring — the accent's hue stepped darker — while the accent itself stays
+* put. Measured across all five grounds a field can land on — the sunken fill,
+* the page background and the three surface rungs — every preset now clears
+* 3:1, the thinnest being signal.light's 3.27. Pointing the ring at the focus
+* role is what made that retune possible without repainting every accent
+* surface in the theme.
+*
+* (Named in prose rather than as `--cue-*` on purpose: `tokensUsed` in the
+* published manifest is scanned out of this file's text, so spelling the other
+* four grounds as tokens would have every control on this chassis claim it
+* paints a surface it never touches.)
+*
+* `--cue-danger` carries the same obligation on an invalid field, where it is
+* the ring rather than only the rim — a 1.4.11 surface, not purely a semantic
+* colour. It needed no retune: the red already clears 3:1 on all five grounds in
+* every preset, thinnest at terminal.dark's 3.13. Both floors are held by
+* `test/theming/contrast.test.ts`, which measures every block on every ground —
+* the guard that was missing when these three shipped a ring nobody could see.
+*
+* The ring is an `outline` and never a `box-shadow`: `forced-colors: active`
+* discards box shadows outright and repaints outlines in the user's own
+* highlight colour, so an outline is the only indicator that survives
+* high-contrast mode.
+*
+* **Invalid and focused: the ring turns red, it does not sit beside the rim.**
+* `data-[invalid]:border-danger` does win the cascade over the focus rim, but
+* winning it changes nothing on screen: an outline's band runs from
+* `border-edge + offset` outward by its own width, so a 2px ring at
+* `-outline-offset-1` spans from one pixel inside the border box to one pixel
+* outside it — the whole 1px rim — and outlines paint after borders. Measured
+* in both engines: an invalid control paints 456 danger pixels at rest and zero
+* while focused. Pushing the ring off the rim would mean either floating it on
+* a gap (WCAG 2.4.13 then wants 3px, and the halo is back) or insetting it
+* further (which buries it deeper). So the ring takes the danger colour instead
+* — `data-[invalid]:focus-visible:outline-danger` — which is the ruling shadcn
+* and Radix both reached: the border stays danger, the ring communicates focus,
+* and red communicates invalid whichever of the two is painting.
+*
+* The compound modifier outranks the plain one on specificity — an attribute
+* selector and a pseudo-class against one pseudo-class — so its position in
+* Tailwind's utility order cannot decide it. `focus-visible:outline-solid` and
+* `focus-visible:outline-2` still supply the style and the width in both cases,
+* which is why only the colour is restated.
+*
 * `focus-visible:outline-solid` re-declares the outline style the sibling
 * `outline-none` switched off — see the note on `buttonChassis`.
 */
-const controlSurface = "w-full rounded-(--radius-control) border border-border bg-sunken font-mono text-fg placeholder:text-fg-subtle outline-none focus:border-accent focus-visible:outline-2 focus-visible:outline-solid focus-visible:outline-offset-1 focus-visible:outline-accent disabled:opacity-40 data-[disabled]:opacity-40 data-[invalid]:border-danger";
+const controlSurface = "w-full rounded-(--radius-control) border border-border bg-sunken font-mono text-fg placeholder:text-fg-subtle outline-none focus:border-border-strong focus-visible:outline-2 focus-visible:outline-solid focus-visible:-outline-offset-1 focus-visible:outline-(--cue-focus) disabled:opacity-40 data-[disabled]:opacity-40 data-[invalid]:border-danger data-[invalid]:focus-visible:outline-danger";
 /**
 * The full recessed-control recipe, one variant per rung of the control ladder.
 *
@@ -51,9 +125,35 @@ const controlClasses = controlVariants();
 const bareControlClasses = "min-w-0 flex-1 border-0 bg-transparent p-0 font-mono text-[length:inherit] text-fg placeholder:text-fg-subtle outline-none disabled:opacity-40";
 /**
 * Focus feedback for a wrapper that owns the rim on behalf of an inner control.
-* A `<div>` never matches `:focus-visible`, so the group has to watch its
-* descendants instead.
+*
+* A `<div>` never matches `:focus-visible` itself, so a group has to read the
+* state off its descendants — and the two halves of {@link controlSurface}'s
+* treatment want two different questions asked of them.
+*
+* The rim follows plain `:focus-within`: anything focused inside strengthens the
+* border. That is the quiet half, and it is the right answer however the focus
+* arrived. The ring follows `:has(:focus-visible)`, so it paints only when the
+* descendant that has focus is itself showing a focus ring. Using
+* `:focus-within` for *both* — the recipe this replaced — is what made a mouse
+* click inside a `SearchInput` or a `NumberField` light the whole cluster up
+* with a saturated block, the single loudest thing in a console form.
+*
+* `:has()` is Baseline — Chrome 105, Safari 15.4, Firefox 121 — so no
+* `:focus-within` fallback layer is needed at the floor this library supports.
+*
+* Geometry matches {@link controlSurface} exactly, down to the negative offset:
+* a grouped field and a plain one are the same control, and a rim that differed
+* by a pixel between them would say otherwise. The inner control stays ringless
+* — see {@link bareControlClasses} — because two concentric rings on one field
+* is the halo this treatment exists to remove.
+*
+* The invalid ruling comes with the geometry, for the same reason: at
+* `-outline-offset-1` the ring covers the rim it is drawn over, so an invalid
+* group in focus recolours the ring rather than pretending the red under it is
+* still visible. `data-invalid` is read off the wrapper, which is where Base
+* UI's `Field` stamps it and where the group already takes
+* `data-[invalid]:border-danger` from {@link controlVariants}.
 */
-const controlGroupFocusClasses = "focus-within:border-accent focus-within:outline-2 focus-within:outline-solid focus-within:outline-offset-1 focus-within:outline-accent";
+const controlGroupFocusClasses = "focus-within:border-border-strong has-focus-visible:outline-2 has-focus-visible:outline-solid has-focus-visible:-outline-offset-1 has-focus-visible:outline-(--cue-focus) data-[invalid]:has-focus-visible:outline-danger";
 //#endregion
 export { bareControlClasses, controlClasses, controlGroupFocusClasses, controlSurface, controlVariants };

package/dist/forms/input-group.d.ts

@@ -17,9 +17,14 @@ interface InputGroupProps extends React.ComponentPropsWithoutRef<"div"> {
  * The group — not the input — owns the chassis, so there is exactly one rim and
  * one fill however many affordances are bolted on. It publishes that fact
  * through context: an {@link Input} rendered inside strips its own border,
- * background, height and padding and inherits the group's font size. Focus
- * feedback moves to `focus-within`, since a `<div>` never matches
- * `:focus-visible`.
+ * background, height and padding and inherits the group's font size.
+ *
+ * Focus feedback splits in two, because a `<div>` matches neither `:focus` nor
+ * `:focus-visible` itself. The rim strengthens on `:focus-within` — anything
+ * focused inside, however it got there — while the ring waits for
+ * `:has(:focus-visible)`, so a mouse click into the field does not light the
+ * whole cluster up. Both halves live on the wrapper; the inner control paints
+ * no ring of its own.
  *
  * @example
  * <InputGroup leading={<Search />} trailing={<Kbd>⌘K</Kbd>}>

package/dist/forms/input-group.js

@@ -17,9 +17,14 @@ const InputGroupContext = React.createContext(false);
 * The group — not the input — owns the chassis, so there is exactly one rim and
 * one fill however many affordances are bolted on. It publishes that fact
 * through context: an {@link Input} rendered inside strips its own border,
-* background, height and padding and inherits the group's font size. Focus
-* feedback moves to `focus-within`, since a `<div>` never matches
-* `:focus-visible`.
+* background, height and padding and inherits the group's font size.
+*
+* Focus feedback splits in two, because a `<div>` matches neither `:focus` nor
+* `:focus-visible` itself. The rim strengthens on `:focus-within` — anything
+* focused inside, however it got there — while the ring waits for
+* `:has(:focus-visible)`, so a mouse click into the field does not light the
+* whole cluster up. Both halves live on the wrapper; the inner control paints
+* no ring of its own.
 *
 * @example
 * <InputGroup leading={<Search />} trailing={<Kbd>⌘K</Kbd>}>

package/dist/forms/number-field.d.ts

@@ -25,8 +25,9 @@ interface NumberFieldProps extends Omit<NumberField.Root.Props, "className"> {
  * and values typed out of range are clamped to `min`/`max` on blur.
  *
  * The group owns the rim; the input and both buttons render bare inside it, so
- * the whole cluster reads as one field and focus feedback moves to
- * `focus-within`.
+ * the whole cluster reads as one field. Focus feedback follows the group's
+ * split: the rim strengthens on `:focus-within`, and the ring waits for
+ * `:has(:focus-visible)` so a click on a stepper does not paint one.
  *
  * @example
  * <NumberField aria-label="Fade time" defaultValue={3} min={0} max={600} step={0.5} />

package/dist/forms/number-field.js

@@ -17,8 +17,9 @@ const stepperClasses = "flex shrink-0 items-center justify-center border-0 bg-tr
 * and values typed out of range are clamped to `min`/`max` on blur.
 *
 * The group owns the rim; the input and both buttons render bare inside it, so
-* the whole cluster reads as one field and focus feedback moves to
-* `focus-within`.
+* the whole cluster reads as one field. Focus feedback follows the group's
+* split: the rim strengthens on `:focus-within`, and the ring waits for
+* `:has(:focus-visible)` so a click on a stepper does not paint one.
 *
 * @example
 * <NumberField aria-label="Fade time" defaultValue={3} min={0} max={600} step={0.5} />

package/dist/icons/containers.d.ts

@@ -0,0 +1,89 @@
+import * as React from "react";
+//#region src/icons/containers.d.ts
+/**
+ * The catalogue itself: everything there is, before anything has been narrowed.
+ *
+ * One tile repeated over a 2×2 rather than a stack of rows, because the row
+ * this marks is the one that *undoes* a filter — "all of it" is a shape, and a
+ * list glyph would have promised an ordering the row does not have.
+ */
+declare function CatalogueIcon(props: React.SVGProps<SVGSVGElement>): React.JSX.Element;
+/**
+ * One person's stack: the set of things they have actually installed.
+ *
+ * Plates seen edge-on — the layers idiom — because a stack is an accumulation
+ * and not a container: things go into it one at a time and the order they went
+ * in is part of what it is.
+ */
+declare function StackIcon(props: React.SVGProps<SVGSVGElement>): React.JSX.Element;
+/**
+ * Every stack at once, one column each: who has what, read across.
+ *
+ * A table rather than more plates. The head rule and the name column are what
+ * make it a matrix instead of a grid — the question it answers is "which of
+ * these does that person not have", and that is a question with two axes.
+ */
+declare function StacksMatrixIcon(props: React.SVGProps<SVGSVGElement>): React.JSX.Element;
+/**
+ * An audience: a named group of people something is published to.
+ *
+ * People, not an abstract shape. An audience is the one container in this set
+ * whose members are humans rather than artefacts, and drawing it as a diamond
+ * or a tag would have filed it with the folders — which is exactly the mistake
+ * a reader makes when deciding where to publish something.
+ */
+declare function AudienceIcon(props: React.SVGProps<SVGSVGElement>): React.JSX.Element;
+/**
+ * The released channel: what a colleague gets when they install without asking
+ * for anything in particular.
+ *
+ * A ring filled solid. Its pair, {@link ChannelBetaIcon}, is the same ring
+ * filled halfway — the two are one mark told twice, so a reader never has to
+ * learn which of two unrelated pictures means "finished".
+ */
+declare function ChannelReleasedIcon(props: React.SVGProps<SVGSVGElement>): React.JSX.Element;
+/**
+ * The beta channel: the same things, one merge earlier.
+ *
+ * The released ring at half fill. Half rather than empty because a beta is not
+ * an absence of a release — it is a release that has not finished happening,
+ * and an empty ring would have read as "nothing here yet".
+ */
+declare function ChannelBetaIcon(props: React.SVGProps<SVGSVGElement>): React.JSX.Element;
+/**
+ * A folder somebody made: a shelf of bookmarks, filed by hand.
+ *
+ * The tab is the whole glyph. A plain rounded box in this library is a panel,
+ * a card or a dialog, and the one thing a folder has to say is that a person
+ * put these here on purpose rather than a query having returned them.
+ */
+declare function FolderIcon(props: React.SVGProps<SVGSVGElement>): React.JSX.Element;
+/**
+ * An MCP server in the registry: a thing an agent connects *to*.
+ *
+ * Two rack units with a status lamp each. It is drawn as hardware on purpose —
+ * an MCP server is the one entry in a catalogue of files that is a running
+ * process somewhere, with an address and a session, and a row that looked like
+ * a document would hide the only fact about it that matters operationally.
+ */
+declare function McpServerIcon(props: React.SVGProps<SVGSVGElement>): React.JSX.Element;
+/**
+ * A CLI tool in the registry: a thing that runs in a terminal.
+ *
+ * A window with a prompt in it, rather than a bare chevron. A chevron on its
+ * own is a disclosure everywhere else in this library, and a navigation row
+ * that appeared to expand and then navigated instead is a worse failure than a
+ * slightly busier glyph at 10px.
+ */
+declare function CliToolIcon(props: React.SVGProps<SVGSVGElement>): React.JSX.Element;
+/**
+ * A skill: the thing every other container in this set holds.
+ *
+ * One mark, and a spark rather than a document, because what is being filed is
+ * a capability. The file it happens to be written in is an implementation
+ * detail of how it travels, and a page glyph would have made the catalogue look
+ * like a folder of documents rather than a list of things an agent can now do.
+ */
+declare function SkillIcon(props: React.SVGProps<SVGSVGElement>): React.JSX.Element;
+//#endregion
+export { AudienceIcon, CatalogueIcon, ChannelBetaIcon, ChannelReleasedIcon, CliToolIcon, FolderIcon, McpServerIcon, SkillIcon, StackIcon, StacksMatrixIcon };