@cueplusplus/ui 0.1.0 → 0.3.0

package/manifest/components/export-dialog.json

@@ -0,0 +1,84 @@
+{
+  "name": "ExportDialog",
+  "slug": "export-dialog",
+  "group": "configurator",
+  "importPath": "@cueplusplus/ui/configurator",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "The export dialog: CSS, DTCG tokens, a `createTheme()` call and a shadcn\n`registry:theme` item.\n\nAll four are generated from the overrides the panel is applying, so the CSS\none is *literally* the stylesheet on the page. Nothing here re-derives a\nvalue.",
+  "props": [
+    {
+      "name": "open",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "Whether the dialog is showing."
+    },
+    {
+      "name": "onOpenChange",
+      "type": "(open: boolean) => void",
+      "required": true,
+      "defaultValue": null,
+      "description": "Called when it should open or close."
+    },
+    {
+      "name": "overrides",
+      "type": "ThemeOverrides",
+      "required": true,
+      "defaultValue": null,
+      "description": "The overrides to export."
+    },
+    {
+      "name": "scope",
+      "type": "ThemeScope",
+      "required": true,
+      "defaultValue": null,
+      "description": "The theme and mode they were made in."
+    },
+    {
+      "name": "defaultFormat",
+      "type": "\"css\" | \"dtcg\" | \"create-theme\" | \"registry\"",
+      "required": false,
+      "defaultValue": "css",
+      "description": "Format shown first. Defaults to `\"css\"`."
+    }
+  ],
+  "typeReferences": [],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-border",
+    "--cue-density",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-font-mono",
+    "--cue-font-pairing-mono",
+    "--cue-font-sans",
+    "--cue-font-scale",
+    "--cue-font-theme-mono",
+    "--cue-radius-control",
+    "--cue-radius-scale",
+    "--cue-space-1",
+    "--cue-space-3",
+    "--cue-space-4",
+    "--cue-sunken",
+    "--cue-text-label",
+    "--cue-text-micro"
+  ],
+  "summary": "The export dialog: CSS, DTCG tokens, a `createTheme()` call and a shadcn `registry:theme` item.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<ExportDialog open={open} onOpenChange={setOpen} overrides={overrides} scope={scope} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/export-dialog",
+  "mdUrl": "/docs/components/export-dialog.md",
+  "jsonUrl": "/r/components/export-dialog.json",
+  "todo": true
+}

package/manifest/components/eyebrow.json

