@gradeui/ui 3.1.0 → 3.2.0

package/dist/index.d.mts

@@ -18,6 +18,7 @@ import * as DropdownMenuPrimitive from '@radix-ui/react-dropdown-menu';
 import * as LabelPrimitive from '@radix-ui/react-label';
 import * as PopoverPrimitive from '@radix-ui/react-popover';
 import * as ProgressPrimitive from '@radix-ui/react-progress';
+import { SortingState, OnChangeFn, VisibilityState } from '@tanstack/react-table';
 import * as ResizablePrimitive from 'react-resizable-panels';
 import * as ScrollAreaPrimitive from '@radix-ui/react-scroll-area';
 import * as SelectPrimitive from '@radix-ui/react-select';
@@ -190,14 +191,14 @@ declare const MediaSurfaceContract: _gradeui_contracts.ComponentContract<{
             description: z.ZodOptional<z.ZodString>;
         }, "strip", z.ZodTypeAny, {
             kind: "book";
-            description?: string | undefined;
             title?: string | undefined;
+            description?: string | undefined;
             author?: string | undefined;
             isbn?: string | undefined;
         }, {
             kind: "book";
-            description?: string | undefined;
             title?: string | undefined;
+            description?: string | undefined;
             author?: string | undefined;
             isbn?: string | undefined;
         }>, z.ZodObject<{
@@ -584,7 +585,7 @@ type Surface = "solid" | "translucent" | "glass" | "glass-strong";
  */
 declare const bannerVariants: (props?: ({
     variant?: "default" | "destructive" | "success" | "warning" | "info" | "announcement" | null | undefined;
-    align?: "between" | "start" | "center" | null | undefined;
+    align?: "center" | "between" | "start" | null | undefined;
     sticky?: boolean | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 interface BannerProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "title">, VariantProps<typeof bannerVariants> {
@@ -640,8 +641,8 @@ declare const Banner: React.ForwardRefExoticComponent<BannerProps & React.RefAtt
  * consistent across primitives.
  */
 declare const buttonVariants: (props?: ({
-    variant?: "default" | "secondary" | "destructive" | "outline" | "ghost" | "link" | "raised" | null | undefined;
-    size?: "2xs" | "xs" | "sm" | "md" | "lg" | "default" | "icon" | null | undefined;
+    variant?: "link" | "default" | "secondary" | "destructive" | "outline" | "ghost" | "raised" | null | undefined;
+    size?: "default" | "2xs" | "xs" | "sm" | "md" | "lg" | "icon" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof buttonVariants> {
     asChild?: boolean;
@@ -868,6 +869,74 @@ declare const Field: React.ForwardRefExoticComponent<FieldProps & React.RefAttri
     Trailing: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & React.RefAttributes<HTMLDivElement>>;
 };
 
+/**
+ * PropertyList — the read-only "one record, stacked" display primitive.
+ *
+ * A property list is a table row transposed: where a Table runs the schema
+ * horizontally (columns) across many records, a PropertyList takes ONE
+ * record and stacks its fields vertically as label / value pairs. Reach for
+ * it for detail panels, inspectors, "about this item" cards, order summaries
+ * — anywhere you're showing the properties of a single thing.
+ *
+ *   <PropertyList>
+ *     <PropertyList.Row label="Status" icon={<Activity />}>
+ *       <Badge variant="warning-soft">Low</Badge>
+ *     </PropertyList.Row>
+ *     <PropertyList.Row label="Owner">
+ *       <Avatar className="h-5 w-5"><AvatarFallback>EO</AvatarFallback></Avatar>
+ *     </PropertyList.Row>
+ *   </PropertyList>
+ *
+ * The value side is deliberately polymorphic — it's a slot (`children`, or
+ * the `value` prop), not a string. A row can hold plain text, a date, a
+ * single Badge, a tag group, an avatar stack, a link, anything. That's the
+ * whole point: the same value renderers that fill a Table cell drop straight
+ * into a PropertyList row, so the two surfaces never drift.
+ *
+ * Semantics: renders a real `<dl>` with `<dt>` / `<dd>` pairs (each pair
+ * wrapped in a `<div>`, which the HTML spec allows), so it's announced as a
+ * description list by assistive tech for free.
+ *
+ * Layout + density are token-driven (`--gds-property-list-*`) so a narrow
+ * inspector and a wide settings page can retune the label column and rhythm
+ * without prop-drilling. `layout="stack"` drops the label above the value
+ * for tight columns.
+ *
+ * This is a DISPLAY primitive. For an editable field (label + control), use
+ * `Field`; a detail panel that flips between read and edit typically swaps a
+ * PropertyList for a stack of Fields.
+ */
+type PropertyListLayout = "row" | "stack";
+type PropertyListDensity = "compact" | "default" | "relaxed";
+type PropertyListAlign = "start" | "center";
+interface PropertyListProps extends React.HTMLAttributes<HTMLDListElement> {
+    /** `row` (default): label column beside value. `stack`: label above value (narrow panels). */
+    layout?: PropertyListLayout;
+    /** Row rhythm. `compact` for dense inspectors, `relaxed` for airy settings pages. */
+    density?: PropertyListDensity;
+    /** Default vertical alignment of label vs value. `center` for single-line values, `start` when values wrap (tag groups, multi-line). */
+    align?: PropertyListAlign;
+    /** Hairline rule between rows. */
+    divider?: boolean;
+    /** Override the label column width (any CSS length). Sets `--gds-property-list-label-width` for all rows. */
+    labelWidth?: string;
+}
+interface PropertyListRowProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "children"> {
+    /** The property name (the `<dt>`). */
+    label: React.ReactNode;
+    /** Optional leading glyph, rendered muted at `--gds-property-list-icon-size`. */
+    icon?: React.ReactNode;
+    /** The value. Provide via `value` or as `children` — accepts any node (text, Badge, tag group, Avatar stack, link…). */
+    value?: React.ReactNode;
+    /** Per-row override of the list's vertical alignment. */
+    align?: PropertyListAlign;
+    children?: React.ReactNode;
+}
+declare const PropertyListRow: React.ForwardRefExoticComponent<PropertyListRowProps & React.RefAttributes<HTMLDivElement>>;
+declare const PropertyList: React.ForwardRefExoticComponent<PropertyListProps & React.RefAttributes<HTMLDListElement>> & {
+    Row: React.ForwardRefExoticComponent<PropertyListRowProps & React.RefAttributes<HTMLDivElement>>;
+};
+
 /**
  * Selection cards — RadioCard / CheckboxCard / SwitchCard.
  *
@@ -1928,7 +1997,7 @@ declare const DropdownMenuShortcut: {
  * rationale.
  */
 declare const inputVariants: (props?: ({
-    size?: "2xs" | "xs" | "sm" | "default" | null | undefined;
+    size?: "default" | "2xs" | "xs" | "sm" | null | undefined;
     variant?: "default" | "ghost" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 type InputSize = NonNullable<VariantProps<typeof inputVariants>["size"]>;
@@ -1949,7 +2018,7 @@ type InputProps = Omit<React.ComponentProps<"input">, "size"> & {
 declare const Input: React.ForwardRefExoticComponent<Omit<InputProps, "ref"> & React.RefAttributes<HTMLInputElement>>;
 
 declare const Label: React.ForwardRefExoticComponent<Omit<LabelPrimitive.LabelProps & React.RefAttributes<HTMLLabelElement>, "ref"> & VariantProps<(props?: ({
-    size?: "2xs" | "xs" | "sm" | "default" | null | undefined;
+    size?: "default" | "2xs" | "xs" | "sm" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string> & React.RefAttributes<HTMLLabelElement>>;
 
 declare const Popover: React.FC<PopoverPrimitive.PopoverProps>;
@@ -2052,6 +2121,230 @@ interface MultiSelectProps {
 }
 declare const MultiSelect: React.ForwardRefExoticComponent<MultiSelectProps & React.RefAttributes<HTMLButtonElement>>;
 
+/**
+ * Combobox — single-pick searchable picker. The single-select sibling of
+ * MultiSelect, and the "selectable badge" pattern popularised by Linear's
+ * status / priority pickers.
+ *
+ * Composes Popover + Command (cmdk) + Button into:
+ *
+ *   - Trigger: a button showing the selected option (its icon + label, or
+ *     a fully custom node via `renderValue`). `triggerVariant="inline"`
+ *     drops the form-control chrome so the trigger reads as an inline
+ *     token — render a Badge through `renderValue` and the value becomes a
+ *     clickable badge that opens the menu (the Linear move).
+ *   - Open: a Popover with a searchable Command list; each row carries an
+ *     optional leading icon and a check on the selected item.
+ *   - Optional `clearable` adds a "Clear" row so the value can return to
+ *     unset (null).
+ *
+ * Controlled and uncontrolled both supported (value / defaultValue mirror
+ * Radix conventions). Selection is a single `string | null` — the caller
+ * pulls the matching option object from their own `options` array.
+ *
+ * Read-only / permissions: pass `disabled` to lock the control to a
+ * display of its current value (the trigger stops opening). A
+ * permission check ("can this user edit?") drives that prop; the Combobox
+ * itself stays unaware of access rules.
+ *
+ * Data-driven via `options` rather than compound children — picker lists
+ * run dozens of items long and the per-option icon has no natural
+ * children-API equivalent. Theming inherits from Popover / Command /
+ * Button / Badge; no new `--gds-combobox-*` tokens needed yet.
+ */
+
+interface ComboboxOption {
+    /** Value stored in selection. Must be unique. */
+    value: string;
+    /** Display label for the dropdown row and the trigger. */
+    label: string;
+    /** Optional lucide-style icon (any component accepting className).
+     *  Rendered in the dropdown row and, by default, on the trigger. */
+    icon?: React.ComponentType<{
+        className?: string;
+    }>;
+    /** Extra search terms beyond the label (cmdk matches against these). */
+    keywords?: string[];
+    /** Disable the row — it can't be picked. */
+    disabled?: boolean;
+}
+type ComboboxTriggerVariant = "default" | "inline";
+interface ComboboxProps {
+    /** The full pool of selectable items. */
+    options: ComboboxOption[];
+    /** Controlled value. When provided, wire `onValueChange` or the
+     *  control becomes a read-only display of `value`. */
+    value?: string | null;
+    /** Uncontrolled initial value. Ignored if `value` is provided. */
+    defaultValue?: string | null;
+    /** Fired with the next value (or null when cleared). */
+    onValueChange?: (next: string | null) => void;
+    /** Trigger text when nothing is selected. */
+    placeholder?: string;
+    /** Search-input placeholder. Default "Search…". */
+    searchPlaceholder?: string;
+    /** Message rendered when search returns no rows. */
+    emptyMessage?: string;
+    /** Hide the search input (short lists). Default true (shown). */
+    searchable?: boolean;
+    /** Add a "Clear" row so the value can return to unset. */
+    clearable?: boolean;
+    /** `default` (form-control surface, like Select) or `inline` (chrome-free
+     *  token trigger — pair with `renderValue` to render a Badge). */
+    triggerVariant?: ComboboxTriggerVariant;
+    /** Render the selected value yourself (e.g. as a Badge). Falls back to
+     *  the option's icon + label. Receives the resolved option. */
+    renderValue?: (option: ComboboxOption) => React.ReactNode;
+    /** Hide the trailing chevron (useful for the inline token look). */
+    hideChevron?: boolean;
+    /** Lock the control to a display of its current value. */
+    disabled?: boolean;
+    /** Popover `modal` — outside clicks don't dismiss until explicit close. */
+    modalPopover?: boolean;
+    /** PopoverContent alignment. Default "start". */
+    align?: "start" | "center" | "end";
+    /** Extra classes on the trigger. */
+    className?: string;
+    /** Forwarded to the trigger for tests / Studio selection. */
+    id?: string;
+    "aria-label"?: string;
+}
+declare const Combobox: React.ForwardRefExoticComponent<ComboboxProps & React.RefAttributes<HTMLButtonElement>>;
+
+/**
+ * DataView — one dataset, drawn as a table, a list of cards, or a grid.
+ *
+ * Wraps TanStack Table so a page stops re-typing the same boilerplate
+ * (sortable-header buttons, flexRender plumbing, selection wiring, the
+ * view switch). You hand it `data` + a `columns` schema; it owns sorting,
+ * column visibility, selection, and view switching.
+ *
+ *   <DataView data={rows} columns={cols} defaultView="table" />
+ *
+ * Schema-driven cells: each column declares a `type` (badge / tags /
+ * number / currency / percent / date / boolean / url / text) and DataView
+ * renders it. `cell` overrides per column for anything bespoke (avatars,
+ * relations). `role: "title"` marks the primary field for card / grid.
+ *
+ * The view toggle can live ANYWHERE. `useDataView()` holds the state
+ * (view / activeId / sorting / columnVisibility) so a `<DataViewToggle>`
+ * or `<DataViewColumns>` placed in a page header drives a `<DataView>`
+ * lower down. Or pass `toolbar` to let DataView render them inline.
+ *
+ * Single-view is first-class: pass `views={["table"]}` (or just
+ * `defaultView` with no toolbar) and it's only ever a table / only cards /
+ * only a grid, no switch.
+ *
+ * Table extras: mark a column `pinned="left"` for a fixed column (sticky,
+ * give it a `width` so multi-pin offsets line up) and `stickyHeader` to
+ * freeze the header row on scroll.
+ *
+ * Tunable via `--gds-data-view-*` (card / grid min column width, gap).
+ */
+
+type DataViewMode = "table" | "cards" | "grid";
+type DataViewCellType = "text" | "badge" | "tags" | "number" | "currency" | "percent" | "date" | "boolean" | "url";
+interface DataViewBadgeOption {
+    value: string;
+    label?: string;
+    variant?: BadgeProps["variant"];
+}
+interface DataViewColumn<T = any> {
+    /** Accessor key into the row + the column id. */
+    key: string;
+    /** Header content. */
+    header: React.ReactNode;
+    /** Built-in renderer to use for the value. Ignored when `cell` is set. */
+    type?: DataViewCellType;
+    /** For `type="badge"`: per-value label + colour. */
+    options?: DataViewBadgeOption[];
+    /** Render the cell yourself (avatars, relations, anything bespoke). */
+    cell?: (row: T) => React.ReactNode;
+    /** Hint for card / grid composition. `title` is the primary field. */
+    role?: "title" | "meta";
+    /** Allow click-to-sort on this column. */
+    sortable?: boolean;
+    /** Pin the column to the left (a fixed column). Give it `width` so
+     *  multi-pin offsets line up. */
+    pinned?: "left";
+    /** Fixed width in px (used for pinned offsets + min sizing). */
+    width?: number;
+    /** Right-align the cell (numbers / currency). */
+    align?: "start" | "end";
+    /** Whether the user can hide it from the Columns menu. Default true. */
+    hideable?: boolean;
+    /** Start hidden. */
+    defaultHidden?: boolean;
+}
+interface UseDataViewOptions {
+    defaultView?: DataViewMode;
+    views?: DataViewMode[];
+    defaultActiveId?: string | null;
+    defaultSorting?: SortingState;
+    defaultColumnVisibility?: VisibilityState;
+}
+interface DataViewState {
+    view: DataViewMode;
+    setView: (v: DataViewMode) => void;
+    views: DataViewMode[];
+    activeId: string | null;
+    setActiveId: (id: string | null) => void;
+    sorting: SortingState;
+    setSorting: OnChangeFn<SortingState>;
+    columnVisibility: VisibilityState;
+    setColumnVisibility: OnChangeFn<VisibilityState>;
+}
+declare function useDataView(options?: UseDataViewOptions): DataViewState;
+interface DataViewToggleProps {
+    value: DataViewMode;
+    onChange: (v: DataViewMode) => void;
+    views?: DataViewMode[];
+    className?: string;
+}
+declare function DataViewToggle({ value, onChange, views, className, }: DataViewToggleProps): React.JSX.Element | null;
+interface DataViewColumnsProps {
+    columns: DataViewColumn[];
+    visibility: VisibilityState;
+    onVisibilityChange: (next: VisibilityState) => void;
+    label?: string;
+    className?: string;
+}
+declare function DataViewColumns({ columns, visibility, onVisibilityChange, label, className, }: DataViewColumnsProps): React.JSX.Element;
+interface DataViewProps<T = any> {
+    data: T[];
+    columns: DataViewColumn<T>[];
+    getRowId?: (row: T, index: number) => string;
+    view?: DataViewMode;
+    defaultView?: DataViewMode;
+    onViewChange?: (v: DataViewMode) => void;
+    views?: DataViewMode[];
+    activeId?: string | null;
+    defaultActiveId?: string | null;
+    onActiveChange?: (id: string | null) => void;
+    sorting?: SortingState;
+    defaultSorting?: SortingState;
+    onSortingChange?: OnChangeFn<SortingState>;
+    columnVisibility?: VisibilityState;
+    defaultColumnVisibility?: VisibilityState;
+    onColumnVisibilityChange?: OnChangeFn<VisibilityState>;
+    /** Freeze the header row on vertical scroll. */
+    stickyHeader?: boolean;
+    /** Render a built-in toolbar (columns menu + view toggle) above the view. */
+    toolbar?: boolean;
+    /** Override card / grid tile rendering. */
+    renderCard?: (row: T, ctx: {
+        active: boolean;
+    }) => React.ReactNode;
+    emptyMessage?: React.ReactNode;
+    className?: string;
+}
+declare function DataView<T extends Record<string, any>>(props: DataViewProps<T>): React.JSX.Element;
+declare namespace DataView {
+    var displayName: string;
+    var Toggle: typeof DataViewToggle;
+    var Columns: typeof DataViewColumns;
+}
+
 declare const RadioGroup: React.ForwardRefExoticComponent<Omit<RadioGroupPrimitive.RadioGroupProps & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
 declare const RadioGroupItem: React.ForwardRefExoticComponent<Omit<RadioGroupPrimitive.RadioGroupItemProps & React.RefAttributes<HTMLButtonElement>, "ref"> & React.RefAttributes<HTMLButtonElement>>;
 
@@ -2093,7 +2386,7 @@ declare const RadioGroupItem: React.ForwardRefExoticComponent<Omit<RadioGroupPri
  *   </ResizablePanelGroup>
  */
 declare const ResizablePanelGroup: ({ className, ...props }: React.ComponentProps<typeof ResizablePrimitive.PanelGroup>) => React.JSX.Element;
-declare const ResizablePanel: React.ForwardRefExoticComponent<Omit<React.HTMLAttributes<HTMLDivElement | HTMLElement | HTMLObjectElement | HTMLSelectElement | HTMLTextAreaElement | HTMLMapElement | HTMLTitleElement | HTMLVideoElement | HTMLButtonElement | HTMLLinkElement | HTMLLabelElement | HTMLStyleElement | HTMLSourceElement | HTMLHtmlElement | HTMLOptionElement | HTMLTableColElement | HTMLAudioElement | HTMLEmbedElement | HTMLProgressElement | HTMLHRElement | HTMLTableElement | HTMLAnchorElement | HTMLFormElement | HTMLHeadingElement | HTMLImageElement | HTMLInputElement | HTMLLIElement | HTMLOListElement | HTMLParagraphElement | HTMLSpanElement | HTMLUListElement | HTMLAreaElement | HTMLBaseElement | HTMLQuoteElement | HTMLBodyElement | HTMLBRElement | HTMLCanvasElement | HTMLDataElement | HTMLDataListElement | HTMLModElement | HTMLDetailsElement | HTMLDialogElement | HTMLDListElement | HTMLFieldSetElement | HTMLHeadElement | HTMLIFrameElement | HTMLLegendElement | HTMLMetaElement | HTMLMeterElement | HTMLOptGroupElement | HTMLOutputElement | HTMLPreElement | HTMLSlotElement | HTMLScriptElement | HTMLTemplateElement | HTMLTableSectionElement | HTMLTableCellElement | HTMLTimeElement | HTMLTableRowElement | HTMLTrackElement | HTMLTableCaptionElement | HTMLMenuElement | HTMLPictureElement>, "id" | "onResize"> & {
+declare const ResizablePanel: React.ForwardRefExoticComponent<Omit<React.HTMLAttributes<HTMLHeadElement | HTMLElement | HTMLLinkElement | HTMLDivElement | HTMLObjectElement | HTMLAnchorElement | HTMLAreaElement | HTMLAudioElement | HTMLBaseElement | HTMLQuoteElement | HTMLBodyElement | HTMLBRElement | HTMLButtonElement | HTMLCanvasElement | HTMLTableColElement | HTMLDataElement | HTMLDataListElement | HTMLModElement | HTMLDetailsElement | HTMLDialogElement | HTMLDListElement | HTMLEmbedElement | HTMLFieldSetElement | HTMLFormElement | HTMLHeadingElement | HTMLHRElement | HTMLHtmlElement | HTMLIFrameElement | HTMLImageElement | HTMLInputElement | HTMLLabelElement | HTMLLegendElement | HTMLLIElement | HTMLMapElement | HTMLMetaElement | HTMLMeterElement | HTMLOListElement | HTMLOptGroupElement | HTMLOptionElement | HTMLOutputElement | HTMLParagraphElement | HTMLPreElement | HTMLProgressElement | HTMLScriptElement | HTMLSelectElement | HTMLSlotElement | HTMLSourceElement | HTMLSpanElement | HTMLStyleElement | HTMLTableElement | HTMLTableSectionElement | HTMLTableCellElement | HTMLTemplateElement | HTMLTextAreaElement | HTMLTimeElement | HTMLTitleElement | HTMLTableRowElement | HTMLTrackElement | HTMLUListElement | HTMLVideoElement | HTMLTableCaptionElement | HTMLMenuElement | HTMLPictureElement>, "id" | "onResize"> & {
     className?: string | undefined;
     collapsedSize?: number | undefined;
     collapsible?: boolean | undefined;
@@ -2133,8 +2426,8 @@ declare const ResizableHandle: ({ withHandle, className, ...props }: React.Compo
  */
 declare const rowVariants: (props?: ({
     gap?: "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | null | undefined;
-    align?: "start" | "center" | "end" | "stretch" | "baseline" | null | undefined;
-    justify?: "between" | "start" | "center" | "end" | "around" | "evenly" | null | undefined;
+    align?: "center" | "start" | "end" | "stretch" | "baseline" | null | undefined;
+    justify?: "center" | "between" | "start" | "end" | "around" | "evenly" | null | undefined;
     wrap?: boolean | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 interface RowProps extends React.HTMLAttributes<HTMLDivElement>, VariantProps<typeof rowVariants> {
@@ -2169,7 +2462,7 @@ declare const Row: React.ForwardRefExoticComponent<RowProps & React.RefAttribute
 declare const gridVariants: (props?: ({
     cols?: "1" | "2" | "3" | "4" | "5" | "6" | "12" | null | undefined;
     gap?: "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | null | undefined;
-    align?: "start" | "center" | "end" | "stretch" | null | undefined;
+    align?: "center" | "start" | "end" | "stretch" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 interface GridProps extends React.HTMLAttributes<HTMLDivElement>, VariantProps<typeof gridVariants> {
     /** When true, render as the single child element via Radix Slot — lets
@@ -2201,10 +2494,10 @@ declare const Grid: React.ForwardRefExoticComponent<GridProps & React.RefAttribu
  * case. Flex is the escape hatch, not the default.
  */
 declare const flexVariants: (props?: ({
-    direction?: "row" | "col" | "row-reverse" | "col-reverse" | null | undefined;
+    direction?: "col" | "row" | "row-reverse" | "col-reverse" | null | undefined;
     gap?: "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | null | undefined;
-    align?: "start" | "center" | "end" | "stretch" | "baseline" | null | undefined;
-    justify?: "between" | "start" | "center" | "end" | "around" | "evenly" | null | undefined;
+    align?: "center" | "start" | "end" | "stretch" | "baseline" | null | undefined;
+    justify?: "center" | "between" | "start" | "end" | "around" | "evenly" | null | undefined;
     wrap?: "wrap" | "nowrap" | "wrap-reverse" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 interface FlexProps extends React.HTMLAttributes<HTMLDivElement>, VariantProps<typeof flexVariants> {
@@ -2238,7 +2531,7 @@ type SelectMenuSize = "default" | "sm" | "xs" | "2xs";
  * existing call site.
  */
 declare const selectTriggerVariants: (props?: ({
-    size?: "2xs" | "xs" | "sm" | "default" | null | undefined;
+    size?: "default" | "2xs" | "xs" | "sm" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 type SelectTriggerSize = NonNullable<VariantProps<typeof selectTriggerVariants>["size"]>;
 declare const SelectTrigger: React.ForwardRefExoticComponent<Omit<SelectPrimitive.SelectTriggerProps & React.RefAttributes<HTMLButtonElement>, "ref"> & {
@@ -2257,6 +2550,10 @@ declare const SelectScrollUpButton: React.ForwardRefExoticComponent<Omit<SelectP
 declare const SelectScrollDownButton: React.ForwardRefExoticComponent<Omit<SelectPrimitive.SelectScrollDownButtonProps & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
 declare const SelectContent: React.ForwardRefExoticComponent<Omit<SelectPrimitive.SelectContentProps & React.RefAttributes<HTMLDivElement>, "ref"> & {
     size?: SelectMenuSize;
+    /** Portal target. Defaults to document.body; pass a themed wrapper to
+     *  keep the menu inside a scoped theme (e.g. the Studio preview, where
+     *  the theme is applied to a div, not :root). */
+    container?: HTMLElement | null;
 } & React.RefAttributes<HTMLDivElement>>;
 declare const SelectLabel: React.ForwardRefExoticComponent<Omit<SelectPrimitive.SelectLabelProps & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
 declare const SelectItem: React.ForwardRefExoticComponent<Omit<SelectPrimitive.SelectItemProps & React.RefAttributes<HTMLDivElement>, "ref"> & {
@@ -2339,7 +2636,7 @@ declare const SheetClose: React.ForwardRefExoticComponent<DialogPrimitive.Dialog
 declare const SheetPortal: React.FC<DialogPrimitive.DialogPortalProps>;
 declare const SheetOverlay: React.ForwardRefExoticComponent<Omit<DialogPrimitive.DialogOverlayProps & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
 declare const sheetVariants: (props?: ({
-    side?: "top" | "right" | "bottom" | "left" | null | undefined;
+    side?: "bottom" | "top" | "right" | "left" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 interface SheetContentProps extends React.ComponentPropsWithoutRef<typeof DialogPrimitive.Content>, VariantProps<typeof sheetVariants> {
     /** Extra classes for the backdrop overlay. e.g. `bg-transparent`
@@ -2495,8 +2792,8 @@ declare const Sortable: SortableRootComponent;
  */
 declare const stackVariants: (props?: ({
     gap?: "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | null | undefined;
-    align?: "start" | "center" | "end" | "stretch" | null | undefined;
-    justify?: "between" | "start" | "center" | "end" | "around" | "evenly" | null | undefined;
+    align?: "center" | "start" | "end" | "stretch" | null | undefined;
+    justify?: "center" | "between" | "start" | "end" | "around" | "evenly" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 interface StackProps extends React.HTMLAttributes<HTMLDivElement>, VariantProps<typeof stackVariants> {
     /** When true, render as the single child element via Radix Slot — lets
@@ -2514,7 +2811,7 @@ declare const Stack: React.ForwardRefExoticComponent<StackProps & React.RefAttri
  * dense tool-panel sizes (the Studio inspector).
  */
 declare const switchTrackVariants: (props?: ({
-    size?: "2xs" | "xs" | "sm" | "default" | null | undefined;
+    size?: "default" | "2xs" | "xs" | "sm" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 type SwitchSize = NonNullable<VariantProps<typeof switchTrackVariants>["size"]>;
 declare const Switch: React.ForwardRefExoticComponent<Omit<Omit<SwitchPrimitives.SwitchProps & React.RefAttributes<HTMLButtonElement>, "ref">, "size"> & {
@@ -2702,7 +2999,7 @@ declare const ChartLegendContent: React.ForwardRefExoticComponent<Omit<React.Cla
  * px-3 / text-sm; `sm` and `xs` are for dense tool panels.
  */
 declare const textareaVariants: (props?: ({
-    size?: "2xs" | "xs" | "sm" | "default" | null | undefined;
+    size?: "default" | "2xs" | "xs" | "sm" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 type TextareaSize = NonNullable<VariantProps<typeof textareaVariants>["size"]>;
 type TextareaProps = Omit<React.ComponentProps<"textarea">, "size"> & {
@@ -2712,11 +3009,11 @@ declare const Textarea: React.ForwardRefExoticComponent<Omit<TextareaProps, "ref
 
 declare const toggleVariants: (props?: ({
     variant?: "default" | "outline" | "segmented" | null | undefined;
-    size?: "2xs" | "xs" | "sm" | "lg" | "default" | null | undefined;
+    size?: "default" | "2xs" | "xs" | "sm" | "lg" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 declare const Toggle: React.ForwardRefExoticComponent<Omit<TogglePrimitive.ToggleProps & React.RefAttributes<HTMLButtonElement>, "ref"> & VariantProps<(props?: ({
     variant?: "default" | "outline" | "segmented" | null | undefined;
-    size?: "2xs" | "xs" | "sm" | "lg" | "default" | null | undefined;
+    size?: "default" | "2xs" | "xs" | "sm" | "lg" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string> & React.RefAttributes<HTMLButtonElement>>;
 
 declare const TooltipProvider: React.FC<TooltipPrimitive.TooltipProviderProps>;
@@ -2726,11 +3023,11 @@ declare const TooltipContent: React.ForwardRefExoticComponent<Omit<TooltipPrimit
 
 declare const ToggleGroup: React.ForwardRefExoticComponent<((Omit<ToggleGroupPrimitive.ToggleGroupSingleProps & React.RefAttributes<HTMLDivElement>, "ref"> | Omit<ToggleGroupPrimitive.ToggleGroupMultipleProps & React.RefAttributes<HTMLDivElement>, "ref">) & VariantProps<(props?: ({
     variant?: "default" | "outline" | "segmented" | null | undefined;
-    size?: "2xs" | "xs" | "sm" | "lg" | "default" | null | undefined;
+    size?: "default" | "2xs" | "xs" | "sm" | "lg" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string>) & React.RefAttributes<HTMLDivElement>>;
 declare const ToggleGroupItem: React.ForwardRefExoticComponent<Omit<ToggleGroupPrimitive.ToggleGroupItemProps & React.RefAttributes<HTMLButtonElement>, "ref"> & VariantProps<(props?: ({
     variant?: "default" | "outline" | "segmented" | null | undefined;
-    size?: "2xs" | "xs" | "sm" | "lg" | "default" | null | undefined;
+    size?: "default" | "2xs" | "xs" | "sm" | "lg" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string> & {
     tooltip?: React.ReactNode;
     tooltipSide?: React.ComponentPropsWithoutRef<typeof TooltipContent>["side"];
@@ -2785,7 +3082,7 @@ declare const ToggleGroupItem: React.ForwardRefExoticComponent<Omit<ToggleGroupP
  * persistent footer toolbars on mobile-style layouts.
  */
 declare const toolbarVariants: (props?: ({
-    position?: "top" | "bottom" | "inline" | null | undefined;
+    position?: "bottom" | "top" | "inline" | null | undefined;
     variant?: "default" | "transparent" | "subtle" | null | undefined;
     size?: "sm" | "md" | "lg" | null | undefined;
     sticky?: boolean | null | undefined;
@@ -4929,4 +5226,4 @@ declare function GradeModeSwitcher({ className, variant }: GradeModeSwitcherProp
  */
 declare function ThemeToggle(): React.JSX.Element;
 
-export { ALL_MODES, Accordion, AccordionContent, AccordionItem, AccordionTrigger, AppShell, AppShellAside, type AppShellAsideProps, AppShellFooter, type AppShellFooterProps, AppShellHeader, type AppShellHeaderProps, AppShellMain, type AppShellMainProps, AppShellNav, type AppShellNavProps, type AppShellProps, Avatar, AvatarFallback, AvatarImage, type AvatarTone, BUILT_IN_INPUTS, BackgroundFill, type BackgroundFillFit, type BackgroundFillProps, type BackgroundFillType, Badge, Banner, type BannerProps, type BaseMediaProps, BlinkingCursor, type BlinkingCursorProps, Breadcrumb, BreadcrumbEllipsis, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, type BreadcrumbMenuItem, BreadcrumbMenuTrigger, BreadcrumbPage, BreadcrumbSeparator, Button, type ButtonShape, COMPONENT_CONTRACTS, Calendar, CalendarDayButton, Callout, CalloutDescription, CalloutTitle, Card, CardContent, CardDescription, CardFooter, CardHeader, type CardStyle, CardTitle, Carousel, CarouselArrows, type CarouselArrowsProps, type AutoplayConfig as CarouselAutoplayConfig, CarouselDots, type CarouselDotsProps, type CarouselNavButtonProps, CarouselNext, CarouselPrev, type CarouselProps, CarouselSlide, type CarouselSlideProps, CarouselVideoSlide, type CarouselVideoSlideProps, type ChartConfig, ChartContainer, ChartLegend, ChartLegendContent, type ChartPalette, ChartStyle, ChartTooltip, ChartTooltipContent, Checkbox, CheckboxCard, type CheckboxCardProps, Code, type CodeDiff, type CodeLanguage, type CodeProps, type CodeReveal, type CodeTrigger, type ColorIntensity, Composer, type ComposerAttachment, type ComposerAttachmentConfig, type ComposerContent, type ComposerFormat, type ComposerHandle, type ComposerMentionItem, type ComposerProps, ComposerReply, type ComposerStep, type ComposerTriggerConfig, DEMO_SPEED_PRESETS, DatePicker, type DatePickerProps, DateRangePicker, type DateRangePickerProps, type DemoSpeed, DemoStage, type DemoStageProps, type DemoTrigger, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, FILL_TOKENS, FRAGMENT_HEADER, Field, FieldDescription, FieldLabel, type FieldProps, FieldTrailing, FillPicker, type FillPickerProps, type FillValue, Flex, type FlexProps, type FontKey, GRADE_PRE_HYDRATION_SCRIPT, type GeneratedTheme, GradeLoader, type GradeLoaderProps, type GradeLoaderSize, GradeModeSwitcher, GradeThemeProvider, type GradeThemeProviderProps, GradeThemeSwitcher, Grid, type GridProps, Input, type InputStyle, Label, LenisProvider, Logo, type LogoLockup, type LogoMode, type LogoProps, type LogoSize, type LogoSources, type LogoVariant, MOTION_ATTR, Map, MapHandle, MapMarker, MapMarkerProps, MapProps, type MediaAspect, type MediaRadius, MediaSurface, MediaSurfaceContract, type MediaSurfaceProps, Message, type MessageProps, type ModeName, Motion, MotionOverlay, type MotionOverlayProps, type MotionOverlayZone, type MotionProps, MotionScene, type MotionSceneProps, type MotionSceneRegistration, type MotionSceneTransition, MotionScreen, type MotionScreenAnimate, type MotionScreenProps, MotionText, type MotionTextProps, type MotionTextTemplate, MultiSelect, type MultiSelectOption, type MultiSelectProps, type OKLCHTriplet, type Palette, Popover, PopoverAnchor, PopoverContent, PopoverTrigger, type PostPreset, Progress, RadioCard, type RadioCardProps, RadioGroup, RadioGroupItem, type RadiusStyle, type Ramp, ResizableHandle, ResizablePanel, ResizablePanelGroup, Reveal, type RevealAnimation, type RevealProps, type RevealStep, RivePlayer, type RivePlayerProps, Row, type RowProps, type SceneContext, type SceneFactory, type SceneHandle, ScreenAnimator, type ScreenAnimatorProps, type ScreenAnimatorShot, type ScriptedDemoContext, type ScriptedDemoState, ScrollArea, ScrollBar, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, Separator, ShaderCompileError, ShaderControls, type ShaderControlsProps, type ShaderPreset, ShaderPresetPicker, type ShaderPresetPickerProps, ShaderPresetPreview, type ShaderPresetPreviewProps, type ShadowIntensity, Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetOverlay, SheetPortal, SheetTitle, SheetTrigger, Sidebar, SidebarContent, type SidebarContentProps, SidebarFooter, type SidebarFooterProps, SidebarHeader, type SidebarHeaderProps, SidebarItem, type SidebarItemProps, type SidebarProps, SidebarSection, type SidebarSectionProps, SidebarTreeItem, type SidebarTreeItemProps, Skeleton, Slider, Sortable, SortableGroup, type SortableGroupProps, SortableHandle, type SortableHandleProps, SortableItem, type SortableItemProps, type SortableProps, type SpacingDensity, Stack, type StackProps, Swatch, SwatchGroup, type SwatchGroupProps, type SwatchProps, Switch, SwitchCard, type SwitchCardProps, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow, Tabs, TabsContent, TabsList, TabsTrigger, Textarea, type ThemeInput, ThemeToggle, ThreeScene, type ThreeSceneProps, Toggle, ToggleGroup, ToggleGroupItem, Toolbar, type ToolbarProps, ToolbarSlot, type ToolbarSlotProps, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, type TypeScalePreset, type UseScriptedDemoOptions, VideoPlayer, type VideoPlayerProps, asideVariants as appShellAsideVariants, footerVariants as appShellFooterVariants, headerVariants as appShellHeaderVariants, mainVariants as appShellMainVariants, navVariants as appShellNavVariants, applyThemeToRoot, badgeVariants, bannerVariants, buildFragmentShaderScene, builtInThemes, buttonVariants, calloutVariants, calmInput, cn, defaultPostPreset, defaultThemeId, deleteUserTheme, sleep as demoSleep, typeText as demoTypeText, duplicateTheme, energyInput, flexVariants, generateTheme, getComponentContract, getTheme, gridVariants, listContractedComponents, listThemes, listUserThemes, loadUserThemeInput, postPresets, rowVariants, saveUserTheme, sceneRegistry, setMotion, shaderPresetById, shaderPresets, shellVariants, stackVariants, swatchVariants, themeToCSSVars, toggleVariants, useCarouselApi, useGradeTheme, useMaybeGradeTheme, useMotionScene, usePageActive, usePrefersReducedMotion, useReducedMotion, useScriptedDemo };
+export { ALL_MODES, Accordion, AccordionContent, AccordionItem, AccordionTrigger, AppShell, AppShellAside, type AppShellAsideProps, AppShellFooter, type AppShellFooterProps, AppShellHeader, type AppShellHeaderProps, AppShellMain, type AppShellMainProps, AppShellNav, type AppShellNavProps, type AppShellProps, Avatar, AvatarFallback, AvatarImage, type AvatarTone, BUILT_IN_INPUTS, BackgroundFill, type BackgroundFillFit, type BackgroundFillProps, type BackgroundFillType, Badge, Banner, type BannerProps, type BaseMediaProps, BlinkingCursor, type BlinkingCursorProps, Breadcrumb, BreadcrumbEllipsis, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, type BreadcrumbMenuItem, BreadcrumbMenuTrigger, BreadcrumbPage, BreadcrumbSeparator, Button, type ButtonShape, COMPONENT_CONTRACTS, Calendar, CalendarDayButton, Callout, CalloutDescription, CalloutTitle, Card, CardContent, CardDescription, CardFooter, CardHeader, type CardStyle, CardTitle, Carousel, CarouselArrows, type CarouselArrowsProps, type AutoplayConfig as CarouselAutoplayConfig, CarouselDots, type CarouselDotsProps, type CarouselNavButtonProps, CarouselNext, CarouselPrev, type CarouselProps, CarouselSlide, type CarouselSlideProps, CarouselVideoSlide, type CarouselVideoSlideProps, type ChartConfig, ChartContainer, ChartLegend, ChartLegendContent, type ChartPalette, ChartStyle, ChartTooltip, ChartTooltipContent, Checkbox, CheckboxCard, type CheckboxCardProps, Code, type CodeDiff, type CodeLanguage, type CodeProps, type CodeReveal, type CodeTrigger, type ColorIntensity, Combobox, type ComboboxOption, type ComboboxProps, Composer, type ComposerAttachment, type ComposerAttachmentConfig, type ComposerContent, type ComposerFormat, type ComposerHandle, type ComposerMentionItem, type ComposerProps, ComposerReply, type ComposerStep, type ComposerTriggerConfig, DEMO_SPEED_PRESETS, DataView, type DataViewBadgeOption, type DataViewCellType, type DataViewColumn, DataViewColumns, type DataViewColumnsProps, type DataViewMode, type DataViewProps, type DataViewState, DataViewToggle, type DataViewToggleProps, DatePicker, type DatePickerProps, DateRangePicker, type DateRangePickerProps, type DemoSpeed, DemoStage, type DemoStageProps, type DemoTrigger, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, FILL_TOKENS, FRAGMENT_HEADER, Field, FieldDescription, FieldLabel, type FieldProps, FieldTrailing, FillPicker, type FillPickerProps, type FillValue, Flex, type FlexProps, type FontKey, GRADE_PRE_HYDRATION_SCRIPT, type GeneratedTheme, GradeLoader, type GradeLoaderProps, type GradeLoaderSize, GradeModeSwitcher, GradeThemeProvider, type GradeThemeProviderProps, GradeThemeSwitcher, Grid, type GridProps, Input, type InputStyle, Label, LenisProvider, Logo, type LogoLockup, type LogoMode, type LogoProps, type LogoSize, type LogoSources, type LogoVariant, MOTION_ATTR, Map, MapHandle, MapMarker, MapMarkerProps, MapProps, type MediaAspect, type MediaRadius, MediaSurface, MediaSurfaceContract, type MediaSurfaceProps, Message, type MessageProps, type ModeName, Motion, MotionOverlay, type MotionOverlayProps, type MotionOverlayZone, type MotionProps, MotionScene, type MotionSceneProps, type MotionSceneRegistration, type MotionSceneTransition, MotionScreen, type MotionScreenAnimate, type MotionScreenProps, MotionText, type MotionTextProps, type MotionTextTemplate, MultiSelect, type MultiSelectOption, type MultiSelectProps, type OKLCHTriplet, type Palette, Popover, PopoverAnchor, PopoverContent, PopoverTrigger, type PostPreset, Progress, PropertyList, type PropertyListProps, PropertyListRow, type PropertyListRowProps, RadioCard, type RadioCardProps, RadioGroup, RadioGroupItem, type RadiusStyle, type Ramp, ResizableHandle, ResizablePanel, ResizablePanelGroup, Reveal, type RevealAnimation, type RevealProps, type RevealStep, RivePlayer, type RivePlayerProps, Row, type RowProps, type SceneContext, type SceneFactory, type SceneHandle, ScreenAnimator, type ScreenAnimatorProps, type ScreenAnimatorShot, type ScriptedDemoContext, type ScriptedDemoState, ScrollArea, ScrollBar, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, Separator, ShaderCompileError, ShaderControls, type ShaderControlsProps, type ShaderPreset, ShaderPresetPicker, type ShaderPresetPickerProps, ShaderPresetPreview, type ShaderPresetPreviewProps, type ShadowIntensity, Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetOverlay, SheetPortal, SheetTitle, SheetTrigger, Sidebar, SidebarContent, type SidebarContentProps, SidebarFooter, type SidebarFooterProps, SidebarHeader, type SidebarHeaderProps, SidebarItem, type SidebarItemProps, type SidebarProps, SidebarSection, type SidebarSectionProps, SidebarTreeItem, type SidebarTreeItemProps, Skeleton, Slider, Sortable, SortableGroup, type SortableGroupProps, SortableHandle, type SortableHandleProps, SortableItem, type SortableItemProps, type SortableProps, type SpacingDensity, Stack, type StackProps, Swatch, SwatchGroup, type SwatchGroupProps, type SwatchProps, Switch, SwitchCard, type SwitchCardProps, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow, Tabs, TabsContent, TabsList, TabsTrigger, Textarea, type ThemeInput, ThemeToggle, ThreeScene, type ThreeSceneProps, Toggle, ToggleGroup, ToggleGroupItem, Toolbar, type ToolbarProps, ToolbarSlot, type ToolbarSlotProps, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, type TypeScalePreset, type UseDataViewOptions, type UseScriptedDemoOptions, VideoPlayer, type VideoPlayerProps, asideVariants as appShellAsideVariants, footerVariants as appShellFooterVariants, headerVariants as appShellHeaderVariants, mainVariants as appShellMainVariants, navVariants as appShellNavVariants, applyThemeToRoot, badgeVariants, bannerVariants, buildFragmentShaderScene, builtInThemes, buttonVariants, calloutVariants, calmInput, cn, defaultPostPreset, defaultThemeId, deleteUserTheme, sleep as demoSleep, typeText as demoTypeText, duplicateTheme, energyInput, flexVariants, generateTheme, getComponentContract, getTheme, gridVariants, listContractedComponents, listThemes, listUserThemes, loadUserThemeInput, postPresets, rowVariants, saveUserTheme, sceneRegistry, setMotion, shaderPresetById, shaderPresets, shellVariants, stackVariants, swatchVariants, themeToCSSVars, toggleVariants, useCarouselApi, useDataView, useGradeTheme, useMaybeGradeTheme, useMotionScene, usePageActive, usePrefersReducedMotion, useReducedMotion, useScriptedDemo };