@cueplusplus/ui 0.11.1 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,203 @@
 # @cueplusplus/ui
 
+## 0.12.0
+
+### Minor Changes
+
+- 11c7307: A design canvas — `Frames` — and a `Preview` that knows how to sit on one.
+
+  **Nothing to do.** `Frames` is a new export, all five of `Preview`'s new props are optional, and no
+  prop that already existed changed shape. A `Preview` called the way you call one today renders
+  **byte-identical markup** — the same string, class for class — and this package's suite holds it to
+  three goldens captured from the tree before the change rather than to a promise.
+  `@cueplusplus/tokens` and `@cueplusplus/brand-tokens` move with it as one fixed family, and neither
+  changes. The snippets below are fragments.
+
+  **`Frames`** (`@cueplusplus/ui`, and `@cueplusplus/ui/layout`) is a new compound in two parts:
+  `Frames.Root` is the canvas, `Frames.Item` is one captioned cell on it. `FramesHeight`,
+  `FramesRootProps` and `FramesItemProps` ship beside them.
+
+  ```tsx
+  import { Button } from "@cueplusplus/ui";
+  import { Frames, Preview } from "@cueplusplus/ui/layout";
+
+  <Frames.Root label="Button frames" hint="drag to pan · 2 frames">
+    <Preview presentation="frame" label="Tone" count={2}>
+      <div className="flex flex-wrap items-end gap-(--cue-space-6)">
+        <Frames.Item caption="accent">
+          <Button variant="primary">Take cue</Button>
+        </Frames.Item>
+        <Frames.Item caption="default">
+          <Button>Take cue</Button>
+        </Frames.Item>
+      </div>
+    </Preview>
+    <Preview presentation="frame" label="Size" count={3}>
+      …
+    </Preview>
+  </Frames.Root>;
+  ```
+
+  - **Short and wide on purpose.** `height` is `"short"` (18.5rem, the default) or `"tall"` (27rem),
+    and a CSS length in `style` beats both. The canvas scrolls sideways and never down.
+  - **`label` is required**, and it is not decoration: the canvas is a `role="region"` with
+    `tabIndex={0}`, and a scroll region with no name is one a screen reader announces as nothing.
+  - **The keyboard scrolls it.** Left and Right step one rung of `--cue-space-8` — read off the canvas
+    itself, so a board inside a `<Density>` island steps by that density's rung — PageUp and PageDown
+    step a viewport, and Home and End reach the ends. Smoothly, or instantly for a reader who asked
+    for less motion.
+  - **Dragging pans it**, by `scrollLeft` and not by a transform, so the scrollbar stays real and a
+    popover opened inside a frame stays anchored. Only the primary button drags, and a drag that
+    starts on a `button`, `a`, `input`, `select`, `textarea`, or an element carrying a `role` of its
+    own, is never a pan — so a frame's own controls keep working. `pan={false}` binds no pointer
+    listener at all and leaves the keyboard alone.
+  - `ground` is `"plain"`, `"dots"` (the default) or `"none"`, and `hint` is an optional node in the
+    bottom-right corner, which is where a line like "drag to pan · 8 frames" goes.
+  - **It does not zoom, and it does not inspect its children** — it never counts them, indexes them or
+    selects one. The count in `hint` is one you passed it. Zoom is a refusal rather than a gap: a
+    transformed subtree breaks every popover anchored inside it.
+  - **`Frames.Item` goes inside a `Preview`**, not directly inside `Frames.Root`: the canvas holds
+    frames, a frame holds a stage, and the stage holds these. `caption` is the line under the
+    specimen, and `selected` draws the outline on the one a reader is inspecting.
+  - **A stage does not arrange several items — you do.** A stage is a centred grid in both
+    presentations, so two items left to it stack. Put them in a row wrapper:
+    `<div className="flex flex-wrap items-end gap-(--cue-space-6)">` — `items-end` so specimens of
+    different heights share a baseline, `flex-wrap` so a narrow frame folds rather than clips. Every
+    example in this library uses that one spelling.
+  - The whole `Frames` module is a client component (`"use client"`), as `Preview` already was — so
+    `Frames.Item` is one too.
+
+  **`Preview` gains five optional props.** `name` and `count` are drawn only in the new `"frame"`
+  presentation; `ground` and `captions` apply to a panel's stage just as well.
+
+  ```tsx
+  <Preview
+    presentation="frame"
+    label="Button tone"
+    name={<ToneMenu />}
+    count={3}
+    captions={false}
+  >
+    …
+  </Preview>
+  ```
+
+  - **`presentation`** is `"panel" | "frame"`. `"panel"` is the default and is what `Preview` has
+    always drawn: a bordered card, `tools` floating over the stage's top right, a footer under it.
+    `"frame"` draws the label row _above_ the stage instead of over it, moves `tools` into that row
+    (where they reserve no room on the stage), makes the stage transparent so whatever it sits on
+    shows through, and puts four crosshair marks at its outer corners.
+  - **`name`** is the label row's leading slot, drawn only in a frame — a plain node, or your own
+    control: pass a `DropdownMenu` whose trigger is the frame's name. Unset, the row opens with
+    `label` as text. A slot and not a built-in menu, because this component imports no overlay, and a
+    page that draws seventeen Previews should not have to pay for one.
+  - **`count`** is the figure drawn after the name, in a frame only. Nothing is counted for you, and
+    `0` is a figure it draws.
+  - **`ground`** is the stage's ground — `"plain"`, `"dots"` or `"none"`. It defaults to `"dots"` in a
+    panel, which is the bench this library has always drawn, and to `"none"` in a frame, where the
+    canvas under it already carries a ground and two dot grids at different pitches read as a moiré.
+  - **`captions={false}`** turns the `Frames.Item` captions off on that stage, and it is paint and
+    nothing more: `opacity: 0` and `pointer-events: none`, never `visibility: hidden` and never
+    `display: none`. Each caption keeps its box, so nothing re-flows, and keeps its place in the
+    accessibility tree, so a screen reader still reads it — a caption is what names one specimen apart
+    from the next. Drop the `caption` prop if the words should not be in the page at all.
+
+  `PreviewPresentation` and `PreviewGround` are exported beside `PreviewProps`.
+
+  **Frame chrome follows the page, exactly as a panel's does.** `theme`, `mode`, `density` and `font`
+  still land on the stage and nowhere else; the label row, the `name` slot, the count, the tools, the
+  crosshairs and the footer stay in the scope around the Preview.
+
+  `manifest/manifest.json`, `manifest/components/frames.json` and `manifest/components/preview.json`
+  were regenerated with them.
+
+### Patch Changes
+
+- 7e8857d: Frame captions, preview footers and bento eyebrows are small again, instead of taking their size from whatever sat above them.
+
+  **Nothing to do.** No prop changed shape, no element moved, no slot was renamed. Six class strings
+  changed one word each; a page that looked right before looks the same, and the lines described
+  below get smaller.
+
+  **What you saw.** Five lines of chrome across three components drew at the size of the text around
+  them rather than at the smallest rung of the type ladder:
+
+  - `Preview`'s footer row, and the count beside a frame's name (`presentation="frame"`) — which sat
+    _larger_ than the name it followed, though it is the quieter of the two;
+  - `Frames.Root`'s corner hint, the "drag to pan · 8 frames" line;
+  - `Frames.Item`'s caption under each specimen;
+  - `Bento.Tile`'s eyebrow, the mono line above a tile's title.
+
+  Each rendered at the font size of its nearest styled ancestor, so the same caption was one size on
+  a page whose section set a size and another size on a page that did not.
+
+  **Why.** All five asked for `--cue-text-meta`, and there is no such token: `@cueplusplus/tokens`
+  publishes six type rungs — `micro`, `label`, `ui`, `body`, `emphasis`, `title` — and `meta` is not
+  one of them. A `var()` naming a property nothing declares makes the whole declaration invalid at
+  computed-value time, so the browser threw the `font-size` away and the element inherited. That is
+  why nothing warned: the class attribute was well-formed, the markup was identical, and only the
+  rendered page was wrong.
+
+  They now ask for `--cue-text-micro`, the rung those lines were always meant to sit on and the one
+  this library already uses for every other mono eyebrow and caption. That is **8px** at the
+  `compact` default, and 8 / 8 / 9 / 10 / 11 px across `ultra-compact` through `ultra-large`, before
+  any `fontScale` you have set on the provider.
+
+  **A sixth line, found by the guard below once it was extended, and a different mistake.** `Drawer`'s grab handle — the
+  little bar at the top of a bottom drawer, or the side of a side one — asked for
+  `rounded-(--radius-full)`, and there is no such Tailwind theme variable: this system's bridge
+  publishes `--radius-control`, `--radius-surface` and `--radius-overlay`, and Tailwind's own scale
+  runs `--radius-xs` through `--radius-4xl`. So the handle drew a 4px-thick rectangle with square
+  ends where it should have been a pill. It is now `rounded-full`, which is the spelling the other
+  184 pill-shaped elements in this library already use — `StatusDot`, `Avatar`, `Spinner`,
+  `InfoTip` — and which needs no theme variable at all.
+
+  **A guard came with it.** `packages/ui` now fails its own suite if a class string anywhere under
+  `src/` names a custom property nothing declares — checked against **both** vocabularies a class can
+  spend from: the `--cue-*` token layer this package builds on, and the Tailwind `@theme` layer,
+  which is this system's bridge (`--radius-control`, `--text-body`, `--color-accent`) together with
+  Tailwind's own default scale, since an app that imports `tailwindcss` keeps both. So the next
+  misspelling in either is a red test rather than a page nobody measured. A property a component
+  sets on its own element, and one spent with a `var()` fallback, are both still allowed — neither
+  can go invalid. Properties another library publishes on its elements (Base UI's `--popup-width`,
+  `--available-height`) are left alone: nothing in this repository could be the authority on whether
+  one of those exists.
+
+  `manifest/manifest.json`, `manifest/components/preview.json`, `manifest/components/frames.json` and
+  `manifest/components/bento.json` were regenerated: each recorded `--cue-text-meta` in its
+  `tokensUsed`, which is how an unresolvable property had been published as part of the contract.
+
+- 3f1aa4a: A click on a control's own words inside a `Frames` canvas is no longer swallowed by the board.
+
+  **Nothing to do.** No prop changed shape and no markup moved; a canvas that behaved correctly
+  before behaves the same way now.
+
+  **What was broken.** On a `Frames.Root`, a menu row, a listbox option, a tab — anything this
+  library draws as a `<div role="…">` with its label in a `<span>` inside it — did nothing when you
+  clicked the words. The same row worked from the keyboard, and it worked if you happened to click
+  its padding a few pixels from the edge, which is what made it read as a broken menu rather than a
+  broken canvas. The most visible case was the frame name menu on a design board: pick a frame, click
+  its name, and the menu stayed open with nothing swapped.
+
+  **Why.** The canvas decides on every `pointerdown` whether you are pressing something or grabbing
+  the board. It looked for `button`, `a`, `input`, `select` and `textarea` _anywhere above the
+  pointer_, but for an ARIA `role` it looked **only at the element directly under it** — so the
+  `<span>` holding a menu row's text was neither, the canvas took the pointer capture, and the
+  `pointerup` and `click` were retargeted to the board. A control's own contents are part of the
+  control, and now they are treated that way: the roles a pointer operates — `menuitem`,
+  `menuitemcheckbox`, `menuitemradio`, `option`, `tab`, `treeitem`, `button`, `link`, `checkbox`,
+  `radio`, `switch`, `slider`, `spinbutton`, `scrollbar`, `separator`, `textbox`, `searchbox` — are
+  matched from the pointer upwards, exactly as `button` always was.
+
+  **Panning is unchanged.** A container role is still a thing to grab, not a thing to press: a drag
+  that starts inside a `role="group"` frame, or on the canvas's own `role="region"` ground, still
+  pans, and so does a drag across a `role="grid"` table, a `role="menu"`'s own padding or a
+  `role="tablist"`'s. Only the elements that _are_ a control, and their contents, are excluded — and
+  an element bearing any `role` at all is still excluded when the pointer is on it directly, as it
+  was before. `pan={false}` still binds no pointer listener.
+
+- @cueplusplus/tokens@0.12.0
+
 ## 0.11.1
 
 ### Patch Changes

