@cueplusplus/ui 0.8.0 → 0.10.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: "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,15 @@ 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 { 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, 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,15 @@ 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 { 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, Sidebar, Stack, Stepper, Timeline, itemVariants, linkVariants, paginationRange, useSidebar };

package/dist/midi/piano-keyboard.js

@@ -49,7 +49,11 @@ const PianoKeyboard = React.forwardRef(function PianoKeyboard({ className, range
 	const [drag, setDrag] = React.useState(null);
 	const settled = React.useMemo(() => keyboardWindow(range, octaves), [range, octaves]);
 	const view = drag?.window ?? settled;
-	const layout = React.useMemo(() => keyboardLayout(view), [view.start, view.end]);
+	const { start: viewStart, end: viewEnd } = view;
+	const layout = React.useMemo(() => keyboardLayout({
+		start: viewStart,
+		end: viewEnd
+	}), [viewStart, viewEnd]);
 	const lit = React.useMemo(() => new Set(highlight ?? []), [highlight]);
 	const setEdge = (edge, note) => {
 		const next = edge === "start" ? {

package/dist/primitives/button.d.ts

@@ -26,6 +26,18 @@ interface ButtonProps extends React.ComponentPropsWithoutRef<"button">, VariantP
    * level without the caller passing a pixel size.
    */
   icon?: React.ElementType;
+  /**
+   * The label. A button with no children and no other accessible name is a
+   * control a screen reader announces as nothing.
+   *
+   * Declared explicitly, although `React.ComponentPropsWithoutRef<"button">`
+   * already carries it, for the reason `Card.Header` and `Bento.Tile` declare
+   * theirs: docgen documents a prop only where the library *declares* it, so
+   * without this line the manifest files no `children` for the system's most
+   * used control — the props table omits it, and a propSet cannot name it,
+   * which is how `/play/button` came to preview an unlabelled `<button>`.
+   */
+  children?: React.ReactNode;
 }
 /**
  * The system's primary action control.

package/dist/styles.css

@@ -3,13 +3,35 @@
  * Consumer app CSS:
  *   @import "tailwindcss";
  *   @import "@cueplusplus/ui/styles.css";
+ *   @import "@cueplusplus/theme-cue/theme.css";   (or any theme package)
  *
  * Tailwind v4 does not scan node_modules, so the library registers its own
  * sources: `@source "./"` resolves relative to THIS file, i.e. the shipped
  * dist/, which is where the class strings live after the build.
  */
 
-@import "@cueplusplus/tokens/theme.css";
+/* Two lines, and the first one is the release's whole behaviour change.
+ *
+ * It used to be `@cueplusplus/tokens/theme.css`, which carried ten palettes and
+ * painted `cue` on a bare `:root`. A palette is a package now, so what this
+ * library ships is the *blank* base: `theme-base/base.css` declares every colour
+ * token at a neutral default and imports `@cueplusplus/tokens/axes.css` for the
+ * geometry and type axes. That is why there is no third line — `base.css`
+ * carries the axes with it, and `tailwind.css` maps utilities onto token names
+ * and pulls nothing.
+ *
+ * An app that imports this and registers no theme therefore paints greys and one
+ * desaturated accent, rather than somebody's brand. To get a palette back:
+ * install a theme package, import its stylesheet after this one, and pass its
+ * manifest to the provider —
+ *
+ *   @import "@cueplusplus/ui/styles.css";
+ *   @import "@cueplusplus/theme-cue/theme.css";
+ *
+ * with `<ThemeProvider themes={[cue]} theme="cue">`. Order matters and is not an
+ * accident: `[data-theme]` and `:root` tie at (0,1,0), so a theme's block wins
+ * by being declared later. */
+@import "@cueplusplus/theme-base/base.css";
 @import "@cueplusplus/tokens/tailwind.css";
 
 @source "./";

package/dist/system/density.d.ts

@@ -1,5 +1,5 @@
 import * as React from "react";
-import { Density } from "@cueplusplus/tokens";
+import { Density } from "@cueplusplus/theme-base";
 //#region src/system/density.d.ts
 interface DensityProps {
   /**
@@ -17,14 +17,23 @@ interface DensityProps {
 /**
  * Re-scope any subtree to a different density level.
  *
- * Renders a plain `<div data-density="…">`: the geometry custom properties are
- * re-declared by the attribute selector and inherit down, so nesting is free and
- * needs no JS. The matching React context is published alongside for the rare
- * JS reads (`useDensity()`, `useControlHeight()`, portal stamping) — the DOM
- * attribute, not the context, is what actually restyles the tree.
+ * Renders a plain `<div data-density="…" data-cue-theme="…">`: the geometry
+ * custom properties are re-declared by the attribute selector and inherit
+ * down, so nesting is free and needs no JS. The matching React context is
+ * published alongside for the rare JS reads (`useDensity()`,
+ * `useControlHeight()`, portal stamping) — the DOM attributes, not the
+ * context, are what actually restyle the tree.
  *
- * Theme and mode are deliberately *not* re-scoped here: density is the only axis
- * an island may override (spec §6).
+ * `data-cue-theme` carries the nearest `<ThemeProvider>`'s name, or is
+ * omitted where there is none. It is read by nothing this island does —
+ * theme and mode are deliberately *not* re-scoped here, density is the only
+ * axis an island may override (spec §6) — it exists so a theme's own
+ * generated CSS can address exactly this island regardless of how many
+ * *other* themed providers sit between it and the one it belongs to. A CSS
+ * ancestor selector can only ask "does some ancestor carry theme `x`", never
+ * "is `x` the *nearest* one"; this stamp answers that question the way
+ * `useContext` already does, at render time, and hands the answer to CSS as
+ * an attribute rather than leaving it unanswerable there.
  *
  * @example
  * <Density density="ultra-compact">

package/dist/system/density.js

@@ -10,14 +10,6 @@ import { jsx } from "react/jsx-runtime";
 * but the level a screen gets when nobody chose is the dense one.
 */
 const DEFAULT_DENSITY = "compact";
-/** The five levels, as a runtime array for validating persisted input. */
-const DENSITY_LEVELS = [
-	"ultra-compact",
-	"compact",
-	"normal",
-	"large",
-	"ultra-large"
-];
 /**
 * Nearest ambient density. `null` means "nothing has stamped a level yet", which
 * `useDensity()` reports as {@link DEFAULT_DENSITY}.
@@ -26,16 +18,45 @@ const DENSITY_LEVELS = [
 */
 const DensityContext = React.createContext(null);
 /**
+* Nearest ambient theme's name, published for exactly one reader: `Density`
+* below, which stamps it onto its island as `data-cue-theme` so a theme's
+* CSS can tell *nearest* theme from *any* theme in the ancestor chain (see
+* `densityRules`/`themeSelector`'s comment). `use-density.ts`'s measuring
+* probe stamps the same attribute from the identical value, read through
+* `ThemeContext` there instead, because it already imports that module with
+* no cycle.
+*
+* Defined here, not in `theme-provider.tsx`, and re-exported from nowhere
+* else. `theme-provider.tsx` already imports `DensityContext` from this
+* module; a context this small living over there and imported back here
+* would cycle the two modules. `null` outside a provider, the same as
+* `ThemeContext`'s own theme field would be if it existed with no provider
+* to require — `Density` used bare, with nothing above it, stamps nothing.
+*
+* Internal: `Density` is the only reader. Not `useTheme()` — that throws
+* outside a provider, and this island has no reason to.
+*/
+const AmbientThemeContext = React.createContext(null);
+/**
 * Re-scope any subtree to a different density level.
 *
-* Renders a plain `<div data-density="…">`: the geometry custom properties are
-* re-declared by the attribute selector and inherit down, so nesting is free and
-* needs no JS. The matching React context is published alongside for the rare
-* JS reads (`useDensity()`, `useControlHeight()`, portal stamping) — the DOM
-* attribute, not the context, is what actually restyles the tree.
+* Renders a plain `<div data-density="…" data-cue-theme="…">`: the geometry
+* custom properties are re-declared by the attribute selector and inherit
+* down, so nesting is free and needs no JS. The matching React context is
+* published alongside for the rare JS reads (`useDensity()`,
+* `useControlHeight()`, portal stamping) — the DOM attributes, not the
+* context, are what actually restyle the tree.
 *
-* Theme and mode are deliberately *not* re-scoped here: density is the only axis
-* an island may override (spec §6).
+* `data-cue-theme` carries the nearest `<ThemeProvider>`'s name, or is
+* omitted where there is none. It is read by nothing this island does —
+* theme and mode are deliberately *not* re-scoped here, density is the only
+* axis an island may override (spec §6) — it exists so a theme's own
+* generated CSS can address exactly this island regardless of how many
+* *other* themed providers sit between it and the one it belongs to. A CSS
+* ancestor selector can only ask "does some ancestor carry theme `x`", never
+* "is `x` the *nearest* one"; this stamp answers that question the way
+* `useContext` already does, at render time, and hands the answer to CSS as
+* an attribute rather than leaving it unanswerable there.
 *
 * @example
 * <Density density="ultra-compact">
@@ -43,10 +64,12 @@ const DensityContext = React.createContext(null);
 * </Density>
 */
 function Density({ density, children, className, style }) {
+	const theme = React.useContext(AmbientThemeContext);
 	return /* @__PURE__ */ jsx(DensityContext.Provider, {
 		value: density,
 		children: /* @__PURE__ */ jsx("div", {
 			"data-density": density,
+			"data-cue-theme": theme ?? void 0,
 			className,
 			style,
 			children
@@ -54,4 +77,4 @@ function Density({ density, children, className, style }) {
 	});
 }
 //#endregion
-export { DEFAULT_DENSITY, DENSITY_LEVELS, Density, DensityContext };
+export { AmbientThemeContext, DEFAULT_DENSITY, Density, DensityContext };