@cueplusplus/ui 0.1.0 → 0.3.0

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\" | \"top\" | \"bottom\" | \"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/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
+}

package/manifest/components/kbd.json

@@ -0,0 +1,52 @@
+{
+  "name": "Kbd",
+  "slug": "kbd",
+  "group": "primitives",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "A key cap for documenting shortcuts inline: `⌘K`, `Esc`, `Shift`.\n\nStatic markup — no `\"use client\"`, so it renders on the server. Sized off the\nchip height so a `Kbd` and a `Chip` line up on the same row, and set in the\nmicro type step because shortcut hints are reference material, not content.",
+  "props": [],
+  "typeReferences": [
+    "React.ComponentPropsWithoutRef<\"kbd\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-border",
+    "--cue-chip-h",
+    "--cue-fg-muted",
+    "--cue-font-mono",
+    "--cue-radius-control",
+    "--cue-space-2",
+    "--cue-surface-2",
+    "--cue-text-micro"
+  ],
+  "summary": "A key cap for documenting shortcuts inline: `⌘K`, `Esc`, `Shift`.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<span>Press <Kbd>⌘</Kbd><Kbd>K</Kbd> to search</span>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/kbd",
+  "mdUrl": "/docs/components/kbd.md",
+  "jsonUrl": "/r/components/kbd.json",
+  "specimens": [
+    {
+      "title": "Kbd",
+      "group": "primitives",
+      "components": [
+        "Kbd"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"single\">\n    <Kbd>G</Kbd>\n  </Specimen>\n  <Specimen label=\"chord\">\n    <Kbd>⌘K</Kbd>\n  </Specimen>\n  <Specimen label=\"in a line\">\n    <span className=\"font-mono text-(length:--cue-text-ui) text-fg-muted\">\n      Press <Kbd>⌘</Kbd> <Kbd>⇧</Kbd> <Kbd>P</Kbd> to open the palette.\n    </span>\n  </Specimen>\n</Specimens>",
+      "note": "A key cap, in the mono face. Static markup, so it renders on the server.",
+      "interaction": "none."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/link.json

@@ -0,0 +1,81 @@
+{
+  "name": "Link",
+  "slug": "link",
+  "group": "layout",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A text link: accent on hover, no rule unless you ask for one.",
+  "props": [
+    {
+      "name": "external",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Open in a new tab, mark the anchor `rel=\"noreferrer noopener\"` and append a\n`↗`. The glyph is not decoration: a link that replaces the user's context\nwithout warning is a WCAG 3.2.5 failure, and the arrow is the warning."
+    },
+    {
+      "name": "render",
+      "type": "RenderProp<Record<string, unknown>>",
+      "required": false,
+      "defaultValue": null,
+      "description": "Replace the rendered element (Base UI render prop). Accepts an element —\n`render={<NextLink href=\"/x\" />}` — or a function returning one. This is\nhow the design system composes with a router without depending on one."
+    },
+    {
+      "name": "variant",
+      "type": "\"plain\" | \"underline\"",
+      "required": false,
+      "defaultValue": "plain",
+      "description": ""
+    }
+  ],
+  "typeReferences": [
+    "React.ComponentPropsWithoutRef<\"a\">",
+    "VariantProps<typeof linkVariants>"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {
+    "variant": [
+      "plain",
+      "underline"
+    ]
+  },
+  "defaultVariants": {
+    "variant": "plain"
+  },
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-border",
+    "--cue-fg",
+    "--cue-font-mono",
+    "--cue-radius-control",
+    "--cue-space-1",
+    "--cue-text-micro"
+  ],
+  "summary": "A text link: accent on hover, no rule unless you ask for one.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Link href=\"/patch\">Patch</Link>\n<Link href=\"https://base-ui.com\" external variant=\"underline\">Base UI</Link>\n<Link render={<NextLink href=\"/cues\" />}>Cues</Link>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/link",
+  "mdUrl": "/docs/components/link.md",
+  "jsonUrl": "/r/components/link.json",
+  "specimens": [
+    {
+      "title": "Link",
+      "group": "layout",
+      "components": [
+        "Link"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"plain\">\n    <Link href=\"#patch\">Open the patch</Link>\n  </Specimen>\n  <Specimen label=\"underline\">\n    <Link href=\"#patch\" variant=\"underline\">\n      Open the patch\n    </Link>\n  </Specimen>\n  <Specimen label=\"external\">\n    <Link href=\"https://cueplusplus.com\" external>\n      cueplusplus.com\n    </Link>\n  </Specimen>\n</Specimens>",
+      "note": "Two variants. Links do not underline by default; the underline variant offsets by 4px so descenders survive.",
+      "interaction": "hover moves the ink to the accent."
+    }
+  ],
+  "todo": true
+}