@cueplusplus/ui 0.2.0 → 0.5.0

package/manifest/components/dmx-strip.json

@@ -0,0 +1,101 @@
+{
+  "name": "DmxStrip",
+  "slug": "dmx-strip",
+  "group": "dmx",
+  "importPath": "@cueplusplus/ui/dmx",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "`DmxBar`'s picture with no console behind it — a lighting rig, simulated.\n\nThis is the marketing device from dmxhub's site: the same 1px-tall pixelated\ncanvas the bridge uses for real output, driven by a model of a plausible rig\ninstead of a wire. Channels are grouped into six-channel fixtures; most sit\nwhere they were left, some are dark, and every so often one re-cues and\ncrossfades to its new level. That grouping is what makes it read as *lighting*\nrather than as noise — a random 512 bytes looks like static, and a rig does\nnot.\n\nEverything about it is seeded, including the re-cues the original left to\n`Math.random()`. A screenshot, a visual-regression run and a test all see the\nsame rig from the same `seed`.\n\nUnder `prefers-reduced-motion` the strip paints its first frame and stops.\nThere is no information in the animation — the point of the component is the\ntexture — so stilling it costs the reader nothing.",
+  "props": [
+    {
+      "name": "cells",
+      "type": "number",
+      "required": false,
+      "defaultValue": "128",
+      "description": "Columns, one per simulated channel. Defaults to `128`."
+    },
+    {
+      "name": "height",
+      "type": "number",
+      "required": false,
+      "defaultValue": "14",
+      "description": "Strip height in px at the 16px root, emitted as `rem`. Defaults to `14`."
+    },
+    {
+      "name": "seed",
+      "type": "number",
+      "required": false,
+      "defaultValue": "1",
+      "description": "Seed for the whole simulation. The same seed always plays the same way. Defaults to `1`."
+    },
+    {
+      "name": "simulate",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "true",
+      "description": "Run the simulation. Defaults to `true`; `false` holds the seeded first frame."
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "What the strip depicts. Defaults to `\"Simulated DMX activity\"`."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-soft",
+    "--cue-border",
+    "--cue-border-overlay",
+    "--cue-control-sm",
+    "--cue-data-ground",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-radius-control",
+    "--cue-radius-overlay",
+    "--cue-scrim",
+    "--cue-space-1",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-surface-2",
+    "--cue-text-emphasis",
+    "--cue-text-label",
+    "--cue-text-micro",
+    "--cue-text-ui"
+  ],
+  "summary": "`DmxBar`'s picture with no console behind it — a lighting rig, simulated.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<DmxStrip seed={7} />\n<DmxStrip cells={256} simulate={false} label=\"Rig activity\" />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/dmx-strip",
+  "mdUrl": "/docs/components/dmx-strip.md",
+  "jsonUrl": "/r/components/dmx-strip.json",
+  "specimens": [
+    {
+      "title": "DmxStrip",
+      "group": "dmx",
+      "components": [
+        "DmxStrip"
+      ],
+      "code": "<div className=\"flex w-full flex-col gap-(--cue-space-4)\">\n  <DmxStrip seed={7} label=\"Simulated rig, seed 7\" />\n  <DmxStrip seed={7} cells={16} height={20} label=\"Simulated rig, 16 cells\" />\n  <DmxStrip seed={42} simulate={false} label=\"Simulated rig, static\" />\n</div>",
+      "note": "A seeded fixture simulation: mulberry32 from the `seed` prop, so the same seed draws the same rig every time. Values ramp rather than jump.",
+      "interaction": "the readout updates through a ref; under prefers-reduced-motion the strip paints one static frame instead of animating."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/document-reference.json

@@ -0,0 +1,90 @@
+{
+  "name": "DocumentReference",
+  "slug": "document-reference",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "A document the answer leans on, with the quoted passage and the page to jump to.",
+  "props": [
+    {
+      "name": "title",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Document name."
+    },
+    {
+      "name": "pages",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "Total page count."
+    },
+    {
+      "name": "anchors",
+      "type": "readonly DocumentAnchor[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "The passages the answer drew on, each pinned to a page."
+    },
+    {
+      "name": "activePage",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "Which anchor is highlighted. A page with no anchor highlights nothing."
+    },
+    {
+      "name": "onJump",
+      "type": "((page: number) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with the page to open."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  \"children\" | \"title\" | \"pages\" | \"anchors\" | \"activePage\" | \"onJump\"\n> & {\n  /** Document name. */\n  title: string;\n  /** Total page count. */\n  pages: number;\n  /** The passages the answer drew on, each pinned to a page. */\n  anchors: readonly DocumentAnchor[];\n  /** Which anchor is highlighted. A page with no anchor highlights nothing. */\n  activePage: number;\n  /** Called with the page to open. */\n  onJump?: (page: number) => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-border-strong",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-radius-overlay",
+    "--cue-radius-surface",
+    "--cue-surface-1",
+    "--cue-text-body",
+    "--cue-text-ui"
+  ],
+  "summary": "A document the answer leans on, with the quoted passage and the page to jump to.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { DocumentReference } from \"@cueplusplus/ui/elements\";\n\n<DocumentReference\n  title=\"migration-0.14.pdf\"\n  pages={14}\n  anchors={anchors}\n  activePage={4}\n  onJump={setPage}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/document-reference",
+  "mdUrl": "/docs/components/document-reference.md",
+  "jsonUrl": "/r/components/document-reference.json",
+  "specimens": [
+    {
+      "title": "DocumentReference",
+      "group": "elements-knowledge",
+      "components": [
+        "DocumentReference"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"page 31 active\" wide>\n    <DocumentReference\n      title=\"ESPRITE user manual, rev. 8\"\n      pages={94}\n      anchors={ANCHORS}\n      activePage={page}\n      onJump={setPage}\n    />\n  </Specimen>\n  <Specimen label=\"one anchor\" wide>\n    <DocumentReference\n      title=\"Truss loading guidance\"\n      pages={18}\n      anchors={ANCHORS.slice(0, 1)}\n      activePage={12}\n    />\n  </Specimen>\n</Specimens>",
+      "note": "One document the answer leans on, with the passages it quoted and the page each is on. Several anchors can cite one page — two of these are both page 31 — so the current one is marked by `aria-current` rather than by matching the number, which is what stops the wrong row lighting up.",
+      "interaction": "every quote is a button that reports its page to `onJump`; the active row takes the recessed field ground, the others only on hover."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/draft-restore.json

@@ -0,0 +1,82 @@
+{
+  "name": "DraftRestore",
+  "slug": "draft-restore",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "Come back to a thread and the sentence you never sent is still waiting.",
+  "props": [
+    {
+      "name": "draft",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "The unsent text, truncated to one line."
+    },
+    {
+      "name": "savedAt",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "When it was last touched, pre-formatted."
+    },
+    {
+      "name": "onRestore",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called to put the draft back in the composer."
+    },
+    {
+      "name": "onDiscard",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called to throw the draft away."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  \"children\" | \"draft\" | \"savedAt\" | \"onRestore\" | \"onDiscard\"\n> & {\n  /** The unsent text, truncated to one line. */\n  draft: string;\n  /** When it was last touched, pre-formatted. */\n  savedAt: string;\n  /** Called to put the draft back in the composer. */\n  onRestore?: () => void;\n  /** Called to throw the draft away. */\n  onDiscard?: () => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-radius-overlay",
+    "--cue-surface-2",
+    "--cue-text-body",
+    "--cue-text-ui"
+  ],
+  "summary": "Come back to a thread and the sentence you never sent is still waiting.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { DraftRestore } from \"@cueplusplus/ui/elements\";\n\n<DraftRestore\n  draft=\"Add a regression test for draft restore\"\n  savedAt=\"2 minutes ago\"\n  onRestore={restore}\n  onDiscard={discard}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/draft-restore",
+  "mdUrl": "/docs/components/draft-restore.md",
+  "jsonUrl": "/r/components/draft-restore.json",
+  "specimens": [
+    {
+      "title": "DraftRestore",
+      "group": "elements-composer",
+      "components": [
+        "DraftRestore"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"waiting\" wide>\n    <DraftRestore\n      draft=\"Patch the back truss too, but leave universe 4 alone\"\n      savedAt=\"14 minutes ago\"\n      onRestore={() => undefined}\n      onDiscard={() => undefined}\n    />\n  </Specimen>\n  <Specimen label=\"long draft\" wide>\n    <DraftRestore\n      draft=\"Check whether the ESPRITEs on the back truss are still in mode 4 and, if they are, tell me before changing anything\"\n      savedAt=\"yesterday\"\n      onRestore={() => undefined}\n      onDiscard={() => undefined}\n    />\n  </Specimen>\n</Specimens>",
+      "note": "Come back to a thread and the sentence you never sent is still sitting there. One line of what it was, when it was saved, and the two answers anybody ever has for it. `savedAt` is pre-formatted like every other time in this family — the element does no date maths, so a server-rendered draft and a client-rendered one cannot disagree.",
+      "interaction": "restore is a worded button and discard is a labelled icon (`Discard the draft`): the destructive one is the one that has to be aimed at."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/drawer.json

@@ -0,0 +1,179 @@
+{
+  "name": "Drawer",
+  "slug": "drawer",
+  "group": "overlays",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A swipe-dismissable edge panel — the touch-first cousin of {@link Sheet }.\n\nWraps Base UI's `Drawer`, so the drag tracking, the velocity-aware dismissal,\nthe nested-drawer stacking and the focus trap are the primitive's. What this\nlayer adds is the shared overlay surface, the portal theme stamp, and one\ndecision the caller should not have to make twice: `swipeDirection` picks the\nedge *and* the gesture together, so a drawer can never be dragged in a\ndirection that would push it further onto the screen.\n\nPrefer `Sheet` on a pointer-first console — a swipe is not discoverable with a\nmouse — and reach for this on touch, or wherever the panel is glanceable\nenough that dismissing it should cost one gesture.",
+  "props": [],
+  "typeReferences": [],
+  "subcomponents": [
+    "Root",
+    "Trigger",
+    "Content",
+    "Title",
+    "Description",
+    "Footer",
+    "Close"
+  ],
+  "parts": [
+    {
+      "name": "Root",
+      "usage": "Drawer.Root",
+      "description": "Groups the parts of a drawer and owns its open state. Renders no element.",
+      "props": [
+        {
+          "name": "swipeDirection",
+          "type": "\"left\" | \"right\" | \"up\" | \"down\"",
+          "required": false,
+          "defaultValue": "down",
+          "description": "Which way the drawer is dragged to dismiss it, which also decides the edge\nit lives on. Defaults to `\"down\"` — the bottom sheet."
+        }
+      ],
+      "typeReferences": [
+        "Omit<BaseDrawer.Root.Props, \"swipeDirection\">"
+      ]
+    },
+    {
+      "name": "Trigger",
+      "usage": "Drawer.Trigger",
+      "description": "The control that opens the drawer. Unstyled — pass `render={<Button />}` so\nthe button's own variant classes stay the last word.",
+      "props": [],
+      "typeReferences": [
+        "BaseDrawer.Trigger.Props"
+      ]
+    },
+    {
+      "name": "Content",
+      "usage": "Drawer.Content",
+      "description": "The drawer's portal, scrim, viewport and popup in one part.\n\nPortalled through {@link useCuePortalProps}, so the surface carries the\ncaller's theme, density and mode even though it mounts at the end of\n`<body>`. The swipe gesture, the rubber-banding, the velocity-aware dismissal\nand the focus trap are all Base UI's; this layer supplies the edge geometry\nand the token skin.",
+      "props": [
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the popup surface."
+        },
+        {
+          "name": "keepMounted",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": null,
+          "description": "Keep the popup mounted while closed, so its content is not re-created."
+        },
+        {
+          "name": "viewportClassName",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the full-viewport box that parks the popup on its edge."
+        },
+        {
+          "name": "backdropClassName",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the scrim behind it."
+        },
+        {
+          "name": "grabHandle",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "true",
+          "description": "Draw the grab bar that advertises the swipe. Defaults to `true`.\n\nPurely decorative — the whole popup is draggable — so it is `aria-hidden`\nand there is no keyboard equivalent to lose by turning it off."
+        }
+      ],
+      "typeReferences": [
+        "Omit<BaseDrawer.Popup.Props, \"className\">"
+      ]
+    },
+    {
+      "name": "Title",
+      "usage": "Drawer.Title",
+      "description": "The drawer's heading, wired to the popup's `aria-labelledby`.",
+      "props": [],
+      "typeReferences": [
+        "BaseDrawer.Title.Props"
+      ]
+    },
+    {
+      "name": "Description",
+      "usage": "Drawer.Description",
+      "description": "The supporting line under the title, published as `aria-describedby`.",
+      "props": [],
+      "typeReferences": [
+        "BaseDrawer.Description.Props"
+      ]
+    },
+    {
+      "name": "Footer",
+      "usage": "Drawer.Footer",
+      "description": "The action strip at the foot of the drawer.",
+      "props": [],
+      "typeReferences": [
+        "React.ComponentPropsWithoutRef<\"div\">"
+      ]
+    },
+    {
+      "name": "Close",
+      "usage": "Drawer.Close",
+      "description": "A control that closes the drawer. Unstyled — wrap it in a `Button`.",
+      "props": [],
+      "typeReferences": [
+        "BaseDrawer.Close.Props"
+      ]
+    }
+  ],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent-soft",
+    "--cue-border",
+    "--cue-border-overlay",
+    "--cue-border-strong",
+    "--cue-control-sm",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-radius-control",
+    "--cue-radius-overlay",
+    "--cue-scrim",
+    "--cue-space-1",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-space-4",
+    "--cue-space-6",
+    "--cue-surface-2",
+    "--cue-text-emphasis",
+    "--cue-text-label",
+    "--cue-text-ui"
+  ],
+  "summary": "A swipe-dismissable edge panel — the touch-first cousin of {@link Sheet }.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Drawer.Root swipeDirection=\"down\">\n  <Drawer.Trigger render={<Button>Cue stack</Button>} />\n  <Drawer.Content>\n    <Drawer.Title>Cue stack</Drawer.Title>\n    <Drawer.Footer><Drawer.Close render={<Button>Done</Button>} /></Drawer.Footer>\n  </Drawer.Content>\n</Drawer.Root>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/drawer",
+  "mdUrl": "/docs/components/drawer.md",
+  "jsonUrl": "/r/components/drawer.json",
+  "specimens": [
+    {
+      "title": "Drawer",
+      "group": "overlays",
+      "components": [
+        "Drawer"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"bottom\">\n    <Drawer.Root>\n      <Drawer.Trigger render={<Button>Open drawer</Button>} />\n      <Drawer.Content>\n        <Drawer.Title>Quick patch</Drawer.Title>\n        <Drawer.Description>The next free block on universe 1.</Drawer.Description>\n        <Drawer.Footer>\n          <Drawer.Close render={<Button>Cancel</Button>} />\n          <Drawer.Close render={<Button variant=\"primary\">Patch</Button>} />\n        </Drawer.Footer>\n      </Drawer.Content>\n    </Drawer.Root>\n  </Specimen>\n  <Specimen label=\"no grab handle\">\n    <Drawer.Root>\n      <Drawer.Trigger render={<Button>Bare drawer</Button>} />\n      <Drawer.Content grabHandle={false}>\n        <Drawer.Title>Quick patch</Drawer.Title>\n        <Drawer.Description>The next free block on universe 1.</Drawer.Description>\n        <Drawer.Footer>\n          <Drawer.Close render={<Button>Close</Button>} />\n        </Drawer.Footer>\n      </Drawer.Content>\n    </Drawer.Root>\n  </Specimen>\n</Specimens>",
+      "note": "The touch-first sheet: a grab handle and a swipe direction.",
+      "interaction": "drag the handle to dismiss; on a pointer device it behaves as an ordinary sheet."
+    }
+  ],
+  "todo": true
+}