@cueplusplus/ui 0.10.0 → 0.11.0

package/dist/layout/preview.js

@@ -0,0 +1,459 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { useIsomorphicLayoutEffect } from "../system/use-isomorphic-layout-effect.js";
+import { AmbientThemeContext, DensityContext } from "../system/density.js";
+import { OverridesContext } from "../system/overrides.js";
+import { ThemeContext } from "../system/theme-provider.js";
+import * as React from "react";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+//#region src/layout/preview.tsx
+const RESIZE_DEFAULTS = {
+	axis: "both",
+	minWidth: 160,
+	maxWidth: 1280,
+	minHeight: 96,
+	maxHeight: 960
+};
+/** One arrow press, in px, and one Shift+arrow press. */
+const STEP = 8;
+const BIG_STEP = 64;
+const ROOT_CLASS = "relative flex min-w-0 flex-col rounded-(--radius-surface) border border-border bg-surface-1 text-fg";
+const BENCH_CLASS = "relative flex min-w-0 flex-1 overflow-auto rounded-t-(--radius-surface)";
+/**
+* The stage: centred, dotted in the stage's own `--cue-hair-strong`, and at
+* least three top rungs of the space ladder tall so a preview reserves its room
+* before its specimen arrives. Static literals, because Tailwind scans text.
+*
+* Centred **safely** (`place-items: safe center`): a specimen wider than the
+* stage starts at the stage's edge and overflows at its end, where the bench
+* scrolls to it. Plain `center` split the overflow across both sides, and the
+* left half sat before the scroll origin, where nothing reaches it.
+*/
+const STAGE_CLASS = "grid h-full w-full min-h-[calc(var(--cue-space-8)*3)] place-items-center-safe bg-surface-1 bg-[radial-gradient(circle,var(--cue-hair-strong)_1px,transparent_1.3px)] bg-[length:14px_14px] p-(--cue-space-6) text-fg";
+const TOOLS_CLASS = "absolute top-(--cue-space-2) right-(--cue-space-2) z-10 flex items-center gap-px rounded-(--radius-control) border border-border bg-surface-2 p-px";
+/**
+* The room the tools take, kept clear on the stage — only when there are tools.
+*
+* The tools sit over the stage's top right, so a specimen that reached that
+* corner sat under them, and its own controls there with it: the index's
+* Calendar paged by an arrow the wrench was drawn over. So a Preview with tools
+* pads its stage's top by the tools' whole depth — their offset, their height
+* (an `sm` control, plus the one-pixel border and padding on each side), and one
+* rung of space below them.
+*
+* **Declared on the bench and read on the stage**, because the two sit in
+* different densities: the tools are drawn in the page's, and the stage may set
+* its own. A custom property's `var()`s are resolved where it is declared, so
+* the stage inherits the depth measured at the page's rung — a compact stage
+* still clears tools drawn at the page's size. And **only with tools**: a bare
+* Preview carries none of it, which is the one the docs' front page draws
+* seventeen times under a byte ceiling.
+*/
+const TOOLS_RESERVE_BENCH = "[--preview-tools-clear:calc(var(--cue-space-2)*2+var(--cue-control-sm)+4px)]";
+const TOOLS_RESERVE_STAGE = "pt-(--preview-tools-clear)";
+const FOOTER_CLASS = "flex min-w-0 items-center gap-(--cue-space-2) border-t border-border px-(--cue-space-4) py-(--cue-space-2)";
+const GRIP_FOCUS = "touch-none outline-none hover:bg-(--cue-border-strong) focus-visible:bg-accent";
+const GRIP_X_CLASS = `absolute top-0 right-0 z-10 h-full w-(--cue-space-2) cursor-col-resize ${GRIP_FOCUS}`;
+const GRIP_Y_CLASS = `absolute bottom-0 left-0 z-10 h-(--cue-space-2) w-full cursor-row-resize ${GRIP_FOCUS}`;
+const GRIP_CORNER_CLASS = "absolute right-0 bottom-0 z-20 size-(--cue-space-4) cursor-nwse-resize touch-none";
+const READOUT_CLASS = "pointer-events-none absolute right-(--cue-space-5) bottom-(--cue-space-5) z-20 rounded-(--radius-control) bg-surface-3 px-(--cue-space-2) py-px font-mono text-(length:--cue-text-label) text-fg-muted";
+function clamp(value, min, max) {
+	return Math.min(max, Math.max(min, value));
+}
+/** The bounds a `resizable` prop means, or `null` for a fixed stage. */
+function resolveResize(resizable) {
+	if (resizable === void 0 || resizable === false) return null;
+	const given = resizable === true ? {} : resizable;
+	return {
+		axis: given.axis ?? RESIZE_DEFAULTS.axis,
+		minWidth: given.minWidth ?? RESIZE_DEFAULTS.minWidth,
+		maxWidth: given.maxWidth ?? RESIZE_DEFAULTS.maxWidth,
+		minHeight: given.minHeight ?? RESIZE_DEFAULTS.minHeight,
+		maxHeight: given.maxHeight ?? RESIZE_DEFAULTS.maxHeight
+	};
+}
+/**
+* The room the stage has: the bench's inline size in whole px, measured at
+* mount and again whenever a `ResizeObserver` says the bench changed — the
+* viewport resizing, a grid track reflowing around it.
+*
+* `null` means "no bound from the room". That covers a fixed Preview, which
+* measures and observes nothing, so a frame without `resizable` costs no
+* observer. It covers a bench that measures 0, which is not laid out
+* (`display: none`, detached, or jsdom). And it covers the first render, which
+* is also the server's, so the markup a server writes and the first client
+* render agree. A host with no `ResizeObserver` gets the measurement at mount
+* and nothing after, as `elements/clamp.tsx` does.
+*/
+function useAvailableWidth(bench, enabled) {
+	const [available, setAvailable] = React.useState(null);
+	useIsomorphicLayoutEffect(() => {
+		const node = bench.current;
+		if (!enabled || node === null) return;
+		const measure = () => {
+			const width = Math.floor(node.getBoundingClientRect().width);
+			setAvailable(width > 0 ? width : null);
+		};
+		measure();
+		if (typeof ResizeObserver === "undefined") return;
+		const observer = new ResizeObserver(measure);
+		observer.observe(node);
+		return () => observer.disconnect();
+	}, [bench, enabled]);
+	return available;
+}
+/**
+* The bounds in force: the given ones, with the widest narrowed to the room
+* the bench has, so a stage never outgrows the frame — or the grid track — it
+* sits in. A room narrower than `minWidth` brings the floor down with it,
+* because a floor wider than the room is a stage that overhangs its tile.
+* Height takes no bound from the room: a taller stage grows its frame.
+*/
+function effectiveBounds(options, available) {
+	if (available === null) return options;
+	const maxWidth = Math.min(options.maxWidth, available);
+	return {
+		...options,
+		maxWidth,
+		minWidth: Math.min(options.minWidth, maxWidth)
+	};
+}
+/**
+* The attributes the stage carries — and, when nothing is asked, none at all.
+*
+* Inheriting is the *absence* of attributes, which is why every branch below
+* is conditional. Three branches add a second attribute, each for a reason in
+* the stylesheets rather than in taste.
+*
+* A theme's light block is the compound selector
+* `[data-theme="t"][data-mode="light"]`, so a mode with no theme restates the
+* page's theme on the same element. Read the other way, a theme with no mode
+* repeats the page's mode. Otherwise the stage would match the theme's dark
+* block under a light page, while every popup opened on it came up light:
+* popups are stamped from the context `StageScope` publishes, which carries
+* the page's mode.
+*
+* A theme's density overrides are addressed through `data-cue-theme`, the
+* stamp `<Density>` writes, so a density names the nearest theme the same way.
+*/
+function stageAttributes(asked, page) {
+	const attributes = {};
+	const scoped = asked.theme ?? (asked.mode === void 0 ? null : page?.theme ?? null);
+	if (scoped !== null) attributes["data-theme"] = scoped;
+	const moded = asked.mode ?? (asked.theme === void 0 ? void 0 : page?.mode);
+	if (moded !== void 0) attributes["data-mode"] = moded;
+	if (asked.density !== void 0) {
+		attributes["data-density"] = asked.density;
+		const nearest = asked.theme ?? page?.theme ?? null;
+		if (nearest !== null) attributes["data-cue-theme"] = nearest;
+	}
+	if (asked.font !== void 0) attributes["data-font"] = asked.font;
+	return attributes;
+}
+/**
+* The contexts the stage republishes, so an overlay opened on it follows it.
+*
+* `useCuePortalProps()` stamps a portal container from `ThemeContext` and
+* `DensityContext`; a popup mounts on `<body>` and inherits nothing from the
+* stage's DOM. So the stage's subtree reads a theme context with the stage's
+* theme and mode, and a density context with the stage's rung. The tools and
+* footer are outside this subtree, so what they open follows the page. A theme
+* the provider did not register leaves `manifest` null, which is what
+* `useTheme()` already reports for a name nobody registered.
+*/
+function StageScope({ theme, mode, density, children }) {
+	const outer = React.useContext(ThemeContext);
+	const outerOverrides = React.useContext(OverridesContext);
+	const outerDensity = React.useContext(DensityContext);
+	const outerAmbient = React.useContext(AmbientThemeContext);
+	const value = React.useMemo(() => {
+		if (outer === null || theme === void 0 && mode === void 0) return outer;
+		const scoped = theme ?? outer.theme;
+		return {
+			...outer,
+			theme: scoped,
+			manifest: scoped === outer.theme ? outer.manifest : null,
+			mode: mode ?? outer.mode,
+			resolvedMode: mode === "dark" || mode === "light" ? mode : outer.resolvedMode
+		};
+	}, [
+		outer,
+		theme,
+		mode
+	]);
+	const stamped = theme !== void 0 || mode !== void 0;
+	return /* @__PURE__ */ jsx(AmbientThemeContext.Provider, {
+		value: theme ?? outerAmbient,
+		children: /* @__PURE__ */ jsx(DensityContext.Provider, {
+			value: density ?? outerDensity,
+			children: /* @__PURE__ */ jsx(OverridesContext.Provider, {
+				value: stamped ? null : outerOverrides,
+				children: /* @__PURE__ */ jsx(ThemeContext.Provider, {
+					value,
+					children
+				})
+			})
+		})
+	});
+}
+/**
+* The stage's size: explicit per axis once a reader has moved it, and the size
+* the layout gives it before that — `null` on an axis, which is also what a
+* double-click returns an axis to.
+*
+* An axis nobody set is measured live, not once. Its value is what the grip
+* announces on focus, before any key, and where the first key or drag starts
+* from, so it has to follow the sizer at rest: the track widening under it, the
+* specimen growing after mount (every listing specimen loads behind a
+* skeleton), a Preview mounted hidden and shown later. Observing the bench is
+* not enough for that. The bench reports a width, and a specimen that grows
+* moves only the height, so the sizer is observed as well, for as long as any
+* axis is unset.
+*/
+function useStageSize(options) {
+	const sizer = React.useRef(null);
+	const [width, setWidth] = React.useState(null);
+	const [height, setHeight] = React.useState(null);
+	const [natural, setNatural] = React.useState({
+		width: 0,
+		height: 0
+	});
+	const [drag, setDrag] = React.useState(null);
+	const enabled = options !== null;
+	const widthSet = width !== null;
+	const heightSet = height !== null;
+	useIsomorphicLayoutEffect(() => {
+		const node = sizer.current;
+		if (!enabled || node === null || widthSet && heightSet) return;
+		const measure = () => {
+			const rect = node.getBoundingClientRect();
+			setNatural((previous) => {
+				const next = {
+					width: widthSet ? previous.width : Math.round(rect.width),
+					height: heightSet ? previous.height : Math.round(rect.height)
+				};
+				return next.width === previous.width && next.height === previous.height ? previous : next;
+			});
+		};
+		measure();
+		if (typeof ResizeObserver === "undefined") return;
+		const observer = new ResizeObserver(measure);
+		observer.observe(node);
+		return () => observer.disconnect();
+	}, [
+		enabled,
+		widthSet,
+		heightSet
+	]);
+	return {
+		sizer,
+		width,
+		height,
+		setWidth,
+		setHeight,
+		shownWidth: options === null ? 0 : clamp(width ?? natural.width, options.minWidth, options.maxWidth),
+		shownHeight: options === null ? 0 : clamp(height ?? natural.height, options.minHeight, options.maxHeight),
+		drag,
+		setDrag
+	};
+}
+/** The two keyboard-operable edges, the corner, and the readout. Chrome, never stage. */
+function Grips({ label, options, size }) {
+	const { shownWidth, shownHeight, drag, setDrag, setWidth, setHeight } = size;
+	const stepWidth = (event) => {
+		const step = event.shiftKey ? BIG_STEP : STEP;
+		let next = null;
+		if (event.key === "ArrowRight") next = shownWidth + step;
+		else if (event.key === "ArrowLeft") next = shownWidth - step;
+		else if (event.key === "Home") next = options.minWidth;
+		else if (event.key === "End") next = options.maxWidth;
+		if (next === null) return;
+		event.preventDefault();
+		setWidth(clamp(next, options.minWidth, options.maxWidth));
+	};
+	const stepHeight = (event) => {
+		const step = event.shiftKey ? BIG_STEP : STEP;
+		let next = null;
+		if (event.key === "ArrowDown") next = shownHeight + step;
+		else if (event.key === "ArrowUp") next = shownHeight - step;
+		else if (event.key === "Home") next = options.minHeight;
+		else if (event.key === "End") next = options.maxHeight;
+		if (next === null) return;
+		event.preventDefault();
+		setHeight(clamp(next, options.minHeight, options.maxHeight));
+	};
+	const pointer = (axis) => ({
+		onPointerDown: (event) => {
+			if (event.button !== 0) return;
+			event.preventDefault();
+			event.currentTarget.setPointerCapture?.(event.pointerId);
+			setDrag({
+				axis,
+				x: event.clientX,
+				y: event.clientY,
+				width: shownWidth,
+				height: shownHeight
+			});
+		},
+		onPointerMove: (event) => {
+			if (drag === null) return;
+			if (drag.axis !== "y") setWidth(clamp(drag.width + event.clientX - drag.x, options.minWidth, options.maxWidth));
+			if (drag.axis !== "x") setHeight(clamp(drag.height + event.clientY - drag.y, options.minHeight, options.maxHeight));
+		},
+		onPointerUp: (event) => {
+			if (drag === null) return;
+			event.currentTarget.releasePointerCapture?.(event.pointerId);
+			setDrag(null);
+		},
+		onPointerCancel: () => setDrag(null)
+	});
+	return /* @__PURE__ */ jsxs(Fragment, { children: [
+		options.axis === "y" ? null : /* @__PURE__ */ jsx("div", {
+			role: "separator",
+			tabIndex: 0,
+			"aria-orientation": "vertical",
+			"aria-label": `Resize ${label} width`,
+			"aria-valuenow": shownWidth,
+			"aria-valuemin": options.minWidth,
+			"aria-valuemax": options.maxWidth,
+			"aria-valuetext": `${shownWidth} pixels wide`,
+			"data-slot": "preview-grip-x",
+			className: GRIP_X_CLASS,
+			onKeyDown: stepWidth,
+			onDoubleClick: () => setWidth(null),
+			...pointer("x")
+		}),
+		options.axis === "x" ? null : /* @__PURE__ */ jsx("div", {
+			role: "separator",
+			tabIndex: 0,
+			"aria-orientation": "horizontal",
+			"aria-label": `Resize ${label} height`,
+			"aria-valuenow": shownHeight,
+			"aria-valuemin": options.minHeight,
+			"aria-valuemax": options.maxHeight,
+			"aria-valuetext": `${shownHeight} pixels tall`,
+			"data-slot": "preview-grip-y",
+			className: GRIP_Y_CLASS,
+			onKeyDown: stepHeight,
+			onDoubleClick: () => setHeight(null),
+			...pointer("y")
+		}),
+		options.axis === "both" ? /* @__PURE__ */ jsx("div", {
+			"aria-hidden": "true",
+			"data-slot": "preview-grip-corner",
+			className: GRIP_CORNER_CLASS,
+			onDoubleClick: () => {
+				setWidth(null);
+				setHeight(null);
+			},
+			...pointer("both")
+		}) : null,
+		drag === null ? null : /* @__PURE__ */ jsx("span", {
+			"aria-hidden": "true",
+			"data-slot": "preview-readout",
+			className: READOUT_CLASS,
+			children: `${shownWidth} × ${shownHeight}`
+		})
+	] });
+}
+/**
+* A frame for one component: a stage that is its own theme island, a slot for
+* tools at the top right, and a footer.
+*
+* **The stage is the island; the chrome is not.** `theme`, `mode`, `density`
+* and `font` land on the stage element only, and the stage republishes the
+* theme and density contexts so an overlay opened on it follows it. The tools,
+* the footer, the grips and anything they open stay in the scope around the
+* Preview — a `terminal` preview's own controls do not turn cyan. With none of
+* the four set, the stage carries no attribute and costs what a `<div>` costs.
+* A stage `theme` with no `mode` repeats the page's mode beside it.
+*
+* **`resizable` is handles of its own**, both axes by default: an edge grip per
+* axis that is a keyboard-operable `separator` valued in pixels, and a corner
+* grip for the pointer. Double-click resets an axis. The width never outgrows
+* the frame: its bound in force is the frame's own width, observed live, when
+* that is under `maxWidth`. Not `Resizable`, which is split panes on an
+* optional peer.
+*
+* Props, not a compound: one stage and two slots, each saying what it is.
+*
+* @example
+* <Preview label="Button preview" tools={<IconButton aria-label="Configure Button" icon={Wrench} />}>
+*   <Button variant="primary">Take cue</Button>
+* </Preview>
+* @example
+* <Preview label="Chip preview" theme="terminal" density="compact" resizable>
+*   <Chip tone="accent">Standby</Chip>
+* </Preview>
+*/
+const Preview = React.forwardRef(function Preview({ children, label, theme, mode, density, font, resizable, tools, footer, className, ...elementProps }, ref) {
+	const outer = React.useContext(ThemeContext);
+	const bench = React.useRef(null);
+	const given = resolveResize(resizable);
+	const available = useAvailableWidth(bench, given !== null);
+	const options = given === null ? null : effectiveBounds(given, available);
+	const size = useStageSize(options);
+	const attributes = stageAttributes({
+		theme,
+		mode,
+		density,
+		font
+	}, outer);
+	const stage = /* @__PURE__ */ jsx("div", {
+		"data-slot": "preview-stage",
+		...attributes,
+		className: cn(STAGE_CLASS, options !== null && "flex-1", tools !== void 0 && TOOLS_RESERVE_STAGE),
+		style: size.height === null ? void 0 : { minHeight: 0 },
+		children: /* @__PURE__ */ jsx(StageScope, {
+			theme,
+			mode,
+			density,
+			children
+		})
+	});
+	return /* @__PURE__ */ jsxs("div", {
+		...elementProps,
+		ref,
+		role: "group",
+		"aria-label": label,
+		"data-slot": "preview",
+		className: cn(ROOT_CLASS, options !== null && "w-full", className),
+		children: [
+			/* @__PURE__ */ jsx("div", {
+				ref: bench,
+				"data-slot": "preview-bench",
+				className: cn(BENCH_CLASS, footer === void 0 && "rounded-b-(--radius-surface)", tools !== void 0 && TOOLS_RESERVE_BENCH),
+				children: options === null ? stage : /* @__PURE__ */ jsxs("div", {
+					ref: size.sizer,
+					"data-slot": "preview-sizer",
+					className: cn("relative flex flex-col", size.width === null && "w-full"),
+					style: {
+						width: size.width === null ? void 0 : `${size.shownWidth}px`,
+						height: size.height === null ? void 0 : `${size.shownHeight}px`,
+						minWidth: `${options.minWidth}px`,
+						maxWidth: `${options.maxWidth}px`,
+						minHeight: `${options.minHeight}px`,
+						maxHeight: `${options.maxHeight}px`
+					},
+					children: [stage, /* @__PURE__ */ jsx(Grips, {
+						label,
+						options,
+						size
+					})]
+				})
+			}),
+			tools === void 0 ? null : /* @__PURE__ */ jsx("div", {
+				"data-slot": "preview-tools",
+				className: TOOLS_CLASS,
+				children: tools
+			}),
+			footer === void 0 ? null : /* @__PURE__ */ jsx("div", {
+				"data-slot": "preview-footer",
+				className: FOOTER_CLASS,
+				children: footer
+			})
+		]
+	});
+});
+//#endregion
+export { Preview };

