gridsmith-ui 0.6.7 → 0.8.0

package/dist/index.d.ts

@@ -105,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;
@@ -409,14 +411,33 @@ interface FormContextValue {
     submitted: boolean;
 }
 declare function useFormContext(): FormContextValue;
+/** An invalid field as the form finds it in its own DOM after a submit. */
+interface FormFieldError {
+    id: string;
+    label: string;
+    message: string;
+}
 interface FormWrapperProps {
     onSubmit: (errors: FormErrors) => void;
     validationMode?: ValidationMode;
     children: ReactNode;
+    /**
+     * The buttons row (submit, cancel) with a clear gap above the last field — never a hand-rolled flex row under it
+     * (bench round 3, R12). Right-aligned like CardFooter and the overlay footers; `actionsAlign="start"` for a narrow form.
+     */
+    actions?: ReactNode;
+    actionsAlign?: "start" | "end";
+    /** After a failed submit, scroll to and focus the first invalid field (default on). */
+    focusFirstError?: boolean;
+    /**
+     * When two or more fields are invalid after a submit, an error summary above the form links to each (default on).
+     * A function renders your own from the list.
+     */
+    errorSummary?: boolean | ((errors: FormFieldError[]) => ReactNode);
     className?: string;
     ref?: React.Ref<HTMLFormElement>;
 }
