gridsmith-ui 0.6.6 → 0.7.0

package/dist/index.d.ts

@@ -1,12 +1,12 @@
 import * as react from 'react';
-import { ButtonHTMLAttributes, ReactNode, InputHTMLAttributes, LabelHTMLAttributes, TextareaHTMLAttributes, Ref, ReactElement, HTMLAttributes, AnchorHTMLAttributes, ComponentType } from 'react';
+import { ButtonHTMLAttributes, ReactNode, InputHTMLAttributes, LabelHTMLAttributes, TextareaHTMLAttributes, Ref, CSSProperties, ReactElement, HTMLAttributes, AnchorHTMLAttributes, ComponentType } from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { IconName } from './icons.js';
 import { B as BreakpointKey } from './use-breakpoint-BfKzmkxx.js';
 export { a as BreakpointWidthProvider, u as useBreakpoint } from './use-breakpoint-BfKzmkxx.js';
 
 type ButtonVariant = "default" | "secondary" | "tertiary" | "outline" | "ghost" | "destructive" | "success" | "warning" | "link";
-type ButtonSize = "sm" | "md" | "lg" | "icon-sm" | "icon" | "icon-lg";
+type ButtonSize = "xs" | "sm" | "md" | "lg" | "icon-xs" | "icon-sm" | "icon" | "icon-lg";
 declare const ButtonSizeContext: react.Context<ButtonSize | null>;
 interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
     variant?: ButtonVariant;