package/dist/index.d.ts

@@ -94,10 +94,12 @@ import { Breadcrumb, BreadcrumbItem, BreadcrumbProps } from "./layout/breadcrumb
 import { Card, CardContentProps, CardDescriptionProps, CardFooterProps, CardHeaderProps, CardRootProps, CardTitleProps } from "./layout/card.js";
 import { Collapsible, CollapsiblePanelProps, CollapsibleRootProps, CollapsibleTriggerProps, Disclosure, DisclosureProps } from "./layout/collapsible.js";
 import { DescriptionList, DescriptionListDetailProps, DescriptionListLayout, DescriptionListRootProps, DescriptionListTermProps } from "./layout/description-list.js";
+import { PreviewGround } from "./layout/_ground.js";
+import { Frames, FramesHeight, FramesItemProps, FramesRootProps } from "./layout/frames.js";
 import { Grid, GridColumns, GridProps } from "./layout/grid.js";
 import { Item, ItemProps, itemVariants } from "./layout/item.js";
 import { Pagination, PaginationEntry, PaginationProps, paginationRange } from "./layout/pagination.js";
-import { Preview, PreviewAxis, PreviewProps, PreviewResizeOptions } from "./layout/preview.js";
+import { Preview, PreviewAxis, PreviewPresentation, PreviewProps, PreviewResizeOptions } from "./layout/preview.js";
 import { Stepper, StepperProps, StepperState, StepperStep } from "./layout/stepper.js";
 import { StatusDot, StatusDotProps, StatusTone } from "./primitives/status-dot.js";
 import { Timeline, TimelineContentProps, TimelineItemProps, TimelineMarkerProps, TimelineRootProps } from "./layout/timeline.js";
