@cueplusplus/ui 0.13.0 → 0.14.1

package/CHANGELOG.md

@@ -1,5 +1,312 @@
 # @cueplusplus/ui
 
+## 0.14.1
+
+### Patch Changes
+
+- 9857b93: Every chrome component now ships hand-written guidance in the manifest.
+
+  Fifteen of the twenty-three had extracted facts and nothing that said when to
+  reach for one. `chrome` joins `layout`, `forms` and `primitives` as a complete
+  group.
+
+  The guidance names the rules these components enforce and a hand-rolled
+  replacement always loses: `SegmentedControl` cannot be emptied and `ToggleGroup`
+  can, which is the whole difference between a view picker and a filter bar;
+  `NavigationMenu` must not take `role="menu"`, because that tells a screen reader
+  to expect commands and swallows the browser's own link affordances; `Toolbar` is
+  one tab stop with arrow keys inside, which is what a flex row of buttons throws
+  away; and `Tree` earns its hand-built implementation on three details together —
+  roving tabindex, a flat DOM carrying `aria-level`/`aria-posinset`/`aria-setsize`,
+  and the keyboard contract.
+
+  No API changed.
+
+- d11bcb7: The six domain groups ship hand-written guidance: date, color, flow, midi, dmx
+  and charts.
+
+  Twenty-eight components gained `whenToUse`, `whenNotToUse` and `commonMistakes`,
+  completing every one of the six. Coverage is 164 of 326, and only `elements` and
+  `icons` remain.
+
+  These are the components most often reached for wrongly, because the right
+  choice depends on the domain rather than the shape: a `DateField` beats a
+  `DatePicker` whenever the user already knows the date, and `TimeField` takes
+  `hourCycle={24}` because a control room does not read AM/PM. `MusicalTimeInput`
+  exists because a number field asks for 4.25 and means "bar 2, beat 1, one
+  sixteenth in". `UniverseGrid` is deliberately not a table: position _is_ the
+  address, which is what makes an overlap visible rather than inferred. And three
+  of them refuse a prop on purpose — `FlowBackground`'s `color` writes a property
+  that outranks the theme map, so passing one opts out of theming rather than
+  into it.
+
+  No API changed.
+
+- 2a5b3aa: Every component in the library now ships hand-written guidance.
+
+  The last 162 — all 152 of `elements` and all 10 of `icons` — gained `whenToUse`,
+  `whenNotToUse` and `commonMistakes`. Coverage is **326 of 326**: an agent reading
+  `manifest.json` now gets the judgement as well as the API for every component,
+  not for the thirty-eight that happened to have prose.
+
+  The guidance is derived from each component's own record, never invented, and
+  where a record had only a one-line summary the file is short rather than padded.
+  What that surfaces is the reasoning the source already carried:
+
+  - `GenerativeUI` takes `spec` as `unknown` on purpose, because a cast is a claim
+    about the bytes nobody is in a position to make — and it never throws, so an
+    error boundary around it is waiting for something that will not happen.
+  - `RevertDock` will not render without `This action cannot be undone.` on screen,
+    and picking a scope only arms it, because the old layout put the destructive
+    control _inside_ the scope control's box at 448px.
+  - `AnimatedNumber` is `tabular-nums` because a proportional `1` is narrower than
+    a `0`, so a stepping counter nudges everything to its right on every update.
+  - `Message` renders React nodes verbatim and will never parse markdown, which is
+    what keeps a consumer from being one prompt away from an injection.
+  - The ten icons each say what misreading their shape prevents: an audience drawn
+    as a tag files people with the folders, an empty beta ring reads as "nothing
+    here yet", and a bare chevron for a CLI tool promises a disclosure that
+    navigates instead.
+
+  No API changed.
+
+- 0b5ed2d: Every forms control now ships hand-written guidance in the manifest.
+
+  Twenty-three of the twenty-nine carried extracted facts — props, variants, types
+  — but nothing that said when to reach for one. They now carry `whenToUse`,
+  `whenNotToUse` and `commonMistakes` alongside the rest, so `forms` joins
+  `primitives` as a complete group.
+
+  The guidance is mostly about pairs that look alike and are not:
+  `Autocomplete` accepts what you typed and `Combobox` does not, which decides what
+  downstream code may assume about the value. `ToggleGroup` can be empty and
+  `SegmentedControl` cannot, which is the difference between a filter bar and a
+  view switcher. `Toggle` announces `aria-pressed` and `Switch` announces
+  `aria-checked`, which is why one belongs in a toolbar and the other in a settings
+  list. `MultiSelect` takes a known set and `TagsInput` takes anything.
+
+  No API changed.
+
+- 3e928f8: Every instrument now ships hand-written guidance in the manifest.
+
+  Fourteen of the twenty-one had extracted facts and nothing that said when to
+  reach for one. `instruments` joins `chrome`, `layout`, `forms` and `primitives`
+  as a complete group.
+
+  Several of these components exist because a hand-rolled version gets one rule
+  wrong, and the guidance names which: `Sparkline` and `UsageChart` fix their axis
+  at 0–100, because a trace scaled to its own range makes a flat 3% look identical
+  to a flat 95%; `Progress` transitions linearly, because a bar that eases is lying
+  about its rate; `GroupBar` gives no cell to an empty group, because a minimum
+  width on a zero draws a group that is not there; `LogViewer` fixes its row height
+  so the virtualiser never measures; and `TwoStepButton` is the right shape for a
+  _routine_ destructive action, where a modal would only teach people to dismiss
+  dialogs.
+
+  No API changed.
+
+- f2e5203: Every layout component now ships hand-written guidance in the manifest.
+
+  Seventeen of the twenty had extracted facts and nothing that said when to reach
+  for one. `layout` joins `forms` and `primitives` as a complete group.
+
+  The guidance is mostly about three disclosure components that look alike and are
+  not: `Accordion` coordinates several peer sections, `Collapsible` is one of them
+  alone, and `Disclosure` is neither — it is an annotation on the form it sits in,
+  which is why giving those fields a summary row makes a form read as twice as long
+  as it is. Also why `Stack` exists at all: `flex gap-2` written by hand pins
+  spacing to a pixel value and quietly opts out of the density ladder.
+
+  No API changed.
+
+- ba6d72e: `ThemeProvider`'s `nonce` now reaches Base UI's style element too, not just the
+  density layer.
+
+  `@base-ui/react` renders one `<style>` of its own — a hoisted
+  `<style precedence>` carrying `.base-ui-disable-scrollbar` — and `ScrollAreaRoot`
+  and `SelectPopup` give it a nonce they read from Base UI's `CSPContext`. Nothing
+  fills that context unless a `CSPProvider` is rendered above them, so under
+  `style-src-elem 'self' 'nonce-<per-request>'` that element shipped bare and the
+  browser refused it by content hash, on every page rendering a Select, a Popover
+  or a ScrollArea.
+
+  It was reported to us as a density-layer problem and it never was: the
+  application that hit it passes no `overrides`, so the density `<style>` did not
+  exist in its tree at all. The nonce prop added for that report was correct and
+  addressed a different element. This is the half that was actually biting.
+
+  Given a nonce, `ThemeProvider` now renders `CSPProvider` around its tree. Given
+  none, it renders none — deliberately, so an application that wraps itself in its
+  own `CSPProvider` keeps it. An unconditional inner provider would overwrite that
+  outer context with `undefined` and un-nonce every Base UI style element in the
+  tree, which is the bug this fixes, caused by its fix.
+
+  No API changed. A tree with no nonce renders exactly what it rendered before.
+
+- b12c65d: Four more groups ship hand-written guidance: overlays, system, chat and the
+  configurator.
+
+  Twenty-one components gained `whenToUse`, `whenNotToUse` and `commonMistakes`,
+  completing all four groups. Coverage is 136 of 326.
+
+  Two of these matter beyond the component they describe. `Message` renders React
+  nodes verbatim and will never parse markdown or HTML, because model output is
+  untrusted text and a component that quietly parsed it would make every consumer
+  of this library one prompt away from an injection — a caller that wants rich text
+  passes its own renderer and owns that decision. And `AskBox` holds only the
+  _draft_ answer: the fact of having answered comes back from the host, because
+  local state as the source of truth for a decision a run depends on survives
+  exactly until the pane unmounts.
+
+  The overlay family's distinctions are the rest: `AlertDialog` refuses
+  outside-press dismissal and `Dialog` does not; `Sheet` is a side channel and
+  `Drawer` is its swipe-dismissable cousin; `HoverCard` is reachable by the pointer
+  and a `Tooltip` is not; `ContextMenu` and `Menubar` re-export `DropdownMenu`'s
+  own rows, so a user can never tell from a row how they got to it.
+
+  No API changed.
+
+- f1fa7b6: Every primitive now ships hand-written guidance in the manifest.
+
+  `Avatar`, `AvatarGroup`, `IconButton`, `Kbd`, `Separator`, `Skeleton`, `Spinner`
+  and `StatusDot` carried extracted facts — props, variants, types — but nothing
+  that said when to reach for one. They now carry `whenToUse`, `whenNotToUse` and
+  `commonMistakes` alongside the rest, so the ten components in `primitives` are
+  complete. An agent reading `manifest.json` gets the judgement as well as the API:
+  that `StatusDot`'s wrapper is the containing block its `sr-only` label needs,
+  that `Skeleton` has no intrinsic size and collapses without one, that
+  `IconButton`'s `aria-label` is the only name the control has.
+
+  No API changed. These are fields the manifest schema already had and thirty-eight
+  other components already filled.
+
+- Updated dependencies [abd9a57]
+  - @cueplusplus/tokens@0.14.1
+
+## 0.14.0
+
+### Minor Changes
+
+- f9bb2ff: **`Frames` takes a `layout`.** The default, `"board"`, is what it has always
+  drawn: a picker across the top and one frame on the stage at a time. The new
+  `"column"` runs every frame down a single scroller instead — each with its own
+  caption and count, all of them on one ground — so a reader comparing eight
+  states of a component reads them rather than clicking through them.
+
+  ```tsx
+  <Frames layout="column" …/>
+  ```
+
+  Nothing changes for markup that does not pass it: `layout` defaults to
+  `"board"`, and a `Frames` with no `layout` prop renders byte-for-byte what it
+  rendered before.
+
+- f9bb2ff: **`ThemeProvider` takes a CSP `nonce`.**
+
+  When `overrides.densities` is set, the provider emits one `<style>` element for
+  the density layer. An application serving `style-src-elem 'self'
+'nonce-<per-request>'` had that element refused on every page load: React
+  renders it on the client, and a client-rendered element cannot pick up a server
+  nonce by itself.
+
+  ```tsx
+  // app/layout.tsx — the nonce your middleware already mints
+  <ThemeProvider nonce={nonce} overrides={{ densities: … }}>
+  ```
+
+  The attribute is set only when you pass one. It is absent otherwise rather than
+  present and empty, because `nonce=""` matches no `'nonce-…'` source and would
+  talk a policy out of admitting the element some other way.
+
+  Nothing else in this library emits a `<style>` element, and `prepaintScript()`
+  returns a string your application renders in a `<script>` of its own — so your
+  application already owns that element's nonce, and this prop is the whole of
+  what a strict `style-src-elem` needs from here.
+
+  **One thing a nonce cannot fix.** The provider always sets a style _attribute_
+  on its root — `color-scheme` and `--cue-font-scale`, plus the font families and
+  overrides where given. CSP has no nonce form for `style-src-attr`: it is
+  `'unsafe-inline'` or `'none'`. Under `'none'` the browser drops those
+  declarations, and no prop here can change that.
+
+### Patch Changes
+
+- 331501f: ## The scope goes public
+
+  Every package in `@cueplusplus` was private on npm. npm authenticates _every_
+  read of a private package, so each consumer needed a granular read-only token,
+  and it could not live in a committed `.npmrc` — pnpm 10 and later ignore an
+  env-expanded `_authToken` there by design. The failure mode was the expensive
+  part: npm answers a private package the same way to a reader it will not admit
+  exists, so a missing credential surfaced as `404 Not Found` rather than `401`,
+  and read as "this was never published".
+
+  That was a fair trade while the design system had no consumer outside the org.
+  It stopped being one the moment a public project depended on it, because a
+  public project cannot ask its readers for a token before they can install it.
+
+  So `access` is `public`, in the Changesets config and in all sixteen manifests.
+  Consumers now run `pnpm add @cueplusplus/ui` and nothing else: no token, no
+  `.npmrc`, nothing to rotate, and no extra step in CI or on a hosting provider.
+
+  Nothing else moves. Same registry, same names, same versions — so no consumer
+  needs to regenerate a lockfile, and a machine that keeps its npm token for
+  another private scope can keep it.
+
+  The guard tests are turned around rather than removed. `changeset-config` still
+  asserts the access level and `publishable-packages` still asserts the registry;
+  both now assert the public contract. `publishable-packages` additionally asserts
+  `access: "public"` per manifest, which it never did before: the Changesets config
+  decides what a release does, but npm defaults a scoped package to restricted, so
+  a manifest that forgets is the one that quietly stays private while its siblings
+  go public.
+
+- 52094a9: **The `@cueplusplus` scope is served by npm now, not GitHub Packages.** Every package is
+  **private** there, so installs still authenticate — but the credential and the configuration both
+  change, and the old ones stop working.
+
+  **What to remove.** The scope routing you were asked to commit:
+
+  ```ini
+  # .npmrc — delete this line
+  @cueplusplus:registry=https://npm.pkg.github.com
+  ```
+
+  Nothing replaces it. npm's own registry is where the scope resolves by default, so there is no
+  routing to commit at all — which also means a project that consumed this scope through a committed
+  `.npmrc` can usually delete the file.
+
+  **What to replace.** The classic GitHub PAT with `read:packages` is no longer used. In its place,
+  an npm **granular access token** with **read-only** permission on the `@cueplusplus` scope,
+  written once at the user level:
+
+  ```sh
+  pnpm config set //registry.npmjs.org/:_authToken npm_…
+  ```
+
+  It goes at the user level for the same reason as before: pnpm 10 and later ignore an env-expanded
+  `_authToken` in a project `.npmrc`, and the install then fails with a `404` — not a `401` — and a
+  warning nobody reads. npm answers a private package the same way to a reader it will not admit
+  exists, so the failure reads as "never published".
+
+  **One token, every scope.** npm authenticates per registry rather than per scope, so a machine
+  that installs other private scopes from npm needs one line, not one per scope — select them all on
+  the same token. Two different tokens for `registry.npmjs.org` cannot coexist in one config.
+
+  **CI changes too, and this one is easy to miss.** Under GitHub Packages a workflow's own
+  `GITHUB_TOKEN` could read the scope, so many workflows carried no secret. npm does not know about
+  that token. Every repository that installs these packages now needs the read-only npm token as a
+  secret, and `setup-node` pointed at `registry.npmjs.org`. The same applies to Vercel, Trigger.dev
+  and any Docker build that installs — `docs/CONSUMING.md` §1 has each of them.
+
+  Nothing about the packages themselves changed: same exports, same versions, same contents. What
+  moved is where they are served from and what proves you may read them.
+
+- Updated dependencies [331501f]
+- Updated dependencies [52094a9]
+  - @cueplusplus/theme-base@1.0.3
+  - @cueplusplus/tokens@0.14.0
+
 ## 0.13.0
 
 ### Minor Changes

