@cueplusplus/ui 0.9.0 → 0.11.0

package/dist/layout/bento.d.ts

@@ -0,0 +1,144 @@
+import { SpaceStep } from "./stack.js";
+import * as React from "react";
+//#region src/layout/bento.d.ts
+/** How many columns the bento resolves to at `lg`. */
+type BentoColumns = 2 | 3 | 4;
+/** How many rows to declare, so a tall tile spans a track that exists. */
+type BentoRows = 1 | 2 | 3 | 4;
+/** How many columns one tile covers, before the container clamps it. */
+type BentoSpan = 1 | 2 | 3 | 4;
+/** How many rows one tile covers. */
+type BentoRowSpan = 1 | 2;
+/** How much height a tile reserves before its content arrives. */
+type BentoMinHeight = "none" | "half" | "hero";
+interface BentoRootProps extends React.ComponentPropsWithoutRef<"div"> {
+  /** How many columns at `lg`. Defaults to `3`. Two from `sm`, one below it. */
+  cols?: BentoColumns;
+  /**
+   * How many rows to declare from `sm` up.
+   *
+   * Only worth setting where a tile spans rows: a `rowSpan` over implicit
+   * tracks sizes itself to the tile's own content, which is not a span.
+   */
+  rows?: BentoRows;
+  /** Pack later tiles into earlier holes instead of leaving them empty. */
+  dense?: boolean;
+  /** Which rung of the density space ladder to spend between tiles. Defaults to `4`. */
+  gap?: SpaceStep;
+  /** The tiles. Declared, so the manifest files it as a documented prop. */
+  children?: React.ReactNode;
+}
+/**
+ * What both tile variants share: the geometry, the four slots and the body.
+ *
+ * An `interface … extends Omit<…>` rather than a type alias over an
+ * intersection, for the same reason `PanelHeaderProps` and `ItemProps` are:
+ * `children` is a documented prop only where a component *declares* it, and a
+ * member of an intersection's object half is attributed to React's own
+ * declaration rather than to this file — so the alias form files every other
+ * slot and silently drops the body.
+ */
+interface BentoTileBase extends Omit<React.ComponentPropsWithoutRef<"div">, "title"> {
+  /** How many columns to cover. Clamped by the container to its own `cols`. */
+  span?: BentoSpan;
+  /** How many rows to cover. Needs a container that declares them. */
+  rowSpan?: BentoRowSpan;
+  /** How much height to hold before the content arrives. Defaults to `"none"`. */
+  minHeight?: BentoMinHeight;
+  /** The qualifier above the name: an import specifier, a family, a device. */
+  eyebrow?: React.ReactNode;
+  /** The tile's name. Rendered as a `<span>`, never as a heading. */
+  title?: React.ReactNode;
+  /** The count beside the name — by convention a `<Chip variant="outline">`. */
+  meta?: React.ReactNode;
+  /** The summary and anything below it. */
+  children?: React.ReactNode;
+}
+/**
+ * A tile whose whole surface is one `<a>`.
+ *
+ * Its content is static: no control, no second link. HTML's content model for
+ * `<a>` is transparent *but* admits no interactive descendant and no `<a>`
+ * descendant, and `inert` changes focus, hit-testing and the accessibility tree
+ * while changing that content model not at all.
+ */
+type BentoLinkTileProps = BentoTileBase & {
+  /** Where the tile goes. Its presence is what makes the tile a link. */
+  href: string;
+  /**
+   * A router's own link element, cloned to carry the tile's classes and slots.
+   *
+   * The **element** form only, and never a render function: a function would
+   * buy a second calling convention at the price of this component's
+   * server-safety, because the hook that reads one is a hook. The element keeps
+   * its own `href` — `next/link` declares that prop required, so passing the
+   * tile's would make the tile the silent owner of a value the element has to
+   * declare anyway. Its own `className` is **merged** with the tile's rather
+   * than replaced by it, which is the other half of the same bargain: `href` is
+   * a value the element owns outright, and a class is one it adds to.
+   */
+  render?: React.ReactElement;
+  /** Never on a link tile: an `<a>` may not contain a control. */
+  action?: never;
+};
+/** A surface that may hold live children; its link or control is a visible sibling. */
+type BentoPanelTileProps = BentoTileBase & {
+  /** Never on a panel tile: `href` is what selects the link variant. */
+  href?: never;
+  /** Never on a panel tile: `render` belongs to the link variant. */
+  render?: never;
+  /** The tile's own link or control, rendered beside the count rather than around it. */
+  action?: React.ReactNode;
+};
+/** Props for {@link Bento.Tile}: a link tile, or a panel tile with an `action`. */
+type BentoTileProps = BentoLinkTileProps | BentoPanelTileProps;
+/**
+ * A grid of unequal tiles: per-item spans, clamped to the container's columns.
+ *
+ * Where `Grid` lays out cells it never touches, a bento's whole content is
+ * per-item — so the span is a prop on the tile, from a closed set, and the
+ * container clamps it on the way past. One column below `sm`, two from `sm`,
+ * the asked-for count from `lg`; the clamp is per breakpoint and not per
+ * `cols`, because every container is two tracks wide in between whatever it
+ * was asked for.
+ *
+ * **Static markup — no hooks, no `"use client"`, and it must stay that way.**
+ * A directive is per *module*, so a `Bento` built on `useRender` would open a
+ * client boundary in every server page that draws one. That is why the router
+ * escape hatch is `render`, an *element* that is cloned, rather than a render
+ * function; and why {@link Bento.Tile} is a discriminated union rather than a
+ * tile that decides at runtime what it is.
+ *
+ * `BentoTileProps` omits the native `title` from its `<div>` props, the same
+ * omission `PanelHeader` and `Item` make: `React.ComponentPropsWithoutRef<"div">`
+ * already declares `title?: string`, and narrowing it to a `ReactNode` without
+ * the `Omit` is TS2430.
+ *
+ * @example
+ * <Bento.Root cols={3} rows={2} gap={5}>
+ *   <Bento.Tile span={2} rowSpan={2} minHeight="hero" title="Kitchen sink">
+ *     Every component, on one page.
+ *   </Bento.Tile>
+ *   <Bento.Tile title="Themes" meta={<Chip variant="outline">10</Chip>} />
+ *   <Bento.Tile title="Density" meta={<Chip variant="outline">5</Chip>} />
+ * </Bento.Root>
+ * @example
+ * <Bento.Tile
+ *   href="/docs/components/grid"
+ *   render={<NextLink href="/docs/components/grid" />}
+ *   eyebrow="@cueplusplus/ui"
+ *   title="Grid"
+ * >
+ *   Equal columns, or as many as fit.
+ * </Bento.Tile>
+ * @example
+ * <Bento.Tile title="Signal" action={<Button onClick={apply}>Apply</Button>}>
+ *   <ThemeSwatches theme="signal" />
+ * </Bento.Tile>
+ */
+declare const Bento: {
+  Root: React.ForwardRefExoticComponent<BentoRootProps & React.RefAttributes<HTMLDivElement>>;
+  Tile: React.ForwardRefExoticComponent<BentoTileProps & React.RefAttributes<HTMLElement>>;
+};
+//#endregion
+export { Bento, BentoColumns, BentoMinHeight, BentoRootProps, BentoRowSpan, BentoRows, BentoSpan, BentoTileProps };

