@sableui/react 0.8.1 → 0.9.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { ClassValue } from 'clsx';
-import { C as ComponentMeta } from './meta-CcE_SeFu.js';
-export { A as AnatomyMeta, a as BestPracticeMeta, E as ExampleMeta, M as MotionMeta, b as MotionSlot, c as PropMeta, R as RelatedMeta, S as SubcomponentMeta, U as UsageMeta } from './meta-CcE_SeFu.js';
+import { C as ComponentMeta } from './meta-DVG8ceze.js';
+export { A as AnatomyMeta, a as BestPracticeMeta, E as ExampleMeta, M as MotionMeta, b as MotionSlot, c as PropMeta, R as RelatedMeta, S as SubcomponentMeta, U as UsageMeta } from './meta-DVG8ceze.js';
 import { T as ThemeManifest, a as ThemeMode$1 } from './_contract-C2M1SjBf.js';
 export { A as ART_TOKENS, D as DENSITY_TOKENS, b as DensityToken, M as MOTION_TOKENS, c as MotionToken, R as RADIUS_TOKENS, d as RadiusToken, S as SEMANTIC_TOKENS, e as SemanticToken, f as TYPE_OVERLINE_TOKENS, g as TYPE_REFINEMENT_TOKENS, h as TYPE_SCALE_TOKENS, i as TYPE_UI_TOKENS, j as TypeOverlineToken, k as TypeRefinementToken, l as TypeScaleToken, m as TypeUiToken, W as WORKSPACE_SURFACE_TOKENS, n as WorkspaceSurfaceToken } from './_contract-C2M1SjBf.js';
 import { T as ThemeId } from './theme-provider-S0NVJs2Y.js';
