gridsmith-ui 0.6.7 → 0.7.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;
@@ -709,7 +711,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 +736,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;
@@ -1011,7 +1088,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;
@@ -1329,8 +1406,10 @@ 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;
 }
-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, }: SegmentedControlProps): react_jsx_runtime.JSX.Element;
 
 interface BottomNavItem {
     label: string;
@@ -1582,15 +1661,20 @@ interface DrawerProps {
 }
 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;
@@ -1859,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;
@@ -1894,6 +2018,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 +2044,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 +2064,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 +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 {
@@ -2013,4 +2179,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, 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 };