package/dist/layout/bento.js

@@ -0,0 +1,266 @@
+import { cn } from "../lib/cn.js";
+import { GAP_CLASSES } from "./stack.js";
+import * as React from "react";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+//#region src/layout/bento.tsx
+/**
+* Static class per count — Tailwind scans source text, not computed strings.
+*
+* One column below `sm`, two from `sm`, the asked-for count only from `lg`:
+* three fixed columns at 640 px would be ~200 px per tile, narrower than the
+* `18rem` minimum measure every grid this replaces already declares.
+*/
+const COLUMN_CLASSES = {
+	2: "grid-cols-1 sm:grid-cols-2",
+	3: "grid-cols-1 sm:grid-cols-2 lg:grid-cols-3",
+	4: "grid-cols-1 sm:grid-cols-2 lg:grid-cols-4"
+};
+/** Static class per row count, from `sm` up — below it the bento is one column. */
+const ROW_CLASSES = {
+	1: "sm:grid-rows-1",
+	2: "sm:grid-rows-2",
+	3: "sm:grid-rows-3",
+	4: "sm:grid-rows-4"
+};
+/**
+* Static class per span, clamped at `sm` because every container is two tracks
+* wide between 640 px and 1024 px whatever its `cols`.
+*
+* So there is no `sm:col-span-3` and no `sm:col-span-4` in this table at all,
+* and no unprefixed `col-span-*` either: an unprefixed span in the one-track
+* base grid grows an implicit second column, which is the same defect one
+* breakpoint down. A span of 1 or 2 carries through from `sm` and needs no
+* `lg:` rung.
+*/
+const SPAN_CLASSES = {
+	1: "sm:col-span-1",
+	2: "sm:col-span-2",
+	3: "sm:col-span-2 lg:col-span-3",
+	4: "sm:col-span-2 lg:col-span-4"
+};
+/** Static class per row span, from `sm` up for the same reason as the columns. */
+const ROW_SPAN_CLASSES = {
+	1: "sm:row-span-1",
+	2: "sm:row-span-2"
+};
+/**
+* Static class per reserved height, spent off the space ladder's top rung so a
+* hero tile shrinks with the rest of the console at ultra-compact.
+*/
+const MIN_HEIGHT_CLASSES = {
+	none: "",
+	half: "min-h-[calc(var(--cue-space-8)*4)]",
+	hero: "min-h-[calc(var(--cue-space-8)*8)]"
+};
+/** The tile surface, shared by both variants so a link tile is not a second look. */
+const TILE_CLASS = "flex flex-col gap-(--cue-space-3) overflow-hidden rounded-(--radius-surface) border border-border bg-surface-1 p-(--cue-space-5)";
+/** What a link tile adds: the hover tint and the focus ring the whole surface takes. */
+const LINK_TILE_CLASS = "no-underline transition-colors duration-150 outline-none hover:bg-surface-2 focus-visible:outline-2 focus-visible:outline-solid focus-visible:outline-offset-2 focus-visible:outline-accent";
+/** The host elements a link tile may not contain, plus anything carrying `tabIndex`. */
+const INTERACTIVE_TAGS = /* @__PURE__ */ new Set([
+	"a",
+	"button",
+	"input",
+	"select",
+	"textarea"
+]);
+/**
+* The first interactive child a link tile was given, named, or `undefined`.
+*
+* Shallow by design — it walks `React.Children` and not the rendered tree,
+* because it must run in a server render as well as a client one and a hook is
+* not available in either. What it cannot see (a control behind a component
+* boundary) is what each converted grid's own DOM assertion catches.
+*/
+function interactiveChild(children) {
+	let found;
+	React.Children.forEach(children, (child) => {
+		if (found !== void 0 || !React.isValidElement(child)) return;
+		const { tabIndex } = child.props;
+		if (typeof child.type === "string" && INTERACTIVE_TAGS.has(child.type)) found = child.type;
+		else if (tabIndex !== void 0) found = typeof child.type === "string" ? child.type : "child";
+	});
+	return found;
+}
+/** The tile's name as a log line can carry it, for a `title` that is not a string. */
+function tileLabel(title) {
+	return typeof title === "string" || typeof title === "number" ? String(title) : "an untitled tile";
+}
+/**
+* The bento container: a responsive grid that clamps the spans of its tiles.
+*
+* It maps `React.Children` and clones every child whose type is the tile,
+* narrowing that tile's `span` to its own `cols`; anything else passes through
+* with its props untouched, so a `<section>` or a bare `<div>` may sit in a
+* band beside the tiles.
+*
+* **The clamp reaches direct children only, and that is a contract rather than
+* an oversight.** `React.Children` does not descend into a component element,
+* so a tile rendered by a child — `<Bento.Root><MyTiles /></Bento.Root>` — is
+* whatever `span` it declared, and an over-wide one grows an implicit column
+* exactly as an unclamped tile would. Reading through a component would mean
+* rendering it, which a container may not do. So: **keep a tile a child
+* component renders at `span={1}`, or clamp it in that component.** The same
+* hazard in fragment form is why an authored `node` fixture of tiles is an
+* array and not a `<>…</>`.
+*
+* Static markup — no `"use client"`.
+*/
+const BentoRoot = React.forwardRef(function BentoRoot({ className, cols = 3, rows, dense = false, gap = 4, children, ...elementProps }, ref) {
+	return /* @__PURE__ */ jsx("div", {
+		ref,
+		"data-slot": "bento",
+		className: cn("grid", COLUMN_CLASSES[cols], rows === void 0 ? null : ROW_CLASSES[rows], dense ? "grid-flow-row-dense" : null, GAP_CLASSES[gap], className),
+		...elementProps,
+		children: React.Children.map(children, (child) => clampTile(child, cols, rows))
+	});
+});
+/**
+* Clamp one child's spans to the container's tracks, and leave everything else
+* exactly as it was written.
+*
+* CSS Grid does not clamp: auto-placement grows the implicit grid to fit the
+* largest definite span, so one `span={4}` in a `cols={3}` bento silently adds
+* a fourth column and shifts every row. The tile cannot do this for itself —
+* reading its container would need a hook, and this component is static markup
+* on purpose — so the container does it, on the way past.
+*
+* **Both axes, and the row axis only where there is something to clamp to.**
+* The column clamp always applies because `cols` always has a value; `rows` is
+* optional, and a container that declares none is one whose rows are all
+* implicit — there is no track count for `rowSpan` to be too large for, and the
+* tile's own docblock already says that spanning rows there sizes the span to
+* the tile's own content. So an undeclared `rows` leaves `rowSpan` alone, and a
+* declared one is a promise the tile is held to.
+*/
+function clampTile(child, cols, rows) {
+	if (!React.isValidElement(child) || child.type !== BentoTile) return child;
+	const tile = child;
+	const span = tile.props.span ?? 1;
+	const rowSpan = tile.props.rowSpan ?? 1;
+	return React.cloneElement(tile, {
+		span: Math.min(span, cols),
+		...rows === void 0 ? {} : { rowSpan: Math.min(rowSpan, rows) }
+	});
+}
+/**
+* One cell of a bento: a link, or a surface with an `action`.
+*
+* The two are a discriminated union rather than one shape with a runtime
+* branch, because half of the rule is something a compiler can hold: `href`
+* and `action` are mutually exclusive in the type. The other half — that a
+* link tile's content is static — is held by a dev-time check here and by a
+* DOM assertion in each grid that draws one.
+*
+* Static markup — no `"use client"`.
+*/
+const BentoTile = React.forwardRef(function BentoTile(props, ref) {
+	const { className, span = 1, rowSpan = 1, minHeight = "none", eyebrow, title, meta, action, href, render, children, ...elementProps } = props;
+	if (process.env.NODE_ENV !== "production" && href !== void 0) {
+		if (render !== void 0 && render.props.href === void 0) console.error(`Bento.Tile (${tileLabel(title)}): \`render\` was given an element with no \`href\` of its own. The clone does not pass the tile's, so the link would go nowhere — put the href on the element, as \`next/link\` requires anyway.`);
+		const offender = interactiveChild(children) ?? interactiveChild(action);
+		if (offender !== void 0) console.error(`Bento.Tile (${tileLabel(title)}): a link tile contains an interactive <${offender}>. An <a> admits no interactive descendant, so use a panel tile and put the control in \`action\` instead of nesting it here.`);
+	}
+	const head = eyebrow !== void 0 || title !== void 0;
+	const tail = meta !== void 0 || action !== void 0;
+	const content = /* @__PURE__ */ jsxs(Fragment, { children: [head || tail ? /* @__PURE__ */ jsxs("div", {
+		className: "flex items-start justify-between gap-(--cue-space-3)",
+		children: [head ? /* @__PURE__ */ jsxs("div", {
+			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: "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",
+				className: "font-mono text-(length:--cue-text-emphasis) font-medium text-fg",
+				children: title
+			})]
+		}) : null, tail ? /* @__PURE__ */ jsxs("div", {
+			className: "flex shrink-0 items-center gap-(--cue-space-2)",
+			children: [meta === void 0 ? null : /* @__PURE__ */ jsx("span", {
+				"data-slot": "bento-tile-meta",
+				children: meta
+			}), action === void 0 ? null : /* @__PURE__ */ jsx("span", {
+				"data-slot": "bento-tile-action",
+				children: action
+			})]
+		}) : null]
+	}) : null, children] });
+	const surface = {
+		"data-slot": "bento-tile",
+		"data-span": String(span),
+		className: cn(TILE_CLASS, href === void 0 ? null : LINK_TILE_CLASS, SPAN_CLASSES[span], ROW_SPAN_CLASSES[rowSpan], MIN_HEIGHT_CLASSES[minHeight], className),
+		...elementProps
+	};
+	if (href === void 0) return /* @__PURE__ */ jsx("div", {
+		...surface,
+		ref,
+		children: content
+	});
+	const anchorSurface = surface;
+	if (render !== void 0) {
+		const routerLink = render;
+		return React.cloneElement(routerLink, {
+			...anchorSurface,
+			className: cn(routerLink.props.className, anchorSurface.className),
+			ref
+		}, content);
+	}
+	return /* @__PURE__ */ jsx("a", {
+		...anchorSurface,
+		href,
+		ref,
+		children: content
+	});
+});
+/**
+* A grid of unequal tiles: per-item spans, clamped to the container's columns.
+*
+* Where `Grid` lays out cells it never touches, a bento's whole content is
+* per-item — so the span is a prop on the tile, from a closed set, and the
+* container clamps it on the way past. One column below `sm`, two from `sm`,
+* the asked-for count from `lg`; the clamp is per breakpoint and not per
+* `cols`, because every container is two tracks wide in between whatever it
+* was asked for.
+*
+* **Static markup — no hooks, no `"use client"`, and it must stay that way.**
+* A directive is per *module*, so a `Bento` built on `useRender` would open a
+* client boundary in every server page that draws one. That is why the router
+* escape hatch is `render`, an *element* that is cloned, rather than a render
+* function; and why {@link Bento.Tile} is a discriminated union rather than a
+* tile that decides at runtime what it is.
+*
+* `BentoTileProps` omits the native `title` from its `<div>` props, the same
+* omission `PanelHeader` and `Item` make: `React.ComponentPropsWithoutRef<"div">`
+* already declares `title?: string`, and narrowing it to a `ReactNode` without
+* the `Omit` is TS2430.
+*
+* @example
+* <Bento.Root cols={3} rows={2} gap={5}>
+*   <Bento.Tile span={2} rowSpan={2} minHeight="hero" title="Kitchen sink">
+*     Every component, on one page.
+*   </Bento.Tile>
+*   <Bento.Tile title="Themes" meta={<Chip variant="outline">10</Chip>} />
+*   <Bento.Tile title="Density" meta={<Chip variant="outline">5</Chip>} />
+* </Bento.Root>
+* @example
+* <Bento.Tile
+*   href="/docs/components/grid"
+*   render={<NextLink href="/docs/components/grid" />}
+*   eyebrow="@cueplusplus/ui"
+*   title="Grid"
+* >
+*   Equal columns, or as many as fit.
+* </Bento.Tile>
+* @example
+* <Bento.Tile title="Signal" action={<Button onClick={apply}>Apply</Button>}>
+*   <ThemeSwatches theme="signal" />
+* </Bento.Tile>
+*/
+const Bento = {
+	Root: BentoRoot,
+	Tile: BentoTile
+};
+//#endregion
+export { Bento };