@@ -9,7 +9,7 @@ export { AspectBox, AspectBoxProps, Bleed, BleedProps, Breakpoint, Center, Cente
 export { Icon, IconContextValue, IconProps, IconProvider, IconProviderProps, composeIconSets, useIconSet } from './icon/index.js';
 export { a as IconRenderProps, I as IconSet, b as IconVariant } from './registry-CyL28OzJ.js';
 import * as react from 'react';
-import { ReactNode, ComponentPropsWithoutRef, ElementType, ReactElement, Ref, ComponentPropsWithRef, ComponentProps } from 'react';
+import { ReactNode, ComponentPropsWithoutRef, ElementType, ReactElement, Ref, ComponentPropsWithRef, MouseEvent, ComponentProps, FormEvent } from 'react';
 import { VariantProps } from 'class-variance-authority';
 import { useRender } from '@base-ui/react/use-render';
 import * as class_variance_authority_types from 'class-variance-authority/types';
@@ -351,17 +351,24 @@ declare const buttonVariants: (props?: ({
     size?: "icon" | "sm" | "md" | "xs" | "cta" | "icon-sm" | "icon-xs" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 
-interface ButtonProps extends ComponentPropsWithRef<"button">, VariantProps<typeof buttonVariants> {
+interface ButtonProps extends Omit<ComponentPropsWithRef<"button">, "onClick">, VariantProps<typeof buttonVariants> {
+    /**
+     * May return a promise: the button then shows `loading` until it settles and
+     * ignores further presses meanwhile, from the first click on (a `busy` flag
+     * in React state only takes effect a render later, so three quick clicks
+     * all ran).
+     */
+    onClick?: (event: MouseEvent<HTMLButtonElement>) => unknown;
     /**
      * Replace the rendered element or compose with another component
      * (e.g. `render={<a href="…" />}`) through Base UI's render prop.
      */
     render?: useRender.RenderProp;
     /**
-     * Disable the button and show a leading Spinner while an action is in flight.
-     * Sets `aria-busy`. A native `<button>` is also `disabled`; a polymorphic
-     * `render` element (e.g. an `<a>`, which can't be disabled) gets
-     * `aria-disabled` instead. @default false
+     * Show a leading Spinner while an action is in flight, and ignore presses.
+     * Sets `aria-busy` and `aria-disabled`, not the native `disabled`: disabling
+     * the focused button dropped focus to the page, so a sheet opened by the
+     * action had nowhere to return it. @default false
      */
     loading?: boolean;
     /** Optional text shown in place of children while loading. */
@@ -408,7 +415,7 @@ type ButtonBleed = "start" | "end" | "both" | "none";
  * Corner radius is theme-driven via `--button-radius` (falls back to full pill) —
  * see `button.variants.ts`.
  */
-declare function Button({ variant, size, className, render, ref, type, loading, loadingLabel, iconStart, iconEnd, badge, bleed, disabled, children, ...props }: ButtonProps): react.ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+declare function Button({ variant, size, className, render, ref, type, loading, loadingLabel, iconStart, iconEnd, badge, bleed, disabled, children, onClick, ...props }: ButtonProps): react.ReactElement<unknown, string | react.JSXElementConstructor<any>>;
 declare namespace Button {
     var displayName: string;
 }
@@ -2240,7 +2247,10 @@ interface StepperProps extends ComponentPropsWithRef<"ol"> {
     /**
      * `horizontal` for a short flow across the top of a form (checkout, 3–5
      * steps); `vertical` for a longer flow or a narrow column, where each step
-     * has room for a description.
+     * has room for a description. Horizontal steps compact themselves when the
+     * stepper is narrower than 28rem (a phone): every disc stays, only the
+     * current step keeps its title on screen, and the others' titles stay for
+     * screen readers.
      * @default "horizontal"
      */
     orientation?: StepperOrientation;
@@ -5082,6 +5092,24 @@ declare namespace AppShell {
     var displayName: string;
 }
 
+/**
+ * SkipLink — the first stop in the tab order: hidden until focused, then a
+ * small primary button pinned to the top-start corner that jumps past the
+ * header and navigation to the page's main content.
+ *
+ * AppShell renders one already. Use this in a layout of your own (a storefront
+ * with a top header, a marketing page), put it first in the body, and give the
+ * `<main>` the matching id:
+ *
+ *   <SkipLink />
+ *   <SiteHeader />
+ *   <main id="main-content" tabIndex={-1}>…</main>
+ */
+declare function SkipLink({ href, children, className, ...props }: ComponentProps<"a">): react.JSX.Element;
+declare namespace SkipLink {
+    var displayName: string;
+}
+
 declare const appShellMeta: ComponentMeta;
 
 type SidebarContextValue = {
@@ -5480,12 +5508,29 @@ declare const searchInputMeta: ComponentMeta;
  *
  * Disabling the whole group propagates through Base UI as data-[disabled] on
  * the root (native <fieldset disabled> also disables its controls).
+ *
+ * `variant="plain"` drops the surface: a bare group whose legend reads as a
+ * field label, for the question a RadioGroup or a run of checkboxes answers
+ * inside a form that is already framed.
+ *
+ *   <Fieldset variant="plain">
+ *     <FieldsetLegend>Delivery</FieldsetLegend>
+ *     <RadioGroup>…</RadioGroup>
+ *   </Fieldset>
  */
+type FieldsetVariant = "card" | "plain";
 type RootProps = Omit<ComponentPropsWithRef<typeof Fieldset$1.Root>, "className"> & {
     className?: string;
+    /**
+     * `card` (default) is a bordered, raised section with padded parts. `plain`
+     * is the grouping alone: no border, surface or inset, and a legend in the
+     * field-label style.
+     * @default "card"
+     */
+    variant?: FieldsetVariant;
 };
-/** The bordered container. Wraps Base.Root (a native <fieldset>) as a raised card surface. */
-declare function Fieldset({ className, ...props }: RootProps): react.JSX.Element;
+/** The container. Wraps Base.Root (a native <fieldset>): a raised card surface, or a bare group. */
+declare function Fieldset({ className, variant, ...props }: RootProps): react.JSX.Element;
 declare namespace Fieldset {
     var displayName: string;
 }
@@ -5521,7 +5566,13 @@ declare namespace FieldsetFooter {
 
 declare const fieldsetMeta: ComponentMeta;
 
-interface FormProps extends ComponentPropsWithRef<"form"> {
+interface FormProps extends Omit<ComponentPropsWithRef<"form">, "onSubmit"> {
+    /**
+     * The native submit handler. It may return a promise: when it (or the
+     * promise) is done, the first control a Field marks invalid takes focus, so
+     * errors your own code sets get the same treatment as Sable's validation.
+     */
+    onSubmit?: (event: FormEvent<HTMLFormElement>) => unknown;
     /**
      * When fields validate: `onSubmit` (default — on submit, then live on change
      * after the first attempt), `onBlur`, or `onChange`. A Field's own
@@ -5536,9 +5587,10 @@ interface FormProps extends ComponentPropsWithRef<"form"> {
     errors?: Form$1.Props["errors"];
     /**
      * Called with the named Field values (as an object) once every field is
-     * valid. Using it calls `preventDefault()` on the native submit for you.
+     * valid. Using it calls `preventDefault()` on the native submit for you. It
+     * may return a promise, as `onSubmit` may.
      */
-    onFormSubmit?: Form$1.Props["onFormSubmit"];
+    onFormSubmit?: (...args: Parameters<NonNullable<Form$1.Props["onFormSubmit"]>>) => unknown;
     /** Imperative actions: `actionsRef.current.validate(name?)`. */
     actionsRef?: Form$1.Props["actionsRef"];
     /**
@@ -5577,7 +5629,7 @@ declare namespace Form {
 }
 /** The native constraint flags of `ValidityState` a Field can word itself. */
 type ConstraintFlag = "valueMissing" | "typeMismatch" | "patternMismatch" | "tooShort" | "tooLong" | "rangeUnderflow" | "rangeOverflow" | "stepMismatch" | "badInput";
-interface FieldProps {
+interface FieldProps extends Omit<ComponentPropsWithRef<"div">, "children" | "title" | "onChange"> {
     /** Field label (wired to the control via htmlFor). */
     label?: ReactNode;
     /** Helper text under the control (wired via aria-describedby). */
@@ -5621,6 +5673,13 @@ interface FieldProps {
      * control then the label inline — for a single checkbox / switch / radio.
      */
     orientation?: "vertical" | "horizontal";
+    /**
+     * Something at the end of the control's row. Vertically, beside the control:
+     * a promo code's Apply button, with the control taking the rest of the row.
+     * Horizontally, at the end of the label's first line: a facet count or a
+     * price, with the label taking the rest.
+     */
+    trailing?: ReactNode;
     className?: string;
     /** The single control element (e.g. `<Input />`, `<Textarea />`, `<Select…>`). */
     children: ReactElement;
@@ -5643,8 +5702,13 @@ interface FieldProps {
  *     <Input />
  *   </Field>
  *   <Field label="Subscribe" orientation="horizontal"><Checkbox /></Field>
+ *   <Field label="Promo code" trailing={<Button variant="secondary">Apply</Button>}>
+ *     <Input />
+ *   </Field>
+ *
+ * Other props (`data-*`, `id`, `aria-*`) land on the root element.
  */
-declare function Field({ label, description, error, required, messages, disabled, name, validate, validationMode, validationDebounceTime, orientation, className, children, }: FieldProps): react.JSX.Element;
+declare function Field({ label, description, error, required, messages, disabled, name, validate, validationMode, validationDebounceTime, orientation, trailing, className, children, ...props }: FieldProps): react.JSX.Element;
 declare namespace Field {
     var displayName: string;
 }
@@ -5733,6 +5797,11 @@ type RadioCardProps = Omit<ComponentProps<typeof Radio$1.Root>, "className" | "c
     title: ReactNode;
     /** Optional supporting copy beneath the title. */
     description?: ReactNode;
+    /**
+     * End-aligned on the title's line: a price ("$12.00"), a delivery date, a
+     * count. The title takes the rest of the row.
+     */
+    trailing?: ReactNode;
     /**
      * Leading icon (e.g. a solid `<Icon>`). Its presence switches the card to the
      * two-dimensional layout — icon top-left, indicator top-right, copy below —
@@ -5755,7 +5824,7 @@ type RadioCardProps = Omit<ComponentProps<typeof Radio$1.Root>, "className" | "c
  * adding a second selected-state shadow. `value` pairs it with the group's
  * selected value.
  */
-declare function RadioCard({ className, title, description, icon, tone, titleClassName, descriptionClassName, ...props }: RadioCardProps): react.JSX.Element;
+declare function RadioCard({ className, title, description, trailing, icon, tone, titleClassName, descriptionClassName, ...props }: RadioCardProps): react.JSX.Element;
 declare namespace RadioCard {
     var displayName: string;
 }
@@ -6419,6 +6488,12 @@ interface CommandItem {
     onSelect: () => void;
     /** Optional leading icon (semantic name, e.g. "home"). */
     icon?: string;
+    /**
+     * A leading visual of your own in place of `icon`: a product thumbnail, an
+     * Avatar. Decorative, since the label names the row; size it to the row
+     * (`size-8` beside a `stacked` detail).
+     */
+    leading?: ReactNode;
     /** Secondary text after the label — a destination, a type, an owner. */
     detail?: ReactNode;
     /**
@@ -6596,6 +6671,8 @@ interface CommandMenuItemProps extends Omit<ComponentPropsWithRef<"div">, "title
     onSelect?: () => void;
     /** Optional leading icon (semantic name). */
     icon?: string;
+    /** A leading visual of your own in place of `icon`: a product thumbnail, an Avatar. */
+    leading?: ReactNode;
     /** Secondary text after the label. */
     detail?: ReactNode;
     /** Put `detail` on its own line under the label, so it never truncates away first. */
@@ -6616,7 +6693,7 @@ interface CommandMenuItemProps extends Omit<ComponentPropsWithRef<"div">, "title
  * combobox: keyboard focus stays in the input and Enter clicks the highlighted
  * row, so the row itself is not in the tab order.
  */
-declare function CommandMenuItem({ onSelect, icon, detail, stacked, hint, id: idProp, className, children, disabled, ...props }: CommandMenuItemProps): react.JSX.Element | null;
+declare function CommandMenuItem({ onSelect, icon, leading, detail, stacked, hint, id: idProp, className, children, disabled, ...props }: CommandMenuItemProps): react.JSX.Element | null;
 
 /**
  * Listens for the platform's palette shortcut — ⌘K on macOS, Ctrl+K elsewhere —
@@ -7347,8 +7424,18 @@ interface MediaTileProps extends Omit<ComponentPropsWithRef<"div">, "title"> {
     title: ReactNode;
     /** The second line — an artist, a channel, a price. Optional. */
     subtitle?: ReactNode;
+    /**
+     * Lines under the subtitle, in its muted type: a price beside its sale price,
+     * a count of finishes, a status Badge. A block, so it can wrap and hold
+     * several elements where the one-line subtitle truncates.
+     */
+    meta?: ReactNode;
     /** Cover image URL. Without one (or when it fails) the cover is GradientArt seeded by the item. */
     src?: string;
+    /** Responsive cover candidates, passed to the `<img>` with `sizes`. */
+    srcSet?: string;
+    /** Which candidate width the layout needs, e.g. `"(min-width: 64rem) 25vw, 50vw"`. */
+    sizes?: string;
     /**
      * Cover alt text. Defaults to `""`: the title right below already names the
      * item, so describing the cover again makes a screen reader say it twice.
@@ -7419,7 +7506,7 @@ interface MediaTileProps extends Omit<ComponentPropsWithRef<"div">, "title"> {
  * and the cover is drawn above it with `order`, so focus moves the way a
  * reader names the item — what it is, who made it, then what to do with it.
  */
-declare function MediaTile({ title, subtitle, src, alt, seed, aspect, size, href, render, subtitleHref, subtitleRender, action, badge, titleAs: TitleTag, loading, className, ...props }: MediaTileProps): react.JSX.Element;
+declare function MediaTile({ title, subtitle, meta, src, srcSet, sizes, alt, seed, aspect, size, href, render, subtitleHref, subtitleRender, action, badge, titleAs: TitleTag, loading, className, ...props }: MediaTileProps): react.JSX.Element;
 declare namespace MediaTile {
     var displayName: string;
 }
@@ -8291,6 +8378,6 @@ interface UseCopyResult {
  */
 declare function useCopy(text: string, { timeout }?: UseCopyOptions): UseCopyResult;
 
-declare const SABLE_UI_VERSION: "0.8.1";
+declare const SABLE_UI_VERSION: "0.9.0";
 
-export { Accordion, AccordionItem, AccordionPanel, AccordionTrigger, AlertDialog, AlertDialogClose, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogOverlay, AlertDialogTitle, AlertDialogTrigger, AppHeader, type AppHeaderProps, AppShell, type AppShellProps, AreaChart, type AreaChartProps, type ArtTone, Attachment, type AttachmentProps, Avatar, AvatarFallback, AvatarGroup, AvatarGroupCount, type AvatarGroupCountProps, type AvatarGroupProps, AvatarImage, type AvatarProps, AvatarRoot, BADGE_APPEARANCES, BADGE_TONES, Badge, type BadgeAppearance, type BadgeProps, type BadgeTone, Banner, type BannerProps, BarChart, type BarChartProps, BottomNav, BottomNavItem, type BottomNavItemProps, BreadcrumbItem, type BreadcrumbItemProps, BreadcrumbLink, type BreadcrumbLinkProps, BreadcrumbPage, type BreadcrumbPageProps, BreadcrumbSeparator, type BreadcrumbSeparatorProps, Breadcrumbs, type BreadcrumbsProps, Browser, type BrowserProps, Bubble, type BubbleProps, BubbleReaction, type BubbleReactionProps, BubbleReactions, type BubbleReactionsProps, Button, type ButtonBleed, type ButtonProps, CHART_SERIES_COUNT, COMPONENT_GROUPS, COMPONENT_TAXONOMY, Calendar, type CalendarProps, Card, CardAction, CardContent, type CardContentProps, CardDescription, CardFooter, type CardFooterProps, CardHeader, CardList, type CardProps, CardTitle, type CardTitleProps, Carousel, type CarouselProps, type CarouselSlidesToShow, type ChartCategories, type ChartCenterLabel, type ChartCurve, type ChartDatum, type ChartSeries, type ChartTone, type ChartTooltipIndicator, type ChartTooltipOptions, type ChartValueFormatter, ChatComposer, type ChatComposerProps, Checkbox, CheckboxCard, type CheckboxCardProps, type CheckboxCardTone, CheckboxGroup, type CheckboxGroupProps, Code, CodeBlock, type CodeBlockProps, CodeHighlightProvider, type CodeHighlighter, type CodeProps, Collapsible, CollapsibleIndicator, CollapsiblePanel, CollapsibleTrigger, ColorField, type ColorFieldProps, Combobox, ComboboxChips, ComboboxClear, ComboboxContent, ComboboxEmpty, ComboboxGroup, ComboboxGroupLabel, ComboboxInput, ComboboxItem, type ComboboxItemGroup, ComboboxItemIndicator, ComboboxList, ComboboxPortal, type ComboboxProps, ComboboxValue, ComboboxVirtualList, type ComboboxVirtualListProps, type CommandFilter, type CommandItem, CommandMenu, CommandMenuGroup, type CommandMenuGroupProps, CommandMenuItem, type CommandMenuItemProps, CommandMenuPanel, type CommandMenuPanelProps, type CommandMenuProps, CommandMenuTrigger, type CommandMenuTriggerProps, type ComponentGroup, type ComponentGuidance, ComponentMeta, type ComponentRegister, type ConstraintFlag, ContextCard, ContextCardArrow, ContextCardContent, ContextCardPortal, ContextCardTrigger, ContextMenu, ContextMenuContent, ContextMenuGroup, ContextMenuGroupLabel, ContextMenuItem, ContextMenuPortal, ContextMenuSeparator, ContextMenuTrigger, DataTable, type DataTableColumn, type DataTableProps, type DataTableRowKey, DatePicker, type DatePickerProps, DateTile, type DateTileProps, Density, DensityProvider, Density as DensityValue, DestructiveActionModal, type DestructiveActionModalProps, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, type DialogSize, DialogTitle, DialogTrigger, DisclosurePicker, DisclosurePickerEmpty, DisclosurePickerList, type DisclosurePickerListProps, DisclosurePickerOption, type DisclosurePickerOptionProps, DisclosurePickerPanel, type DisclosurePickerPanelProps, type DisclosurePickerProps, type DisclosurePickerSearch, DisclosurePickerTrigger, type DisclosurePickerTriggerProps, EmptyState, type EmptyStateProps, Entity, type EntityProps, Feedback, type FeedbackData, type FeedbackProps, type FeedbackRating, Field, type FieldProps, Fieldset, FieldsetContent, FieldsetDescription, FieldsetFooter, FieldsetLegend, FileDropzone, type FileDropzoneProps, type FileRejection, type FileRejectionCode, FontPicker, type FontPickerFont, type FontPickerOption, type FontPickerProps, Form, type FormProps, GlidingHighlight, type GlidingHighlightProps, GradientArt, type GradientArtProps, type Hsv, InlineStatus, type InlineStatusProps, type StatusTone as InlineTone, Input, type InputProps$1 as InputProps, Kbd, KbdGroup, type KbdGroupProps, type KbdProps, Label, type LabelProps$2 as LabelProps, LineChart, type LineChartProps, Marker, type MarkerProps, Marquee, type MarqueeProps, MediaImage, type MediaImageProps, MediaTile, type MediaTileProps, Menu, MenuCheckboxItem, MenuContent, MenuGroup, MenuGroupLabel, MenuItem, MenuPortal, MenuRadioGroup, MenuRadioItem, MenuSeparator, MenuSubmenu, MenuSubmenuTrigger, MenuTrigger, Message, type MessageProps, MessageScroller, type MessageScrollerHandle, type MessageScrollerProps, Meter, MeterIndicator, MeterLabel, type MeterSize, type MeterTone, MeterTrack, MeterValue, MiddleTruncate, type MiddleTruncateProps, type MotionPolicy, MotionProvider, type MotionProviderProps, Note, type NoteAction, type NoteProps, NotificationBadge, type NotificationBadgeProps, NumberField, type NumberFieldProps, type OrbMode, type OrbSize, OtpField, type OtpFieldProps, OverflowMenu, type OverflowMenuProps, PageHeader, type PageHeaderProps, PageLoader, type PageLoaderProps, Pagination, type PaginationProps, Panel, PanelGroup, PanelResizer, type PanelResizerProps, PanelSection, type PanelWidthBounds, Phone, type PhoneProps, PieChart, type PieChartProps, Pill, type PillProps, Popover, PopoverArrow, PopoverClose, PopoverContent, PopoverDescription, PopoverPortal, PopoverTitle, PopoverTrigger, Presence, type PresenceProps, type Presentation, PresentationProvider, Progress, ProgressIndicator, ProgressLabel, type ProgressSize, ProgressTrack, ProgressValue, PropertyPair, PropertyRow, RadarChart, type RadarChartProps, RadialChart, type RadialChartProps, Radio, RadioCard, type RadioCardProps, type RadioCardTone, RadioGroup, RelativeTime, type RelativeTimeProps, Reveal, type RevealProps, type Rgb, SABLE_UI_VERSION, SEGMENTED_BAR_TONES, STATUS_TONES, STATUS_TONE_ICON, type ScrollCommandOptions, Scroller, type ScrollerProps, ScrubField, type ScrubFieldProps, SearchInput, type SearchInputProps, SectionHeader, type SectionHeaderProps, SegmentedBar, type SegmentedBarProps, type SegmentedBarSegment, type SegmentedBarTone, Select, SelectContent, SelectGroup, SelectGroupLabel, SelectItem, SelectPortal, SelectSeparator, SelectTrigger, SelectValue, Separator, type SeparatorProps$3 as SeparatorProps, SettingsMenu, type SettingsMenuProps, SettingsRow, type SettingsRowProps, Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetList, SheetPortal, SheetTitle, SheetTrigger, ShowMore, type ShowMoreProps, SideNav, type SideNavActiveVariant, SideNavGroup, type SideNavGroupProps, SideNavItem, type SideNavItemProps, type SideNavProps, type SideNavSize, Sidebar, SidebarBrand, type SidebarBrandProps, SidebarFooter, SidebarHeader, SidebarItem, type SidebarItemProps, SidebarNav, type SidebarProps, SimpleTooltip, Skeleton, Slider, SliderControl, SliderIndicator, SliderRoot, SliderThumb, SliderTrack, SliderValue, Sparkline, type SparklineProps, Spinner, type SpinnerProps, StatusBar, StatusBarGroup, StatusBarSeparator, StatusDot, type StatusDotProps, type StatusTone, type StepStatus, Stepper, StepperItem, type StepperItemProps, type StepperOrientation, type StepperProps, StreamingText, type StreamingTextProps, Switch, TRANSPARENT, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow, Tabs, TabsPanel as TabsContent, TabsList, TabsPanel, TabsTrigger, TextReveal, type TextRevealProps, Textarea, type TextareaProps, ThemeId, ThemeManifest, ThemeMode$1 as ThemeManifestMode, type ThemeMode, ThemePreview, type ThemePreviewProps, ThemeSelector, type ThemeSelectorProps, ThemeSwitcher, type ThemeSwitcherProps, ThinkingOrb, type ThinkingOrbProps, ToastAction, type ToastApi, ToastClose, ToastContent, ToastDescription, type ToastManagerApi, type ToastOptions, type ToastPosition, ToastProvider, type ToastProviderProps, ToastRoot, ToastTitle, type ToastType, ToastViewport, Toggle, ToggleGroup, type ToggleGroupAppearance, Toggle as ToggleGroupItem, Toolbar, ToolbarButton, type ToolbarButtonProps, ToolbarGroup, type ToolbarGroupProps, ToolbarInput, type ToolbarInputProps, ToolbarLink, type ToolbarLinkProps, type ToolbarProps, ToolbarSeparator, type ToolbarSeparatorProps, Tooltip, TooltipArrow, TooltipContent, TooltipPortal, TooltipProvider, TooltipTrigger, Tree, TreeAddRow, TreeEmpty, TreeRow, TreeSection, type UseCopyOptions, type UseCopyResult, type UseInViewOptions, type UsePanelWidthOptions, Video, type VideoProps, ViewTransitionName, type ViewTransitionNameProps, Workspace, WorkspaceBar, WorkspaceCanvas, accordionMeta, appHeaderMeta, appShellMeta, areaChartMeta, attachmentMeta, avatarGroupVariants, avatarMeta, avatarVariants, badgeMeta, badgeVariants, bannerMeta, bannerVariants, barChartMeta, bottomNavMeta, breadcrumbsMeta, browserMeta, bubbleMeta, buttonMeta, buttonVariants, calendarMeta, cardMeta, carouselMeta, chartColor, toneColor as chartToneColor, chatComposerMeta, checkboxCardMeta, checkboxMeta, cn, codeBlockMeta, codeMeta, collapsibleMeta, colorFieldMeta, comboboxMeta, commandMenuMeta, componentGuidance, componentLabel, componentSlug, componentsInGroup, contextCardMeta, contextMenuMeta, dataTableMeta, datePickerMeta, dateTileMeta, destructiveActionModalMeta, dialogMeta, disclosurePickerMeta, emptyStateMeta, entityMeta, feedbackMeta, fieldsetMeta, fileDropzoneMeta, fileDropzoneVariants, fontPickerMeta, formMeta, formatFileSize, formatHex, glidingHighlightMeta, gradientArtMeta, hsvToRgb, hueColor, inlineStatusMeta, inputMeta, isTransparent, kbdMeta, labelMeta, lineChartMeta, markerMeta, marqueeMeta, mediaImageMeta, mediaTileMeta, menuMeta, messageMeta, messageScrollerMeta, meterIndicatorVariants, meterMeta, meterTrackVariants, middleTruncateMeta, noteMeta, noteVariants, notificationBadgeMeta, notificationCountVariants, notificationDotVariants, numberFieldMeta, otpFieldMeta, overflowMenuMeta, pageHeaderMeta, pageLoaderMeta, paginationMeta, panelGroupMeta, panelSectionMeta, parseHex, phoneMeta, pieChartMeta, pillMeta, pillVariants, popoverMeta, progressMeta, progressTrackVariants, radarChartMeta, radialChartMeta, radioCardMeta, radioMeta, relativeTimeMeta, rgbToHsv, scrollerMeta, scrubFieldMeta, searchInputMeta, sectionHeaderMeta, segmentedBarMeta, segmentedBarSegmentVariants, segmentedBarVariants, selectMeta, separatorMeta, settingsMenuMeta, sheetMeta, sheetVariants, showMoreMeta, sideNavMeta, sidebarMeta, skeletonMeta, sliderMeta, sparklineMeta, spinnerMeta, startViewTransition, statusBarMeta, statusDotMeta, statusDotVariants, stepperConnectorVariants, stepperIndicatorVariants, stepperMeta, streamingTextMeta, supportsViewTransitions, switchMeta, tableMeta, tabsMeta, textareaMeta, themeSelectorMeta, themeSwitcherMeta, thinkingOrbMeta, toast, toastMeta, toggleMeta, toolbarGroupVariants, toolbarMeta, toolbarSeparatorVariants, toolbarVariants, tooltipMeta, treeIndent, treeMeta, useAnchoredDensity, useComboboxFilteredItems, useCommandMenuShortcut, useCopy, useDensity, useDisclosurePicker, useInView, useMotion, usePanelWidth, usePresentation, useReducedMotion, useScrollActivity, useSidebar, useToast, useToastManager, useTypeTier, videoMeta, workspaceMeta };
+export { Accordion, AccordionItem, AccordionPanel, AccordionTrigger, AlertDialog, AlertDialogClose, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogOverlay, AlertDialogTitle, AlertDialogTrigger, AppHeader, type AppHeaderProps, AppShell, type AppShellProps, AreaChart, type AreaChartProps, type ArtTone, Attachment, type AttachmentProps, Avatar, AvatarFallback, AvatarGroup, AvatarGroupCount, type AvatarGroupCountProps, type AvatarGroupProps, AvatarImage, type AvatarProps, AvatarRoot, BADGE_APPEARANCES, BADGE_TONES, Badge, type BadgeAppearance, type BadgeProps, type BadgeTone, Banner, type BannerProps, BarChart, type BarChartProps, BottomNav, BottomNavItem, type BottomNavItemProps, BreadcrumbItem, type BreadcrumbItemProps, BreadcrumbLink, type BreadcrumbLinkProps, BreadcrumbPage, type BreadcrumbPageProps, BreadcrumbSeparator, type BreadcrumbSeparatorProps, Breadcrumbs, type BreadcrumbsProps, Browser, type BrowserProps, Bubble, type BubbleProps, BubbleReaction, type BubbleReactionProps, BubbleReactions, type BubbleReactionsProps, Button, type ButtonBleed, type ButtonProps, CHART_SERIES_COUNT, COMPONENT_GROUPS, COMPONENT_TAXONOMY, Calendar, type CalendarProps, Card, CardAction, CardContent, type CardContentProps, CardDescription, CardFooter, type CardFooterProps, CardHeader, CardList, type CardProps, CardTitle, type CardTitleProps, Carousel, type CarouselProps, type CarouselSlidesToShow, type ChartCategories, type ChartCenterLabel, type ChartCurve, type ChartDatum, type ChartSeries, type ChartTone, type ChartTooltipIndicator, type ChartTooltipOptions, type ChartValueFormatter, ChatComposer, type ChatComposerProps, Checkbox, CheckboxCard, type CheckboxCardProps, type CheckboxCardTone, CheckboxGroup, type CheckboxGroupProps, Code, CodeBlock, type CodeBlockProps, CodeHighlightProvider, type CodeHighlighter, type CodeProps, Collapsible, CollapsibleIndicator, CollapsiblePanel, CollapsibleTrigger, ColorField, type ColorFieldProps, Combobox, ComboboxChips, ComboboxClear, ComboboxContent, ComboboxEmpty, ComboboxGroup, ComboboxGroupLabel, ComboboxInput, ComboboxItem, type ComboboxItemGroup, ComboboxItemIndicator, ComboboxList, ComboboxPortal, type ComboboxProps, ComboboxValue, ComboboxVirtualList, type ComboboxVirtualListProps, type CommandFilter, type CommandItem, CommandMenu, CommandMenuGroup, type CommandMenuGroupProps, CommandMenuItem, type CommandMenuItemProps, CommandMenuPanel, type CommandMenuPanelProps, type CommandMenuProps, CommandMenuTrigger, type CommandMenuTriggerProps, type ComponentGroup, type ComponentGuidance, ComponentMeta, type ComponentRegister, type ConstraintFlag, ContextCard, ContextCardArrow, ContextCardContent, ContextCardPortal, ContextCardTrigger, ContextMenu, ContextMenuContent, ContextMenuGroup, ContextMenuGroupLabel, ContextMenuItem, ContextMenuPortal, ContextMenuSeparator, ContextMenuTrigger, DataTable, type DataTableColumn, type DataTableProps, type DataTableRowKey, DatePicker, type DatePickerProps, DateTile, type DateTileProps, Density, DensityProvider, Density as DensityValue, DestructiveActionModal, type DestructiveActionModalProps, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, type DialogSize, DialogTitle, DialogTrigger, DisclosurePicker, DisclosurePickerEmpty, DisclosurePickerList, type DisclosurePickerListProps, DisclosurePickerOption, type DisclosurePickerOptionProps, DisclosurePickerPanel, type DisclosurePickerPanelProps, type DisclosurePickerProps, type DisclosurePickerSearch, DisclosurePickerTrigger, type DisclosurePickerTriggerProps, EmptyState, type EmptyStateProps, Entity, type EntityProps, Feedback, type FeedbackData, type FeedbackProps, type FeedbackRating, Field, type FieldProps, Fieldset, FieldsetContent, FieldsetDescription, FieldsetFooter, FieldsetLegend, type FieldsetVariant, FileDropzone, type FileDropzoneProps, type FileRejection, type FileRejectionCode, FontPicker, type FontPickerFont, type FontPickerOption, type FontPickerProps, Form, type FormProps, GlidingHighlight, type GlidingHighlightProps, GradientArt, type GradientArtProps, type Hsv, InlineStatus, type InlineStatusProps, type StatusTone as InlineTone, Input, type InputProps$1 as InputProps, Kbd, KbdGroup, type KbdGroupProps, type KbdProps, Label, type LabelProps$2 as LabelProps, LineChart, type LineChartProps, Marker, type MarkerProps, Marquee, type MarqueeProps, MediaImage, type MediaImageProps, MediaTile, type MediaTileProps, Menu, MenuCheckboxItem, MenuContent, MenuGroup, MenuGroupLabel, MenuItem, MenuPortal, MenuRadioGroup, MenuRadioItem, MenuSeparator, MenuSubmenu, MenuSubmenuTrigger, MenuTrigger, Message, type MessageProps, MessageScroller, type MessageScrollerHandle, type MessageScrollerProps, Meter, MeterIndicator, MeterLabel, type MeterSize, type MeterTone, MeterTrack, MeterValue, MiddleTruncate, type MiddleTruncateProps, type MotionPolicy, MotionProvider, type MotionProviderProps, Note, type NoteAction, type NoteProps, NotificationBadge, type NotificationBadgeProps, NumberField, type NumberFieldProps, type OrbMode, type OrbSize, OtpField, type OtpFieldProps, OverflowMenu, type OverflowMenuProps, PageHeader, type PageHeaderProps, PageLoader, type PageLoaderProps, Pagination, type PaginationProps, Panel, PanelGroup, PanelResizer, type PanelResizerProps, PanelSection, type PanelWidthBounds, Phone, type PhoneProps, PieChart, type PieChartProps, Pill, type PillProps, Popover, PopoverArrow, PopoverClose, PopoverContent, PopoverDescription, PopoverPortal, PopoverTitle, PopoverTrigger, Presence, type PresenceProps, type Presentation, PresentationProvider, Progress, ProgressIndicator, ProgressLabel, type ProgressSize, ProgressTrack, ProgressValue, PropertyPair, PropertyRow, RadarChart, type RadarChartProps, RadialChart, type RadialChartProps, Radio, RadioCard, type RadioCardProps, type RadioCardTone, RadioGroup, RelativeTime, type RelativeTimeProps, Reveal, type RevealProps, type Rgb, SABLE_UI_VERSION, SEGMENTED_BAR_TONES, STATUS_TONES, STATUS_TONE_ICON, type ScrollCommandOptions, Scroller, type ScrollerProps, ScrubField, type ScrubFieldProps, SearchInput, type SearchInputProps, SectionHeader, type SectionHeaderProps, SegmentedBar, type SegmentedBarProps, type SegmentedBarSegment, type SegmentedBarTone, Select, SelectContent, SelectGroup, SelectGroupLabel, SelectItem, SelectPortal, SelectSeparator, SelectTrigger, SelectValue, Separator, type SeparatorProps$3 as SeparatorProps, SettingsMenu, type SettingsMenuProps, SettingsRow, type SettingsRowProps, Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetList, SheetPortal, SheetTitle, SheetTrigger, ShowMore, type ShowMoreProps, SideNav, type SideNavActiveVariant, SideNavGroup, type SideNavGroupProps, SideNavItem, type SideNavItemProps, type SideNavProps, type SideNavSize, Sidebar, SidebarBrand, type SidebarBrandProps, SidebarFooter, SidebarHeader, SidebarItem, type SidebarItemProps, SidebarNav, type SidebarProps, SimpleTooltip, Skeleton, SkipLink, Slider, SliderControl, SliderIndicator, SliderRoot, SliderThumb, SliderTrack, SliderValue, Sparkline, type SparklineProps, Spinner, type SpinnerProps, StatusBar, StatusBarGroup, StatusBarSeparator, StatusDot, type StatusDotProps, type StatusTone, type StepStatus, Stepper, StepperItem, type StepperItemProps, type StepperOrientation, type StepperProps, StreamingText, type StreamingTextProps, Switch, TRANSPARENT, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow, Tabs, TabsPanel as TabsContent, TabsList, TabsPanel, TabsTrigger, TextReveal, type TextRevealProps, Textarea, type TextareaProps, ThemeId, ThemeManifest, ThemeMode$1 as ThemeManifestMode, type ThemeMode, ThemePreview, type ThemePreviewProps, ThemeSelector, type ThemeSelectorProps, ThemeSwitcher, type ThemeSwitcherProps, ThinkingOrb, type ThinkingOrbProps, ToastAction, type ToastApi, ToastClose, ToastContent, ToastDescription, type ToastManagerApi, type ToastOptions, type ToastPosition, ToastProvider, type ToastProviderProps, ToastRoot, ToastTitle, type ToastType, ToastViewport, Toggle, ToggleGroup, type ToggleGroupAppearance, Toggle as ToggleGroupItem, Toolbar, ToolbarButton, type ToolbarButtonProps, ToolbarGroup, type ToolbarGroupProps, ToolbarInput, type ToolbarInputProps, ToolbarLink, type ToolbarLinkProps, type ToolbarProps, ToolbarSeparator, type ToolbarSeparatorProps, Tooltip, TooltipArrow, TooltipContent, TooltipPortal, TooltipProvider, TooltipTrigger, Tree, TreeAddRow, TreeEmpty, TreeRow, TreeSection, type UseCopyOptions, type UseCopyResult, type UseInViewOptions, type UsePanelWidthOptions, Video, type VideoProps, ViewTransitionName, type ViewTransitionNameProps, Workspace, WorkspaceBar, WorkspaceCanvas, accordionMeta, appHeaderMeta, appShellMeta, areaChartMeta, attachmentMeta, avatarGroupVariants, avatarMeta, avatarVariants, badgeMeta, badgeVariants, bannerMeta, bannerVariants, barChartMeta, bottomNavMeta, breadcrumbsMeta, browserMeta, bubbleMeta, buttonMeta, buttonVariants, calendarMeta, cardMeta, carouselMeta, chartColor, toneColor as chartToneColor, chatComposerMeta, checkboxCardMeta, checkboxMeta, cn, codeBlockMeta, codeMeta, collapsibleMeta, colorFieldMeta, comboboxMeta, commandMenuMeta, componentGuidance, componentLabel, componentSlug, componentsInGroup, contextCardMeta, contextMenuMeta, dataTableMeta, datePickerMeta, dateTileMeta, destructiveActionModalMeta, dialogMeta, disclosurePickerMeta, emptyStateMeta, entityMeta, feedbackMeta, fieldsetMeta, fileDropzoneMeta, fileDropzoneVariants, fontPickerMeta, formMeta, formatFileSize, formatHex, glidingHighlightMeta, gradientArtMeta, hsvToRgb, hueColor, inlineStatusMeta, inputMeta, isTransparent, kbdMeta, labelMeta, lineChartMeta, markerMeta, marqueeMeta, mediaImageMeta, mediaTileMeta, menuMeta, messageMeta, messageScrollerMeta, meterIndicatorVariants, meterMeta, meterTrackVariants, middleTruncateMeta, noteMeta, noteVariants, notificationBadgeMeta, notificationCountVariants, notificationDotVariants, numberFieldMeta, otpFieldMeta, overflowMenuMeta, pageHeaderMeta, pageLoaderMeta, paginationMeta, panelGroupMeta, panelSectionMeta, parseHex, phoneMeta, pieChartMeta, pillMeta, pillVariants, popoverMeta, progressMeta, progressTrackVariants, radarChartMeta, radialChartMeta, radioCardMeta, radioMeta, relativeTimeMeta, rgbToHsv, scrollerMeta, scrubFieldMeta, searchInputMeta, sectionHeaderMeta, segmentedBarMeta, segmentedBarSegmentVariants, segmentedBarVariants, selectMeta, separatorMeta, settingsMenuMeta, sheetMeta, sheetVariants, showMoreMeta, sideNavMeta, sidebarMeta, skeletonMeta, sliderMeta, sparklineMeta, spinnerMeta, startViewTransition, statusBarMeta, statusDotMeta, statusDotVariants, stepperConnectorVariants, stepperIndicatorVariants, stepperMeta, streamingTextMeta, supportsViewTransitions, switchMeta, tableMeta, tabsMeta, textareaMeta, themeSelectorMeta, themeSwitcherMeta, thinkingOrbMeta, toast, toastMeta, toggleMeta, toolbarGroupVariants, toolbarMeta, toolbarSeparatorVariants, toolbarVariants, tooltipMeta, treeIndent, treeMeta, useAnchoredDensity, useComboboxFilteredItems, useCommandMenuShortcut, useCopy, useDensity, useDisclosurePicker, useInView, useMotion, usePanelWidth, usePresentation, useReducedMotion, useScrollActivity, useSidebar, useToast, useToastManager, useTypeTier, videoMeta, workspaceMeta };

package/dist/index.js

@@ -160,7 +160,7 @@ import { PresentationProvider, usePresentation } from "./lib/presentation.js";
 import { useScrollActivity } from "./lib/use-scroll-activity.js";
 import { useCopy } from "./lib/use-copy.js";
 import { STATUS_TONES, STATUS_TONE_ICON } from "./lib/status-tone.js";
-var SABLE_UI_VERSION = "0.8.1";
+var SABLE_UI_VERSION = "0.9.0";
 export {
   ART_TOKENS,
   CHART_SERIES_COUNT,

package/dist/{meta-CcE_SeFu.d.ts → meta-DVG8ceze.d.ts}

@@ -214,6 +214,15 @@ interface ComponentMeta {
      * otherwise — a deprecation with no forward path just strands the reader.
      */
     supersededBy?: string;
+    /**
+     * Marks a composition: a designed arrangement of parts for one kind of item
+     * (a cover tile, a calendar date), not a behaviour. Agents treat it as a
+     * reference, used when its layout fits the brief, otherwise rebuilt to the
+     * product's own design from the parts named here (e.g. "AspectBox,
+     * MediaImage, Card render, Badge"). Behaviour components never set it: those
+     * are always used, never rebuilt.
+     */
+    composition?: string;
     /** Public props of the root component only — never subcomponents. */
     props: PropMeta[];
     /**

package/dist/patterns/index.d.ts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { P as PatternMeta } from '../meta-CcE_SeFu.js';
+import { P as PatternMeta } from '../meta-DVG8ceze.js';
 
 declare function AuthPage(): react.JSX.Element;
 

package/dist/styles.css

@@ -1547,6 +1547,31 @@
 	--split-gap: initial;
 }
 
+/* Toasts keep clear of an open Sheet's actions. A right sheet's pinned footer
+   (Check out) sat under a bottom-right toast, and its close button under a
+   top-right one. Where there is room, the stack moves beside the sheet (both are
+   w-95); on a narrower screen a bottom stack moves to the top, away from the
+   footer. A bottom sheet sends a bottom stack to the top at any width. */
+@media (width >= 52rem) {
+	:root:has([data-sable-sheet="right"][data-open]) [data-sable-toast-viewport][data-position$="right"] {
+		right: calc(min(var(--spacing) * 95, 90vw) + var(--spacing) * 4);
+	}
+	:root:has([data-sable-sheet="left"][data-open]) [data-sable-toast-viewport][data-position$="left"] {
+		left: calc(min(var(--spacing) * 95, 90vw) + var(--spacing) * 4);
+	}
+}
+@media (width < 52rem) {
+	:root:has([data-sable-sheet="right"][data-open]) [data-sable-toast-viewport][data-position="bottom-right"],
+	:root:has([data-sable-sheet="left"][data-open]) [data-sable-toast-viewport][data-position="bottom-left"] {
+		top: calc(var(--spacing) * 4);
+		bottom: auto;
+	}
+}
+:root:has([data-sable-sheet="bottom"][data-open]) [data-sable-toast-viewport][data-position^="bottom"] {
+	top: calc(var(--spacing) * 4);
+	bottom: auto;
+}
+
 /* `Col span={{ base, md, lg }}` / `start={…}` — each breakpoint resolves to the
    most specific value defined at or below it (mobile-first cascade). */
 [data-sable-col] {
@@ -1970,7 +1995,12 @@
    it on data-[starting-style]/data-[ending-style]; this recipe carries the
    overflow, the transition, and the content fade. */
 @utility motion-disclosure {
+	/* Clipped for the height animation, with a margin so a focus ring (or a
+	   control a few pixels proud of its row) at the panel's edge is not cut
+	   off. `hidden` is the fallback where `clip` is unsupported. */
 	overflow: hidden;
+	overflow: clip;
+	overflow-clip-margin: calc(var(--spacing) * 1);
 	transition-property: height, opacity;
 	transition-duration: var(--motion-duration-base);
 	transition-timing-function: var(--motion-ease-standard);

package/llms/components/app-shell.md

@@ -30,6 +30,12 @@ Use AppShell as the outer product frame for authenticated or app-like experience
 | Bottom nav | no | Mobile fixed navigation with reserved bottom space. |
 | Dock | no | Persistent bottom chrome that outlives routes — a now-playing bar, a call bar. Sticky above the bottom nav; the desktop Sidebar shortens to clear it. |
 
+## Subcomponents
+
+| Name | Type | Description |
+| --- | --- | --- |
+| SkipLink | ComponentProps<"a"> | AppShell's skip link on its own, for a layout that is not an AppShell (a storefront with a top header). Put it first in the body and give the page's <main> the matching id: `<SkipLink />` then `<main id="main-content" tabIndex={-1}>`. `href` defaults to #main-content, the label to "Skip to content". |
+
 ## Props
 
 | Name | Type | Default | Description |
@@ -90,6 +96,26 @@ import { AppHeader, AppShell, Banner, BottomNav, BottomNavItem, Icon, PageHeader
 </AppShell>
 ```
 
+### SkipLink in a layout of your own
+
+```tsx
+import { Button, Icon, PageHeader, Region, SkipLink } from "@sableui/react"
+// <Link> = your router's link (react-router, next/link, @tanstack/router, …)
+
+<>
+  <SkipLink />
+  <header className="flex items-center justify-between px-(--page-inset) py-4">
+    <Link to="/">Alder & Lune</Link>
+    <Button variant="ghost" size="icon" aria-label="Search"><Icon name="search" /></Button>
+  </header>
+  <main id="main-content" tabIndex={-1}>
+    <Region max="wide">
+      <PageHeader title="Lighting" />
+    </Region>
+  </main>
+</>
+```
+
 ### Minimal (sidebar + content only)
 
 ```tsx

package/llms/components/button.md

@@ -41,7 +41,8 @@ Use Button when the user commits an action, submits a form, opens UI, or confirm
 | variant | "primary" \| "secondary" \| "ghost" \| "outline" \| "destructive" \| "link" \| "floating" \| "field" \| "on-color" \| "on-color-outline" \| "on-color-ghost" | "primary" | Visual emphasis tier. One primary per screen. The on-color tiers are for buttons ON a coloured fill: they paint with the inherited text colour (the fill's ink) — on-color is solid (ink background, fill-coloured label via the optional --on-color-fill var, else black/white), on-color-outline and on-color-ghost are transparent with an ink label. Never use them on page or card surfaces. floating is for a control that sits OVER content (carousel arrows, a marquee pause, a jump-to-latest over a conversation): its own edge, lift and translucent popover fill, so it reads on arbitrary content beneath. field is for a button docked in a workspace panel among xs fields: the inset panel-field fill and the field's corner, so a picker trigger or an add action reads as one of the row's controls; pair it with size xs or icon-xs. |
 | size | "xs" \| "sm" \| "md" \| "cta" \| "icon" \| "icon-sm" \| "icon-xs" | "md" | Reads the density ladder, so every value differs by register: page 28/32/40/44, workspace 24/28/32/36. xs and icon-xs were added in 0.31.0 for the workspace control floor and are the sizes tool chrome wants; md is the default everywhere. icon/icon-sm/icon-xs are square. |
 | render | ReactElement \| (props, state) => ReactElement | — | Compose with another element/component through the Base UI render prop. |
-| loading | boolean | false | Disable the button and show a leading Spinner while an action is in flight. Sets aria-busy; a native button is disabled, a render element (e.g. an <a>) gets aria-disabled. |
+| loading | boolean | false | Show a leading Spinner while an action is in flight and refuse presses. Sets aria-busy and aria-disabled, never the native disabled: disabling the focused button sent focus to <body>, so a sheet the action opened had nowhere to return it. |
+| onClick | (event: MouseEvent<HTMLButtonElement>) => unknown | — | May return a promise: the button shows `loading` until it settles and ignores further presses meanwhile, from the first click on. Prefer it to a `busy` flag in state, which takes effect a render late (three fast clicks ran three times). |
 | badge | ReactNode | — | A corner indicator (usually <NotificationBadge dot /> or a count) overlaid on the top-end corner of the glyph. For icon-only sizes; never hand-position a badge over a Button with absolute offsets. |
 | loadingLabel | ReactNode | — | Optional text shown in place of children while loading. |
 | iconStart | ReactNode | — | Icon before the label. The button takes one 2px step off its start padding so icon + label read as centred. Replaced by the spinner while loading. |

package/llms/components/card.md

@@ -45,7 +45,7 @@ Use Card for a discrete thing with its own boundary, such as one product, one no
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
-| variant | "default" \| "flat" | "default" | "default" raises with bg-card + border + soft shadow; "flat" is transparent. |
+| variant | "default" \| "flat" | "default" | "default" raises with bg-card + border + soft shadow; "flat" is transparent, for a card inside a section that already frames it. A flat card made a link or button shows its shape only on hover (the muted fill), so over a photo with square bottom corners it reads as a cropped image at rest: give a linked media card the default variant. |
 | density | "comfortable" \| "compact" | "comfortable" | Padding of the Header/Content/Footer parts: comfortable = p-6 (default), compact = p-4 for denser section panels (pair compact with the flat variant for a settings / form section panel). Threaded to the parts via the inherited --card-p custom property. Card sets --card-p via inline style, which beats a plain (non-!important) stylesheet override of the same property on the same element — use this prop rather than a className override; if an external override is unavoidable, it needs !important. |
 | render | useRender.RenderProp | — | Replace the rendered element through the Base UI render prop — most often `render={<a href="/x" />}` (or a router Link) to make the whole card one link. When the rendered element is a link (a[href]) or a button, the card gains a hover state (stronger border and shadow; a muted fill when flat), a full-card focus-visible ring and motion-interactive easing. Any other element (article, li) stays a static surface. Children can answer the hover with `group-hover/card:`. |
 

package/llms/components/data-table.md

@@ -16,6 +16,7 @@ Use DataTable when a data array and column definition should render a sortable,
 - Do: Provide stable rowKey values for dynamic data so selection and sorting do not jump.
 - Do: Use sortable only on columns where ordering is obvious and useful.
 - Do: Pair server-side datasets with Pagination and pass already-sorted/paged rows.
+- Do: Move to TanStack Table, rendered with Sable's Table parts, once the table needs server-side sorting or filtering, column visibility or resizing, grouping, or virtualised rows. DataTable stays dependency-free and does not grow into a data grid; `sable docs tables-with-tanstack` maps one onto the other.
 - Don't: Make every row clickable and also fill it with competing buttons. Choose a clear row interaction model.
 - Don't: Use DataTable for heterogeneous cards or timeline content. A list or card layout will scan better.
 

package/llms/components/fieldset.md

@@ -2,7 +2,7 @@
 
 **Status:** stable
 
-Form section panel (Card-like bordered surface) over Base UI Fieldset, with Legend/Description/Content/Footer parts.
+Form section panel (Card-like bordered surface) over Base UI Fieldset, with Legend/Description/Content/Footer parts; `variant="plain"` is the bare group, for a radio group's shared name.
 
 **Keywords:** fieldset, form group, legend, fields
 
@@ -14,6 +14,7 @@ Use Fieldset to group related controls under a shared label or explanation.
 
 - Do: Use it for grouped form sections such as contact details, preferences, or permissions.
 - Do: Keep the legend meaningful so assistive tech and agents understand the group purpose.
+- Do: Use `variant="plain"` to name a radio group or a run of checkboxes inside a form or card that is already framed: the legend reads as a field label and nothing draws a second box. Do not strip the card variant with classes instead.
 - Don't: Do not use Fieldset as a generic spacing wrapper outside forms.
 - Don't: Do not use a Legend that is really a heading. A legend names the group's question for assistive technology; using it as a section title puts a question mark where the outline should be.
 
@@ -40,6 +41,7 @@ Use Fieldset to group related controls under a shared label or explanation.
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
+| variant | "card" \| "plain" | "card" | `card` is a bordered, raised section with padded parts. `plain` is the grouping alone (no border, surface or inset) with the legend in the field-label style: the shared name a radio group needs, inside a form that is already framed. |
 | disabled | boolean | — | Disables the whole group. Renders <fieldset disabled> (native control disabling) and surfaces data-[disabled] for dimming. |
 | render | ReactElement \| function | — | Base UI render prop to replace or compose the underlying element. |
 | className | string | — | Merged onto each part via cn() for one-off overrides. |
@@ -104,3 +106,21 @@ import { Field, Fieldset, FieldsetContent, FieldsetLegend, Radio, RadioGroup } f
 //   a Card section on a page; a legend that is really a heading lies to
 //   assistive technology about the form's structure.
 ```
+
+### A radio group's name, without a second box
+
+```tsx
+import { Card, CardContent, Fieldset, FieldsetLegend, RadioCard, RadioGroup } from "@sableui/react"
+
+<Card>
+  <CardContent>
+    <Fieldset variant="plain">
+      <FieldsetLegend>Delivery</FieldsetLegend>
+      <RadioGroup defaultValue="standard">
+        <RadioCard value="standard" title="Standard" description="3–5 working days" trailing="Free" />
+        <RadioCard value="express" title="Express" description="Next working day" trailing="$12.00" />
+      </RadioGroup>
+    </Fieldset>
+  </CardContent>
+</Card>
+```

package/llms/components/form.md

@@ -32,13 +32,14 @@ Use Form and Field as the default wrapper for Sable form controls. Field owns th
 
 | Name | Type | Description |
 | --- | --- | --- |
-| Field | { label?: ReactNode; description?: ReactNode; error?: ReactNode; required?: boolean; messages?: Partial<Record<"valueMissing" \| "typeMismatch" \| "patternMismatch" \| "tooShort" \| "tooLong" \| "rangeUnderflow" \| "rangeOverflow" \| "stepMismatch" \| "badInput", ReactNode>>; disabled?: boolean; name?: string; validate?: (value, formValues) => string \| string[] \| null \| Promise<…>; validationMode?: "onSubmit" \| "onBlur" \| "onChange"; validationDebounceTime?: number; orientation?: "vertical" \| "horizontal"; className?: string; children: ReactElement } | Wraps a single control element (e.g. <Input />) on Base UI Field and wires label (htmlFor + aria-labelledby), helper text and error (aria-describedby), aria-invalid, and required onto it automatically. Base UI-backed controls (Input, Textarea, Select, Combobox, NumberField, Checkbox, Switch, Slider, OtpField…) register through context; the child is also cloned so plain elements keep the same wiring. error renders a destructive message and takes precedence; without it the slot shows the field's messages entry for the native constraint that failed (messages={{ valueMissing: "Enter a subject." }}), else Base UI's validation message (the browser's wording for a native constraint, validate, or Form errors). required adds the native attribute plus a visual asterisk (defaults to false). disabled disables the control and dims the label. name keys the field in Form errors / onFormSubmit. validationMode overrides the Form's. orientation defaults to "vertical" (label → control); "horizontal" places control then label inline for a single checkbox / switch / radio — the control centres on the label's first line (it stays there when the label wraps) and description/error sit in the label's column. The root, label, description, error and control carry data-invalid / data-valid, data-touched, data-dirty, data-filled, data-focused and data-disabled for state styling. |
+| Field | { label?: ReactNode; description?: ReactNode; error?: ReactNode; required?: boolean; messages?: Partial<Record<"valueMissing" \| "typeMismatch" \| "patternMismatch" \| "tooShort" \| "tooLong" \| "rangeUnderflow" \| "rangeOverflow" \| "stepMismatch" \| "badInput", ReactNode>>; disabled?: boolean; name?: string; validate?: (value, formValues) => string \| string[] \| null \| Promise<…>; validationMode?: "onSubmit" \| "onBlur" \| "onChange"; validationDebounceTime?: number; orientation?: "vertical" \| "horizontal"; trailing?: ReactNode; className?: string; children: ReactElement } + other div props on the root | Wraps a single control element (e.g. <Input />) on Base UI Field and wires label (htmlFor + aria-labelledby), helper text and error (aria-describedby), aria-invalid, and required onto it automatically. Base UI-backed controls (Input, Textarea, Select, Combobox, NumberField, Checkbox, Switch, Slider, OtpField…) register through context; the child is also cloned so plain elements keep the same wiring. error renders a destructive message and takes precedence; without it the slot shows the field's messages entry for the native constraint that failed (messages={{ valueMissing: "Enter a subject." }}), else Base UI's validation message (the browser's wording for a native constraint, validate, or Form errors). required adds the native attribute plus a visual asterisk (defaults to false). disabled disables the control and dims the label. name keys the field in Form errors / onFormSubmit. validationMode overrides the Form's. orientation defaults to "vertical" (label → control); "horizontal" places control then label inline for a single checkbox / switch / radio — the control centres on the label's first line (it stays there when the label wraps) and description/error sit in the label's column. trailing puts something at the end of the control's row: vertically, beside the control (a promo code's Apply button, the control taking the rest); horizontally, at the end of the label's first line (a facet count). Other props (data-*, id, aria-*) land on the root. The root, label, description, error and control carry data-invalid / data-valid, data-touched, data-dirty, data-filled, data-focused and data-disabled for state styling. |
 
 ## Props
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
-| Form | { validationMode?: "onSubmit" \| "onBlur" \| "onChange"; errors?: Record<string, string \| string[]>; onFormSubmit?: (values, details) => void; actionsRef?: RefObject<Form.Actions> } + ComponentPropsWithRef<"form"> | — | A <form> laid out as a vertical column with comfortable field spacing (override with className, e.g. gap-4). On submit it validates every Field (native constraints plus Field validate), shows each message under its field, focuses the first invalid control, and only then calls onSubmit. validationMode defaults to "onSubmit" (then live re-validation on change). errors shows external (e.g. server) messages keyed by Field name and clears one when its field is edited. onFormSubmit receives the named Field values and prevents the native submit. A control outside any Field is still checked by the browser before onSubmit runs. Validating in your own code (react-hook-form, a schema, state)? Pass noValidate: onSubmit always runs and each Field shows the error you set; without it an empty required Field stops the submit before your handler can set that error. |
+| Form | { validationMode?: "onSubmit" \| "onBlur" \| "onChange"; errors?: Record<string, string \| string[]>; onFormSubmit?: (values, details) => void; actionsRef?: RefObject<Form.Actions> } + ComponentPropsWithRef<"form"> | — | A <form> laid out as a vertical column with comfortable field spacing (override with className, e.g. gap-4). On submit it validates every Field (native constraints plus Field validate), shows each message under its field, focuses the first invalid control, and only then calls onSubmit. validationMode defaults to "onSubmit" (then live re-validation on change). errors shows external (e.g. server) messages keyed by Field name and clears one when its field is edited. onFormSubmit receives the named Field values and prevents the native submit. A control outside any Field is still checked by the browser before onSubmit runs. Validating in your own code (react-hook-form, a schema, state)? Pass noValidate: onSubmit always runs and each Field shows the error you set; without it an empty required Field stops the submit before your handler can set that error. Either way, once onSubmit returns (or the promise it returns settles), the first control a Field marks invalid takes focus. |
+| onSubmit | (event: FormEvent<HTMLFormElement>) => unknown | — | The native submit handler. It may return a promise. When it returns, or its promise settles, the first control a Field marks invalid takes focus, so errors your own code sets get the same treatment as Sable's validation. |
 | validationMode | "onSubmit" \| "onBlur" \| "onChange" | "onSubmit" | When Fields validate. After the first submit, fields re-check as the user edits. A Field's own validationMode wins. |
 | errors | Record<string, string \| string[]> | — | External (e.g. server) messages keyed by Field name, shown under that field. Each clears when its field is edited. |
 | onFormSubmit | (values: Record<string, unknown>, details) => void | — | Called with the named Field values after validation passes; prevents the native submit. |
@@ -79,6 +80,14 @@ import { Field, Input } from "@sableui/react"
 <Field label="Password" error="Must be at least 8 characters."><Input type="password" /></Field>
 ```
 
+### An input with its action
+
+```tsx
+import { Button, Field, Input } from "@sableui/react"
+
+<Field label="Promo code" error={promoError} trailing={<Button variant="secondary" onClick={applyPromo}>Apply</Button>}><Input name="promo" autoCapitalize="characters" /></Field>
+```
+
 ### Your own wording for a missing value
 
 ```tsx

package/llms/components/media-tile.md

@@ -36,7 +36,10 @@ The item in a media grid or shelf: an album, a playlist, a video, a podcast, a f
 | --- | --- | --- | --- |
 | title | ReactNode | — | The item's name. Seeds the fallback art when it is a string. |
 | subtitle | ReactNode | — | The second line — an artist, a channel, a year. |
+| meta | ReactNode | — | Lines under the subtitle, in its muted type: a price beside its sale price, a count of finishes, a status Badge. A wrapping block, where the subtitle is one truncated line. Use it for a product tile instead of building one. |
 | src | string | — | Cover image URL. Without one, or when it fails, the cover is GradientArt seeded by the item. |
+| srcSet | string | — | Responsive cover candidates, passed to the `<img>`. |
+| sizes | string | — | The cover's layout width for `srcSet`, e.g. `"(min-width: 64rem) 25vw, 50vw"`. |
 | alt | string | "" | Cover alt text. Empty by default: the title below already names the item. |
 | seed | string \| number | — | Seeds the fallback art. Defaults to `title` when it is a string. |
 | aspect | "square" \| "video" \| "poster" \| number | "square" | The cover's shape: square (albums, podcasts), video (16:9), poster (2:3 — films, books), or any width / height ratio. |
@@ -82,6 +85,35 @@ The item in a media grid or shelf: an album, a playlist, a video, a podcast, a f
 
 ## Examples
 
+### Product tile
+
+```tsx
+import { Badge, Grid, MediaTile } from "@sableui/react"
+// <Link> = your router's link (react-router, next/link, @tanstack/router, …)
+
+<Grid minItemWidth="14rem" gap={4}>
+	{products.map((product) => (
+		<MediaTile
+			key={product.id}
+			aspect={4 / 5}
+			title={product.name}
+			subtitle={product.material}
+			src={product.image}
+			srcSet={product.imageSet}
+			sizes="(min-width: 64rem) 25vw, 50vw"
+			render={<Link to={`/products/${product.slug}`} />}
+			badge={product.isNew ? <Badge appearance="overlay">New</Badge> : undefined}
+			meta={
+				<>
+					<span className="text-foreground">{formatPrice(product.price)}</span>
+					<span>{product.finishes.length} finishes</span>
+				</>
+			}
+		/>
+	))}
+</Grid>
+```
+
 ### Album grid
 
 ```tsx

package/llms/components/radio-card.md

@@ -37,6 +37,7 @@ Use RadioCard for visual choice cards when users compare a small set of named op
 | value | string | — | The unique value that pairs this card with the group's selected value. |
 | title | ReactNode | — | The card's primary label (rendered as text-title-sm). |
 | description | ReactNode | — | Optional supporting copy beneath the title (text-body-sm, muted). |
+| trailing | ReactNode | — | End-aligned on the title's line: a price, a delivery date, a count. The title takes the rest of the row. |
 | icon | ReactNode | — | Leading icon (e.g. a solid <Icon>). Its presence switches to the two-dimensional card — icon top-left, indicator top-right, copy below — and the glyph is rendered as a solid-fill icon in the tone colour. |
 | tone | "neutral" \| "standard" \| "collectible" \| "edition" \| "info" \| "warning" | "neutral" | Semantic colour the selected state carries across the border, radio, and icon glyph. Neutral uses the primary ring with a muted wash. |
 | disabled | boolean | false | Dims the card and blocks selection. The group skips it during keyboard navigation. |