@cueplusplus/ui 0.2.0 → 0.5.0

package/manifest/components/icon-button.json

@@ -0,0 +1,88 @@
+{
+  "name": "IconButton",
+  "slug": "icon-button",
+  "group": "primitives",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A square, icon-only button for toolbars, row affordances and panel headers.\n\nDefaults to the `ghost` variant: in a dense console most icon buttons should\nbe invisible until hovered, speaking through text colour rather than a rim.",
+  "props": [
+    {
+      "name": "aria-label",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Required. An icon-only control has no text to name it, so the label is not\noptional — the type makes forgetting it a compile error."
+    },
+    {
+      "name": "icon",
+      "type": "ElementType<any, keyof IntrinsicElements>",
+      "required": true,
+      "defaultValue": null,
+      "description": "The icon component to render (e.g. a lucide icon). Rendered `aria-hidden`\nand sized to the density icon token."
+    },
+    {
+      "name": "render",
+      "type": "RenderProp<Record<string, unknown>>",
+      "required": false,
+      "defaultValue": null,
+      "description": "Replace the rendered element (Base UI render prop)."
+    },
+    {
+      "name": "size",
+      "type": "\"sm\" | \"md\" | \"lg\"",
+      "required": false,
+      "defaultValue": "md",
+      "description": ""
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"button\">, \"children\">",
+    "VariantProps<typeof iconButtonVariants>"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ]
+  },
+  "defaultVariants": {
+    "variant": "ghost",
+    "size": "md"
+  },
+  "tokensUsed": [
+    "--cue-control-lg",
+    "--cue-control-md",
+    "--cue-control-sm",
+    "--cue-icon-md",
+    "--cue-icon-sm"
+  ],
+  "summary": "A square, icon-only button for toolbars, row affordances and panel headers.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<IconButton aria-label=\"Close panel\" icon={X} />\n<IconButton aria-label=\"Delete cue\" icon={Trash} variant=\"danger-outline\" size=\"sm\" />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/icon-button",
+  "mdUrl": "/docs/components/icon-button.md",
+  "jsonUrl": "/r/components/icon-button.json",
+  "specimens": [
+    {
+      "title": "IconButton",
+      "group": "primitives",
+      "components": [
+        "IconButton"
+      ],
+      "code": "<Specimens>\n  {BUTTON_VARIANTS.map((variant) => (\n    <Specimen key={variant} label={variant}>\n      <IconButton aria-label={`Play, ${variant}`} icon={Play} variant={variant} />\n    </Specimen>\n  ))}\n  <Specimen label=\"disabled\">\n    <IconButton aria-label=\"Delete cue\" icon={Trash2} disabled />\n  </Specimen>\n  {SIZES.map((size) => (\n    <Specimen key={size} label={`size ${size}`}>\n      <IconButton aria-label={`Pause, ${size}`} icon={Pause} size={size} />\n    </Specimen>\n  ))}\n</Specimens>",
+      "note": "A square button with a required accessible name. There is no unlabelled variant.",
+      "interaction": "same ring as Button; the hit target stays at the control height even when the glyph shrinks."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/image-generation.json

@@ -0,0 +1,67 @@
+{
+  "name": "ImageGeneration",
+  "slug": "image-generation",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "A dot grid holds the frame while the image resolves out of a blur.",
+  "props": [
+    {
+      "name": "prompt",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Prompt text shown under the image frame."
+    },
+    {
+      "name": "generating",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "When true the frame holds a pulsing dot grid; otherwise the image resolves."
+    }
+  ],
+  "typeReferences": [
+    "Omit<ComponentProps<\"div\">, \"children\" | \"prompt\" | \"generating\"> & {\n  /** Prompt text shown under the image frame. */\n  prompt: string;\n  /** When true the frame holds a pulsing dot grid; otherwise the image resolves. */\n  generating: boolean;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-radius-overlay",
+    "--cue-surface-3",
+    "--cue-text-ui"
+  ],
+  "summary": "A dot grid holds the frame while the image resolves out of a blur.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { ImageGeneration } from \"@cueplusplus/ui/elements\";\n\n<ImageGeneration prompt=\"A calm blue abstract\" generating={false} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/image-generation",
+  "mdUrl": "/docs/components/image-generation.md",
+  "jsonUrl": "/r/components/image-generation.json",
+  "specimens": [
+    {
+      "title": "ImageGeneration",
+      "group": "elements-agents",
+      "components": [
+        "ImageGeneration"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"generating\">\n    <ImageGeneration prompt=\"Pre-vis: front wash at 8.4 m trim\" generating />\n  </Specimen>\n  <Specimen label=\"resolved\">\n    <ImageGeneration prompt=\"Pre-vis: front wash at 8.4 m trim\" generating={false} />\n  </Specimen>\n</Specimens>",
+      "note": "A dot grid holds the square while the image resolves out of a blur — the frame is the right size from the first frame, so nothing below it moves when the picture lands. While generating, the prompt is replaced by a shimmering label; when it settles, the prompt is what is left under the image.",
+      "interaction": "regenerate is a labelled icon button. The grid and the image are both `aria-hidden`: the prompt underneath is the description, and a decorative placeholder should not be announced as a picture."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/info-tip.json

@@ -0,0 +1,98 @@
+{
+  "name": "InfoTip",
+  "slug": "info-tip",
+  "group": "overlays",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "The 13px circular \"i\" badge: a footnote marker for a field, a column or a\nnumber whose definition is not obvious.\n\nA real focusable `<button>`, not a bare `<span>` with a hover handler — the\nexplanation has to be reachable from the keyboard, and the badge's own\n`cursor-help` is the only hint sighted users get that it is there at all.\nEverything else (portal theme stamping, `role=\"tooltip\"`, dismissal) comes\nfrom {@link Tooltip}.\n\nThe badge stays 13px across densities on purpose: it is a punctuation mark\nsitting in a line of text, so it tracks the text, not the control ladder.",
+  "props": [
+    {
+      "name": "text",
+      "type": "ReactNode",
+      "required": true,
+      "defaultValue": null,
+      "description": "The explanation to reveal. One or two sentences; longer belongs in a `Popover`."
+    },
+    {
+      "name": "width",
+      "type": "number",
+      "required": false,
+      "defaultValue": "224",
+      "description": "Width of the revealed panel in px, applied as rem so it scales with the\nroot font size. Defaults to `224`."
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "required": false,
+      "defaultValue": "More information",
+      "description": "Accessible name for the badge. Defaults to `\"More information\"`."
+    },
+    {
+      "name": "side",
+      "type": "\"left\" | \"right\" | \"bottom\" | \"top\" | \"inline-end\" | \"inline-start\"",
+      "required": false,
+      "defaultValue": "top",
+      "description": "Preferred side of the badge. Defaults to `\"top\"`."
+    },
+    {
+      "name": "align",
+      "type": "\"center\" | \"end\" | \"start\"",
+      "required": false,
+      "defaultValue": null,
+      "description": "Alignment along that side. Defaults to `\"center\"`."
+    },
+    {
+      "name": "delay",
+      "type": "number",
+      "required": false,
+      "defaultValue": "200",
+      "description": "Hover delay in ms before the panel appears. Defaults to `200`."
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes for the badge."
+    }
+  ],
+  "typeReferences": [],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-border-strong",
+    "--cue-fg-muted",
+    "--cue-font-mono",
+    "--cue-text-micro"
+  ],
+  "summary": "The 13px circular \"i\" badge: a footnote marker for a field, a column or a number whose definition is not obvious.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<FieldLabel>Pace <InfoTip text=\"Where usage should be by today, pro-rated.\" /></FieldLabel>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/info-tip",
+  "mdUrl": "/docs/components/info-tip.md",
+  "jsonUrl": "/r/components/info-tip.json",
+  "specimens": [
+    {
+      "title": "Tooltip / InfoTip",
+      "group": "overlays",
+      "components": [
+        "Tooltip",
+        "InfoTip"
+      ],
+      "code": "<Tooltip.Provider>\n  <Specimens>\n    <Specimen label=\"tooltip\">\n      <Tooltip.Root>\n        <Tooltip.Trigger render={<IconButton aria-label=\"Go\" icon={Play} />} />\n        <Tooltip.Content>Fire the selected cue</Tooltip.Content>\n      </Tooltip.Root>\n    </Specimen>\n    <Specimen label=\"side bottom\">\n      <Tooltip.Root>\n        <Tooltip.Trigger render={<IconButton aria-label=\"Copy address\" icon={Copy} />} />\n        <Tooltip.Content side=\"bottom\">Copy 10.0.0.42</Tooltip.Content>\n      </Tooltip.Root>\n    </Specimen>\n    <Specimen label=\"info tip\">\n      <span className=\"flex items-center gap-(--cue-space-2) font-mono text-(length:--cue-text-ui) text-fg-muted\">\n        Pace tick\n        <InfoTip text=\"Where the meter would be if usage were flat across the period.\" />\n      </span>\n    </Specimen>\n    <Specimen label=\"wide info tip\">\n      <InfoTip\n        width={320}\n        label=\"About provenance\"\n        text=\"Vendor numbers are measured, estimated ones are hatched, and an unbounded meter draws no percentage at all.\"\n      />\n    </Specimen>\n  </Specimens>\n</Tooltip.Provider>",
+      "note": "A tooltip names a control; an InfoTip is the 13px `i` badge that explains one.",
+      "interaction": "tooltips open on hover and on keyboard focus, and never on touch; the InfoTip badge is a real button."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/inline-citation.json

@@ -0,0 +1,77 @@
+{
+  "name": "InlineCitation",
+  "slug": "inline-citation",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "Numbered references inside a sentence, each with a hover preview of its source.",
+  "props": [
+    {
+      "name": "sources",
+      "type": "CitationSource[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Sources attached to the numbered reference markers in the sentence."
+    },
+    {
+      "name": "openIndex",
+      "type": "number | null",
+      "required": true,
+      "defaultValue": null,
+      "description": "Which citation preview is open, or null when none is open."
+    },
+    {
+      "name": "onOpenIndexChange",
+      "type": "(index: number | null) => void",
+      "required": true,
+      "defaultValue": null,
+      "description": "Called when a citation marker opens or closes its preview."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"p\">,\n  \"children\"\n>"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-fg",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-radius-control",
+    "--cue-radius-overlay",
+    "--cue-surface-2",
+    "--cue-text-body",
+    "--cue-text-micro"
+  ],
+  "summary": "Numbered references inside a sentence, each with a hover preview of its source.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { InlineCitation } from \"@cueplusplus/ui/elements\";\n\n<InlineCitation\n  sources={[\n    {\n      domain: \"docs.example.com\",\n      title: \"Optimistic updates\",\n      snippet: \"Confirm writes after paint.\",\n    },\n  ]}\n  openIndex={0}\n  onOpenIndexChange={setOpenIndex}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/inline-citation",
+  "mdUrl": "/docs/components/inline-citation.md",
+  "jsonUrl": "/r/components/inline-citation.json",
+  "specimens": [
+    {
+      "title": "InlineCitation",
+      "group": "elements-knowledge",
+      "components": [
+        "InlineCitation"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"the first marker open\" wide>\n    <InlineCitation\n      sources={CITED}\n      openIndex={citation}\n      onOpenIndexChange={setCitation}\n    />\n  </Specimen>\n  <Specimen label=\"both closed\" wide>\n    <InlineCitation\n      sources={CITED}\n      openIndex={null}\n      onOpenIndexChange={() => undefined}\n    />\n  </Specimen>\n</Specimens>",
+      "note": "The marker inside the sentence, rather than the list under it: a numbered chip the paragraph flows around, and behind each one the page it stands on. `Sources` is the bibliography; this is the footnote, and the two are meant to be read together — the chip says a claim is attributable without spending a clause saying so.",
+      "interaction": "each marker is a button, so the preview is reachable from a keyboard as well as a pointer; the open one inverts to the accent fill. The card is the family's one portal, and it carries the island stamp — opened inside an `AgentSurface`, it paints in that island's values rather than the document's."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/input-group.json

@@ -0,0 +1,91 @@
+{
+  "name": "InputGroup",
+  "slug": "input-group",
+  "group": "forms",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A control and its adornments, drawn as a single field.\n\nThe group — not the input — owns the chassis, so there is exactly one rim and\none fill however many affordances are bolted on. It publishes that fact\nthrough context: an {@link Input } rendered inside strips its own border,\nbackground, height and padding and inherits the group's font size. Focus\nfeedback moves to `focus-within`, since a `<div>` never matches\n`:focus-visible`.",
+  "props": [
+    {
+      "name": "leading",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "Content pinned to the left gutter — a glyph, a unit prefix, a protocol."
+    },
+    {
+      "name": "trailing",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "Content pinned to the right gutter — a unit suffix, a `Kbd`, a clear button."
+    },
+    {
+      "name": "size",
+      "type": "\"sm\" | \"md\" | \"lg\"",
+      "required": false,
+      "defaultValue": null,
+      "description": "Rung of the control ladder for the whole cluster. Defaults to `\"md\"`."
+    },
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": true,
+      "defaultValue": null,
+      "description": "The control. An {@link Input } here renders bare and fills the middle."
+    }
+  ],
+  "typeReferences": [
+    "React.ComponentPropsWithoutRef<\"div\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-border",
+    "--cue-control-lg",
+    "--cue-control-md",
+    "--cue-control-sm",
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-radius-control",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-space-4",
+    "--cue-space-5",
+    "--cue-sunken",
+    "--cue-text-body",
+    "--cue-text-label",
+    "--cue-text-ui"
+  ],
+  "summary": "A control and its adornments, drawn as a single field.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<InputGroup leading={<Search />} trailing={<Kbd>⌘K</Kbd>}>\n  <Input aria-label=\"Search cues\" />\n</InputGroup>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/input-group",
+  "mdUrl": "/docs/components/input-group.md",
+  "jsonUrl": "/r/components/input-group.json",
+  "specimens": [
+    {
+      "title": "InputGroup",
+      "group": "forms",
+      "components": [
+        "InputGroup"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"leading\">\n    <InputGroup leading={<Plug aria-hidden=\"true\" className=\"size-icon-md\" />}>\n      <Input aria-label=\"Node address\" defaultValue=\"10.0.0.42\" />\n    </InputGroup>\n  </Specimen>\n  <Specimen label=\"trailing\">\n    <InputGroup trailing={<span className=\"font-mono text-fg-subtle\">%</span>}>\n      <Input aria-label=\"Level\" defaultValue=\"80\" />\n    </InputGroup>\n  </Specimen>\n  <Specimen label=\"both, sm\">\n    <InputGroup\n      size=\"sm\"\n      leading={<Ruler aria-hidden=\"true\" className=\"size-icon-sm\" />}\n      trailing={<span className=\"font-mono text-fg-subtle\">m</span>}\n    >\n      <Input aria-label=\"Throw distance\" defaultValue=\"7.5\" />\n    </InputGroup>\n  </Specimen>\n</Specimens>",
+      "note": "One rim around a control and its adornments, so the group focuses as a unit.",
+      "interaction": "focus inside the group lights the whole rim, not just the input."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/input.json

@@ -0,0 +1,89 @@
+{
+  "name": "Input",
+  "slug": "input",
+  "group": "forms",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "The single-line text control.\n\nWraps Base UI's `Input`, so dropping one inside a {@link Field } wires up the\nlabel, the description and the validity state with no `id` plumbing. Rides\nthe recessed chassis: `bg-sunken` sets it into the panel rather than raising\nit off, which is how this system distinguishes \"you type here\" from \"you\npress here\".\n\nInside an {@link InputGroup } it renders bare — the group owns the rim — so the\ntwo compose without a doubled border.",
+  "props": [
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes, merged over the chassis."
+    },
+    {
+      "name": "size",
+      "type": "\"sm\" | \"md\" | \"lg\"",
+      "required": false,
+      "defaultValue": null,
+      "description": "Rung of the control ladder. Defaults to `\"md\"`. Shadows the native `size`\nattribute (a character count), which nothing in a token-driven layout wants."
+    }
+  ],
+  "typeReferences": [
+    "Omit<BaseInput.Props, \"className\" | \"size\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-border",
+    "--cue-control-lg",
+    "--cue-control-md",
+    "--cue-control-sm",
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-radius-control",
+    "--cue-space-3",
+    "--cue-space-4",
+    "--cue-space-5",
+    "--cue-sunken",
+    "--cue-text-body",
+    "--cue-text-label",
+    "--cue-text-ui"
+  ],
+  "summary": "The single-line text control, recessed into its surface.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Input placeholder=\"e.g. Blackout\" />\n<Input type=\"number\" size=\"sm\" defaultValue={512} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/input",
+  "mdUrl": "/docs/components/input.md",
+  "jsonUrl": "/r/components/input.json",
+  "whenToUse": [
+    "Free text or a plain number the user types: names, addresses, ports, counts.",
+    "Inside a `Field`, which wires the label, the description and the error state with no id plumbing."
+  ],
+  "whenNotToUse": [
+    "A number the user adjusts by feel rather than types. Use `ScrubInput`, or `NumberField` where a stepper is expected.",
+    "A value from a known set. Use `Select`, `Combobox` or `RadioGroup`.",
+    "A search box with debounce and Escape-to-clear. Use `SearchInput`."
+  ],
+  "commonMistakes": [
+    "Expecting its own rim inside an `InputGroup`. The group owns the border; the input renders bare.",
+    "Using the placeholder as the label. A placeholder is gone the moment typing starts.",
+    "Adding a background utility. Inputs are sunken in this system, which is how a reader tells \"type here\" from \"press here\"."
+  ],
+  "specimens": [
+    {
+      "title": "Input",
+      "group": "forms",
+      "components": [
+        "Input"
+      ],
+      "code": "<Specimens>\n  {SIZES.map((size) => (\n    <Specimen key={size} label={size}>\n      <Input aria-label={`Cue label, ${size}`} size={size} defaultValue=\"1/12 @ 80%\" />\n    </Specimen>\n  ))}\n  <Specimen label=\"placeholder\">\n    <Input aria-label=\"Empty cue label\" placeholder=\"e.g. Blackout\" />\n  </Specimen>\n  <Specimen label=\"disabled\">\n    <Input aria-label=\"Disabled cue label\" defaultValue=\"Read-only\" disabled />\n  </Specimen>\n  <Specimen label=\"readonly\">\n    <Input aria-label=\"Read-only cue label\" defaultValue=\"1/12 @ 80%\" readOnly />\n  </Specimen>\n</Specimens>",
+      "note": "The recessed chassis: sunken fill, hairline rim, height from the density ladder.",
+      "interaction": "the rim goes accent on focus and the ring sits outside it; `invalid` turns the rim danger and outranks focus."
+    }
+  ]
+}

package/manifest/components/item.json

@@ -0,0 +1,129 @@
+{
+  "name": "Item",
+  "slug": "item",
+  "group": "layout",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "One thing in a list, with room for a glyph, a name, a line of detail and a\ncontrol — the shape a settings entry, a search hit and a device row all want.\n\nWhere `Row` is a line of a hairline table, `Item` is a self-contained object\nthat can stand alone, sit in a `Stack` or fill a `Grid` cell. It is a real\n`<button>` when interactive rather than a `<div>` with an `onClick`, so\nkeyboard users get it for free.\n\nStatic markup — no `\"use client\"`.",
+  "props": [
+    {
+      "name": "media",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "Leading slot: an icon, an avatar, a status dot."
+    },
+    {
+      "name": "title",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "The item's name — one line, truncated rather than wrapped."
+    },
+    {
+      "name": "description",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "One supporting line under the title, a rung smaller and muted."
+    },
+    {
+      "name": "actions",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "Trailing slot: a value, a chip, a control.\n\nDo not combine with `interactive` — the whole item is then a `<button>`,\nand a button may not contain another one. Put the controls beside the item\ninstead, or drop `interactive` and make the title itself the link."
+    },
+    {
+      "name": "variant",
+      "type": "\"plain\" | \"outline\" | \"soft\"",
+      "required": false,
+      "defaultValue": null,
+      "description": "Which framing to paint. Defaults to `\"plain\"`."
+    },
+    {
+      "name": "interactive",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Render as a `<button>` with hover feedback and a focus ring instead of a\nstatic `<div>`. Use for items that select, open or toggle something."
+    },
+    {
+      "name": "disabled",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": null,
+      "description": "Disable the interactive form. Ignored when `interactive` is not set."
+    },
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra content between the text column and the action slot."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.HTMLAttributes<HTMLElement>, \"title\">",
+    "VariantProps<typeof itemVariants>"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {
+    "variant": [
+      "plain",
+      "outline",
+      "soft"
+    ],
+    "interactive": [
+      "true",
+      "false"
+    ]
+  },
+  "defaultVariants": {
+    "variant": "plain",
+    "interactive": "false"
+  },
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-border",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-font-mono",
+    "--cue-pad-row-x",
+    "--cue-pad-row-y",
+    "--cue-radius-control",
+    "--cue-space-1",
+    "--cue-space-2",
+    "--cue-space-4",
+    "--cue-surface-2",
+    "--cue-text-label",
+    "--cue-text-ui"
+  ],
+  "summary": "One thing in a list, with room for a glyph, a name, a line of detail and a control — the shape a settings entry, a search hit and a device row all want.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Item media={<StatusDot tone=\"ok\" />} title=\"Node 12\" description=\"10.0.0.12\" />\n<Item interactive variant=\"outline\" title=\"Front truss\" onClick={open} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/item",
+  "mdUrl": "/docs/components/item.md",
+  "jsonUrl": "/r/components/item.json",
+  "specimens": [
+    {
+      "title": "Item",
+      "group": "layout",
+      "components": [
+        "Item"
+      ],
+      "code": "<div className=\"flex w-full max-w-[36rem] flex-col gap-(--cue-space-3)\">\n  <Item\n    media={<Lightbulb aria-hidden=\"true\" className=\"size-icon-md text-fg-subtle\" />}\n    title=\"Source Four 26°\"\n    description=\"Universe 1, channels 12 to 19.\"\n    actions={<Chip tone=\"ok\">patched</Chip>}\n  />\n  <Item\n    variant=\"outline\"\n    title=\"MAC Viper Profile\"\n    description=\"Universe 2, channels 1 to 32.\"\n    actions={<Button size=\"sm\">Inspect</Button>}\n  />\n  <Item variant=\"soft\" interactive title=\"Sharpy Plus\" description=\"Unpatched.\" />\n  <Item variant=\"outline\" disabled title=\"Molefay 4-lite\" description=\"Profile missing.\" />\n</div>",
+      "note": "A media, title, description and actions row. Three variants, plus interactive and disabled.",
+      "interaction": "the interactive variant takes a hover ground and a focus ring; it is a button, so Enter and Space activate it."
+    }
+  ],
+  "todo": true
+}