package/README.md

@@ -5,25 +5,8 @@ Base UI underneath for behaviour and accessibility, Tailwind v4 on top for the p
 
 ## Install
 
-The `@cueplusplus` scope is served by **GitHub Packages**, not npmjs.com, and GitHub Packages
-authenticates *every* install. That is two settings, in two places, and the split is not
-cosmetic — pnpm ignores an env-expanded credential in a project `.npmrc` and the install fails
-with `401`.
-
-Commit the scope routing, and nothing else, at the root of your project:
-
-```ini
-# .npmrc
-@cueplusplus:registry=https://npm.pkg.github.com
-```
-
-Then write the credential once, at the **user** level, where pnpm reads it from. It is a
-**classic** personal access token with `read:packages` — GitHub Packages accepts neither
-fine-grained PATs nor OIDC:
-
-```sh
-pnpm config set //npm.pkg.github.com/:_authToken ghp_…
-```
+The `@cueplusplus` scope is **public on npm** and resolves there by default, so there is nothing
+to configure and no credential to supply — it installs like any other package.
 
 ```sh
 pnpm add @cueplusplus/ui @cueplusplus/tokens @cueplusplus/theme-cue @base-ui/react

package/dist/index.d.ts

@@ -96,7 +96,7 @@ import { Card, CardContentProps, CardDescriptionProps, CardFooterProps, CardHead
 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 { Frames, FramesHeight, FramesItemProps, FramesLayout, 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";
@@ -135,4 +135,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 { DEFAULT_STYLE_SET, DensityEntry, DensityLevel, FontEntry, FontName, Mode, STYLE_SETS, StyleSet, 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, Band, type BandProps, type BandSeparation, type BandWidth, 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, DEFAULT_STYLE_SET, 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, STYLE_SETS, 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, type StyleSet, 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, Band, type BandProps, type BandSeparation, type BandWidth, 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, DEFAULT_STYLE_SET, 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 FramesLayout, 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, STYLE_SETS, 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, type StyleSet, 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/layout/frames.d.ts

@@ -29,7 +29,25 @@ interface FramesRootProps extends Omit<React.ComponentPropsWithoutRef<"div">, "c
    * listener at all; and the keyboard scrolls the canvas either way.
    */
   pan?: boolean;
+  /**
+   * How the frames are arranged. Defaults to `"board"`.
+   *
+   * `"board"` is the original: a short, wide, sideways scroller a reader drags
+   * through — right where the frames are a set you *browse*, on a homepage wall
+   * or a design surface.
+   *
+   * `"column"` stacks them one under the next, each at the full width it is
+   * given, and the canvas grows to whatever it holds. It exists for the page
+   * that *reads*: a documentation page scrolls vertically already, and asking a
+   * reader to pan a second axis to reach the fifth variant of a component —
+   * with that fifth variant clipped at the board's edge until they do — hides
+   * the examples behind an interaction. A column has no fixed height, so
+   * `height` is ignored, and nothing pans, so `pan` and `hint` are moot.
+   */
+  layout?: FramesLayout;
 }
+/** Whether a canvas browses sideways or reads downwards. */
+type FramesLayout = "board" | "column";
 interface FramesItemProps extends React.ComponentPropsWithoutRef<"div"> {
   /** The specimen. */
   children: React.ReactNode;
@@ -67,4 +85,4 @@ declare const Frames: {
   Item: React.ForwardRefExoticComponent<FramesItemProps & React.RefAttributes<HTMLDivElement>>;
 };
 //#endregion
-export { Frames, FramesHeight, FramesItemProps, FramesRootProps };
+export { Frames, FramesHeight, FramesItemProps, FramesLayout, FramesRootProps };

package/dist/layout/frames.js

@@ -118,6 +118,18 @@ const ROOT_CLASS = "relative min-w-0 overflow-hidden rounded-(--radius-surface)
 * must not be.
 */
 const CANVAS_CLASS = "flex h-full min-w-0 items-start gap-(--cue-space-8) overflow-x-auto overflow-y-hidden scroll-smooth p-(--cue-space-6) outline-none motion-reduce:scroll-auto focus-visible:outline-2 focus-visible:outline-solid focus-visible:-outline-offset-2 focus-visible:outline-accent";
+/**
+* The column: the same frames, stacked, sized by what they hold.
+*
+* `overflow-visible` on both axes is the point — the box grows instead of
+* clipping, which is the one thing the board deliberately does not do. No
+* scroller of its own, so the page's scroller is the only one a reader meets.
+* It keeps the focus ring and the keyboard handler: the region is still
+* focusable, and arrow keys still scroll it, they just scroll the page.
+*/
+const COLUMN_CLASS = "flex min-w-0 flex-col gap-(--cue-space-6) p-(--cue-space-6) outline-none focus-visible:outline-2 focus-visible:outline-solid focus-visible:-outline-offset-2 focus-visible:outline-accent";
+/** A column is sized by its contents, so the box must not hold a height. */
+const COLUMN_ROOT_CLASS = "h-auto";
 /** The affordance, and only where there is something to afford. */
 const PANNABLE_CLASS = "cursor-grab";
 /**
@@ -143,18 +155,20 @@ const HINT_CLASS = "pointer-events-none absolute right-(--cue-space-4) bottom-(-
 *   <Preview presentation="frame" label="Tone" count={4}>…</Preview>
 * </Frames.Root>
 */
-const FramesRoot = React.forwardRef(function FramesRoot({ children, label, height = "short", ground = "dots", hint, pan = true, className, ...elementProps }, ref) {
+const FramesRoot = React.forwardRef(function FramesRoot({ children, label, height = "short", ground = "dots", hint, pan = true, layout = "board", className, ...elementProps }, ref) {
 	const drag = React.useRef(null);
 	const canvasRef = React.useRef(null);
 	const [panning, setPanning] = React.useState(false);
+	const column = layout === "column";
+	const pans = pan && !column;
 	React.useEffect(() => {
-		if (pan) return;
+		if (pans) return;
 		const started = drag.current;
 		if (started === null) return;
 		canvasRef.current?.releasePointerCapture?.(started.id);
 		drag.current = null;
 		setPanning(false);
-	}, [pan]);
+	}, [pans]);
 	const scroll = (event) => {
 		if (event.defaultPrevented || event.target !== event.currentTarget) return;
 		const canvas = event.currentTarget;
@@ -203,7 +217,7 @@ const FramesRoot = React.forwardRef(function FramesRoot({ children, label, heigh
 		...elementProps,
 		ref,
 		"data-slot": "frames",
-		className: cn(ROOT_CLASS, HEIGHT_CLASSES[height], GROUND_CLASSES[ground], className),
+		className: cn(ROOT_CLASS, column ? COLUMN_ROOT_CLASS : HEIGHT_CLASSES[height], GROUND_CLASSES[ground], className),
 		children: [/* @__PURE__ */ jsx("div", {
 			ref: canvasRef,
 			role: "region",
@@ -211,11 +225,11 @@ const FramesRoot = React.forwardRef(function FramesRoot({ children, label, heigh
 			"aria-label": label,
 			"data-slot": "frames-canvas",
 			"data-panning": panning ? "true" : void 0,
-			className: cn(CANVAS_CLASS, pan && PANNABLE_CLASS, panning && PANNING_CLASS),
+			className: column ? COLUMN_CLASS : cn(CANVAS_CLASS, pans && PANNABLE_CLASS, panning && PANNING_CLASS),
 			onKeyDown: scroll,
-			...pan ? pointer : {},
+			...pans ? pointer : {},
 			children
-		}), hint === void 0 ? null : /* @__PURE__ */ jsx("span", {
+		}), hint === void 0 || column ? null : /* @__PURE__ */ jsx("span", {
 			"data-slot": "frames-hint",
 			className: HINT_CLASS,
 			children: hint

package/dist/layout/index.d.ts

@@ -9,11 +9,11 @@ import { Card, CardContentProps, CardDescriptionProps, CardFooterProps, CardHead
 import { Collapsible, CollapsiblePanelProps, CollapsibleRootProps, CollapsibleTriggerProps, Disclosure, DisclosureProps } from "./collapsible.js";
 import { DescriptionList, DescriptionListDetailProps, DescriptionListLayout, DescriptionListRootProps, DescriptionListTermProps } from "./description-list.js";
 import { PreviewGround } from "./_ground.js";
-import { Frames, FramesHeight, FramesItemProps, FramesRootProps } from "./frames.js";
+import { Frames, FramesHeight, FramesItemProps, FramesLayout, FramesRootProps } from "./frames.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, PreviewPresentation, PreviewProps, PreviewResizeOptions } from "./preview.js";
 import { Stepper, StepperProps, StepperState, StepperStep } from "./stepper.js";
 import { Timeline, TimelineContentProps, TimelineItemProps, TimelineMarkerProps, TimelineRootProps } from "./timeline.js";
-export { Accordion, type AccordionHeaderProps, type AccordionItemProps, type AccordionPanelProps, type AccordionRootProps, type AccordionTriggerProps, Bento, type BentoColumns, type BentoMinHeight, type BentoRootProps, type BentoRowSpan, type BentoRows, type BentoSpan, type BentoTileProps, Breadcrumb, type BreadcrumbItem, type BreadcrumbProps, Card, type CardContentProps, type CardDescriptionProps, type CardFooterProps, type CardHeaderProps, type CardRootProps, type CardTitleProps, Collapsible, type CollapsiblePanelProps, type CollapsibleRootProps, type CollapsibleTriggerProps, Container, type ContainerProps, type ContainerWidth, DescriptionList, type DescriptionListDetailProps, type DescriptionListLayout, type DescriptionListRootProps, type DescriptionListTermProps, Disclosure, type DisclosureProps, Frames, type FramesHeight, type FramesItemProps, type FramesRootProps, Grid, type GridColumns, type GridProps, Item, type ItemProps, Link, type LinkProps, Pagination, type PaginationEntry, type PaginationProps, Preview, type PreviewAxis, type PreviewGround, type PreviewPresentation, 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 };
+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, Frames, type FramesHeight, type FramesItemProps, type FramesLayout, type FramesRootProps, Grid, type GridColumns, type GridProps, Item, type ItemProps, Link, type LinkProps, Pagination, type PaginationEntry, type PaginationProps, Preview, type PreviewAxis, type PreviewGround, type PreviewPresentation, 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/primitives/chip.d.ts

@@ -30,7 +30,7 @@ import * as React from "react";
  * <span className={chipVariants({ variant: "tag" })}>mcp</span>
  */
 declare const chipVariants: (props?: ({
-  tone?: "danger" | "info" | "warn" | "busy" | "accent" | "ok" | "neutral" | null | undefined;
+  tone?: "info" | "warn" | "danger" | "busy" | "accent" | "ok" | "neutral" | null | undefined;
   variant?: "outline" | "tinted" | "tag" | null | undefined;
   interactive?: boolean | null | undefined;
 } & ClassProp) | undefined) => string;

package/dist/system/theme-provider.d.ts

@@ -236,6 +236,51 @@ interface ThemeProviderProps {
   storageKey?: string;
   /** Restore and write root preferences in localStorage. Defaults to `true`. */
   persistPreferences?: boolean;
+  /**
+   * The Content-Security-Policy nonce for every `<style>` element this tree
+   * renders — this library's and Base UI's.
+   *
+   * When `overrides.densities` is set this provider emits one `<style>`
+   * element (see {@link ThemeProviderProps.overrides}). Under a policy of
+   * `style-src-elem 'self' 'nonce-<per-request>'` the browser refuses that
+   * element on every page load, because an element React renders on the client
+   * cannot pick up a server nonce by itself. Pass the request's nonce here and
+   * it is set on the element.
+   *
+   * It also reaches **Base UI**. Given a nonce, this provider renders
+   * `@base-ui/react`'s own `CSPProvider` around the tree, so the hoisted
+   * `<style>` that `ScrollAreaRoot` and `SelectPopup` emit carries it too.
+   * Without that, a strict policy refuses it by content hash on every page
+   * rendering a Select, a Popover or a ScrollArea — and a consumer has no way
+   * to guess the remedy lives in a peer dependency's provider. An outer
+   * `CSPProvider` a consumer renders itself is left alone: no nonce here means
+   * no provider here, rather than one that overwrites theirs with `undefined`.
+   *
+   * `prepaintScript()` returns a *string* the application renders in a
+   * `<script>` of its own — so the application already controls that element's
+   * nonce, and between it and this prop a strict policy needs nothing else
+   * from here.
+   *
+   * **Pass this OR render your own `CSPProvider` — not both.** Base UI's
+   * context carries a second value beside the nonce, `disableStyleElements`,
+   * and its provider is the only public way to set either: the package exports
+   * `CSPProvider` and no hook, so a provider rendered here *replaces* an outer
+   * one rather than extending it. Given a nonce this provider therefore sets
+   * `disableStyleElements` back to its default, and a consumer who had turned
+   * it on outside loses it silently — Base UI resumes emitting the very style
+   * element they suppressed. An application already rendering its own
+   * `CSPProvider` needs nothing from this prop: leave it unset and the outer
+   * context survives untouched, which is the case
+   * `base-ui-nonce-outer-provider.test.tsx` pins.
+   *
+   * **A nonce cannot rescue a style ATTRIBUTE**, and this provider always sets
+   * one on its root: `color-scheme` and `--cue-font-scale`, plus the font
+   * families and overrides where they are given. CSP has no nonce form for
+   * `style-src-attr` — it is `'unsafe-inline'` or `'none'` — so an application
+   * serving `style-src-attr 'none'` loses those declarations, silently. That is
+   * a policy decision rather than something this prop can change.
+   */
+  nonce?: string;
   /** Stamp the single child element instead of rendering a wrapper `<div>`. */
   asChild?: boolean;
   /** Extra classes for the provider root. */
@@ -285,6 +330,6 @@ interface ThemeProviderProps {
  *   <App />
  * </ThemeProvider>
  */
-declare function ThemeProvider({ themes: themesProp, theme: themeProp, density: densityProp, mode: modeProp, font: fontProp, styleSet: styleSetProp, fontScale, fontFamilies, overrides, storageKey, persistPreferences, asChild, className, style: styleProp, children }: ThemeProviderProps): React.JSX.Element;
+declare function ThemeProvider({ themes: themesProp, theme: themeProp, density: densityProp, mode: modeProp, font: fontProp, styleSet: styleSetProp, fontScale, fontFamilies, overrides, storageKey, persistPreferences, nonce, asChild, className, style: styleProp, children }: ThemeProviderProps): React.JSX.Element;
 //#endregion
 export { FontFamilies, ResolvedMode, ThemeContextValue, ThemeProvider, ThemeProviderProps };