@@ -65,18 +65,21 @@ declare function Input({ className, size, error, prefix, suffix, ...props }: Omi
 interface TextareaProps extends TextareaHTMLAttributes<HTMLTextAreaElement> {
     autoResize?: boolean;
     maxRows?: number;
+    error?: boolean;
     ref?: Ref<HTMLTextAreaElement>;
 }
-declare function Textarea({ className, autoResize, maxRows, ref, ...props }: TextareaProps): react_jsx_runtime.JSX.Element;
+declare function Textarea({ className, autoResize, maxRows, error, ref, ...props }: TextareaProps): react_jsx_runtime.JSX.Element;
 declare function Label({ className, children, ...props }: LabelHTMLAttributes<HTMLLabelElement>): react_jsx_runtime.JSX.Element;
 type ToggleLayout = "full" | "compact";
-declare function Toggle({ checked, onChange, label, disabled, error, layout, "aria-labelledby": ariaLabelledBy, ...rest }: {
+type ToggleSize = "sm" | "md";
+declare function Toggle({ checked, onChange, label, disabled, error, layout, size, "aria-labelledby": ariaLabelledBy, ...rest }: {
     checked: boolean;
     onChange: (v: boolean) => void;
     label?: string;
     disabled?: boolean;
     error?: boolean;
     layout?: ToggleLayout;
+    size?: ToggleSize;
     "aria-labelledby"?: string;
 } & Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "onChange">): react_jsx_runtime.JSX.Element;
 
@@ -102,8 +105,10 @@ interface DropdownProps {
     error?: boolean;
     /** When multiple, show removable chips below the trigger. Defaults to true. Set false in toolbar contexts where chips are shown elsewhere. */
     showChips?: boolean;
+    /** Accessible name for the trigger, for when there is no visible `label` (e.g. in a toolbar). */
+    "aria-label"?: string;
 }
-declare function Dropdown({ options, value, onChange, label, disabled, placeholder, multiple, searchable, size, className, ref, container, error, showChips, }: DropdownProps): react_jsx_runtime.JSX.Element;
+declare function Dropdown({ options, value, onChange, label, disabled, placeholder, multiple, searchable, size, className, ref, container, error, showChips, "aria-label": ariaLabel, }: DropdownProps): react_jsx_runtime.JSX.Element;
 
 interface ComboboxOption {
     value: string;
@@ -124,16 +129,18 @@ interface ComboboxProps {
 }
 declare function Combobox({ value, onChange, options, placeholder, disabled, loading, className, ref, container, error }: ComboboxProps): react_jsx_runtime.JSX.Element;
 
+type CheckboxSize = "sm" | "md";
 interface CheckboxProps {
     checked: boolean;
     onChange: (checked: boolean) => void;
     label?: string;
+    size?: CheckboxSize;
     disabled?: boolean;
     indeterminate?: boolean;
     className?: string;
     ref?: Ref<HTMLInputElement>;
 }
-declare function Checkbox({ checked, onChange, label, disabled, indeterminate, className, ref }: CheckboxProps): react_jsx_runtime.JSX.Element;
+declare function Checkbox({ checked, onChange, label, size, disabled, indeterminate, className, ref }: CheckboxProps): react_jsx_runtime.JSX.Element;
 interface CheckboxGroupProps {
     value: string[];
     onChange: (value: string[]) => void;
@@ -257,8 +264,13 @@ interface SliderRangeProps {
     className?: string;
     ref?: Ref<HTMLDivElement>;
     error?: boolean;
+    /**
+     * Paint the track yourself (e.g. a hue spectrum for a colour slider). The
+     * accent fill is hidden so the custom track stays fully visible.
+     */
+    trackStyle?: CSSProperties;
 }
-declare function SliderRange({ value, onChange, min, max, step, disabled, showValue, className, ref, error, label }: SliderRangeProps): react_jsx_runtime.JSX.Element;
+declare function SliderRange({ value, onChange, min, max, step, disabled, showValue, className, ref, error, label, trackStyle }: SliderRangeProps): react_jsx_runtime.JSX.Element;
 
 interface TimePickerProps {
     value: string;
@@ -699,14 +711,97 @@ interface AvatarGroupProps {
 declare function AvatarGroup({ items, max, size, ring, onOverflowClick, className }: AvatarGroupProps): react_jsx_runtime.JSX.Element;
 
 interface EmptyStateProps {
-    icon?: ReactNode;
+    /**
+     * An icon name from the theme's pack ("inbox", "filter") or an element. A
+     * name is the easy path: the state renders it at the frame's size. An `Icon`
+     * element is resized to match; any other element is rendered as given. A
+     * string that is not an icon name is a type error, not a printed word.
+     * (The Sprint 22 bench saw builders pass names into a ReactNode prop and
+     * React print the word — 14 Sep 2026.)
+     */
+    icon?: IconName | Exclude<ReactNode, string>;
+    /** How the icon is framed: the neutral circle (default), or none when the icon element brings its own frame. */
+    iconFrame?: "circle" | "none";
     title: string;
     description?: string;
     action?: ReactNode;
     variant?: "empty" | "filtered" | "error" | "no-permission";
+    /**
+     * Draw a subtle solid border around the state. Off by default: the icon,
+     * centred title and padding already read as "nothing here", and a dashed
+     * frame (the old default) is what FileUpload uses to mean "drop here".
+     */
+    bordered?: boolean;
+    className?: string;
+}
+declare function EmptyState({ icon, iconFrame, title, description, action, variant, bordered, className }: EmptyStateProps): react_jsx_runtime.JSX.Element;
+
+interface SkipLinkProps {
+    /** The id of the main region (AppShell names its <main> "main"). */
+    href?: string;
+    children?: string;
+    className?: string;
+}
+/**
+ * The first focusable element on a page with repeated navigation: invisible
+ * until it receives keyboard focus, then a small floating button that jumps
+ * past the sidebar and navbar to the main content (WCAG 2.4.1). AppShell
+ * renders one by default; a page outside AppShell composes it first.
+ */
+declare function SkipLink({ href, children, className }: SkipLinkProps): react_jsx_runtime.JSX.Element;
+
+interface TableToolbarFilterOption {
+    value: string;
+    label: string;
+}
+interface TableToolbarActiveFilter {
+    id: string;
+    label: string;
+    onRemove: () => void;
+}
+interface TableToolbarProps {
+    /** The search box. `label` is its accessible name and the default placeholder. */
+    search?: {
+        value: string;
+        onChange: (value: string) => void;
+        label: string;
+        placeholder?: string;
+    };
+    /** The one filter worth showing inline: a SegmentedControl, or a Dropdown when the toolbar is narrow. */
+    primaryFilter?: {
+        label: string;
+        options: TableToolbarFilterOption[];
+        value: string;
+        onChange: (value: string) => void;
+    };
+    /** Further filters, one click away behind the Filters button. */
+    filters?: ReactNode;
+    filtersOpen?: boolean;
+    onFiltersOpenChange?: (open: boolean) => void;
+    /** Shown on the Filters button while the row is collapsed. */
+    activeFilterCount?: number;
+    /** Chips for the filters in force, each removable. */
+    activeFilters?: TableToolbarActiveFilter[];
+    onClearAll?: () => void;
+    /** How many rows match; shown with `resultNoun`. */
+    resultCount?: number;
+    resultNoun?: [singular: string, plural: string];
+    /** Utility actions on the right — an overflow DropdownMenu, an export button. Primary actions belong in the PageHeader. */
+    actions?: ReactNode;
+    size?: "sm" | "md";
+    /** Container width below which the primary filter becomes a Dropdown. */
+    compactBreakpoint?: number;
     className?: string;
 }
-declare function EmptyState({ icon, title, description, action, variant, className }: EmptyStateProps): react_jsx_runtime.JSX.Element;
+/**
+ * The toolbar above a table or list: search, one inline filter, further
+ * filters behind a Filters button, the result count with removable chips for
+ * the filters in force, and utility actions on the right. The corpus's
+ * progressive-disclosure toolbar (search#1, search#3, search#12) as one
+ * component, so a page never hand-rolls the row. Primary actions belong in
+ * the PageHeader, not here.
+ */
+declare function TableToolbar({ search, primaryFilter, filters, filtersOpen, onFiltersOpenChange, activeFilterCount, activeFilters, onClearAll, resultCount, resultNoun, actions, size, compactBreakpoint, className, }: TableToolbarProps): react_jsx_runtime.JSX.Element;
 
 interface TimelineItem {
     title: string;
@@ -805,38 +900,221 @@ interface CarouselProps {
 }
 declare function Carousel({ children, autoPlay, autoPlayInterval, loop, showIndicators, showArrows, className, ref, }: CarouselProps): react_jsx_runtime.JSX.Element;
 
+interface ChatMessageSender {
+    name: string;
+    avatar?: string;
+    /** Glyph for a sender with no photo — an assistant or system sender. */
+    icon?: IconName;
+}
+/** bubble: a speech bubble (people talking). block: full width, no bubble — assistant replies that carry Cards, charts, code and links. */
+type ChatMessageLayout = "bubble" | "block";
+/** streaming: still arriving (caret, aria-busy, Stop in the composer). error: delivery failed. */
+type ChatMessageStatus = "sent" | "streaming" | "error";
+type ChatMessageAction = "copy" | "regenerate" | "thumbs-up" | "thumbs-down" | "retry" | {
+    id: string;
+    label: string;
+    icon: IconName;
+};
+interface ChatMessageSource {
+    label: string;
+    href: string;
+}
 interface ChatMessage {
     id: string;
-    sender: {
-        name: string;
-        avatar?: string;
-    };
+    sender: ChatMessageSender;
     content: string | ReactNode;
     timestamp: Date;
     isOwn?: boolean;
+    /** Overrides the list's defaultLayout for this message. */
+    layout?: ChatMessageLayout;
+    status?: ChatMessageStatus;
+    /** Citation row rendered under the content. */
+    sources?: ChatMessageSource[];
+    /** Controls under the content — revealed on hover or keyboard focus, always in the DOM. */
+    actions?: ChatMessageAction[];
 }
 interface ChatMessageListProps {
     messages: ChatMessage[];
     typingUser?: string;
     showInput?: boolean;
     onSend?: (text: string) => void;
+    /** A built-in action id ("copy", "regenerate", …) or a custom action's id. */
+    onAction?: (messageId: string, action: string) => void;
+    /** While a reply is arriving: send is disabled and a Stop control appears (calls onStop). */
+    busy?: boolean;
+    onStop?: () => void;
+    /** The attachment and voice controls render only when a handler is given. */
+    onAttach?: () => void;
+    onVoice?: () => void;
+    placeholder?: string;
+    /** Starter prompts; clicking one sends it. Part of the empty state, and optionally shown after every reply. */
+    suggestions?: string[];
+    /** Default "empty-only". */
+    suggestionsMode?: "empty-only" | "always";
+    /** Replaces the default empty state (an EmptyState with the suggestions). */
+    emptyState?: ReactNode;
+    /** Layout for messages that do not set their own. Default "bubble". */
+    defaultLayout?: ChatMessageLayout;
+    /** Hook for markdown or custom rendering of a message's content. */
+    renderContent?: (message: ChatMessage) => ReactNode;
+    /** Keep the newest message in view while the reader is at the bottom; otherwise offer "Jump to latest". Default true. */
+    autoScroll?: boolean;
     className?: string;
 }
-declare function ChatMessageList({ messages, typingUser, showInput, onSend, className, }: ChatMessageListProps): react_jsx_runtime.JSX.Element;
+declare function ChatMessageList({ messages, typingUser, showInput, onSend, onAction, busy, onStop, onAttach, onVoice, placeholder, suggestions, suggestionsMode, emptyState, defaultLayout, renderContent, autoScroll, className, }: ChatMessageListProps): react_jsx_runtime.JSX.Element;
+
+type ChatPanelStatusTone = "success" | "warning" | "error" | "neutral";
+interface ChatPanelProps {
+    /** Heading text, rendered as an h2 whose id is `${id}-title` — pass that id to the surface's labelledBy. */
+    title: string;
+    /** Short line under the title: the model, the team, "Support". */
+    description?: string;
+    /** Presence or health beside the title, rendered with StatusDot. */
+    status?: {
+        label: string;
+        tone?: ChatPanelStatusTone;
+    };
+    /** Leading visual: a curated icon name or an element such as an Avatar. Default "sparkles". */
+    icon?: IconName | ReactNode;
+    /** Extra header controls, rendered before the built-in ones. */
+    actions?: ReactNode;
+    onClose: () => void;
+    /** Shows a "New conversation" control when given. */
+    onNewConversation?: () => void;
+    /** Shows an expand / collapse control when given (CornerPanel and full-page layouts use it). */
+    onExpandedChange?: (expanded: boolean) => void;
+    expanded?: boolean;
+    /** The conversation — usually ChatMessageList. Laid out as a column that fills the panel. */
+    children: ReactNode;
+    /** Small muted footer, e.g. an AI disclaimer. */
+    footer?: ReactNode;
+    id?: string;
+    className?: string;
+}
+/**
+ * The chrome around a conversation: header (icon, title, status, description,
+ * controls), a body that fills the remaining height, and an optional footer.
+ * Surface-agnostic — it never positions itself. Put it inside a non-modal
+ * Drawer, a CornerPanel, or a page column, and give ChatMessageList as children.
+ */
+declare function ChatPanel({ title, description, status, icon, actions, onClose, onNewConversation, onExpandedChange, expanded, children, footer, id, className, }: ChatPanelProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Where the window anchors. bottom-right / bottom-left: above a bubble or pill Launcher
+ * (anchorInset keeps the launcher clear). top-right / top-left: hanging under the top bar,
+ * for an assistant opened from a Navbar button — pass offset.y as the bar's height plus a gap.
+ * right / left: beside a ribbon Launcher on that edge, inset by the ribbon's width; `align`
+ * places it near the end of the edge or mid-edge, like the ribbon.
+ */
+type CornerPanelEdge = "bottom-right" | "bottom-left" | "top-right" | "top-left" | "right" | "left";
+interface CornerPanelProps {
+    open: boolean;
+    onClose: () => void;
+    /** Where to anchor — match the Launcher's edge (see CornerPanelEdge). Default "bottom-right". */
+    edge?: CornerPanelEdge;
+    /** Side edges (right / left) only: near the end of the edge (default) or mid-edge — match the ribbon's align. */
+    align?: "end" | "center";
+    /** Default "380px". */
+    width?: string;
+    /** Default "600px"; never taller than the viewport minus the offsets. */
+    height?: string;
+    /** Distance from the viewport edges — match the Launcher's offset. Default var(--ds-space-4) on both axes. */
+    offset?: {
+        x?: string;
+        y?: string;
+    };
+    /** Space reserved below the window for the launcher: its height plus a gap. Default the lg launcher (48px) + one step; pass "0px" when no launcher sits in the corner. */
+    anchorInset?: string;
+    /** Fills the viewport, inset by offset. Controlled — ChatPanel's expand control drives it. */
+    expanded?: boolean;
+    onExpandedChange?: (expanded: boolean) => void;
+    /** id applied to the dialog element, for the Launcher's aria-controls. */
+    id?: string;
+    /** id of the element that names the dialog — ChatPanel's heading. */
+    labelledBy: string;
+    /** Keep the window mounted while closed (hidden, out of the tab order) so drafts and scroll survive. Default true — this surface exists for persistent assistants. */
+    keepMounted?: boolean;
+    /** Render inside this element (absolute) instead of document.body (fixed) — preview frames. */
+    container?: Element | DocumentFragment;
+    children: ReactNode;
+    className?: string;
+}
+/**
+ * A compact non-modal window anchored above a bubble or pill Launcher — the
+ * Intercom shape. Same contract as Drawer with modal={false}: the page stays
+ * operable, nothing traps focus, Escape closes only while focus is inside,
+ * focus returns to the opener, an outside click does nothing. Toasts move above
+ * it while it is open. At phone width it is the modal Sheet.
+ */
+declare function CornerPanel({ open, onClose, edge, align, width, height, offset, anchorInset, expanded, id, labelledBy, keepMounted, container, children, className, }: CornerPanelProps): react_jsx_runtime.JSX.Element;
+
+type AsidePanelSide = "right" | "left";
+type AsidePanelPosition = "flush" | "floating";
+interface AsidePanelProps {
+    open: boolean;
+    onClose: () => void;
+    /** Which side of the content column. Default "right". Pass the same value as AppShell's asideSide. */
+    side?: AsidePanelSide;
+    /** Column width while open. Default "420px" — the same as the side panel. */
+    width?: string;
+    /**
+     * flush (default, edge-to-edge with one border) or floating (inset by the shell gutter, rounded, glass —
+     * the same card as a floating Sidebar). Give it the Sidebar's position: the column is the sidebar's mirror.
+     */
+    position?: AsidePanelPosition;
+    /** Whether the navbar above is floating — its bottom gutter is then the gap, so the floating column drops its top inset (as Sidebar does). */
+    navbarFloating?: boolean;
+    /** Whether the sidebar is floating — a left-docked floating column then drops its outer gutter, because the sidebar's own gutter is the gap (as PageHeader does). */
+    sidebarFloating?: boolean;
+    /** Below this breakpoint the page is too narrow to share: the panel renders as a non-modal Drawer instead (and as the modal Sheet at or below sm, as Drawer does). Default "lg". */
+    collapseBelow?: BreakpointKey;
+    /** Keep the content mounted while closed (hidden) so drafts and scroll survive. Default true — the column exists for persistent assistants. */
+    keepMounted?: boolean;
+    /** Let the user drag the page-side edge to widen the column, between width and maxWidth. Default true. */
+    resizable?: boolean;
+    /** Upper bound for resizing. Default 60% of the viewport (or of the container). */
+    maxWidth?: string;
+    /** Accessible name of the landmark — ChatPanel's heading id. */
+    labelledBy: string;
+    id?: string;
+    children: ReactNode;
+    className?: string;
+}
+/**
+ * A docked column beside the page content: the page narrows to make room
+ * instead of being covered (the Copilot / Sidekick layout). In-flow, so it is
+ * a landmark (`role="complementary"`), not a dialog. Same non-modal contract as
+ * Drawer modal={false}: no focus trap, Escape closes only from inside, focus
+ * returns to the opener, an outside click does nothing, drafts survive closing.
+ * Below `collapseBelow` it becomes the overlay Drawer; on phones the Sheet.
+ */
+declare function AsidePanel({ open, onClose, side, width, position, navbarFloating: navbarFloatingProp, sidebarFloating: sidebarFloatingProp, collapseBelow, keepMounted, resizable, maxWidth, labelledBy, id, children, className, }: AsidePanelProps): react_jsx_runtime.JSX.Element;
 
 interface StackedListItem {
     id: string | number;
     leading?: ReactNode;
     title: string;
     subtitle?: string;
+    /** Third line under the subtitle (a message preview, a summary). Rows with one align their leading element to the top. */
+    description?: string;
     meta?: ReactNode;
     actions?: ReactNode;
+    /**
+     * Read/unread emphasis for inbox-style lists: unread rows take a bold title
+     * and an accent dot before the meta; read rows drop the title to secondary
+     * text. Leave undefined for lists without that distinction.
+     */
+    unread?: boolean;
+    /** Marks this row as the current one (aria-current). `selectedId` on the list is the usual way to set it. */
+    selected?: boolean;
     onClick?: () => void;
 }
 interface StackedListProps {
     items: StackedListItem[];
     divided?: boolean;
     flush?: boolean;
+    /** The current row in a master-detail list. Its treatment follows the theme's in-page vertical active style (rail, tint or pill), like Tabs. */
+    selectedId?: string | number;
     className?: string;
 }
 declare const StackedList: react.ForwardRefExoticComponent<StackedListProps & react.RefAttributes<HTMLUListElement>>;
@@ -873,6 +1151,47 @@ interface LinkProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
  */
 declare const Link: react.ForwardRefExoticComponent<LinkProps & react.RefAttributes<HTMLAnchorElement>>;
 
+type LauncherVariant = "bubble" | "pill" | "ribbon";
+type LauncherEdge = "bottom-right" | "bottom-left" | "right" | "left" | "bottom";
+type LauncherWhenOpen = "close" | "hide" | "keep";
+type LauncherTone = "neutral" | "neutral-accent" | "subtle" | "accent";
+type LauncherSize = "md" | "lg";
+interface LauncherProps {
+    /** Visual form. bubble: a square the height of a Button, icon only. pill: icon + label at Button proportions. ribbon: flush to an edge — sideways label on a side edge, horizontal on the bottom edge. Default "bubble". */
+    variant?: LauncherVariant;
+    /** Height, matching Button's md (40px) and lg (48px) steps; the bubble is that size square. Default "lg". Ribbons are unaffected. */
+    size?: LauncherSize;
+    /** Colour weight. neutral (default): surface background, border, primary text — present without competing with the page's primary action. neutral-accent: the same surface with only the icon in the accent (gradient included). subtle: accent tint. accent: the primary fill (gradient included), for products that want the assistant prominent. */
+    tone?: LauncherTone;
+    /** bubble and pill accept the two bottom corners; ribbon accepts right, left and bottom. Default "bottom-right" (or "right" for ribbon). */
+    edge?: LauncherEdge;
+    /** ribbon only: where along the edge. "end" (default) sits near the bottom of a side edge or near the right of the bottom edge; "center" is mid-edge. */
+    align?: "center" | "end";
+    /** Accessible name for every variant; visible text for pill and ribbon. */
+    label: string;
+    /** bubble and pill default to "sparkles" (curated; the Feather pack substitutes a star). A ribbon shows only its label unless an icon is given. */
+    icon?: IconName | ReactNode;
+    /** Unread count (number) or a dot (true). */
+    badge?: number | boolean;
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    /** id of the panel this launcher controls — emitted as aria-controls while open (the panel may not be in the DOM while closed). */
+    panelId?: string;
+    /** While the panel is open: close morphs the launcher into a close button (default); hide keeps it mounted but invisible and out of the tab order; keep leaves it unchanged. */
+    whenOpen?: LauncherWhenOpen;
+    /** Distance from the edges. Default var(--ds-space-4) on both axes; safe-area insets are added on top. */
+    offset?: {
+        x?: string;
+        y?: string;
+    };
+    /** Keyboard shortcut such as "mod+." (mod is ⌘ on macOS, Ctrl elsewhere; avoid keys the browser owns, like Ctrl+J). Toggles when closed; with the panel open it moves focus into the panel, or closes when focus is already inside. Shown in the bubble's tooltip. */
+    shortcut?: string;
+    /** Render inside this element (absolute) instead of document.body (fixed) — preview frames and the BuilderShell. */
+    container?: Element | DocumentFragment;
+    className?: string;
+}
+declare function Launcher({ variant, size, tone, edge, align, label, icon, badge, open, onOpenChange, panelId, whenOpen, offset, shortcut, container, className, }: LauncherProps): react.ReactPortal | null;
+
 type TabsOverflow = "scroll" | "hidden" | "truncate";
 interface Tab {
     id: string;
@@ -993,6 +1312,10 @@ interface SidebarContextValue {
     onCollapsedChange: (collapsed: boolean) => void;
     portalContainer: Element | null;
     type: SidebarType;
+    /** flush or floating — with a floating navbar, a minimal flush sidebar drops its top inset; floating keeps it inside the card. */
+    position: SidebarPosition;
+    /** Whether the adjacent navbar is floating (the floating navbar carries its own inset below it). */
+    navbarFloating: boolean;
     navSize?: "sm" | "md";
 }
 declare function useSidebar(): SidebarContextValue | null;
@@ -1001,7 +1324,13 @@ interface SidebarProps {
     header?: ReactNode;
     footer?: ReactNode;
     children: ReactNode;
+    /** Controlled collapse state. */
     collapsed?: boolean;
+    /**
+     * Initial collapse state for a locally-owned Sidebar. Passing this opts out of
+     * the AppShell's responsive collapse (auto-rail between md and lg) in favour of
+     * plain local state.
+     */
     defaultCollapsed?: boolean;
     onCollapsedChange?: (collapsed: boolean) => void;
     variant?: SidebarVariant;
@@ -1061,15 +1390,26 @@ interface SegmentedControlOption {
     label: string;
     disabled?: boolean;
 }
+type SegmentedControlSize = "xs" | "sm" | "md" | "lg";
 interface SegmentedControlProps {
     value: string;
     onChange: (value: string) => void;
     options: SegmentedControlOption[];
-    size?: "sm" | "md" | "lg";
+    /** xs is for dense tool chrome (toolbars, inspectors): 24px tall. */
+    size?: SegmentedControlSize;
     variant?: "default" | "ghost";
+    /** Stretch to the container and share the width equally between options. */
+    fullWidth?: boolean;
+    /**
+     * Called with an option's value while the pointer is over it and with null
+     * when it leaves, so a picker can preview a choice before committing it.
+     */
+    onHoverChange?: (value: string | null) => void;
     className?: string;
+    /** Accessible name for the radiogroup, for when there is no visible label (e.g. in a toolbar). */
+    "aria-label"?: string;
 }
-declare function SegmentedControl({ value, onChange, options, size, variant, className, }: SegmentedControlProps): react_jsx_runtime.JSX.Element;
+declare function SegmentedControl({ value, onChange, options, size, variant, fullWidth, onHoverChange, className, "aria-label": ariaLabel, }: SegmentedControlProps): react_jsx_runtime.JSX.Element;
 
 interface BottomNavItem {
     label: string;
@@ -1257,7 +1597,15 @@ interface DialogProps {
     size?: DialogSize;
     alert?: boolean;
     container?: Element | DocumentFragment;
-    /** Called when Enter is pressed in the dialog (e.g. form submit). Primary footer button should use type="submit". */
+    /**
+     * Primary action for Enter. Dialog owns the form's default button, so Enter in
+     * any single-line field runs this regardless of how the footer is typed, and a
+     * footer button without an explicit `type` never submits when clicked. Ignored
+     * for `variant="destructive"`: Enter in a field must not perform a destructive
+     * action (Apple HIG: Cancel is the default; APG: focus the least destructive
+     * action). If the footer has a `type="submit"` button and it is disabled, Enter
+     * does nothing, mirroring native implicit submission.
+     */
     onSubmit?: () => void;
 }
 declare function Dialog({ open, onClose, title, description, children, footer, variant, size, alert, container, onSubmit }: DialogProps): react.ReactPortal | null;
@@ -1286,18 +1634,47 @@ interface DrawerProps {
     mobile?: "sheet" | "panel";
     /** Snap points for the phone-width Sheet, as fractions of the viewport. Default [0.5, 0.92]. */
     snapPoints?: number[];
+    /**
+     * Default true. false makes the drawer a persistent, non-modal panel the user works alongside
+     * (an assistant, help): no backdrop, no scroll lock, no focus trap — the page stays operable.
+     * It closes only on Escape while focus is inside it, its close control, or onClose from the
+     * consumer; an outside click does nothing. At phone width the Sheet is always modal.
+     */
+    modal?: boolean;
+    /**
+     * Keep the panel in the DOM while closed (hidden and out of the tab order) so a half-typed
+     * message, the scroll position and any in-progress rendering survive close and reopen.
+     * Default false — the panel unmounts after its close transition, as it always has.
+     */
+    keepMounted?: boolean;
+    /** id applied to the dialog element, for an opener's aria-controls. */
+    id?: string;
+    /** id of the element that names the dialog when no title is rendered — e.g. ChatPanel's heading. */
+    labelledBy?: string;
+    /**
+     * Let the user drag the page-side edge to widen a non-modal side drawer,
+     * between `width` and maxWidth (default 60% of the viewport). Default false —
+     * ordinary drawers keep the one shared width. Ignored when modal or at phone width.
+     */
+    resizable?: boolean;
+    maxWidth?: string;
 }
 declare function Drawer(props: DrawerProps): react_jsx_runtime.JSX.Element;
 
-interface TooltipProps {
+interface TooltipProps extends Omit<HTMLAttributes<HTMLElement>, "content"> {
     content: ReactNode;
     children: ReactNode;
     side?: Side;
     delay?: number;
     className?: string;
     container?: Element | DocumentFragment;
+    /**
+     * A Tooltip can itself be the child of a Slot — `<DropdownMenu trigger={<Tooltip …><Button/></Tooltip>}>` —
+     * so the ref and handlers a parent merges onto it are passed through to its own trigger (14 Sep 2026).
+     */
+    ref?: Ref<HTMLElement>;
 }
-declare function Tooltip({ content, children, side, delay, className, container }: TooltipProps): react_jsx_runtime.JSX.Element;
+declare function Tooltip({ content, children, side, delay, className, container, ref: forwardedRef, ...slotProps }: TooltipProps): react_jsx_runtime.JSX.Element;
 
 interface PopoverProps {
     open: boolean;
@@ -1375,8 +1752,14 @@ interface SheetProps {
     container?: Element | DocumentFragment;
     /** Remove default content padding — use when the child handles its own spacing. */
     flush?: boolean;
+    /** Keep the sheet in the DOM while closed (hidden, out of the tab order) so its content's state survives close and reopen. Default false. */
+    keepMounted?: boolean;
+    /** id applied to the dialog element, for an opener's aria-controls. */
+    id?: string;
+    /** id of the element that names the dialog when no title is rendered. */
+    labelledBy?: string;
 }
-declare function Sheet({ open, onClose, title, children, footer, snapPoints, container, flush }: SheetProps): react.ReactPortal | null;
+declare function Sheet({ open, onClose, title, children, footer, snapPoints, container, flush, keepMounted, id, labelledBy }: SheetProps): react.ReactPortal | null;
 
 interface Notification {
     id: string;
@@ -1560,6 +1943,46 @@ interface ScrollAreaProps {
 }
 declare function ScrollArea({ children, className, orientation, maxHeight, maxWidth, }: ScrollAreaProps): react_jsx_runtime.JSX.Element;
 
+/**
+ * The theme's shell-level decisions, carried once by AppShell so that
+ * PageHeader and PageContainer can render a page the way the builder preview
+ * renders it without the page passing a single flag (Sprint 25, 14 Sep 2026).
+ *
+ * The generated shell passes the object the template emits; the builder
+ * preview passes the same values from the theme state. Every field is
+ * optional: a page's own props always win over the theme, and a header
+ * outside any shell falls back to the component defaults it always had.
+ */
+type ChromePosition = "flush" | "floating";
+type ThemePageHeaderVariant = "default" | "colourful" | "minimal" | "tabs-integrated";
+type ThemePageHeaderBehavior = "static" | "snapping";
+type ThemePageHeaderIntensity = "subtle" | "bold";
+type ThemeBreadcrumbPosition = "inline" | "contained";
+type ThemeBreadcrumbStyle = "default" | "pill";
+type ThemeBreadcrumbSeparator = "chevron" | "slash" | "dot" | "arrow";
+interface AppShellTheme {
+    /** Where the navbar sits; a floating navbar's gutter is the gap above a floating header. Confirmed by the rendered Navbar. */
+    navbarPosition?: ChromePosition;
+    /** Where the sidebar sits; a floating sidebar's gutter is the gap beside a floating header. Confirmed by the rendered Sidebar. */
+    sidebarPosition?: ChromePosition;
+    pageHeader?: {
+        variant?: ThemePageHeaderVariant;
+        behavior?: ThemePageHeaderBehavior;
+        position?: ChromePosition;
+        /** Colourful only. */
+        intensity?: ThemePageHeaderIntensity;
+        /** Colourful on the home page only; other pages take `otherPagesVariant`. The shell decides which page is home. */
+        colourfulHomeOnly?: boolean;
+        otherPagesVariant?: "default" | "minimal";
+    };
+    breadcrumbs?: {
+        /** Inline in the header, or a contained strip the container renders above it. */
+        position?: ThemeBreadcrumbPosition;
+        style?: ThemeBreadcrumbStyle;
+        separator?: ThemeBreadcrumbSeparator;
+    };
+}
+
 interface AppShellContextValue {
     hasSidebar: boolean;
     hasMobileMenu: boolean;
@@ -1569,6 +1992,42 @@ interface AppShellContextValue {
     isMobile: boolean;
     /** True only for tablet-sized viewports (between sm and md breakpoints). Drawer shows here, not on small mobile. */
     isTablet: boolean;
+    /**
+     * Effective sidebar collapse for a traditional Sidebar rendered in the shell.
+     * The user's explicit choice wins; otherwise the auto tier applies — collapsed
+     * to a rail at or below the `lg` breakpoint, expanded above it. Lives here rather
+     * than in Sidebar so it survives the sidebar unmounting in the drawer range.
+     */
+    sidebarCollapsed: boolean;
+    /** Records an explicit user choice. Overrides the auto tier in both directions for the session. */
+    setSidebarCollapsed: (collapsed: boolean) => void;
+    /** True while a docked AsidePanel in the aside slot is open beside the content. Pages may hide non-essential chrome on it. */
+    asideOpen: boolean;
+    /** Set by AsidePanel; not for pages to call. */
+    setAsideOpen: (open: boolean) => void;
+    /** Which side the aside slot is on (AppShell's asideSide). */
+    asideSide: "right" | "left";
+    /** True while the docked AsidePanel is floating — a floating PageHeader drops its gutter on that side, as it does beside a floating Sidebar. */
+    asideFloating: boolean;
+    /** Set by AsidePanel; not for pages to call. */
+    setAsideFloating: (floating: boolean) => void;
+    /**
+     * The shell's root element, for previews that need to render overlays inside their frame
+     * (the dashboard builder passes it to Launcher, CornerPanel and Drawer as `container`).
+     * Components never read it themselves: a container moves the toast-inset claim onto that
+     * element, where a body-level ToastProvider cannot see it.
+     */
+    container: HTMLElement | null;
+    /** The theme's shell-level decisions (Sprint 25). PageHeader and PageContainer resolve their defaults from it. */
+    theme: AppShellTheme | null;
+    /** The current route is the home page (`currentPath === homePath`); decides `colourfulHomeOnly`. */
+    isHome: boolean;
+    /** The rendered Navbar floats (registered by the Navbar; the theme's `navbarPosition` until it has). */
+    navbarFloating: boolean;
+    /** The rendered Sidebar floats, and is a sidebar rather than a drawer: false below md and in stacked layouts. */
+    sidebarFloating: boolean;
+    /** Called by Sidebar and Navbar so the shell knows the chrome that is actually rendered. Returns the unregister. */
+    registerChrome: (kind: "navbar" | "sidebar", position: ChromePosition) => () => void;
 }
 declare function useAppShell(): AppShellContextValue | null;
 type AppShellLayout = "sidebar" | "stacked" | "sidebar-header" | "multi-column";
@@ -1585,10 +2044,32 @@ interface AppShellProps {
     mobileMenuFlush?: boolean;
     navbar?: ReactNode;
     mobileNav?: ReactNode;
+    /** Rendered below the page content inside the scrolling region and pinned to the bottom on short pages. Ignored when `scrollable` is false. */
+    footer?: ReactNode;
+    /** Render a SkipLink as the first focusable element (default true); it targets `mainId`. */
+    skipLink?: boolean;
+    /** The id of the <main> region the skip link jumps to. */
+    mainId?: string;
+    /** A docked AsidePanel rendered beside the content column: the page narrows to make room. Rendered at every width — the panel decides its own fallbacks. */
+    aside?: ReactNode;
+    /** Which side of the content the aside sits on. Default "right". Pass the same value to the AsidePanel. */
+    asideSide?: "right" | "left";
+    /**
+     * A Launcher for the assistant. Rendered only above the sm breakpoint — a conditional render,
+     * because the Launcher portals out of any wrapper — so on phones the Navbar button is the entry point
+     * and it never collides with BottomNav.
+     */
+    launcher?: ReactNode;
     children: ReactNode;
     className?: string;
     /** When false, main area won't scroll — use for full-height layouts like ResizablePanelGroup. Default true. */
     scrollable?: boolean;
+    /** The theme's shell-level decisions: what the generated shell passes once so pages carry nothing (Sprint 25). */
+    theme?: AppShellTheme;
+    /** The current route's path, so the shell knows which page is home. */
+    currentPath?: string;
+    /** The home page's path. Default "/". */
+    homePath?: string;
 }
 declare const AppShell: react.ForwardRefExoticComponent<AppShellProps & react.RefAttributes<HTMLDivElement>>;
 
@@ -1602,11 +2083,31 @@ interface PageContainerProps {
     /** Lower-level max-width escape hatch. Use `width` for standard cases. */
     maxWidth?: MaxWidth;
     padding?: Padding;
+    /**
+     * Vertical padding of the content column. With a PageHeader as a direct child the header owns the space under the
+     * navbar, so only the bottom value applies; without one the default is the usual top and bottom padding.
+     */
     verticalPadding?: VerticalPadding;
     centered?: boolean;
     children: ReactNode;
     className?: string;
+    /**
+     * Wraps the PageHeader the container found among its children — for previews that need a badge or a ref on it.
+     * The header keeps reading the container's context through the wrapper. The wrapper must not form a box
+     * (`display: contents`): a snapping header sticks within its containing block, which has to be this container.
+     */
+    renderHeader?: (header: ReactNode) => ReactNode;
 }
+/**
+ * The page's width constraint, and — when a PageHeader is among its direct
+ * children — the page's composition: the header is placed inside the column
+ * (default, minimal, tabs-integrated) or above it spanning the page
+ * (colourful, snapping, floating), contained breadcrumbs become a strip above
+ * the header, a floating header's content is inset by the shell gutter, and a
+ * colourful overlap pulls the content up. The decisions come from the theme
+ * the AppShell carries; a page writes `<PageContainer><PageHeader title />…`
+ * and nothing else (Sprint 25).
+ */
 declare const PageContainer: react.ForwardRefExoticComponent<PageContainerProps & react.RefAttributes<HTMLDivElement>>;
 
 interface SectionHeadingProps {
@@ -1678,4 +2179,4 @@ interface UseTextOverflowResult {
  */
 declare function useTextOverflow(options?: UseTextOverflowOptions): UseTextOverflowResult;
 
-export { Accordion, ActionPanel, ActionPanelGroup, Alert, type AlertPlacement, AppShell, type AppShellContextValue, Avatar, AvatarGroup, type AvatarGroupItem, type AvatarGroupProps, type AvatarStatus, Badge, type BadgePaletteColor, type BadgeSize, type BadgeVariant, BottomNav, type BottomNavItem, type BreadcrumbItem$1 as BreadcrumbItem, Breadcrumbs, type BreadcrumbsSeparator, type BreadcrumbsSize, type BreadcrumbsVariant, BreakpointKey, BulkActionBar, Button, ButtonSizeContext, Calendar, Card, CardContent, CardDescription, CardFooter, CardHeader, type CardSelectType, CardTitle, type CardVariant, Carousel, ChatMessageList, Checkbox, CheckboxGroup, CheckboxGroupItem, CodeBlock, Collapsible, ColorPicker, type Column, Combobox, CommandPalette, ContextMenu, DEFAULT_DATE_RANGE_PRESETS, DataList, DatePicker, type DateRange, DateRangePicker, type DateRangePickerProps, type DateRangePreset, type DescriptionItem, DescriptionList, type DescriptionListOrientation, type DescriptionListSize, Dialog, Divider, Dock, Drawer, Dropdown, DropdownMenu, type DropdownMenuDivider, type DropdownMenuEntry, type DropdownMenuItem, EmptyState, Field, type FieldControlProps, type FieldProps, FileUpload, FormWrapper, HoverCard, InlineFieldError, Input, Kbd, Label, Link, type LinkProps, MentionInput, MobileHeaderMenu, type MobileHeaderMenuItemData, type MobileHeaderMenuType, NavItem, type NavItemProps, type NavItemType, NavMenu, type NavMenuItem, Navbar, type NavbarSize, type NavbarType, type NavbarVariant, NotificationCenter, NumberInput, PageContainer, type PageContainerWidth, PageHeader, type PageHeaderBehavior, type PageHeaderIntensity, type PageHeaderProps, type PageHeaderVariant, Pagination, PinInput, Popover, Progress, type PromiseToastMessages, RadioGroup, Rating, ScrollArea, SectionHeading, SegmentedControl, Sheet, Sidebar, type SidebarContextValue, type SidebarItem, SidebarNav, type SidebarNavSize, type SidebarPosition, type SidebarSection, type SidebarType, Skeleton, SliderRange, Spinner, StackedList, StatsCard, StatusDot, type StatusDotVariant, Stepper, type Tab, Table, type TableDensity, type TableProps, Tabs, Tag, TagInput, type TagPaletteColor, type TagVariant, TextOverflow, type TextOverflowProps, Textarea, TimePicker, Timeline, Toast, type ToastAction, type ToastApi, type ToastOptions, type ToastPosition, ToastProvider, type ToastVariant, Toggle, Tooltip, Tour, TransferList, TreeView, type UseTextOverflowOptions, type UseTextOverflowResult, useAppShell, useFormContext, useSidebar, useTextOverflow, useToast };
+export { Accordion, ActionPanel, ActionPanelGroup, Alert, type AlertPlacement, AppShell, type AppShellContextValue, type AppShellTheme, AsidePanel, type AsidePanelProps, type AsidePanelSide, Avatar, AvatarGroup, type AvatarGroupItem, type AvatarGroupProps, type AvatarStatus, Badge, type BadgePaletteColor, type BadgeSize, type BadgeVariant, BottomNav, type BottomNavItem, type BreadcrumbItem$1 as BreadcrumbItem, Breadcrumbs, type BreadcrumbsSeparator, type BreadcrumbsSize, type BreadcrumbsVariant, BreakpointKey, BulkActionBar, Button, ButtonSizeContext, Calendar, Card, CardContent, CardDescription, CardFooter, CardHeader, type CardSelectType, CardTitle, type CardVariant, Carousel, type ChatMessage, type ChatMessageAction, type ChatMessageLayout, ChatMessageList, type ChatMessageSender, type ChatMessageSource, type ChatMessageStatus, ChatPanel, type ChatPanelProps, type ChatPanelStatusTone, Checkbox, CheckboxGroup, CheckboxGroupItem, CodeBlock, Collapsible, ColorPicker, type Column, Combobox, CommandPalette, ContextMenu, CornerPanel, type CornerPanelEdge, type CornerPanelProps, DEFAULT_DATE_RANGE_PRESETS, DataList, DatePicker, type DateRange, DateRangePicker, type DateRangePickerProps, type DateRangePreset, type DescriptionItem, DescriptionList, type DescriptionListOrientation, type DescriptionListSize, Dialog, Divider, Dock, Drawer, Dropdown, DropdownMenu, type DropdownMenuDivider, type DropdownMenuEntry, type DropdownMenuItem, EmptyState, Field, type FieldControlProps, type FieldProps, FileUpload, FormWrapper, HoverCard, InlineFieldError, Input, Kbd, Label, Launcher, type LauncherEdge, type LauncherProps, type LauncherVariant, type LauncherWhenOpen, Link, type LinkProps, MentionInput, MobileHeaderMenu, type MobileHeaderMenuItemData, type MobileHeaderMenuType, NavItem, type NavItemProps, type NavItemType, NavMenu, type NavMenuItem, Navbar, type NavbarSize, type NavbarType, type NavbarVariant, NotificationCenter, NumberInput, PageContainer, type PageContainerWidth, PageHeader, type PageHeaderBehavior, type PageHeaderIntensity, type PageHeaderProps, type PageHeaderVariant, Pagination, PinInput, Popover, Progress, type PromiseToastMessages, RadioGroup, Rating, ScrollArea, SectionHeading, SegmentedControl, Sheet, Sidebar, type SidebarContextValue, type SidebarItem, SidebarNav, type SidebarNavSize, type SidebarPosition, type SidebarSection, type SidebarType, Skeleton, SkipLink, SliderRange, Spinner, StackedList, StatsCard, StatusDot, type StatusDotVariant, Stepper, type Tab, Table, type TableDensity, type TableProps, TableToolbar, type TableToolbarActiveFilter, type TableToolbarFilterOption, Tabs, Tag, TagInput, type TagPaletteColor, type TagVariant, TextOverflow, type TextOverflowProps, Textarea, TimePicker, Timeline, Toast, type ToastAction, type ToastApi, type ToastOptions, type ToastPosition, ToastProvider, type ToastVariant, Toggle, Tooltip, Tour, TransferList, TreeView, type UseTextOverflowOptions, type UseTextOverflowResult, useAppShell, useFormContext, useSidebar, useTextOverflow, useToast };