@@ -132,4 +134,4 @@ import { useDensities, useFonts, useThemes } from "./system/theme-registry.js";
 import { ControlSize, useControlHeight, useDensity } from "./system/use-density.js";
 import { useTheme } from "./system/use-theme.js";
 import { DensityEntry, DensityLevel, FontEntry, FontName, Mode, ThemeManifest, ThemeName } from "./system/index.js";
-export { AGENT_COLOR_PROPERTY, AGENT_HUES, AGENT_ROOT_COLOR, Accordion, type AccordionHeaderProps, type AccordionItemProps, type AccordionPanelProps, type AccordionRootProps, type AccordionTriggerProps, type AgentColorOptions, AgentPile, type AgentPileEntry, type AgentPileProps, type AgentPileSize, AlertDialog, type AlertDialogActionProps, type AlertDialogCancelProps, type AlertDialogContentProps, type AlertDialogDescriptionProps, type AlertDialogFooterProps, type AlertDialogRootProps, type AlertDialogTitleProps, type AlertDialogTriggerProps, AppBar, type AppBarActionsProps, type AppBarBrandProps, type AppBarLinkProps, type AppBarNavProps, type AppBarRegister, type AppBarRootProps, type AppBarSeparatorProps, AppShell, type AppShellAsideProps, type AppShellBarProps, type AppShellBodyProps, type AppShellContentProps, type AppShellNavTriggerProps, type AppShellRootProps, type AppShellScrollerProps, type AppShellSidebarProps, AppWindowFrame, type AppWindowFrameProps, type AskAnswer, AskBox, type AskBoxProps, type AskDanger, type AskKind, type AskOption, AudienceIcon, Autocomplete, type AutocompleteProps, Avatar, AvatarGroup, type AvatarGroupProps, type AvatarProps, type AvatarSize, type BarOverflow, Bento, type BentoColumns, type BentoMinHeight, type BentoRootProps, type BentoRowSpan, type BentoRows, type BentoSpan, type BentoTileProps, type BrandAssetProps, type BrandSize, type BrandTone, Breadcrumb, type BreadcrumbItem, type BreadcrumbProps, Button, ButtonGroup, type ButtonGroupOrientation, type ButtonGroupProps, type ButtonProps, Card, type CardContentProps, type CardDescriptionProps, type CardFooterProps, type CardHeaderProps, type CardRootProps, type CardTitleProps, CatalogueIcon, ChannelBetaIcon, ChannelReleasedIcon, Checkbox, CheckboxGroup, type CheckboxGroupProps, type CheckboxProps, Chip, type ChipProps, CliToolIcon, CodeBlock, type CodeBlockProps, Collapsible, type CollapsiblePanelProps, type CollapsibleRootProps, type CollapsibleTriggerProps, Combobox, type ComboboxOption, type ComboboxProps, CommandPalette, type CommandPaletteItem, type CommandPaletteProps, Composer, type ComposerProps, type ComposerSubmitKey, Container, type ContainerProps, type ContainerWidth, ContextMenu, type ContextMenuContentProps, type ContextMenuRootProps, type ContextMenuTriggerProps, type ControlSize, type ControlVariantProps, CopyButton, type CopyButtonProps, CueLogotype, type CueLogotypeProps, CueMark, type CueMarkProps, CuePortalFrame, type CuePortalFrameProps, DEFAULT_STORAGE_KEY, DataRow, type DataRowDisclosure, type DataRowRootProps, type DataRowSlotProps, DataTree, type DataTreeItem, type DataTreeProps, type DataTreeRowState, DelegationCard, type DelegationCardProps, type DelegationDirection, type DelegationStatus, Density, type DensityEntry, type DensityLevel, type DensityProps, DescriptionList, type DescriptionListDetailProps, type DescriptionListLayout, type DescriptionListRootProps, type DescriptionListTermProps, Dialog, type DialogCloseProps, type DialogContentProps, type DialogDescriptionProps, type DialogFooterProps, type DialogRootProps, type DialogTitleProps, type DialogTriggerProps, Disclosure, type DisclosureProps, Drawer, type DrawerCloseProps, type DrawerContentProps, type DrawerDescriptionProps, type DrawerFooterProps, type DrawerRootProps, type DrawerSwipeDirection, type DrawerTitleProps, type DrawerTriggerProps, DropdownMenu, type DropdownMenuCheckboxItemProps, type DropdownMenuContentProps, type DropdownMenuGroupProps, type DropdownMenuItemProps, type DropdownMenuLabelProps, type DropdownMenuRootProps, type DropdownMenuSeparatorProps, type DropdownMenuTriggerProps, EmptyState, type EmptyStateProps, EnvVarInput, type EnvVarInputProps, Eyebrow, type EyebrowProps, Field, FieldDescription, type FieldDescriptionProps, FieldError, type FieldErrorProps, type FieldIssue, FieldLabel, type FieldLabelProps, type FieldProps, type FilePartition, type FilePartitionOptions, type FileRejectReason, type FileRejection, FileUpload, type FileUploadProps, FolderIcon, type FontEntry, type FontFamilies, type FontName, Footer, type FooterProps, type FormControlSize, Grid, type GridColumns, type GridProps, GroupBar, type GroupBarItem, type GroupBarProps, type GroupBarTone, HoverCard, type HoverCardContentProps, type HoverCardRootProps, type HoverCardTriggerProps, IconButton, type IconButtonProps, InfoTip, type InfoTipProps, Input, InputGroup, type InputGroupProps, type InputProps, Inspector, type InspectorFooterProps, type InspectorRootProps, type InspectorRowProps, type InspectorSectionProps, Item, type ItemProps, Kbd, type KbdProps, Ledger, type LedgerEmptyProps, type LedgerGroupProps, type LedgerRootProps, type LedgerTierProps, Link, type LinkProps, McpServerIcon, Menubar, type MenubarContentProps, type MenubarMenuProps, type MenubarRootProps, type MenubarTriggerProps, Message, MessageList, type MessageListProps, type MessageProps, type MessageRole, Meter, type MeterProps, type MeterProvenance, type MeterTone, type Mode, MultiSelect, type MultiSelectProps, NavigationMenu, type NavigationMenuContentProps, type NavigationMenuItemProps, type NavigationMenuLinkProps, type NavigationMenuListProps, type NavigationMenuRootProps, type NavigationMenuTriggerProps, type NavigationMenuViewportProps, NumberField, type NumberFieldProps, OTPField, type OTPFieldProps, OVERLAY_SIDE_OFFSET, PageShell, type PageShellProps, type PageWidth, Pagination, type PaginationEntry, type PaginationProps, Panel, PanelHeader, type PanelHeaderProps, type PanelProps, PasswordInput, type PasswordInputProps, type PersistedPreferences, Plussie, type PlussieExpression, type PlussieProps, Popover, type PopoverCloseProps, type PopoverContentProps, type PopoverDescriptionProps, type PopoverRootProps, type PopoverTitleProps, type PopoverTriggerProps, type PrepaintDefaults, type PrepaintOptions, Preview, type PreviewAxis, type PreviewProps, type PreviewResizeOptions, Progress, type ProgressProps, Radio, RadioGroup, type RadioGroupProps, type RadioProps, Rating, type RatingProps, type RatingSize, type ResolvedMode, Row, type RowProps, ScrollArea, type ScrollAreaOrientation, type ScrollAreaProps, type ScrollEdges, ScrollableTabsList, type ScrollableTabsListProps, ScrubInput, type ScrubInputProps, SeamCell, type SeamCellProps, SeamGrid, type SeamGridProps, type SeamGround, SeamList, type SeamListProps, SearchInput, type SearchInputProps, SectionHeader, type SectionHeaderProps, SegmentedControl, type SegmentedControlItem, type SegmentedControlProps, type SegmentedControlSize, Select, type SelectOption, type SelectProps, Separator, type SeparatorProps, Sheet, type SheetCloseProps, type SheetContentProps, type SheetDescriptionProps, type SheetFooterProps, type SheetRootProps, type SheetTitleProps, type SheetTriggerProps, Sidebar, type SidebarItemProps, type SidebarRailProps, type SidebarRootProps, type SidebarSectionProps, Skeleton, type SkeletonProps, SkillIcon, Slider, type SliderProps, type SpaceStep, Sparkline, type SparklineProps, Spinner, type SpinnerProps, Stack, type StackAlign, StackIcon, type StackJustify, type StackProps, StacksMatrixIcon, Stat, type StatProps, type StatTone, StatusBar, type StatusBarGroupProps, type StatusBarItemProps, type StatusBarProminence, type StatusBarProps, type StatusBarTone, StatusDot, type StatusDotProps, type StatusTone, Stepper, type StepperProps, type StepperState, type StepperStep, Switch, type SwitchProps, TAB_FADE_PX, TREE_GUIDE_GLYPHS, Table, type TableCaptionProps, type TableCellProps, type TableGroupRowProps, type TableHeadProps, type TableRootProps, type TableRowProps, TableScrollRegion, type TableScrollRegionProps, type TableSectionProps, Tabs, type TabsListProps, type TabsPanelProps, type TabsRootProps, type TabsTabProps, TagsInput, type TagsInputProps, TerminalFrame, type TerminalFrameLine, type TerminalFrameProps, type TerminalLine, type TerminalLineTone, type TerminalScript, type TerminalStep, Textarea, type TextareaProps, type ThemeContextValue, type ThemeManifest, type ThemeName, ThemeProvider, type ThemeProviderProps, type ThemeRegistry, Timeline, type TimelineContentProps, type TimelineItemProps, type TimelineMarkerProps, type TimelineRootProps, TitleBar, type TitleBarProps, Toast, type ToastManager, type ToastOptions, type ToastProviderProps, type ToastTone, type ToastViewportProps, Toggle, ToggleGroup, type ToggleGroupProps, type ToggleProps, type TokenOverrides, Toolbar, type ToolbarButtonProps, type ToolbarGroupProps, type ToolbarRootProps, type ToolbarSeparatorProps, Tooltip, type TooltipContentProps, type TooltipProviderProps, type TooltipRootProps, type TooltipTriggerProps, Tree, type TreeGuide, type TreeItem, type TreeProps, type TreeRow, type TreeVisibility, TreeVisibilityToggle, type TreeVisibilityToggleProps, TwoStepButton, type TwoStepButtonProps, type TwoStepTone, type UploadFile, type UploadStatus, UsageChart, type UsageChartPoint, type UsageChartProps, type UsageChartTone, 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, type AccordionHeaderProps, type AccordionItemProps, type AccordionPanelProps, type AccordionRootProps, type AccordionTriggerProps, type AgentColorOptions, AgentPile, type AgentPileEntry, type AgentPileProps, type AgentPileSize, AlertDialog, type AlertDialogActionProps, type AlertDialogCancelProps, type AlertDialogContentProps, type AlertDialogDescriptionProps, type AlertDialogFooterProps, type AlertDialogRootProps, type AlertDialogTitleProps, type AlertDialogTriggerProps, AppBar, type AppBarActionsProps, type AppBarBrandProps, type AppBarLinkProps, type AppBarNavProps, type AppBarRegister, type AppBarRootProps, type AppBarSeparatorProps, AppShell, type AppShellAsideProps, type AppShellBarProps, type AppShellBodyProps, type AppShellContentProps, type AppShellNavTriggerProps, type AppShellRootProps, type AppShellScrollerProps, type AppShellSidebarProps, AppWindowFrame, type AppWindowFrameProps, type AskAnswer, AskBox, type AskBoxProps, type AskDanger, type AskKind, type AskOption, AudienceIcon, Autocomplete, type AutocompleteProps, Avatar, AvatarGroup, type AvatarGroupProps, type AvatarProps, type AvatarSize, type BarOverflow, Bento, type BentoColumns, type BentoMinHeight, type BentoRootProps, type BentoRowSpan, type BentoRows, type BentoSpan, type BentoTileProps, type BrandAssetProps, type BrandSize, type BrandTone, Breadcrumb, type BreadcrumbItem, type BreadcrumbProps, Button, ButtonGroup, type ButtonGroupOrientation, type ButtonGroupProps, type ButtonProps, Card, type CardContentProps, type CardDescriptionProps, type CardFooterProps, type CardHeaderProps, type CardRootProps, type CardTitleProps, CatalogueIcon, ChannelBetaIcon, ChannelReleasedIcon, Checkbox, CheckboxGroup, type CheckboxGroupProps, type CheckboxProps, Chip, type ChipProps, CliToolIcon, CodeBlock, type CodeBlockProps, Collapsible, type CollapsiblePanelProps, type CollapsibleRootProps, type CollapsibleTriggerProps, Combobox, type ComboboxOption, type ComboboxProps, CommandPalette, type CommandPaletteItem, type CommandPaletteProps, Composer, type ComposerProps, type ComposerSubmitKey, Container, type ContainerProps, type ContainerWidth, ContextMenu, type ContextMenuContentProps, type ContextMenuRootProps, type ContextMenuTriggerProps, type ControlSize, type ControlVariantProps, CopyButton, type CopyButtonProps, CueLogotype, type CueLogotypeProps, CueMark, type CueMarkProps, CuePortalFrame, type CuePortalFrameProps, DEFAULT_STORAGE_KEY, DataRow, type DataRowDisclosure, type DataRowRootProps, type DataRowSlotProps, DataTree, type DataTreeItem, type DataTreeProps, type DataTreeRowState, DelegationCard, type DelegationCardProps, type DelegationDirection, type DelegationStatus, Density, type DensityEntry, type DensityLevel, type DensityProps, DescriptionList, type DescriptionListDetailProps, type DescriptionListLayout, type DescriptionListRootProps, type DescriptionListTermProps, Dialog, type DialogCloseProps, type DialogContentProps, type DialogDescriptionProps, type DialogFooterProps, type DialogRootProps, type DialogTitleProps, type DialogTriggerProps, Disclosure, type DisclosureProps, Drawer, type DrawerCloseProps, type DrawerContentProps, type DrawerDescriptionProps, type DrawerFooterProps, type DrawerRootProps, type DrawerSwipeDirection, type DrawerTitleProps, type DrawerTriggerProps, DropdownMenu, type DropdownMenuCheckboxItemProps, type DropdownMenuContentProps, type DropdownMenuGroupProps, type DropdownMenuItemProps, type DropdownMenuLabelProps, type DropdownMenuRootProps, type DropdownMenuSeparatorProps, type DropdownMenuTriggerProps, EmptyState, type EmptyStateProps, EnvVarInput, type EnvVarInputProps, Eyebrow, type EyebrowProps, Field, FieldDescription, type FieldDescriptionProps, FieldError, type FieldErrorProps, type FieldIssue, FieldLabel, type FieldLabelProps, type FieldProps, type FilePartition, type FilePartitionOptions, type FileRejectReason, type FileRejection, FileUpload, type FileUploadProps, FolderIcon, type FontEntry, type FontFamilies, type FontName, Footer, type FooterProps, type FormControlSize, Frames, type FramesHeight, type FramesItemProps, type FramesRootProps, Grid, type GridColumns, type GridProps, GroupBar, type GroupBarItem, type GroupBarProps, type GroupBarTone, HoverCard, type HoverCardContentProps, type HoverCardRootProps, type HoverCardTriggerProps, IconButton, type IconButtonProps, InfoTip, type InfoTipProps, Input, InputGroup, type InputGroupProps, type InputProps, Inspector, type InspectorFooterProps, type InspectorRootProps, type InspectorRowProps, type InspectorSectionProps, Item, type ItemProps, Kbd, type KbdProps, Ledger, type LedgerEmptyProps, type LedgerGroupProps, type LedgerRootProps, type LedgerTierProps, Link, type LinkProps, McpServerIcon, Menubar, type MenubarContentProps, type MenubarMenuProps, type MenubarRootProps, type MenubarTriggerProps, Message, MessageList, type MessageListProps, type MessageProps, type MessageRole, Meter, type MeterProps, type MeterProvenance, type MeterTone, type Mode, MultiSelect, type MultiSelectProps, NavigationMenu, type NavigationMenuContentProps, type NavigationMenuItemProps, type NavigationMenuLinkProps, type NavigationMenuListProps, type NavigationMenuRootProps, type NavigationMenuTriggerProps, type NavigationMenuViewportProps, NumberField, type NumberFieldProps, OTPField, type OTPFieldProps, OVERLAY_SIDE_OFFSET, PageShell, type PageShellProps, type PageWidth, Pagination, type PaginationEntry, type PaginationProps, Panel, PanelHeader, type PanelHeaderProps, type PanelProps, PasswordInput, type PasswordInputProps, type PersistedPreferences, Plussie, type PlussieExpression, type PlussieProps, Popover, type PopoverCloseProps, type PopoverContentProps, type PopoverDescriptionProps, type PopoverRootProps, type PopoverTitleProps, type PopoverTriggerProps, type PrepaintDefaults, type PrepaintOptions, Preview, type PreviewAxis, type PreviewGround, type PreviewPresentation, type PreviewProps, type PreviewResizeOptions, Progress, type ProgressProps, Radio, RadioGroup, type RadioGroupProps, type RadioProps, Rating, type RatingProps, type RatingSize, type ResolvedMode, Row, type RowProps, ScrollArea, type ScrollAreaOrientation, type ScrollAreaProps, type ScrollEdges, ScrollableTabsList, type ScrollableTabsListProps, ScrubInput, type ScrubInputProps, SeamCell, type SeamCellProps, SeamGrid, type SeamGridProps, type SeamGround, SeamList, type SeamListProps, SearchInput, type SearchInputProps, SectionHeader, type SectionHeaderProps, SegmentedControl, type SegmentedControlItem, type SegmentedControlProps, type SegmentedControlSize, Select, type SelectOption, type SelectProps, Separator, type SeparatorProps, Sheet, type SheetCloseProps, type SheetContentProps, type SheetDescriptionProps, type SheetFooterProps, type SheetRootProps, type SheetTitleProps, type SheetTriggerProps, Sidebar, type SidebarItemProps, type SidebarRailProps, type SidebarRootProps, type SidebarSectionProps, Skeleton, type SkeletonProps, SkillIcon, Slider, type SliderProps, type SpaceStep, Sparkline, type SparklineProps, Spinner, type SpinnerProps, Stack, type StackAlign, StackIcon, type StackJustify, type StackProps, StacksMatrixIcon, Stat, type StatProps, type StatTone, StatusBar, type StatusBarGroupProps, type StatusBarItemProps, type StatusBarProminence, type StatusBarProps, type StatusBarTone, StatusDot, type StatusDotProps, type StatusTone, Stepper, type StepperProps, type StepperState, type StepperStep, Switch, type SwitchProps, TAB_FADE_PX, TREE_GUIDE_GLYPHS, Table, type TableCaptionProps, type TableCellProps, type TableGroupRowProps, type TableHeadProps, type TableRootProps, type TableRowProps, TableScrollRegion, type TableScrollRegionProps, type TableSectionProps, Tabs, type TabsListProps, type TabsPanelProps, type TabsRootProps, type TabsTabProps, TagsInput, type TagsInputProps, TerminalFrame, type TerminalFrameLine, type TerminalFrameProps, type TerminalLine, type TerminalLineTone, type TerminalScript, type TerminalStep, Textarea, type TextareaProps, type ThemeContextValue, type ThemeManifest, type ThemeName, ThemeProvider, type ThemeProviderProps, type ThemeRegistry, Timeline, type TimelineContentProps, type TimelineItemProps, type TimelineMarkerProps, type TimelineRootProps, TitleBar, type TitleBarProps, Toast, type ToastManager, type ToastOptions, type ToastProviderProps, type ToastTone, type ToastViewportProps, Toggle, ToggleGroup, type ToggleGroupProps, type ToggleProps, type TokenOverrides, Toolbar, type ToolbarButtonProps, type ToolbarGroupProps, type ToolbarRootProps, type ToolbarSeparatorProps, Tooltip, type TooltipContentProps, type TooltipProviderProps, type TooltipRootProps, type TooltipTriggerProps, Tree, type TreeGuide, type TreeItem, type TreeProps, type TreeRow, type TreeVisibility, TreeVisibilityToggle, type TreeVisibilityToggleProps, TwoStepButton, type TwoStepButtonProps, type TwoStepTone, type UploadFile, type UploadStatus, UsageChart, type UsageChartPoint, type UsageChartProps, type UsageChartTone, 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/index.js

@@ -94,6 +94,7 @@ import { Breadcrumb } from "./layout/breadcrumb.js";
 import { Card } from "./layout/card.js";
 import { Collapsible, Disclosure } from "./layout/collapsible.js";
 import { DescriptionList } from "./layout/description-list.js";
+import { Frames } from "./layout/frames.js";
 import { Grid } from "./layout/grid.js";
 import { Item, itemVariants } from "./layout/item.js";
 import { Pagination, paginationRange } from "./layout/pagination.js";
@@ -118,4 +119,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, 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 };
+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, Frames, 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/layout/_ground.d.ts