package/dist/layout/index.d.ts

@@ -2,14 +2,16 @@ import { Link, LinkProps, linkVariants } from "./link.js";
 import { Sidebar, SidebarItemProps, SidebarRailProps, SidebarRootProps, SidebarSectionProps, useSidebar } from "./sidebar.js";
 import { Container, ContainerProps, ContainerWidth } from "./container.js";
 import { Accordion, AccordionHeaderProps, AccordionItemProps, AccordionPanelProps, AccordionRootProps, AccordionTriggerProps } from "./accordion.js";
+import { SpaceStep, Stack, StackAlign, StackJustify, StackProps } from "./stack.js";
+import { Bento, BentoColumns, BentoMinHeight, BentoRootProps, BentoRowSpan, BentoRows, BentoSpan, BentoTileProps } from "./bento.js";
 import { Breadcrumb, BreadcrumbItem, BreadcrumbProps } from "./breadcrumb.js";
 import { Card, CardContentProps, CardDescriptionProps, CardFooterProps, CardHeaderProps, CardRootProps, CardTitleProps } from "./card.js";
 import { Collapsible, CollapsiblePanelProps, CollapsibleRootProps, CollapsibleTriggerProps, Disclosure, DisclosureProps } from "./collapsible.js";
 import { DescriptionList, DescriptionListDetailProps, DescriptionListLayout, DescriptionListRootProps, DescriptionListTermProps } from "./description-list.js";
-import { SpaceStep, Stack, StackAlign, StackJustify, StackProps } from "./stack.js";
 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, 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

@@ -2,14 +2,16 @@ import { Link, linkVariants } from "./link.js";
 import { Sidebar, useSidebar } from "./sidebar.js";
 import { Container } from "./container.js";
 import { Accordion } from "./accordion.js";
+import { Stack } from "./stack.js";
+import { Bento } from "./bento.js";
 import { Breadcrumb } from "./breadcrumb.js";
 import { Card } from "./card.js";
 import { Collapsible, Disclosure } from "./collapsible.js";
 import { DescriptionList } from "./description-list.js";
-import { Stack } from "./stack.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, 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 };