@cueplusplus/ui 0.10.0 → 0.11.0

package/dist/index.js

@@ -37,12 +37,13 @@ import { EmptyState } from "./chrome/empty-state.js";
 import { Eyebrow } from "./chrome/eyebrow.js";
 import { Container } from "./layout/container.js";
 import { Footer } from "./chrome/footer.js";
+import { SectionHeader } from "./chrome/section-header.js";
+import { Inspector } from "./chrome/inspector.js";
 import { NavigationMenu } from "./chrome/navigation-menu.js";
 import { PageShell } from "./chrome/page-shell.js";
 import { Panel, PanelHeader } from "./chrome/panel.js";
 import { Row, SeamList, rowVariants } from "./chrome/row.js";
 import { ScrollArea } from "./chrome/scroll-area.js";
-import { SectionHeader } from "./chrome/section-header.js";
 import { SegmentedControl } from "./chrome/segmented-control.js";
 import { StatusBar } from "./chrome/status-bar.js";
 import { ScrollableTabsList, Tabs } from "./chrome/tabs.js";
@@ -72,6 +73,7 @@ import { AudienceIcon, CatalogueIcon, ChannelBetaIcon, ChannelReleasedIcon, CliT
 import { activateRowFromClick, activateRowFromKeyDown } from "./instruments/_data-row.js";
 import { AppWindowFrame } from "./instruments/app-window-frame.js";
 import { CopyButton } from "./instruments/copy-button.js";
+import { CodeBlock } from "./instruments/code-block.js";
 import { DataRow } from "./instruments/data-row.js";
 import { DataTree } from "./instruments/data-tree.js";
 import { GroupBar } from "./instruments/group-bar.js";
@@ -95,6 +97,7 @@ import { DescriptionList } from "./layout/description-list.js";
 import { Grid } from "./layout/grid.js";
 import { Item, itemVariants } from "./layout/item.js";
 import { Pagination, paginationRange } from "./layout/pagination.js";
+import { Preview } from "./layout/preview.js";
 import { Stepper } from "./layout/stepper.js";
 import { StatusDot } from "./primitives/status-dot.js";
 import { Timeline } from "./layout/timeline.js";
@@ -115,4 +118,4 @@ import { Kbd } from "./primitives/kbd.js";
 import { Skeleton } from "./primitives/skeleton.js";
 import { useControlHeight, useDensity } from "./system/use-density.js";
 import { useTheme } from "./system/use-theme.js";
-export { AGENT_COLOR_PROPERTY, AGENT_HUES, AGENT_ROOT_COLOR, Accordion, AgentPile, AlertDialog, AppBar, AppShell, AppWindowFrame, AskBox, AudienceIcon, Autocomplete, Avatar, AvatarGroup, Bento, Breadcrumb, Button, ButtonGroup, Card, CatalogueIcon, ChannelBetaIcon, ChannelReleasedIcon, Checkbox, CheckboxGroup, Chip, CliToolIcon, Collapsible, Combobox, CommandPalette, Composer, Container, ContextMenu, CopyButton, CueLogotype, CueMark, CuePortalFrame, DEFAULT_STORAGE_KEY, DataRow, DataTree, DelegationCard, Density, DescriptionList, Dialog, Disclosure, Drawer, DropdownMenu, EmptyState, EnvVarInput, Eyebrow, Field, FieldDescription, FieldError, FieldLabel, FileUpload, FolderIcon, Footer, Grid, GroupBar, HoverCard, IconButton, InfoTip, Input, InputGroup, Item, Kbd, Ledger, Link, McpServerIcon, Menubar, Message, MessageList, Meter, MultiSelect, NavigationMenu, NumberField, OTPField, OVERLAY_SIDE_OFFSET, PageShell, Pagination, Panel, PanelHeader, PasswordInput, Plussie, Popover, Progress, Radio, RadioGroup, Rating, Row, ScrollArea, ScrollableTabsList, ScrubInput, SeamCell, SeamGrid, SeamList, SearchInput, SectionHeader, SegmentedControl, Select, Separator, Sheet, Sidebar, Skeleton, SkillIcon, Slider, Sparkline, Spinner, Stack, StackIcon, StacksMatrixIcon, Stat, StatusBar, StatusDot, Stepper, Switch, TAB_FADE_PX, TREE_GUIDE_GLYPHS, Table, TableScrollRegion, Tabs, TagsInput, TerminalFrame, Textarea, ThemeProvider, Timeline, TitleBar, Toast, Toggle, ToggleGroup, Toolbar, Tooltip, Tree, TreeVisibilityToggle, TwoStepButton, UsageChart, activateRowFromClick, activateRowFromKeyDown, agentColor, agentColorStyle, bareControlClasses, buttonVariants, chipVariants, computeScrollEdges, controlClasses, controlGroupFocusClasses, controlSurface, controlVariants, edgeFadeMask, envReference, flattenTree, isSafeTokenValue, itemVariants, linkVariants, menuItemClasses, menuLabelClasses, menuPopupClasses, menuSeparatorClasses, overlayDescriptionClasses, overlayFooterClasses, overlayModalTransitionClasses, overlayPopupTransitionClasses, overlayPositionerClasses, overlaySurfaceClasses, overlayTextClasses, overlayTitleClasses, paginationRange, parseEnvReference, partitionFiles, prepaintScript, rowVariants, scrimClasses, useControlHeight, useCuePortalProps, useDensities, useDensity, useFonts, useSidebar, useTheme, useThemes, useToast };
+export { AGENT_COLOR_PROPERTY, AGENT_HUES, AGENT_ROOT_COLOR, Accordion, AgentPile, AlertDialog, AppBar, AppShell, AppWindowFrame, AskBox, AudienceIcon, Autocomplete, Avatar, AvatarGroup, Bento, Breadcrumb, Button, ButtonGroup, Card, CatalogueIcon, ChannelBetaIcon, ChannelReleasedIcon, Checkbox, CheckboxGroup, Chip, CliToolIcon, CodeBlock, Collapsible, Combobox, CommandPalette, Composer, Container, ContextMenu, CopyButton, CueLogotype, CueMark, CuePortalFrame, DEFAULT_STORAGE_KEY, DataRow, DataTree, DelegationCard, Density, DescriptionList, Dialog, Disclosure, Drawer, DropdownMenu, EmptyState, EnvVarInput, Eyebrow, Field, FieldDescription, FieldError, FieldLabel, FileUpload, FolderIcon, Footer, Grid, GroupBar, HoverCard, IconButton, InfoTip, Input, InputGroup, Inspector, Item, Kbd, Ledger, Link, McpServerIcon, Menubar, Message, MessageList, Meter, MultiSelect, NavigationMenu, NumberField, OTPField, OVERLAY_SIDE_OFFSET, PageShell, Pagination, Panel, PanelHeader, PasswordInput, Plussie, Popover, Preview, Progress, Radio, RadioGroup, Rating, Row, ScrollArea, ScrollableTabsList, ScrubInput, SeamCell, SeamGrid, SeamList, SearchInput, SectionHeader, SegmentedControl, Select, Separator, Sheet, Sidebar, Skeleton, SkillIcon, Slider, Sparkline, Spinner, Stack, StackIcon, StacksMatrixIcon, Stat, StatusBar, StatusDot, Stepper, Switch, TAB_FADE_PX, TREE_GUIDE_GLYPHS, Table, TableScrollRegion, Tabs, TagsInput, TerminalFrame, Textarea, ThemeProvider, Timeline, TitleBar, Toast, Toggle, ToggleGroup, Toolbar, Tooltip, Tree, TreeVisibilityToggle, TwoStepButton, UsageChart, activateRowFromClick, activateRowFromKeyDown, agentColor, agentColorStyle, bareControlClasses, buttonVariants, chipVariants, computeScrollEdges, controlClasses, controlGroupFocusClasses, controlSurface, controlVariants, edgeFadeMask, envReference, flattenTree, isSafeTokenValue, itemVariants, linkVariants, menuItemClasses, menuLabelClasses, menuPopupClasses, menuSeparatorClasses, overlayDescriptionClasses, overlayFooterClasses, overlayModalTransitionClasses, overlayPopupTransitionClasses, overlayPositionerClasses, overlaySurfaceClasses, overlayTextClasses, overlayTitleClasses, paginationRange, parseEnvReference, partitionFiles, prepaintScript, rowVariants, scrimClasses, useControlHeight, useCuePortalProps, useDensities, useDensity, useFonts, useSidebar, useTheme, useThemes, useToast };

package/dist/instruments/code-block.d.ts

@@ -0,0 +1,35 @@
+import * as React from "react";
+//#region src/instruments/code-block.d.ts
+interface CodeBlockProps extends Omit<React.ComponentPropsWithoutRef<"div">, "children"> {
+  /** The code. Printed verbatim, already dedented by whoever produced it; the copy button copies exactly this. */
+  code: string;
+  /** What the block is, in the caption strip: a filename, an example's title. Defaults to the language. */
+  label?: string;
+  /**
+   * The fence language, on the `<pre>` as `data-language`. Defaults to `"tsx"`.
+   * `"jsx"` turns on emphasis: tag names, attribute names and punctuation in
+   * three inks the theme already has. Every other value prints plain.
+   */
+  language?: string;
+}
+/**
+ * A block of code with a copy button and no syntax-highlighter palette.
+ *
+ * Every colour a token-driven site paints has to come from the token layer, and
+ * a highlighter theme is a second palette that would need porting to every
+ * preset before it could sit beside them — so there is none. What `language="jsx"`
+ * adds is emphasis in three inks the theme already has: tag names in `--cue-fg`,
+ * attribute names in `--cue-fg-muted`, punctuation in `--cue-fg-subtle`. Mono
+ * type, the sunken ground every input uses, and a copy button that works.
+ *
+ * No directive: the copy button is the only client code, and a server page can
+ * draw the rest.
+ *
+ * @example
+ * <CodeBlock label="install" code="pnpm add @cueplusplus/ui" language="sh" />
+ * @example
+ * <CodeBlock label="JSX" language="jsx" code={'<Button variant="primary">Take cue</Button>'} />
+ */
+declare const CodeBlock: React.ForwardRefExoticComponent<CodeBlockProps & React.RefAttributes<HTMLDivElement>>;
+//#endregion
+export { CodeBlock, CodeBlockProps };

package/dist/instruments/code-block.js

@@ -0,0 +1,173 @@
+import { cn } from "../lib/cn.js";
+import { Panel } from "../chrome/panel.js";
+import { CopyButton } from "./copy-button.js";
+import * as React from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/instruments/code-block.tsx
+/** The three inks, and nothing else: a highlighter theme would be a second palette. */
+const INK = {
+	tag: "text-fg",
+	attr: "text-fg-muted",
+	punct: "text-fg-subtle"
+};
+/**
+* The end of a `{…}` expression starting at `start`, braces balanced; the
+* code's end if unclosed.
+*
+* A JS string literal inside the expression (`"…"`, `'…'`, `` `…` ``,
+* backslash escapes honoured) is skipped whole rather than scanned for
+* braces: `{"a { b"}` has a real `{` and a stray one sitting inside a string,
+* and only the first is the expression's own. Treating the string as opaque
+* is also what keeps `{"<b>hi</b>"}` a single span for the caller that uses
+* this to find where a JSX child expression ends — the `<b>` inside never
+* gets a chance to look like a tag.
+*/
+function expressionEnd(code, start) {
+	let depth = 0;
+	let index = start;
+	while (index < code.length) {
+		const ch = code[index];
+		if (ch === "\"" || ch === "'" || ch === "`") {
+			const quote = ch;
+			index += 1;
+			while (index < code.length && code[index] !== quote) index += code[index] === "\\" ? 2 : 1;
+			index += 1;
+			continue;
+		}
+		if (ch === "{") depth += 1;
+		else if (ch === "}") {
+			depth -= 1;
+			if (depth === 0) return index + 1;
+		}
+		index += 1;
+	}
+	return code.length;
+}
+/**
+* JSX, cut into the four kinds this block paints.
+*
+* A tag opens at `<` or `</` followed by a letter — so `a < b` is text — and
+* runs to `>` or `/>`. Inside it, a name is an attribute, `=` is punctuation,
+* and a quoted string or a balanced `{…}` is text. Outside a tag everything is
+* text, comments included — and a `{…}` expression child (`{"<b>hi</b>"}`, the
+* shape `JSON.stringify` produces) stays opaque too, found with the same
+* brace-and-string-aware scan as an attribute's expression value, so a `<`
+* sitting inside its string can never be mistaken for a tag opening. The
+* pieces concatenate back to the input exactly, which the suite asserts and
+* the copy button depends on.
+*/
+function jsxTokens(code) {
+	const tokens = [];
+	const push = (kind, from, to) => {
+		if (to <= from) return;
+		const last = tokens.at(-1);
+		if (kind === "text" && last?.kind === "text") last.text += code.slice(from, to);
+		else tokens.push({
+			kind,
+			text: code.slice(from, to),
+			at: from
+		});
+	};
+	let index = 0;
+	while (index < code.length) {
+		const open = /^<\/?(?=[A-Za-z])/.exec(code.slice(index));
+		if (open === null) {
+			let cursor = code[index] === "{" ? expressionEnd(code, index) : index + 1;
+			while (cursor < code.length) {
+				const ch = code[cursor];
+				if (ch === "{") {
+					cursor = expressionEnd(code, cursor);
+					continue;
+				}
+				if (ch === "<") break;
+				cursor += 1;
+			}
+			push("text", index, cursor);
+			index = cursor;
+			continue;
+		}
+		push("punct", index, index + open[0].length);
+		index += open[0].length;
+		const name = /^[A-Za-z][\w.]*/.exec(code.slice(index))[0];
+		push("tag", index, index + name.length);
+		index += name.length;
+		while (index < code.length) {
+			const rest = code.slice(index);
+			const space = /^\s+/.exec(rest);
+			const close = /^\/?>/.exec(rest);
+			const attribute = /^[^\s=>/"{]+/.exec(rest);
+			if (space !== null) {
+				push("text", index, index + space[0].length);
+				index += space[0].length;
+			} else if (close !== null) {
+				push("punct", index, index + close[0].length);
+				index += close[0].length;
+				break;
+			} else if (rest.startsWith("=")) {
+				push("punct", index, index + 1);
+				index += 1;
+			} else if (rest.startsWith("\"")) {
+				const quote = code.indexOf("\"", index + 1);
+				const end = quote === -1 ? code.length : quote + 1;
+				push("text", index, end);
+				index = end;
+			} else if (rest.startsWith("{")) {
+				const end = expressionEnd(code, index);
+				push("text", index, end);
+				index = end;
+			} else if (attribute !== null) {
+				push("attr", index, index + attribute[0].length);
+				index += attribute[0].length;
+			} else {
+				push("text", index, index + 1);
+				index += 1;
+			}
+		}
+	}
+	return tokens;
+}
+/**
+* A block of code with a copy button and no syntax-highlighter palette.
+*
+* Every colour a token-driven site paints has to come from the token layer, and
+* a highlighter theme is a second palette that would need porting to every
+* preset before it could sit beside them — so there is none. What `language="jsx"`
+* adds is emphasis in three inks the theme already has: tag names in `--cue-fg`,
+* attribute names in `--cue-fg-muted`, punctuation in `--cue-fg-subtle`. Mono
+* type, the sunken ground every input uses, and a copy button that works.
+*
+* No directive: the copy button is the only client code, and a server page can
+* draw the rest.
+*
+* @example
+* <CodeBlock label="install" code="pnpm add @cueplusplus/ui" language="sh" />
+* @example
+* <CodeBlock label="JSX" language="jsx" code={'<Button variant="primary">Take cue</Button>'} />
+*/
+const CodeBlock = React.forwardRef(function CodeBlock({ code, label, language = "tsx", className, ...elementProps }, ref) {
+	const body = language === "jsx" ? jsxTokens(code).map((token) => token.kind === "text" ? token.text : /* @__PURE__ */ jsx("span", {
+		"data-token": token.kind,
+		className: INK[token.kind],
+		children: token.text
+	}, token.at)) : code;
+	return /* @__PURE__ */ jsxs(Panel, {
+		...elementProps,
+		ref,
+		"data-slot": "code-block",
+		className: cn("bg-sunken", className),
+		children: [/* @__PURE__ */ jsxs("div", {
+			className: "flex items-center justify-between gap-(--cue-space-4) border-b border-border px-(--cue-pad-row-x) py-(--cue-pad-row-y)",
+			children: [/* @__PURE__ */ jsx("span", {
+				"data-slot": "code-block-label",
+				className: "font-mono text-(length:--cue-text-micro) tracking-[0.15em] text-fg-subtle uppercase",
+				children: label ?? language
+			}), /* @__PURE__ */ jsx(CopyButton, { value: code })]
+		}), /* @__PURE__ */ jsx("pre", {
+			"data-language": language,
+			className: "overflow-x-auto p-(--cue-space-4) font-mono text-(length:--cue-text-ui) leading-relaxed text-fg",
+			children: /* @__PURE__ */ jsx("code", { children: body })
+		})]
+	});
+});
+//#endregion
+export { CodeBlock };

package/dist/instruments/index.d.ts

@@ -1,5 +1,6 @@
 import { activateRowFromClick, activateRowFromKeyDown } from "./_data-row.js";
 import { AppWindowFrame, AppWindowFrameProps } from "./app-window-frame.js";
+import { CodeBlock, CodeBlockProps } from "./code-block.js";
 import { CopyButton, CopyButtonProps } from "./copy-button.js";
 import { DataRow, DataRowDisclosure, DataRowRootProps, DataRowSlotProps } from "./data-row.js";
 import { DataTree, DataTreeItem, DataTreeProps, DataTreeRowState } from "./data-tree.js";
@@ -14,4 +15,4 @@ import { Table, TableCaptionProps, TableCellProps, TableGroupRowProps, TableHead
 import { TerminalFrame, TerminalFrameLine, TerminalFrameProps, TerminalLine, TerminalLineTone, TerminalScript, TerminalStep } from "./terminal-frame.js";
 import { TwoStepButton, TwoStepButtonProps, TwoStepTone } from "./two-step-button.js";
 import { UsageChart, UsageChartPoint, UsageChartProps, UsageChartTone } from "./usage-chart.js";
-export { AppWindowFrame, type AppWindowFrameProps, CopyButton, type CopyButtonProps, DataRow, type DataRowDisclosure, type DataRowRootProps, type DataRowSlotProps, DataTree, type DataTreeItem, type DataTreeProps, type DataTreeRowState, GroupBar, type GroupBarItem, type GroupBarProps, type GroupBarTone, Ledger, type LedgerEmptyProps, type LedgerGroupProps, type LedgerRootProps, type LedgerTierProps, Meter, type MeterProps, type MeterProvenance, type MeterTone, Progress, type ProgressProps, SeamCell, type SeamCellProps, SeamGrid, type SeamGridProps, type SeamGround, Sparkline, type SparklineProps, Stat, type StatProps, type StatTone, Table, type TableCaptionProps, type TableCellProps, type TableGroupRowProps, type TableHeadProps, type TableRootProps, type TableRowProps, TableScrollRegion, type TableScrollRegionProps, type TableSectionProps, TerminalFrame, type TerminalFrameLine, type TerminalFrameProps, type TerminalLine, type TerminalLineTone, type TerminalScript, type TerminalStep, TwoStepButton, type TwoStepButtonProps, type TwoStepTone, UsageChart, type UsageChartPoint, type UsageChartProps, type UsageChartTone, activateRowFromClick, activateRowFromKeyDown };
+export { AppWindowFrame, type AppWindowFrameProps, CodeBlock, type CodeBlockProps, CopyButton, type CopyButtonProps, DataRow, type DataRowDisclosure, type DataRowRootProps, type DataRowSlotProps, DataTree, type DataTreeItem, type DataTreeProps, type DataTreeRowState, GroupBar, type GroupBarItem, type GroupBarProps, type GroupBarTone, Ledger, type LedgerEmptyProps, type LedgerGroupProps, type LedgerRootProps, type LedgerTierProps, Meter, type MeterProps, type MeterProvenance, type MeterTone, Progress, type ProgressProps, SeamCell, type SeamCellProps, SeamGrid, type SeamGridProps, type SeamGround, Sparkline, type SparklineProps, Stat, type StatProps, type StatTone, Table, type TableCaptionProps, type TableCellProps, type TableGroupRowProps, type TableHeadProps, type TableRootProps, type TableRowProps, TableScrollRegion, type TableScrollRegionProps, type TableSectionProps, TerminalFrame, type TerminalFrameLine, type TerminalFrameProps, type TerminalLine, type TerminalLineTone, type TerminalScript, type TerminalStep, TwoStepButton, type TwoStepButtonProps, type TwoStepTone, UsageChart, type UsageChartPoint, type UsageChartProps, type UsageChartTone, activateRowFromClick, activateRowFromKeyDown };

package/dist/instruments/index.js

@@ -1,6 +1,7 @@
 import { activateRowFromClick, activateRowFromKeyDown } from "./_data-row.js";
 import { AppWindowFrame } from "./app-window-frame.js";
 import { CopyButton } from "./copy-button.js";
+import { CodeBlock } from "./code-block.js";
 import { DataRow } from "./data-row.js";
 import { DataTree } from "./data-tree.js";
 import { GroupBar } from "./group-bar.js";
@@ -14,4 +15,4 @@ import { Table, TableScrollRegion } from "./table.js";
 import { TerminalFrame } from "./terminal-frame.js";
 import { TwoStepButton } from "./two-step-button.js";
 import { UsageChart } from "./usage-chart.js";
-export { AppWindowFrame, CopyButton, DataRow, DataTree, GroupBar, Ledger, Meter, Progress, SeamCell, SeamGrid, Sparkline, Stat, Table, TableScrollRegion, TerminalFrame, TwoStepButton, UsageChart, activateRowFromClick, activateRowFromKeyDown };
+export { AppWindowFrame, CodeBlock, CopyButton, DataRow, DataTree, GroupBar, Ledger, Meter, Progress, SeamCell, SeamGrid, Sparkline, Stat, Table, TableScrollRegion, TerminalFrame, TwoStepButton, UsageChart, activateRowFromClick, activateRowFromKeyDown };

package/dist/layout/bento.js

@@ -169,7 +169,7 @@ const BentoTile = React.forwardRef(function BentoTile(props, ref) {
 			className: "flex min-w-0 flex-col gap-(--cue-space-1)",
 			children: [eyebrow === void 0 ? null : /* @__PURE__ */ jsx("span", {
 				"data-slot": "bento-tile-eyebrow",
-				className: "font-mono text-(length:--cue-text-meta) text-fg-muted",
+				className: "min-w-0 truncate font-mono text-(length:--cue-text-meta) text-fg-muted",
 				children: eyebrow
 			}), title === void 0 ? null : /* @__PURE__ */ jsx("span", {
 				"data-slot": "bento-tile-title",

package/dist/layout/index.d.ts

@@ -11,6 +11,7 @@ import { DescriptionList, DescriptionListDetailProps, DescriptionListLayout, Des
 import { Grid, GridColumns, GridProps } from "./grid.js";
 import { Item, ItemProps, itemVariants } from "./item.js";
 import { Pagination, PaginationEntry, PaginationProps, paginationRange } from "./pagination.js";
+import { Preview, PreviewAxis, PreviewProps, PreviewResizeOptions } from "./preview.js";
 import { Stepper, StepperProps, StepperState, StepperStep } from "./stepper.js";
 import { Timeline, TimelineContentProps, TimelineItemProps, TimelineMarkerProps, TimelineRootProps } from "./timeline.js";
-export { Accordion, type AccordionHeaderProps, type AccordionItemProps, type AccordionPanelProps, type AccordionRootProps, type AccordionTriggerProps, Bento, type BentoColumns, type BentoMinHeight, type BentoRootProps, type BentoRowSpan, type BentoRows, type BentoSpan, type BentoTileProps, Breadcrumb, type BreadcrumbItem, type BreadcrumbProps, Card, type CardContentProps, type CardDescriptionProps, type CardFooterProps, type CardHeaderProps, type CardRootProps, type CardTitleProps, Collapsible, type CollapsiblePanelProps, type CollapsibleRootProps, type CollapsibleTriggerProps, Container, type ContainerProps, type ContainerWidth, DescriptionList, type DescriptionListDetailProps, type DescriptionListLayout, type DescriptionListRootProps, type DescriptionListTermProps, Disclosure, type DisclosureProps, Grid, type GridColumns, type GridProps, Item, type ItemProps, Link, type LinkProps, Pagination, type PaginationEntry, type PaginationProps, Sidebar, type SidebarItemProps, type SidebarRailProps, type SidebarRootProps, type SidebarSectionProps, type SpaceStep, Stack, type StackAlign, type StackJustify, type StackProps, Stepper, type StepperProps, type StepperState, type StepperStep, Timeline, type TimelineContentProps, type TimelineItemProps, type TimelineMarkerProps, type TimelineRootProps, itemVariants, linkVariants, paginationRange, useSidebar };
+export { Accordion, type AccordionHeaderProps, type AccordionItemProps, type AccordionPanelProps, type AccordionRootProps, type AccordionTriggerProps, Bento, type BentoColumns, type BentoMinHeight, type BentoRootProps, type BentoRowSpan, type BentoRows, type BentoSpan, type BentoTileProps, Breadcrumb, type BreadcrumbItem, type BreadcrumbProps, Card, type CardContentProps, type CardDescriptionProps, type CardFooterProps, type CardHeaderProps, type CardRootProps, type CardTitleProps, Collapsible, type CollapsiblePanelProps, type CollapsibleRootProps, type CollapsibleTriggerProps, Container, type ContainerProps, type ContainerWidth, DescriptionList, type DescriptionListDetailProps, type DescriptionListLayout, type DescriptionListRootProps, type DescriptionListTermProps, Disclosure, type DisclosureProps, Grid, type GridColumns, type GridProps, Item, type ItemProps, Link, type LinkProps, Pagination, type PaginationEntry, type PaginationProps, Preview, type PreviewAxis, type PreviewProps, type PreviewResizeOptions, Sidebar, type SidebarItemProps, type SidebarRailProps, type SidebarRootProps, type SidebarSectionProps, type SpaceStep, Stack, type StackAlign, type StackJustify, type StackProps, Stepper, type StepperProps, type StepperState, type StepperStep, Timeline, type TimelineContentProps, type TimelineItemProps, type TimelineMarkerProps, type TimelineRootProps, itemVariants, linkVariants, paginationRange, useSidebar };

package/dist/layout/index.js

@@ -11,6 +11,7 @@ import { DescriptionList } from "./description-list.js";
 import { Grid } from "./grid.js";
 import { Item, itemVariants } from "./item.js";
 import { Pagination, paginationRange } from "./pagination.js";
+import { Preview } from "./preview.js";
 import { Stepper } from "./stepper.js";
 import { Timeline } from "./timeline.js";
-export { Accordion, Bento, Breadcrumb, Card, Collapsible, Container, DescriptionList, Disclosure, Grid, Item, Link, Pagination, Sidebar, Stack, Stepper, Timeline, itemVariants, linkVariants, paginationRange, useSidebar };
+export { Accordion, Bento, Breadcrumb, Card, Collapsible, Container, DescriptionList, Disclosure, Grid, Item, Link, Pagination, Preview, Sidebar, Stack, Stepper, Timeline, itemVariants, linkVariants, paginationRange, useSidebar };

package/dist/layout/preview.d.ts

@@ -0,0 +1,110 @@
+import * as React from "react";
+import { Density, FontName, Mode, ThemeName } from "@cueplusplus/theme-base";
+//#region src/layout/preview.d.ts
+/** Which edges of the stage a reader may drag. */
+type PreviewAxis = "x" | "y" | "both";
+/** How far a resizable stage may go, in CSS pixels, and along which axes. */
+interface PreviewResizeOptions {
+  /** Which axes resize. Defaults to `"both"`; `"x"` or `"y"` narrows it to one grip. */
+  axis?: PreviewAxis;
+  /** The narrowest the stage may be made, in px. Defaults to `160`. */
+  minWidth?: number;
+  /**
+   * The widest the stage may be made, in px. Defaults to `1280`. The bound in
+   * force is the smaller of this and the frame's own width, measured live, so a
+   * stage never outgrows the frame — or the grid track — it sits in.
+   */
+  maxWidth?: number;
+  /** The shortest the stage may be made, in px. Defaults to `96`. */
+  minHeight?: number;
+  /** The tallest the stage may be made, in px. Defaults to `960`. */
+  maxHeight?: number;
+}
+interface PreviewProps extends Omit<React.ComponentPropsWithoutRef<"div">, "children"> {
+  /** The specimen. It renders on the stage, inside whatever scope the stage sets. */
+  children: React.ReactNode;
+  /**
+   * The frame's accessible name — "Button preview". Required: a frame that holds
+   * controls and has no name is a group nobody can find.
+   */
+  label: string;
+  /**
+   * A theme for the stage only. Unset, the stage inherits — no attribute is
+   * emitted at all. **Naming a theme does not load it**: the stage is scoped to
+   * `[data-theme="<name>"]`, and that theme's stylesheet must already be on the
+   * page (`@cueplusplus/theme-<name>/theme.css`). The tools, the footer and
+   * anything they open stay in the page's theme. With no `mode`, the stage
+   * repeats the page's mode beside the theme — `"system"` included — so a light
+   * page's stage paints the theme's light block, not its dark one, and agrees
+   * with every overlay opened on it.
+   */
+  theme?: ThemeName;
+  /**
+   * Dark, light or system, for the stage only. A theme's light block is the
+   * compound selector `[data-theme][data-mode]`, so with no `theme` the stage
+   * restates the page's theme beside the mode; outside any `ThemeProvider` there
+   * is no theme to restate and the mode alone changes nothing. A stage
+   * `"system"` is stamped as it is, so the stylesheet's `[data-mode="system"]`
+   * block follows the OS; `useTheme().resolvedMode` read on the stage reports
+   * the page's resolved mode.
+   */
+  mode?: Mode;
+  /** A rung of the density ladder for the stage only, as a `<Density>` island would set it. */
+  density?: Density;
+  /** A font pairing for the stage only, as `data-font`. Portals still follow the root's pairing. */
+  font?: FontName;
+  /**
+   * Resize the stage by dragging or with the keyboard. `true` gives both axes
+   * inside the default bounds (160–1280 px wide, 96–960 px tall); an object
+   * narrows the axis or moves the bounds. The width never outgrows the frame:
+   * its bound in force is the smaller of `maxWidth` and the frame's own width,
+   * observed with a `ResizeObserver`, so a Preview in a grid track stays inside
+   * it as the viewport changes. The height is bounded by `maxHeight` alone, and
+   * a taller stage grows its frame. Unset, the stage is fixed: no grips, and
+   * nothing measured or observed.
+   *
+   * A resizable frame fills its container's width (`w-full`), because the room
+   * it measures has to be its container's. In a flex row or a centred column a
+   * frame sized by its content would measure its own stage, and a stage bounded
+   * by itself can only shrink, with each step lowering the ceiling. A fixed
+   * Preview keeps sizing to its content; `className` can still set a width.
+   */
+  resizable?: boolean | PreviewResizeOptions;
+  /** The top-right slot — by convention a row of `IconButton`s. Drawn outside the stage. */
+  tools?: React.ReactNode;
+  /** The strip under the stage: the thin text and the way out. Drawn outside the stage. */
+  footer?: React.ReactNode;
+}
+/**
+ * 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>
+ */
+declare const Preview: React.ForwardRefExoticComponent<PreviewProps & React.RefAttributes<HTMLDivElement>>;
+//#endregion
+export { Preview, PreviewAxis, PreviewProps, PreviewResizeOptions };