package/manifest/components/code-block.json

@@ -0,0 +1,106 @@
+{
+  "name": "CodeBlock",
+  "slug": "code-block",
+  "group": "instruments",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "A block of code with a copy button and no syntax-highlighter palette.\n\nEvery colour a token-driven site paints has to come from the token layer, and\na highlighter theme is a second palette that would need porting to every\npreset before it could sit beside them — so there is none. What `language=\"jsx\"`\nadds is emphasis in three inks the theme already has: tag names in `--cue-fg`,\nattribute names in `--cue-fg-muted`, punctuation in `--cue-fg-subtle`. Mono\ntype, the sunken ground every input uses, and a copy button that works.\n\nNo directive: the copy button is the only client code, and a server page can\ndraw the rest.",
+  "props": [
+    {
+      "name": "code",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "The code. Printed verbatim, already dedented by whoever produced it; the copy button copies exactly this.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "What the block is, in the caption strip: a filename, an example's title. Defaults to the language.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "language",
+      "type": "string",
+      "required": false,
+      "defaultValue": "tsx",
+      "description": "The fence language, on the `<pre>` as `data-language`. Defaults to `\"tsx\"`.\n`\"jsx\"` turns on emphasis: tag names, attribute names and punctuation in\nthree inks the theme already has. Every other value prints plain.",
+      "control": {
+        "kind": "string"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-border",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-pad-row-x",
+    "--cue-pad-row-y",
+    "--cue-space-4",
+    "--cue-sunken",
+    "--cue-text-micro",
+    "--cue-text-ui"
+  ],
+  "summary": "A block of code with a copy button and no highlighter palette; `language=\"jsx\"` adds emphasis in three inks the theme already has.",
+  "examples": [
+    {
+      "title": "An install line",
+      "code": "<CodeBlock label=\"install\" language=\"sh\" code=\"pnpm add @cueplusplus/ui\" />",
+      "language": "tsx"
+    },
+    {
+      "title": "JSX, in three inks",
+      "code": "<CodeBlock label=\"JSX\" language=\"jsx\" code={'<Button variant=\"primary\">Take cue</Button>'} />",
+      "language": "tsx"
+    },
+    {
+      "title": "Usage",
+      "code": "<CodeBlock label=\"install\" code=\"pnpm add\n<CodeBlock label=\"JSX\" language=\"jsx\" code={'<Button variant=\"primary\">Take cue</Button>'} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/code-block",
+  "mdUrl": "/docs/components/code-block.md",
+  "jsonUrl": "/r/components/code-block.json",
+  "whenToUse": [
+    "Any snippet a reader will copy: an install line, an example, the source of a state on screen.",
+    "JSX a reader should scan by structure — tag names, then attributes — without a second palette to port to every theme."
+  ],
+  "whenNotToUse": [
+    "Inline code in a sentence. That is a `<code>` in prose.",
+    "A diff, or code a reader runs. Those are `CodeDiff` and `CodeRunner`."
+  ],
+  "commonMistakes": [
+    "Expecting colour for a language other than `jsx`. There is no highlighter; every other language prints plain, on purpose.",
+    "Passing code that still carries its indentation from the file it came from. The block prints verbatim — dedent it first."
+  ],
+  "specimens": [
+    {
+      "title": "CodeBlock",
+      "group": "instruments",
+      "components": [
+        "CodeBlock"
+      ],
+      "code": "<div className=\"flex w-full flex-col gap-(--cue-space-4)\">\n  <CodeBlock label=\"install\" language=\"sh\" code=\"pnpm add @cueplusplus/ui\" />\n  <CodeBlock label=\"JSX\" language=\"jsx\" code={'<Button variant=\"primary\" size=\"sm\">\\n  Take cue\\n</Button>'} />\n</div>",
+      "interaction": "the copy button is the one control; the code is plain, selectable text."
+    }
+  ]
+}

package/manifest/components/input.json

@@ -17,6 +17,16 @@
         "kind": "string"
       }
     },
+    {
+      "name": "aria-label",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Accessible name for the input, when no `FieldLabel` names it. Declared here\nrather than left to the inherited attribute so the props table carries the\nrow: a bare input outside a `Field` has no other way to be named.",
+      "control": {
+        "kind": "string"
+      }
+    },
     {
       "name": "size",
       "type": "\"sm\" | \"md\" | \"lg\"",
@@ -31,6 +41,16 @@
           "lg"
         ]
       }
+    },
+    {
+      "name": "placeholder",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "An example of what goes in the field, shown while it is empty. Not a name:\nit disappears on the first keystroke, so pair it with `aria-label` or a\n`FieldLabel`. Declared for the props-table row, as `aria-label` is above.",
+      "control": {
+        "kind": "string"
+      }
     }
   ],
   "typeReferences": [