@cueplusplus/ui 0.13.0

package/manifest/components/copy-button.json

@@ -0,0 +1,118 @@
+{
+  "name": "CopyButton",
+  "slug": "copy-button",
+  "group": "instruments",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "Copy one string, and say so.\n\nThe confirmation is a label swap rather than a colour change or a toast: at\nconsole density a toast for \"copied an id\" is heavier than the action, and\ncolour alone would not be announced. The label lives in an `aria-live`\nregion, so screen-reader users hear the state change too (WCAG 1.4.1).\n\nFailure is never dressed up as success — if both the async clipboard and the\n`execCommand` fallback fail, the label stays put and `onCopyError` fires.",
+  "props": [
+    {
+      "name": "value",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "The text to put on the clipboard.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "timeout",
+      "type": "number",
+      "required": false,
+      "defaultValue": "1200",
+      "description": "ms the confirmation stays up before reverting. Defaults to `1200`.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": "Copy",
+      "description": "The idle label. Defaults to `\"Copy\"`.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    },
+    {
+      "name": "copiedLabel",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": "Copied",
+      "description": "The confirmation label. Defaults to `\"Copied\"`.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    },
+    {
+      "name": "onCopy",
+      "type": "((value: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with `value` once it is actually on the clipboard. Replaces the\nnative `onCopy` clipboard-event handler, which is meaningless on a button.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    },
+    {
+      "name": "onCopyError",
+      "type": "((error: unknown) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with whatever the clipboard threw. Nothing is claimed on failure.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    },
+    {
+      "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={<a href=\"/x\" />}` — or a function returning one. When set, the\ndefault `type=\"button\"` is dropped so non-button elements stay valid.",
+      "control": {
+        "kind": "opaque"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<ButtonProps, \"icon\" | \"children\" | \"onCopy\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [],
+  "summary": "Copy one string, and say so.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<CopyButton value={fixture.id} />\n<CopyButton value={dsn} variant=\"ghost\" size=\"sm\" copiedLabel=\"On the clipboard\">\n  Copy DSN\n</CopyButton>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/copy-button",
+  "mdUrl": "/docs/components/copy-button.md",
+  "jsonUrl": "/r/components/copy-button.json",
+  "specimens": [
+    {
+      "title": "CopyButton",
+      "group": "instruments",
+      "components": [
+        "CopyButton"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"default\">\n    <CopyButton value=\"10.0.0.42\">Copy address</CopyButton>\n  </Specimen>\n  <Specimen label=\"ghost\">\n    <CopyButton value=\"pnpm add @cueplusplus/ui\" variant=\"ghost\">\n      Copy install\n    </CopyButton>\n  </Specimen>\n  <Specimen label=\"custom confirmation\">\n    <CopyButton value=\"universe 1\" copiedLabel=\"On the clipboard\">\n      Copy universe\n    </CopyButton>\n  </Specimen>\n</Specimens>",
+      "note": "Copies, then says so for a beat. The confirmation is text, not a colour change.",
+      "interaction": "the label swaps to the copied state and reverts after the timeout; the accessible name swaps with it."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/cost-meter.json

@@ -0,0 +1,84 @@
+{
+  "name": "CostMeter",
+  "slug": "cost-meter",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "What the run spent, split by model, against the session total.",
+  "props": [
+    {
+      "name": "runCost",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Pre-formatted cost of this run.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "sessionCost",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Pre-formatted cumulative cost.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "lines",
+      "type": "readonly CostLine[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Per-model breakdown, ordered largest first so the bar reads left to right.",
+      "control": {
+        "kind": "array",
+        "fixture": "agents.costs"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  \"children\" | \"runCost\" | \"sessionCost\" | \"lines\"\n> & {\n  /** Pre-formatted cost of this run. */\n  runCost: string;\n  /** Pre-formatted cumulative cost. */\n  sessionCost: string;\n  /** Per-model breakdown, ordered largest first so the bar reads left to right. */\n  lines: readonly CostLine[];\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-radius-overlay",
+    "--cue-stream",
+    "--cue-surface-2",
+    "--cue-surface-3",
+    "--cue-text-body",
+    "--cue-text-title"
+  ],
+  "summary": "What the run spent, split by model, against the session total.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { CostMeter } from \"@cueplusplus/ui/elements\";\n\n<CostMeter runCost=\"$2.76\" sessionCost=\"$18.40\" lines={lines} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/cost-meter",
+  "mdUrl": "/docs/components/cost-meter.md",
+  "jsonUrl": "/r/components/cost-meter.json",
+  "specimens": [
+    {
+      "title": "CostMeter",
+      "group": "elements-agents",
+      "components": [
+        "CostMeter"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"three models\" wide>\n    <CostMeter runCost=\"$5.02\" sessionCost=\"$41.87\" lines={COSTS} />\n  </Specimen>\n  <Specimen label=\"one model, whole run\" wide>\n    <CostMeter\n      runCost=\"$0.46\"\n      sessionCost=\"$41.87\"\n      lines={[{ ...COSTS[2]!, share: 1 }]}\n    />\n  </Specimen>\n</Specimens>",
+      "note": "What the run spent, against what the session has spent — two numbers, then the arithmetic under them. Every figure arrives pre-formatted: the element does no currency maths and no rounding, so a bench and a billing page cannot disagree about what `$3.12` means.",
+      "interaction": "none. `share` drives the bar and the lines are given largest-first, so the bar reads left to right in the same order as the rows."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/cue-logotype.json

@@ -0,0 +1,110 @@
+{
+  "name": "CueLogotype",
+  "slug": "cue-logotype",
+  "group": "brand",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "The CUE++ logotype: the wordmark and the mark, locked up.\n\n778:367, and it stays that shape at every size — `size` sets the height and\nthe width follows, so a logotype and a {@link CueMark } beside it line up on\nthe same row of a toolbar without either being measured by hand.\n\nOne paint, not two. The artwork draws the lock-up's mark as a single\n`evenodd` path, which makes its two \"+\" glyphs holes rather than ink: they\nshow whatever the logotype is standing on, so the whole thing is one\n`fill` and there is nothing to keep in step with a background.\n\nDecorative by default, like every asset in this group — pass a `title` only\nwhen nothing else on the page names the product.\n\nStatic markup — no `\"use client\"`.",
+  "props": [
+    {
+      "name": "size",
+      "type": "number | BrandSize",
+      "required": false,
+      "defaultValue": "md",
+      "description": "Rung of the density control ladder to draw at, or an explicit height in px.\nDefaults to `\"md\"`.\n\nHeight, always — every asset here keeps its own aspect ratio, so the width\nfollows from the artwork rather than from the caller.",
+      "control": {
+        "kind": "opaque"
+      }
+    },
+    {
+      "name": "tone",
+      "type": "\"inherit\" | \"fg\" | \"accent\"",
+      "required": false,
+      "defaultValue": "inherit",
+      "description": "Where the ink comes from: `currentColor`, the foreground token, or the\naccent. Defaults to `\"inherit\"`.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "inherit",
+          "fg",
+          "accent"
+        ]
+      }
+    },
+    {
+      "name": "title",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "The accessible name.\n\nOmit it and the asset is decorative — `aria-hidden`, announced by nothing.\nPass one only when the mark is the *only* thing naming what it sits on: a\nbare logo link, a splash screen with no heading.",
+      "control": {
+        "kind": "string"
+      }
+    }
+  ],
+  "typeReferences": [
+    "BrandAssetProps"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-fg",
+    "--cue-bg",
+    "--cue-control-lg",
+    "--cue-control-md",
+    "--cue-control-sm",
+    "--cue-fg"
+  ],
+  "summary": "The CUE++ wordmark and mark locked up, at 778:367 whatever size you draw it.",
+  "examples": [
+    {
+      "title": "A top bar",
+      "code": "import { CueLogotype } from \"@cueplusplus/ui\";\n\n<header className=\"flex h-(--cue-chrome-titlebar) items-center px-(--cue-space-4)\">\n  <CueLogotype size=\"sm\" title=\"CUE++\" />\n</header>;",
+      "language": "tsx"
+    },
+    {
+      "title": "On the accent",
+      "code": "<CueLogotype size=\"lg\" tone=\"accent\" />;",
+      "language": "tsx"
+    },
+    {
+      "title": "Usage",
+      "code": "<CueLogotype />\n<CueLogotype size=\"lg\" title=\"CUE++\" />",
+      "language": "tsx"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/cue-logotype",
+  "mdUrl": "/docs/components/cue-logotype.md",
+  "jsonUrl": "/r/components/cue-logotype.json",
+  "whenToUse": [
+    "The one place on a screen that says which product this is: a top bar, a sign-in card, an empty state.",
+    "A print or export header, where the name has to travel with the document."
+  ],
+  "whenNotToUse": [
+    "Repeatedly down a page. One identity per screen; use `CueMark` for the rest.",
+    "In a space narrower than about eight times its height. Use `CueMark`.",
+    "For another CUE++ property. venu.studio, Twinkle and SupBuddy are not in this library: they belong to other products, and two of them exist only as raster art."
+  ],
+  "commonMistakes": [
+    "Constraining its width. `size` sets the height and the width follows the artwork, which is what keeps a logotype and a `CueMark` on the same toolbar row the same height.",
+    "Painting a background behind it to make the `+` glyphs read. They are holes in the artwork, so they show whatever is behind them by design.",
+    "Choosing a file for the mode. There is no light and dark version: `tone` reads the token layer, which already knows which mode it is."
+  ],
+  "specimens": [
+    {
+      "title": "CueLogotype",
+      "group": "brand",
+      "components": [
+        "CueLogotype"
+      ],
+      "code": "<Specimens>\n  {SIZES.map((size) => (\n    <Specimen key={size} label={`size ${size}`} wide>\n      <CueLogotype size={size} />\n    </Specimen>\n  ))}\n</Specimens>\n<Specimens>\n  {TONES.map((tone) => (\n    <Specimen key={tone} label={`tone ${tone}`} wide>\n      <CueLogotype size={40} tone={tone} />\n    </Specimen>\n  ))}\n  <Specimen label=\"named\" wide>\n    <CueLogotype size={40} title=\"CUE++\" />\n  </Specimen>\n</Specimens>",
+      "note": "The wordmark and the mark, locked up at 778:367. The size sets the height and the width follows, so a logotype and a mark on the same toolbar row are the same height.",
+      "interaction": "none. One fill for the whole lock-up: the mark's two '+' are holes in the artwork, so they show whatever is behind them."
+    }
+  ]
+}

package/manifest/components/cue-mark.json

@@ -0,0 +1,111 @@
+{
+  "name": "CueMark",
+  "slug": "cue-mark",
+  "group": "brand",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "The CUE++ mark: the circular one, with no words in it.\n\nSquare at every size, drawn from the artwork's own path data, and painted\nentirely from tokens — the disc takes the tone's ink and the two \"+\" glyphs\ntake the ground, which is exactly the relationship the two shipped SVGs\nencode by hand. One element is therefore correct in all ten presets and\nboth modes, and there is no light/dark variant to pick.\n\nThe two glyphs are {@link Plussie }'s eyes; both components read one geometry\nmodule, so the mark cannot stop being the character's face.\n\nDecorative by default. It renders `aria-hidden` unless you give it a `title`,\nbecause a mark beside a wordmark, a heading or a link that already says\n\"CUE++\" is the second time a reader is told.\n\nStatic markup — no `\"use client\"`.",
+  "props": [
+    {
+      "name": "size",
+      "type": "number | BrandSize",
+      "required": false,
+      "defaultValue": "md",
+      "description": "Rung of the density control ladder to draw at, or an explicit height in px.\nDefaults to `\"md\"`.\n\nHeight, always — every asset here keeps its own aspect ratio, so the width\nfollows from the artwork rather than from the caller.",
+      "control": {
+        "kind": "opaque"
+      }
+    },
+    {
+      "name": "tone",
+      "type": "\"inherit\" | \"fg\" | \"accent\"",
+      "required": false,
+      "defaultValue": "inherit",
+      "description": "Where the ink comes from: `currentColor`, the foreground token, or the\naccent. Defaults to `\"inherit\"`.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "inherit",
+          "fg",
+          "accent"
+        ]
+      }
+    },
+    {
+      "name": "title",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "The accessible name.\n\nOmit it and the asset is decorative — `aria-hidden`, announced by nothing.\nPass one only when the mark is the *only* thing naming what it sits on: a\nbare logo link, a splash screen with no heading.",
+      "control": {
+        "kind": "string"
+      }
+    }
+  ],
+  "typeReferences": [
+    "BrandAssetProps"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-fg",
+    "--cue-bg",
+    "--cue-control-lg",
+    "--cue-control-md",
+    "--cue-control-sm",
+    "--cue-fg"
+  ],
+  "summary": "The circular CUE++ mark, painted from tokens rather than shipped as a light/dark pair.",
+  "examples": [
+    {
+      "title": "In a header",
+      "code": "import { CueMark } from \"@cueplusplus/ui\";\n\n<a href=\"/\" className=\"flex items-center gap-(--cue-space-2)\">\n  <CueMark size=\"sm\" />\n  <span>CUE++</span>\n</a>;",
+      "language": "tsx"
+    },
+    {
+      "title": "On its own, so it needs a name",
+      "code": "<a href=\"/\">\n  <CueMark size=\"lg\" title=\"CUE++ home\" />\n</a>;",
+      "language": "tsx"
+    },
+    {
+      "title": "Usage",
+      "code": "<CueMark />\n<CueMark size=\"lg\" tone=\"accent\" title=\"CUE++\" />",
+      "language": "tsx"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/cue-mark",
+  "mdUrl": "/docs/components/cue-mark.md",
+  "jsonUrl": "/r/components/cue-mark.json",
+  "whenToUse": [
+    "A compact identity next to a product name: a sidebar rail, a tab favicon slot, a status bar.",
+    "Anywhere the logotype is too wide. The mark is square at every rung of the control ladder.",
+    "As the visual half of a link or heading that already says CUE++, in which case leave `title` off and let it stay decorative."
+  ],
+  "whenNotToUse": [
+    "As the whole of a home link with nothing else naming it. Pass a `title` so it is announced, or put a visible label beside it.",
+    "As a generic avatar or status glyph. Use `Avatar` or `StatusDot`.",
+    "For another CUE++ property's mark. venu.studio, Twinkle and SupBuddy are not in this library: they belong to other products, and two of them exist only as raster art."
+  ],
+  "commonMistakes": [
+    "Reaching for a `variant=\"dark\"`. There is not one, on purpose: the disc takes `currentColor` or a token and the two `+` take the ground, so a single element is correct in all ten presets and both modes.",
+    "Setting a width. `size` sets both dimensions here and the height everywhere in this group; the artwork's ratio does the rest.",
+    "Passing a `title` to every instance. A mark beside a wordmark that already says CUE++ announces the name twice."
+  ],
+  "specimens": [
+    {
+      "title": "CueMark",
+      "group": "brand",
+      "components": [
+        "CueMark"
+      ],
+      "code": "<Specimens>\n  {SIZES.map((size) => (\n    <Specimen key={size} label={`size ${size}`}>\n      <CueMark size={size} />\n    </Specimen>\n  ))}\n  <Specimen label=\"size 64\">\n    <CueMark size={64} />\n  </Specimen>\n</Specimens>\n<Specimens>\n  {TONES.map((tone) => (\n    <Specimen key={tone} label={`tone ${tone}`}>\n      <CueMark size={48} tone={tone} />\n    </Specimen>\n  ))}\n  <Specimen label=\"named\">\n    <CueMark size={48} title=\"CUE++\" />\n  </Specimen>\n</Specimens>",
+      "note": "The circular mark, square at every rung. The disc takes the tone's ink and the two '+' take the ground, which is how one component draws both of the shipped SVGs.",
+      "interaction": "none. It is a picture, and it is aria-hidden unless you name it."
+    }
+  ]
+}

package/manifest/components/cue-portal-frame.json

@@ -0,0 +1,65 @@
+{
+  "name": "CuePortalFrame",
+  "slug": "cue-portal-frame",
+  "group": "system",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "Inline version of the portal contract, for portals whose container cannot be\nchosen (a third-party overlay, or content already portaled by something else).\n\nWraps `children` in a `display: contents` element carrying the same\n`data-theme` / `data-density` / `data-font` / `data-mode` / `data-style` /\n`data-cue-skin` / `data-cue-fidelity` stamp, `--cue-font-scale` and\n`overrides` properties as {@link useCuePortalProps}. Prefer the hook — a\nstamped container costs one element per overlay instead of one per render\ntree — and reach for this only when the container prop is not available.",
+  "props": [
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": true,
+      "defaultValue": null,
+      "description": "Portal content to stamp.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes for the frame element.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "style",
+      "type": "CSSProperties",
+      "required": false,
+      "defaultValue": null,
+      "description": "Inline styles, merged after `display: contents`.",
+      "control": {
+        "kind": "opaque"
+      }
+    }
+  ],
+  "typeReferences": [],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-font-mono",
+    "--cue-font-sans",
+    "--cue-font-scale"
+  ],
+  "summary": "Inline version of the portal contract, for portals whose container cannot be chosen (a third-party overlay, or content already portaled by something else).",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<SomeThirdPartyPortal><CuePortalFrame>{content}</CuePortalFrame></SomeThirdPartyPortal>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/cue-portal-frame",
+  "mdUrl": "/docs/components/cue-portal-frame.md",
+  "jsonUrl": "/r/components/cue-portal-frame.json",
+  "todo": true
+}