@cueplusplus/ui 0.13.0

package/dist/layout/preview.js

@@ -0,0 +1,628 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { useIsomorphicLayoutEffect } from "../system/use-isomorphic-layout-effect.js";
+import { AmbientThemeContext, DensityContext, StyleSetContext } from "../system/density.js";
+import { OverridesContext } from "../system/overrides.js";
+import { ThemeContext } from "../system/theme-provider.js";
+import { GROUND_CLASSES } from "./_ground.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, grounded, 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.
+*
+* **Three pieces rather than one literal, and the seam is where the ground
+* goes.** `cn` preserves the order it is given, so a ground appended after the
+* padding would emit the dot grid in a different place from the one every
+* caller's markup has today — and `/`'s seventeen bare Previews and the group
+* pages' 326 tooled ones are both measured to the byte. Head, ground, tail, in
+* that order, is today's string.
+*/
+const STAGE_HEAD = "grid h-full w-full min-h-[calc(var(--cue-space-8)*3)] place-items-center-safe";
+const STAGE_TAIL = "p-(--cue-space-6) text-fg";
+/** Which ground a presentation paints when the caller names none (spec §4.1). */
+const DEFAULT_GROUND = {
+	panel: "dots",
+	frame: "none"
+};
+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)";
+/**
+* A frame's root: no card, no border, no fill. The frame is a thing on a
+* canvas, and the canvas is what paints. `shrink-0` because a canvas is a flex
+* row that scrolls, and a frame that shrank to fit would defeat the scrolling.
+*/
+const FRAME_ROOT_CLASS = "relative flex min-w-0 shrink-0 flex-col gap-(--cue-space-2) text-fg";
+/**
+* A frame's footer: the same row as a panel's, without the rule across the top
+* or the card's horizontal padding — there is no card for either to belong to.
+*/
+const FRAME_FOOTER_CLASS = "flex min-w-0 items-center gap-(--cue-space-2) text-(length:--cue-text-micro) text-fg-subtle";
+/** The row above a frame's stage: the name (or its control), the count, and the tools. */
+const FRAME_LABEL_CLASS = "flex min-w-0 items-center gap-(--cue-space-2) text-(length:--cue-text-label) text-fg-muted";
+/** The name when the caller passed no control for it — the frame's `label`, as text. */
+const FRAME_NAME_CLASS = "min-w-0 truncate font-mono text-(length:--cue-text-label) text-fg";
+/** The count beside it: quieter, and never allowed to shrink the name's truncation away. */
+const FRAME_COUNT_CLASS = "shrink-0 font-mono text-(length:--cue-text-micro) text-fg-subtle";
+/**
+* A frame's tools: pushed to the row's end, and carrying none of the panel's
+* overlay chrome. A frame's stage is transparent, so a toolbar drawn over it
+* would float on the canvas ground with nothing behind it (spec §4.1 Decision 2).
+*/
+const FRAME_TOOLS_CLASS = "ml-auto flex shrink-0 items-center gap-px";
+/**
+* The box that holds the bench and the four marks.
+*
+* One more element than the spec's Decision 3 priced, and it is not avoidable.
+* The bench is `overflow-auto`: a mark positioned inside it is clipped at the
+* padding box and scrolls with the content. The frame's root is no good either
+* — its first child is the label row, so the root's top-left corner is the
+* label's and not the stage's. So the frame gets one `relative` box whose
+* borders are exactly the stage's, and the marks hang off that.
+*/
+const FRAME_BOX_CLASS = "relative flex min-w-0 flex-col";
+/**
+* Captions off, as properties the item reads rather than a prop each item takes.
+*
+* A reader turns captions off for a whole frame from its settings popover,
+* never for one item — so the switch is on the frame and the item obeys it
+* through inheritance.
+*
+* **`opacity: 0`, and deliberately not `visibility: hidden`.** §4.1 Decision 4
+* refuses "removing a hidden caption from the accessibility tree", and
+* `visibility: hidden` does exactly that — a browser drops such a node as
+* surely as it drops a `display: none` one. Zero opacity keeps the box, so
+* nothing re-flows, *and* keeps the caption announced, which is what the
+* refusal is for: the caption is what names the specimen for a reader who
+* cannot see the difference between two of them.
+*
+* **Two properties, declared together here so the pair is never half-applied.**
+* Custom properties are untyped text: `opacity` wants a number and
+* `pointer-events` wants a keyword, so one property cannot carry both. The
+* second is what stops an unpainted caption being clicked, or a drag across the
+* stage selecting words nobody can see.
+*/
+const CAPTIONS_OFF = "[--preview-captions:0] [--preview-captions-pe:none]";
+/**
+* One corner mark: an 11×11 box with a one-pixel cross drawn as two linear
+* gradients — a vertical hairline and a horizontal one — so the mark is a
+* background and not four more elements.
+*
+* Not a border and not an SVG. A border would have to be on the stage, and the
+* stage is the theme island: a frame's chrome that moved with a stage theme is
+* the one thing ruling 7 forbids.
+*/
+const CROSS_CLASS = "pointer-events-none absolute z-10 size-[11px] bg-[linear-gradient(var(--cue-fg-subtle),var(--cue-fg-subtle)),linear-gradient(var(--cue-fg-subtle),var(--cue-fg-subtle))] bg-[length:1px_11px,11px_1px] bg-[position:center,center] bg-no-repeat";
+/** The four corners, each half outside the box so the cross straddles the corner. */
+const CROSS_CORNERS = [
+	"-top-[5px] -left-[5px]",
+	"-top-[5px] -right-[5px]",
+	"-bottom-[5px] -left-[5px]",
+	"-bottom-[5px] -right-[5px]"
+];
+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.
+*
+* The style set adds no second attribute, and that is the difference worth
+* writing down beside the three that do: a `[data-style]` block is a single
+* attribute selector naming no other axis, so a set stamped alone matches on
+* its own.
+*/
+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;
+	if (asked.styleSet !== void 0) attributes["data-style"] = asked.styleSet;
+	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.
+*
+* The style set travels with the density for the same reason and by the same
+* route: `useCuePortalProps()` stamps a portal container from `StyleSetContext`,
+* and a popup opened on the stage inherits nothing from the stage's DOM.
+*/
+function StageScope({ theme, mode, density, styleSet, children }) {
+	const outer = React.useContext(ThemeContext);
+	const outerOverrides = React.useContext(OverridesContext);
+	const outerDensity = React.useContext(DensityContext);
+	const outerAmbient = React.useContext(AmbientThemeContext);
+	const outerStyleSet = React.useContext(StyleSetContext);
+	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(StyleSetContext.Provider, {
+				value: styleSet ?? outerStyleSet,
+				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 card for one component: a stage that is its own theme island, a slot for
+* tools at the top right, and a footer.
+*
+* **Two presentations, one stage.** `"panel"`, the default and what every
+* existing caller gets, is that card: a border, a fill, a dot grid under the
+* specimen, and the tools floating over the stage's top right. `"frame"` is a
+* design-canvas frame — no card, no border, no fill; the name, the count and
+* the tools sit in a row *above* the stage rather than over it, four crosshairs
+* mark the stage's outer corners, and the stage paints nothing by default, so
+* whatever canvas the frame sits on shows through. Everything below holds in
+* both.
+*
+* **The stage is the island; the chrome is not.** `theme`, `mode`, `density`,
+* `font` and `styleSet` land on the stage element only, and the stage
+* republishes the theme, density and style-set 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 five 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 its 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>
+* @example
+* <Preview label="Button" presentation="frame" count={3}>
+*   <Button variant="primary">Take cue</Button>
+* </Preview>
+* @example
+* <Preview label="Editorial band" styleSet="editorial" presentation="frame">
+*   <Container className="max-w-(--cue-measure-prose)">…</Container>
+* </Preview>
+*/
+const Preview = React.forwardRef(function Preview({ children, label, theme, mode, density, font, styleSet, resizable, tools, footer, presentation = "panel", name, count, ground, captions = true, 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,
+		styleSet
+	}, outer);
+	const framed = presentation === "frame";
+	const stage = /* @__PURE__ */ jsx("div", {
+		"data-slot": "preview-stage",
+		...attributes,
+		className: cn(STAGE_HEAD, GROUND_CLASSES[ground ?? DEFAULT_GROUND[presentation]], STAGE_TAIL, options !== null && "flex-1", !framed && tools !== void 0 && TOOLS_RESERVE_STAGE, !captions && CAPTIONS_OFF),
+		style: size.height === null ? void 0 : { minHeight: 0 },
+		children: /* @__PURE__ */ jsx(StageScope, {
+			theme,
+			mode,
+			density,
+			styleSet,
+			children
+		})
+	});
+	const benched = /* @__PURE__ */ jsx("div", {
+		ref: bench,
+		"data-slot": "preview-bench",
+		className: cn(BENCH_CLASS, footer === void 0 && "rounded-b-(--radius-surface)", !framed && 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
+			})]
+		})
+	});
+	if (framed) return /* @__PURE__ */ jsxs("div", {
+		...elementProps,
+		ref,
+		role: "group",
+		"aria-label": label,
+		"data-slot": "preview",
+		"data-presentation": "frame",
+		className: cn(FRAME_ROOT_CLASS, options !== null && "w-full", className),
+		children: [
+			/* @__PURE__ */ jsxs("div", {
+				"data-slot": "preview-frame-label",
+				className: FRAME_LABEL_CLASS,
+				children: [
+					name === void 0 ? /* @__PURE__ */ jsx("span", {
+						"data-slot": "preview-name",
+						className: FRAME_NAME_CLASS,
+						children: label
+					}) : name,
+					count === void 0 ? null : /* @__PURE__ */ jsx("span", {
+						"data-slot": "preview-count",
+						className: FRAME_COUNT_CLASS,
+						children: count
+					}),
+					tools === void 0 ? null : /* @__PURE__ */ jsx("div", {
+						"data-slot": "preview-tools",
+						className: FRAME_TOOLS_CLASS,
+						children: tools
+					})
+				]
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				"data-slot": "preview-frame",
+				className: FRAME_BOX_CLASS,
+				children: [benched, CROSS_CORNERS.map((corner) => /* @__PURE__ */ jsx("span", {
+					"aria-hidden": "true",
+					"data-slot": "preview-crosshair",
+					className: cn(CROSS_CLASS, corner)
+				}, corner))]
+			}),
+			footer === void 0 ? null : /* @__PURE__ */ jsx("div", {
+				"data-slot": "preview-footer",
+				className: FRAME_FOOTER_CLASS,
+				children: footer
+			})
+		]
+	});
+	return /* @__PURE__ */ jsxs("div", {
+		...elementProps,
+		ref,
+		role: "group",
+		"aria-label": label,
+		"data-slot": "preview",
+		className: cn(ROOT_CLASS, options !== null && "w-full", className),
+		children: [
+			benched,
+			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/dist/layout/resizable.d.ts

@@ -0,0 +1,38 @@
+import * as React from "react";
+import { Group, Panel, Separator } from "react-resizable-panels";
+//#region src/layout/resizable.d.ts
+/** Which way the panels are laid out. */
+type ResizableOrientation = "horizontal" | "vertical";
+interface ResizableGroupProps extends React.ComponentProps<typeof Group> {}
+interface ResizablePanelProps extends React.ComponentProps<typeof Panel> {}
+interface ResizableHandleProps extends React.ComponentProps<typeof Separator> {
+  /**
+   * Draw a short grip line down the middle of the handle.
+   *
+   * A 4px strip that only colours on hover is easy to miss on first sight; the
+   * grip is the standing hint that the seam is draggable, for the price of one
+   * hairline.
+   */
+  withGrip?: boolean;
+}
+/**
+ * Split panes the user can drag, on `react-resizable-panels`.
+ *
+ * `react-resizable-panels` is an **optional peer**: import this from
+ * `@cueplusplus/ui/layout/resizable`, never from the core barrel, so an app
+ * with no split view never installs one.
+ *
+ * @example
+ * <Resizable.Group orientation="horizontal">
+ *   <Resizable.Panel id="tree" defaultSize={25} minSize={15}>…</Resizable.Panel>
+ *   <Resizable.Handle withGrip />
+ *   <Resizable.Panel id="editor">…</Resizable.Panel>
+ * </Resizable.Group>
+ */
+declare const Resizable: {
+  Group: React.ForwardRefExoticComponent<ResizableGroupProps & React.RefAttributes<HTMLDivElement>>;
+  Panel: React.ForwardRefExoticComponent<ResizablePanelProps & React.RefAttributes<HTMLDivElement>>;
+  Handle: React.ForwardRefExoticComponent<ResizableHandleProps & React.RefAttributes<HTMLDivElement>>;
+};
+//#endregion
+export { Resizable, ResizableGroupProps, ResizableHandleProps, ResizableOrientation, ResizablePanelProps };