@@ -0,0 +1,56 @@
+{
+  "name": "Eyebrow",
+  "slug": "eyebrow",
+  "group": "chrome",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "The small accent kicker that sits above a title: `// PATCH`.\n\nMono, uppercase and widely tracked, in the theme's accent — the one place\nwhere the accent is used for pure typography rather than for a control. The\nslashes are marked `aria-hidden` and `select-none`, so a screen reader reads\n\"patch\" and a copy-paste of the page does not carry punctuation that was only\never decoration.\n\nStatic markup — no `\"use client\"`.",
+  "props": [
+    {
+      "name": "slashes",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "true",
+      "description": "Print the `//` motif ahead of the label. Defaults to `true` — the slashes\nare the brand mark of this system, and an eyebrow without them is just\nsmall uppercase text. Pass `false` for a plain kicker."
+    }
+  ],
+  "typeReferences": [
+    "React.ComponentPropsWithoutRef<\"span\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-font-mono",
+    "--cue-space-2",
+    "--cue-text-label"
+  ],
+  "summary": "The small accent kicker that sits above a title: `// PATCH`.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Eyebrow>Patch</Eyebrow>\n<Eyebrow slashes={false}>Beta</Eyebrow>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/eyebrow",
+  "mdUrl": "/docs/components/eyebrow.md",
+  "jsonUrl": "/r/components/eyebrow.json",
+  "specimens": [
+    {
+      "title": "Eyebrow",
+      "group": "chrome",
+      "components": [
+        "Eyebrow"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"default\">\n    <Eyebrow>smoke matrix</Eyebrow>\n  </Specimen>\n  <Specimen label=\"no slashes\">\n    <Eyebrow slashes={false}>smoke matrix</Eyebrow>\n  </Specimen>\n</Specimens>",
+      "note": "The `//` motif from the brand site, in mono micro.",
+      "interaction": "none."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/field-description.json

@@ -0,0 +1,63 @@
+{
+  "name": "FieldDescription",
+  "slug": "field-description",
+  "group": "forms",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "Quiet helper text under a control, published to assistive tech as the\ncontrol's `aria-describedby` target.",
+  "props": [
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes, merged over the helper-text defaults."
+    }
+  ],
+  "typeReferences": [
+    "Omit<BaseField.Description.Props, \"className\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-danger",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-space-1",
+    "--cue-space-2",
+    "--cue-text-label",
+    "--cue-text-micro"
+  ],
+  "summary": "Quiet helper text under a control, published to assistive tech as the control's `aria-describedby` target.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<FieldDescription>1–512</FieldDescription>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/field-description",
+  "mdUrl": "/docs/components/field-description.md",
+  "jsonUrl": "/r/components/field-description.json",
+  "specimens": [
+    {
+      "title": "Field / FieldLabel / FieldDescription / FieldError",
+      "group": "forms",
+      "components": [
+        "Field",
+        "FieldLabel",
+        "FieldDescription",
+        "FieldError"
+      ],
+      "code": "<div className=\"grid w-full gap-(--cue-space-5) lg:grid-cols-3\">\n  <Field name=\"cue\">\n    <FieldLabel>Cue name</FieldLabel>\n    <Input placeholder=\"e.g. Blackout\" />\n    <FieldDescription>Shown in the cue list.</FieldDescription>\n  </Field>\n  <Field name=\"universe\" invalid>\n    <FieldLabel>Universe</FieldLabel>\n    <Input defaultValue=\"9\" />\n    <FieldError issues={INVALID_ISSUE} />\n  </Field>\n  <Field name=\"locked\" disabled>\n    <FieldLabel>Locked</FieldLabel>\n    <Input defaultValue=\"Read-only\" />\n    <FieldDescription>Set by the show file.</FieldDescription>\n  </Field>\n</div>",
+      "note": "The labelling wrapper. Base UI generates the ids, so the label names the control with no htmlFor bookkeeping, and `invalid` stamps the whole subtree.",
+      "interaction": "clicking the label focuses the control; the error line is announced when it appears."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/field-error.json

@@ -0,0 +1,77 @@
+{
+  "name": "FieldError",
+  "slug": "field-error",
+  "group": "forms",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "The error line under a control.\n\nTwo ways to drive it, and they are mutually exclusive by design:\npass `issues` from a Standard Schema parse (`schema.safeParse(x).issues`) and\nthe component owns visibility, or pass `match` + `children` and let Base UI\nkey off the native `ValidityState`.",
+  "props": [
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes, merged over the danger-text defaults."
+    },
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "Message to show when driving visibility from `match` instead of `issues`."
+    },
+    {
+      "name": "issues",
+      "type": "readonly FieldIssue[]",
+      "required": false,
+      "defaultValue": null,
+      "description": "Standard Schema issues for this field. When supplied, the component shows\nexactly these messages and stops consulting native `ValidityState`: an\nempty array renders nothing, one issue renders inline, several render as a\nlist. Leave it `undefined` to fall back to `match` + `children`."
+    }
+  ],
+  "typeReferences": [
+    "Omit<BaseField.Error.Props, \"className\" | \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-danger",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-space-1",
+    "--cue-space-2",
+    "--cue-text-label",
+    "--cue-text-micro"
+  ],
+  "summary": "The error line under a control.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<FieldError issues={result.issues} />\n<FieldError match=\"valueMissing\">Please name the cue</FieldError>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/field-error",
+  "mdUrl": "/docs/components/field-error.md",
+  "jsonUrl": "/r/components/field-error.json",
+  "specimens": [
+    {
+      "title": "Field / FieldLabel / FieldDescription / FieldError",
+      "group": "forms",
+      "components": [
+        "Field",
+        "FieldLabel",
+        "FieldDescription",
+        "FieldError"
+      ],
+      "code": "<div className=\"grid w-full gap-(--cue-space-5) lg:grid-cols-3\">\n  <Field name=\"cue\">\n    <FieldLabel>Cue name</FieldLabel>\n    <Input placeholder=\"e.g. Blackout\" />\n    <FieldDescription>Shown in the cue list.</FieldDescription>\n  </Field>\n  <Field name=\"universe\" invalid>\n    <FieldLabel>Universe</FieldLabel>\n    <Input defaultValue=\"9\" />\n    <FieldError issues={INVALID_ISSUE} />\n  </Field>\n  <Field name=\"locked\" disabled>\n    <FieldLabel>Locked</FieldLabel>\n    <Input defaultValue=\"Read-only\" />\n    <FieldDescription>Set by the show file.</FieldDescription>\n  </Field>\n</div>",
+      "note": "The labelling wrapper. Base UI generates the ids, so the label names the control with no htmlFor bookkeeping, and `invalid` stamps the whole subtree.",
+      "interaction": "clicking the label focuses the control; the error line is announced when it appears."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/field-label.json

@@ -0,0 +1,63 @@
+{
+  "name": "FieldLabel",
+  "slug": "field-label",
+  "group": "forms",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "The name of a field: mono, uppercase, tracked out, one rung below body text.\n\nRenders a real `<label>` wired to the field's control, so clicking it focuses\n(or toggles) that control.",
+  "props": [
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes, merged over the label typography."
+    }
+  ],
+  "typeReferences": [
+    "Omit<BaseField.Label.Props, \"className\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-danger",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-space-1",
+    "--cue-space-2",
+    "--cue-text-label",
+    "--cue-text-micro"
+  ],
+  "summary": "The name of a field: mono, uppercase, tracked out, one rung below body text.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<FieldLabel>Universe</FieldLabel>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/field-label",
+  "mdUrl": "/docs/components/field-label.md",
+  "jsonUrl": "/r/components/field-label.json",
+  "specimens": [
+    {
+      "title": "Field / FieldLabel / FieldDescription / FieldError",
+      "group": "forms",
+      "components": [
+        "Field",
+        "FieldLabel",
+        "FieldDescription",
+        "FieldError"
+      ],
+      "code": "<div className=\"grid w-full gap-(--cue-space-5) lg:grid-cols-3\">\n  <Field name=\"cue\">\n    <FieldLabel>Cue name</FieldLabel>\n    <Input placeholder=\"e.g. Blackout\" />\n    <FieldDescription>Shown in the cue list.</FieldDescription>\n  </Field>\n  <Field name=\"universe\" invalid>\n    <FieldLabel>Universe</FieldLabel>\n    <Input defaultValue=\"9\" />\n    <FieldError issues={INVALID_ISSUE} />\n  </Field>\n  <Field name=\"locked\" disabled>\n    <FieldLabel>Locked</FieldLabel>\n    <Input defaultValue=\"Read-only\" />\n    <FieldDescription>Set by the show file.</FieldDescription>\n  </Field>\n</div>",
+      "note": "The labelling wrapper. Base UI generates the ids, so the label names the control with no htmlFor bookkeeping, and `invalid` stamps the whole subtree.",
+      "interaction": "clicking the label focuses the control; the error line is announced when it appears."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/field.json

@@ -0,0 +1,79 @@
+{
+  "name": "Field",
+  "slug": "field",
+  "group": "forms",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "The labelling and validation wrapper every form control belongs in.\n\nWraps Base UI's `Field.Root`, which generates the ids that tie\n{@link FieldLabel}, {@link FieldDescription} and {@link FieldError} to the\ncontrol inside it — so `<FieldLabel>Cue name</FieldLabel>` names an\n{@link Input } with no `htmlFor`/`id` bookkeeping from the caller. Base UI also\nstamps `data-invalid` / `data-disabled` down the subtree, which is what the\nchassis' danger rim keys off.",
+  "props": [
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes, merged over the vertical stack defaults."
+    }
+  ],
+  "typeReferences": [
+    "Omit<BaseField.Root.Props, \"className\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-danger",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-space-1",
+    "--cue-space-2",
+    "--cue-text-label",
+    "--cue-text-micro"
+  ],
+  "summary": "The label, description and validation wrapper a form control belongs in.",
+  "examples": [
+    {
+      "title": "A field with validation",
+      "code": "<Field name=\"cue\">\n  <FieldLabel>Cue name</FieldLabel>\n  <Input placeholder=\"e.g. Blackout\" />\n  <FieldDescription>Shown in the cue list.</FieldDescription>\n  <FieldError issues={result.issues} />\n</Field>",
+      "language": "tsx"
+    },
+    {
+      "title": "Usage",
+      "code": "<Field name=\"cue\">\n  <FieldLabel>Cue name</FieldLabel>\n  <Input placeholder=\"e.g. Blackout\" />\n  <FieldDescription>Shown in the cue list.</FieldDescription>\n  <FieldError issues={result.issues} />\n</Field>",
+      "language": "tsx"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/field",
+  "mdUrl": "/docs/components/field.md",
+  "jsonUrl": "/r/components/field.json",
+  "whenToUse": [
+    "Any control that needs a visible label, helper text, or validation output.",
+    "Rendering Standard Schema issues (Zod, Valibot, ArkType) through `FieldError`."
+  ],
+  "whenNotToUse": [
+    "A control in a table row or a toolbar, where the column heading is already the label. Give the control an `aria-label` instead.",
+    "Grouping controls that share one value. Use `CheckboxGroup` or `RadioGroup`, which own the value and the group name."
+  ],
+  "commonMistakes": [
+    "Writing `htmlFor` and `id` by hand. `Field` generates them, and hand-written ids collide as soon as the form repeats.",
+    "Putting two controls in one `Field`, which points the generated description at the wrong one."
+  ],
+  "specimens": [
+    {
+      "title": "Field / FieldLabel / FieldDescription / FieldError",
+      "group": "forms",
+      "components": [
+        "Field",
+        "FieldLabel",
+        "FieldDescription",
+        "FieldError"
+      ],
+      "code": "<div className=\"grid w-full gap-(--cue-space-5) lg:grid-cols-3\">\n  <Field name=\"cue\">\n    <FieldLabel>Cue name</FieldLabel>\n    <Input placeholder=\"e.g. Blackout\" />\n    <FieldDescription>Shown in the cue list.</FieldDescription>\n  </Field>\n  <Field name=\"universe\" invalid>\n    <FieldLabel>Universe</FieldLabel>\n    <Input defaultValue=\"9\" />\n    <FieldError issues={INVALID_ISSUE} />\n  </Field>\n  <Field name=\"locked\" disabled>\n    <FieldLabel>Locked</FieldLabel>\n    <Input defaultValue=\"Read-only\" />\n    <FieldDescription>Set by the show file.</FieldDescription>\n  </Field>\n</div>",
+      "note": "The labelling wrapper. Base UI generates the ids, so the label names the control with no htmlFor bookkeeping, and `invalid` stamps the whole subtree.",
+      "interaction": "clicking the label focuses the control; the error line is announced when it appears."
+    }
+  ]
+}

package/manifest/components/file-upload.json

@@ -0,0 +1,159 @@
+{
+  "name": "FileUpload",
+  "slug": "file-upload",
+  "group": "forms",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A drop zone with a file list under it.\n\nThe zone is a real `<button>`, not a div with a drop handler: dropping is the\nmouse affordance, and pressing Enter on a focused button to open the file\ndialog is the keyboard one. A zone that only accepts drops is unusable\nwithout a pointer (WCAG 2.1.1), and it is the single most common defect in\nhand-rolled uploaders.\n\nState is the caller's. This component turns drops into `File[]` (plus\nreasoned rejections, via {@link partitionFiles}) and renders whatever rows it\nis handed — it never holds an upload queue, because the transport, the\nretries and the progress belong to the app.",
+  "props": [
+    {
+      "name": "label",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": "Drop files",
+      "description": "The zone's own copy, and its accessible name. Defaults to `\"Drop files\"`."
+    },
+    {
+      "name": "hint",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "A second line under the label — the rules, in plain words."
+    },
+    {
+      "name": "accept",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "`accept` string forwarded to the input and used for rejection."
+    },
+    {
+      "name": "multiple",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Allow more than one file per drop."
+    },
+    {
+      "name": "maxSize",
+      "type": "number",
+      "required": false,
+      "defaultValue": null,
+      "description": "Largest accepted file, in bytes."
+    },
+    {
+      "name": "maxFiles",
+      "type": "number",
+      "required": false,
+      "defaultValue": null,
+      "description": "How many files may be accepted per drop."
+    },
+    {
+      "name": "disabled",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Refuse drops and grey the zone out."
+    },
+    {
+      "name": "files",
+      "type": "readonly UploadFile[]",
+      "required": false,
+      "defaultValue": null,
+      "description": "Rows to render under the zone. The caller owns upload state."
+    },
+    {
+      "name": "onFilesAccepted",
+      "type": "((files: File[]) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with the files that passed the rules."
+    },
+    {
+      "name": "onFilesRejected",
+      "type": "((rejections: FileRejection[]) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with the files that did not, each with its reason."
+    },
+    {
+      "name": "onRemove",
+      "type": "((id: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with a row's `id` when its remove control is pressed."
+    },
+    {
+      "name": "removeLabel",
+      "type": "((file: UploadFile) => string)",
+      "required": false,
+      "defaultValue": "(file) => `Remove ${file.name}`",
+      "description": "Spoken name of a row's remove control. Defaults to `Remove <name>`."
+    },
+    {
+      "name": "zoneClassName",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes for the drop zone."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"onDrop\" | \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-soft",
+    "--cue-border",
+    "--cue-border-strong",
+    "--cue-control-sm",
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-icon-sm",
+    "--cue-ok",
+    "--cue-radius-control",
+    "--cue-space-1",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-space-4",
+    "--cue-space-5",
+    "--cue-sunken",
+    "--cue-surface-2",
+    "--cue-surface-3",
+    "--cue-text-label",
+    "--cue-text-ui"
+  ],
+  "summary": "A drop zone with a file list under it.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<FileUpload\n  label=\"Drop show files\"\n  hint=\"CSV or QLab bundle, up to 20 MB\"\n  accept=\".csv,.qlab\"\n  maxSize={20_000_000}\n  files={rows}\n  onFilesAccepted={enqueue}\n  onFilesRejected={explain}\n  onRemove={cancel}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/file-upload",
+  "mdUrl": "/docs/components/file-upload.md",
+  "jsonUrl": "/r/components/file-upload.json",
+  "specimens": [
+    {
+      "title": "FileUpload",
+      "group": "forms",
+      "components": [
+        "FileUpload"
+      ],
+      "code": "<div className=\"grid w-full gap-(--cue-space-5) lg:grid-cols-2\">\n  <FileUpload\n    label=\"Drop a show file\"\n    hint=\"One .cue file, up to 5 MB.\"\n    accept=\".cue\"\n    maxSize={5_000_000}\n    files={uploads.map((file) => ({ ...file, status: \"done\" as const, progress: 100 }))}\n    onRemove={(id) => setUploads((current) => current.filter((file) => file.id !== id))}\n  />\n  <FileUpload\n    label=\"Drop fixture profiles\"\n    hint=\"Several .gdtf files.\"\n    multiple\n    files={[\n      { id: \"a\", name: \"mac-viper.gdtf\", size: 240_000, status: \"uploading\", progress: 62 },\n      { id: \"b\", name: \"sharpy.gdtf\", size: 180_000, status: \"error\", error: \"Unsupported revision\" },\n    ]}\n  />\n</div>",
+      "note": "A drop zone that is also a button, so a keyboard can reach it. Rejections say which rule they broke.",
+      "interaction": "the zone lights on drag-over; Enter or Space opens the file dialog."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/flow-background.json

@@ -0,0 +1,50 @@
+{
+  "name": "FlowBackground",
+  "slug": "flow-background",
+  "group": "flow",
+  "importPath": "@cueplusplus/ui/flow",
+  "peerDependencies": [
+    "@xyflow/react"
+  ],
+  "clientOnly": true,
+  "description": "The canvas grid: dots one rung off the ground, at the system's own spacing.\n\nLeave `color` unset. It writes `--xy-background-pattern-color-props`, which\noutranks the theme map — passing a colour is how you opt *out* of theming, not\nhow you theme it.",
+  "props": [],
+  "typeReferences": [
+    "React.ComponentProps<typeof Background>"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-border-overlay",
+    "--cue-radius-overlay"
+  ],
+  "summary": "The canvas grid: dots one rung off the ground, at the system's own spacing.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<ReactFlow …><FlowBackground /></ReactFlow>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/flow-background",
+  "mdUrl": "/docs/components/flow-background.md",
+  "jsonUrl": "/r/components/flow-background.json",
+  "specimens": [
+    {
+      "title": "useFlowTheme / FlowControls / FlowBackground / SignalEdge",
+      "group": "flow",
+      "components": [
+        "FlowControls",
+        "FlowBackground",
+        "SignalEdge"
+      ],
+      "code": "<div className=\"h-[24rem] w-full overflow-hidden rounded-(--radius-surface) border border-border\">\n  <ReactFlow\n    nodes={NODES}\n    edges={EDGES}\n    nodeTypes={NODE_TYPES}\n    edgeTypes={theme.edgeTypes}\n    defaultEdgeOptions={theme.defaultEdgeOptions}\n    colorMode={theme.colorMode}\n    style={theme.style}\n    fitView\n    proOptions={{ hideAttribution: true }}\n  >\n    <FlowBackground />\n    <FlowControls />\n  </ReactFlow>\n</div>",
+      "note": "The hook returns the `--xy-*` token map plus stable `edgeTypes` and `defaultEdgeOptions` identities. Every part also publishes the map on its own root, so the group is correct before flow.css is imported and correct again after.",
+      "interaction": "the controls capsule is an overlay surface; a live wire animates its dash overlay and stops under prefers-reduced-motion."
+    }
+  ],
+  "todo": true
+}