@@ -0,0 +1,22 @@
+//#region src/layout/_ground.d.ts
+/**
+ * The three grounds a stage or a canvas may paint, and the classes for each.
+ *
+ * One table and not two, because `Preview`'s stage and `Frames.Root`'s canvas
+ * take the same three members and a second copy would be the one that drifted.
+ * Static literals, because Tailwind scans source text and never a computed
+ * string.
+ *
+ * `dots` is written as three classes in exactly the order `STAGE_CLASS` carried
+ * them before this table existed — `bg-surface-1`, then the radial gradient,
+ * then its size. `cn` is `twMerge(clsx(...))`, which keeps the order it is
+ * given, so composing head + ground + tail reproduces today's string token for
+ * token. `preview.test.tsx`'s byte gate is what holds that.
+ *
+ * @internal Not part of the public API. The type is re-exported from
+ * `./preview`, which is where §4.1 of the showroom spec declares it.
+ */
+/** The stage's ground, in the settings popover's own words. */
+type PreviewGround = "plain" | "dots" | "none";
+//#endregion
+export { PreviewGround };

package/dist/layout/_ground.js

@@ -0,0 +1,9 @@
+//#region src/layout/_ground.ts
+/** What each ground paints. `"none"` paints nothing, so whatever is behind shows through. */
+const GROUND_CLASSES = {
+	plain: "bg-surface-1",
+	dots: "bg-surface-1 bg-[radial-gradient(circle,var(--cue-hair-strong)_1px,transparent_1.3px)] bg-[length:14px_14px]",
+	none: ""
+};
+//#endregion
+export { GROUND_CLASSES };

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: "min-w-0 truncate font-mono text-(length:--cue-text-meta) text-fg-muted",
+				className: "min-w-0 truncate font-mono text-(length:--cue-text-micro) text-fg-muted",
 				children: eyebrow
 			}), title === void 0 ? null : /* @__PURE__ */ jsx("span", {
 				"data-slot": "bento-tile-title",

package/dist/layout/frames.d.ts

@@ -0,0 +1,70 @@
+import { PreviewGround } from "./_ground.js";
+import * as React from "react";
+//#region src/layout/frames.d.ts
+/** How tall the canvas stands. A design board is short and wide on purpose. */
+type FramesHeight = "short" | "tall";
+interface FramesRootProps extends Omit<React.ComponentPropsWithoutRef<"div">, "children"> {
+  /** The frames. Anything — this never inspects them. */
+  children: React.ReactNode;
+  /**
+   * The canvas's accessible name — "Button frames". Required: the canvas is a
+   * focusable scroll region, and a scroll region with no name is one a screen
+   * reader announces as nothing.
+   */
+  label: string;
+  /** `"short"` is 18.5rem, `"tall"` 27rem. A CSS length in `style` overrides both. */
+  height?: FramesHeight;
+  /** The canvas ground. Defaults to `"dots"`. */
+  ground?: PreviewGround;
+  /** The line in the bottom-right corner — "drag to pan · 8 frames". Unset, none is drawn. */
+  hint?: React.ReactNode;
+  /**
+   * Drag-to-pan with the pointer. Defaults to `true`. A drag that starts on a
+   * control is never a pan, so a frame's own controls stay usable — and "on a
+   * control" counts the control's own contents: the words inside a
+   * `role="menuitem"` row, the icon inside a `button`. A drag inside a
+   * role-bearing box that is not itself a control — a `role="group"` frame, a
+   * `role="region"` — still pans, because a frame is such a box and a board is
+   * mostly frames. Only the primary button drags; `false` binds no pointer
+   * listener at all; and the keyboard scrolls the canvas either way.
+   */
+  pan?: boolean;
+}
+interface FramesItemProps extends React.ComponentPropsWithoutRef<"div"> {
+  /** The specimen. */
+  children: React.ReactNode;
+  /** The line under it. Hidden — not removed — when the frame sets `captions={false}`. */
+  caption?: React.ReactNode;
+  /** Draws the selection outline the frame gives the item a reader is inspecting. */
+  selected?: boolean;
+}
+/**
+ * A design canvas: frames side by side, each holding one axis of one component.
+ *
+ * `Frames.Root` is the canvas — short, wide, scrollable sideways, focusable,
+ * and pannable with the pointer. `Frames.Item` is one captioned cell, and it is
+ * used **inside a `Preview`** rather than inside the Root. The two are apart
+ * because that is how they are used, and a props-only API cannot say it.
+ *
+ * **The canvas knows nothing about its children.** It does not count them, does
+ * not index them and does not select one; `hint` is where a caller puts what it
+ * knows. A canvas that knew its frames would be a manifest API, and this is a
+ * slot API.
+ *
+ * @example
+ * <Frames.Root label="Button frames" hint="drag to pan · 3 frames">
+ *   <Preview presentation="frame" label="Tone" count={3} name={<ToneMenu />}>
+ *     <div className="flex flex-wrap items-end gap-(--cue-space-6)">
+ *       <Frames.Item caption="accent"><Button tone="accent">Take cue</Button></Frames.Item>
+ *       <Frames.Item caption="ok"><Button tone="ok">Take cue</Button></Frames.Item>
+ *       <Frames.Item caption="warn"><Button tone="warn">Take cue</Button></Frames.Item>
+ *     </div>
+ *   </Preview>
+ * </Frames.Root>
+ */
+declare const Frames: {
+  Root: React.ForwardRefExoticComponent<FramesRootProps & React.RefAttributes<HTMLDivElement>>;
+  Item: React.ForwardRefExoticComponent<FramesItemProps & React.RefAttributes<HTMLDivElement>>;
+};
+//#endregion
+export { Frames, FramesHeight, FramesItemProps, FramesRootProps };