-declare function FormWrapper({ onSubmit, validationMode, children, className, ref }: FormWrapperProps): react_jsx_runtime.JSX.Element;
+declare function FormWrapper({ onSubmit, validationMode, children, actions, actionsAlign, focusFirstError, errorSummary, className, ref }: FormWrapperProps): react_jsx_runtime.JSX.Element;
 
 interface TransferItem {
     id: string;
@@ -474,7 +495,11 @@ interface CardHeaderProps extends HTMLAttributes<HTMLDivElement> {
     menuItems?: DropdownMenuEntry[];
 }
 declare const CardHeader: react.ForwardRefExoticComponent<CardHeaderProps & react.RefAttributes<HTMLDivElement>>;
-declare const CardTitle: react.ForwardRefExoticComponent<HTMLAttributes<HTMLHeadingElement> & react.RefAttributes<HTMLHeadingElement>>;
+interface CardTitleProps extends HTMLAttributes<HTMLHeadingElement> {
+    /** Max lines before clamping (with the full title on hover). Default 2, like CardDescription; 1 truncates on one line; 0 = no limit. */
+    lines?: number;
+}
+declare const CardTitle: react.ForwardRefExoticComponent<CardTitleProps & react.RefAttributes<HTMLHeadingElement>>;
 interface CardDescriptionProps extends HTMLAttributes<HTMLParagraphElement> {
     /** Max lines before clamping. Default 2. Set to 0 for no limit. */
     lines?: number;
@@ -486,6 +511,8 @@ declare const CardFooter: react.ForwardRefExoticComponent<HTMLAttributes<HTMLDiv
 interface Trend {
     direction: "up" | "down" | "flat";
     value: string;
+    /** Whether the change is good news. Default: up = positive, down = negative, flat = neutral. Pass "positive" for a falling cost or overdue count, "negative" for rising churn or errors. */
+    sentiment?: "positive" | "negative" | "neutral";
 }
 interface StatsCardProps {
     value: string | number;
@@ -526,7 +553,8 @@ interface DescriptionListProps {
     columns?: 1 | 2 | 3 | 4;
     size?: DescriptionListSize;
     dividers?: boolean;
-    stackBelow?: "sm" | "md" | "lg";
+    /** Below this breakpoint a multi-column list becomes one column. Default "sm" when columns > 1 (a phone never shows two columns of pairs); "none" keeps the columns at every width. */
+    stackBelow?: "sm" | "md" | "lg" | "none";
     className?: string;
 }
 declare const DescriptionList: react.ForwardRefExoticComponent<DescriptionListProps & react.RefAttributes<HTMLDListElement>>;
@@ -709,7 +737,15 @@ 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;
@@ -726,6 +762,73 @@ interface EmptyStateProps {
 }
 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;
+}
+/**
+ * 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;
     description?: string;
@@ -735,19 +838,24 @@ interface TimelineItem {
 }
 interface TimelineProps {
     items: TimelineItem[];
+    /** "responsive" lays the items out horizontally only when they fit at minItemWidth each, else vertically. */
     orientation?: "vertical" | "horizontal" | "responsive";
+    /** The least width a horizontal item gets before the row scrolls (a structural size, not a design value). */
+    minItemWidth?: number;
     className?: string;
     ref?: Ref<HTMLDivElement>;
 }
-declare function Timeline({ items, orientation, className, ref }: TimelineProps): react_jsx_runtime.JSX.Element;
+declare function Timeline({ items, orientation, minItemWidth, className, ref }: TimelineProps): react_jsx_runtime.JSX.Element;
 
 interface CodeBlockProps {
     code: string;
     language?: string;
     showLineNumbers?: boolean;
+    /** Wrap long lines instead of scrolling sideways. Default: on for a single-line snippet (a tracking tag, a command), off for multi-line code. */
+    wrap?: boolean;
     className?: string;
 }
-declare function CodeBlock({ code, language, showLineNumbers, className, }: CodeBlockProps): react_jsx_runtime.JSX.Element;
+declare function CodeBlock({ code, language, showLineNumbers, wrap, className, }: CodeBlockProps): react_jsx_runtime.JSX.Element;
 
 interface CollapsibleProps {
     open?: boolean;
@@ -1011,7 +1119,7 @@ interface AsidePanelProps {
  * 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, sidebarFloating, collapseBelow, keepMounted, resizable, maxWidth, labelledBy, id, children, className, }: AsidePanelProps): react_jsx_runtime.JSX.Element;
+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;
@@ -1038,6 +1146,8 @@ interface StackedListProps {
     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;
+    /** How an interactive row answers the pointer: "tint" (default) shades the row; "title" colours the title, for article lists (a knowledge base, a changelog). */
+    hover?: "tint" | "title";
     className?: string;
 }
 declare const StackedList: react.ForwardRefExoticComponent<StackedListProps & react.RefAttributes<HTMLUListElement>>;
@@ -1176,6 +1286,137 @@ declare const Tabs: typeof TabsRoot & {
     Content: typeof TabsContent;
 };
 
+/**
+ * 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";
+type ThemeSettingsLayout = "sidebar" | "tabs";
+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;
+    };
+    /** The customer's settings.layout preference: a rail of sections beside the panel, or horizontal tabs above it. SettingsLayout reads it. */
+    settingsLayout?: ThemeSettingsLayout;
+}
+
+interface SettingsSection {
+    id: string;
+    label: string;
+    icon?: IconName;
+    /** Heading above this section in the rail; the option group in the collapsed Dropdown. */
+    group?: string;
+    disabled?: boolean;
+}
+interface SettingsLayoutProps {
+    sections: SettingsSection[];
+    /** The selected section id. */
+    value: string;
+    onChange: (id: string) => void;
+    /**
+     * 'sidebar': a rail of sections beside the panel; 'tabs': horizontal tabs above it.
+     * Default: the shell theme's settings.layout preference, else 'sidebar'. A page passes nothing.
+     */
+    layout?: ThemeSettingsLayout;
+    /** Width of the rail in px (sidebar layout). */
+    railWidth?: number;
+    /**
+     * Below this width of the layout itself (not the viewport) the rail becomes a Dropdown. Default: the rail plus a
+     * usable panel (railWidth + 480). Measured on the layout, so a narrow PageContainer or a sidebar shell counts.
+     */
+    collapseBelow?: number;
+    /** Accessible name of the section navigation. */
+    "aria-label"?: string;
+    /** The panel: the selected section's content. */
+    children: ReactNode;
+    className?: string;
+}
+/**
+ * The settings page composition (Sprint 25.2, R8): a rail of sections beside
+ * the panel, sticky while the page scrolls, or horizontal tabs above it — the
+ * customer's settings.layout preference decides which, the component decides
+ * the breakpoints. The collapse is measured on the layout's own width (a narrow
+ * PageContainer, a sidebar shell): when the rail would leave too little for the
+ * panel it becomes a Dropdown above the panel; a vertical rail never sits above
+ * the content (settings#10).
+ *
+ * The rail is a Tabs (vertical) styled by the theme's in-page vertical style;
+ * the page assembles the sections' contents and nothing else.
+ */
+declare function SettingsLayout({ sections, value, onChange, layout: layoutProp, railWidth, collapseBelow, "aria-label": ariaLabel, children, className, }: SettingsLayoutProps): react_jsx_runtime.JSX.Element;
+
+interface SplitViewProps {
+    /** The list (an inbox, a queue): it scrolls on its own. */
+    list: ReactNode;
+    /** The selected item (a thread, a record): it fills the height and scrolls on its own. */
+    detail: ReactNode;
+    /** Context beside the detail (a contact, properties). Collapses to a toggle that opens it in a Drawer when the layout is narrower than `asideCollapseBelow`. */
+    aside?: ReactNode;
+    /** Names the aside's toggle and Drawer. */
+    asideTitle?: string;
+    /**
+     * Below `collapseBelow` the list shows alone; with `detailOpen` the detail replaces it, with a Back button that calls
+     * `onDetailClose` (detailMode "stack"). The page owns the selection, so it owns this flag.
+     */
+    detailOpen?: boolean;
+    onDetailClose?: () => void;
+    /** "stack" (default): the detail stacks over the list below the collapse width. "route": the app navigates to the detail's own route instead, and this renders the list alone there. */
+    detailMode?: "stack" | "route";
+    backLabel?: string;
+    /** Percent of the width the list takes; the divider is draggable. */
+    listWidth?: number;
+    listMinWidth?: number;
+    asideWidth?: number;
+    /** Below this width of the layout itself (px) the list and detail stop sitting side by side. */
+    collapseBelow?: number;
+    /** Below this width of the layout itself (px) the aside becomes a toggle. */
+    asideCollapseBelow?: number;
+    /** A bordered, rounded surface (inside a page with padding) instead of edge to edge (filling <main>). */
+    bordered?: boolean;
+    "aria-label"?: string;
+    className?: string;
+}
+/**
+ * The reading-pane composition (Sprint 25.2, R3): one surface with dividers —
+ * list, detail and an optional aside — that fills the height it is given (an
+ * AppShell's <main> already gives it) and never three cards with gaps. The
+ * panels compose ResizablePanelGroup, so the dividers drag. Below the collapse
+ * width, measured on the layout itself, the list shows alone and the detail
+ * stacks over it (or the app routes to it); the aside collapses to a toggle.
+ * The page owns the selection and assembles the contents; keyboard movement
+ * through the list is the list's job (StackedList selectedId).
+ */
+declare function SplitView({ list, detail, aside, asideTitle, detailOpen, onDetailClose, detailMode, backLabel, listWidth, listMinWidth, asideWidth, collapseBelow, asideCollapseBelow, bordered, "aria-label": ariaLabel, className, }: SplitViewProps): react_jsx_runtime.JSX.Element;
+
 interface BreadcrumbItem$1 {
     label: string;
     href?: string;
@@ -1329,8 +1570,15 @@ interface SegmentedControlProps {
      */
     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;
+    /**
+     * Above this many options the control renders a Dropdown with the same value, onChange and options — a row of
+     * eleven segments runs off the page (bench round 3). Default 6; raise it only where the row is known to fit.
+     */
+    maxOptions?: number;
 }
-declare function SegmentedControl({ value, onChange, options, size, variant, fullWidth, onHoverChange, className, }: SegmentedControlProps): react_jsx_runtime.JSX.Element;
+declare function SegmentedControl({ value, onChange, options, size, variant, fullWidth, onHoverChange, className, "aria-label": ariaLabel, maxOptions, }: SegmentedControlProps): react_jsx_runtime.JSX.Element;
 
 interface BottomNavItem {
     label: string;
@@ -1375,7 +1623,7 @@ interface PageHeaderProps {
     intensity?: PageHeaderIntensity;
     /** Colourful: background image URL — overlaid with accent colour */
     backgroundImage?: string;
-    /** Colourful: extra bottom padding (px) for content overlap. Content below should use -mt-[value] to pull up. */
+    /** Colourful: extra bottom padding (px) for content overlap. PageContainer pulls the content up by the same amount; the page adds no negative margin. */
     overlapHeight?: number;
     /** Snapping: content shown only when expanded */
     expandedContent?: ReactNode;
@@ -1514,6 +1762,10 @@ interface DialogProps {
     description?: string;
     children?: ReactNode;
     footer?: ReactNode;
+    /** The content has unsaved changes: Escape, the backdrop and the close control ask before discarding, inside the dialog (Sprint 25.2, C1). */
+    dirty?: boolean;
+    /** Called when the user chooses to discard, before onClose. */
+    onDiscard?: () => void;
     variant?: "default" | "destructive";
     size?: DialogSize;
     alert?: boolean;
@@ -1529,7 +1781,7 @@ interface DialogProps {
      */
     onSubmit?: () => void;
 }
-declare function Dialog({ open, onClose, title, description, children, footer, variant, size, alert, container, onSubmit }: DialogProps): react.ReactPortal | null;
+declare function Dialog({ open, onClose: onCloseProp, title, description, children, footer, variant, size, alert, container, onSubmit, dirty, onDiscard }: DialogProps): react.ReactPortal | null;
 
 interface DrawerProps {
     open: boolean;
@@ -1579,18 +1831,27 @@ interface DrawerProps {
      */
     resizable?: boolean;
     maxWidth?: string;
+    /** The content has unsaved changes: every close path asks before discarding, inside the drawer (Sprint 25.2, C1). */
+    dirty?: boolean;
+    /** Called when the user chooses to discard, before onClose. */
+    onDiscard?: () => void;
 }
 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;
@@ -1662,6 +1923,8 @@ interface SheetProps {
     title?: ReactNode;
     children: ReactNode;
     footer?: ReactNode;
+    /** A strip between the content and the footer (the Drawer's unsaved-changes question). */
+    confirm?: ReactNode;
     /** Heights the sheet snaps to, as fractions of the viewport (or container). Default [0.5, 0.92]. */
     snapPoints?: number[];
     /** Render inside this element (absolute positioning, no body scroll lock) instead of document.body. */
@@ -1675,7 +1938,7 @@ interface SheetProps {
     /** 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, keepMounted, id, labelledBy }: SheetProps): react.ReactPortal | null;
+declare function Sheet({ open, onClose, title, children, footer, confirm, snapPoints, container, flush, keepMounted, id, labelledBy }: SheetProps): react.ReactPortal | null;
 
 interface Notification {
     id: string;
@@ -1894,6 +2157,16 @@ interface AppShellContextValue {
      * 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";
@@ -1910,6 +2183,12 @@ 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. */
@@ -1924,6 +2203,12 @@ interface AppShellProps {
     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>>;
 
@@ -1937,11 +2222,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 {
@@ -2013,4 +2318,4 @@ interface UseTextOverflowResult {
  */
 declare function useTextOverflow(options?: UseTextOverflowOptions): UseTextOverflowResult;
 
-export { Accordion, ActionPanel, ActionPanelGroup, Alert, type AlertPlacement, AppShell, type AppShellContextValue, 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, 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, SettingsLayout, type SettingsLayoutProps, type SettingsSection, Sheet, Sidebar, type SidebarContextValue, type SidebarItem, SidebarNav, type SidebarNavSize, type SidebarPosition, type SidebarSection, type SidebarType, Skeleton, SkipLink, SliderRange, Spinner, SplitView, type SplitViewProps, 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 Trend, type UseTextOverflowOptions, type UseTextOverflowResult, useAppShell, useFormContext, useSidebar, useTextOverflow, useToast };