gridsmith-ui 0.9.1 → 0.10.0

package/dist/index.d.ts

@@ -443,7 +443,7 @@ interface FormWrapperProps {
     className?: string;
     ref?: React.Ref<HTMLFormElement>;
 }
-declare function FormWrapper({ onSubmit, validationMode, children, actions, actionsAlign, focusFirstError, errorSummary, className, ref }: FormWrapperProps): react_jsx_runtime.JSX.Element;
+declare function FormWrapper({ onSubmit, validationMode: validationModeProp, children, actions, actionsAlign: actionsAlignProp, focusFirstError, errorSummary, className, ref }: FormWrapperProps): react_jsx_runtime.JSX.Element;
 
 interface TransferItem {
     id: string;
@@ -599,6 +599,13 @@ interface Column {
     };
     /** CSS max-width for the column (e.g. "200px", "30ch"). Helps constrain wide text columns. */
     maxWidth?: string;
+    /**
+     * CSS width for the column (e.g. "40%", "240px"). Sibling tables that share a column set (a permissions matrix
+     * split into sections) line up when their columns carry the same widths (round 14, the owner's 50.3).
+     */
+    width?: string;
+    /** CSS min-width for the column. */
+    minWidth?: string;
     /** Explicit column kind. When omitted the Table infers it from data values. */
     kind?: ColumnKind;
 }
@@ -627,7 +634,7 @@ interface TableProps {
     mobileBreakpoint?: BreakpointKey;
     ref?: Ref<HTMLDivElement>;
 }
-declare function Table({ columns, data, className, sortable, sortKey: controlledSortKey, sortDir: controlledSortDir, onSortChange, selectable, selectedRows, onSelectionChange, expandable, renderExpanded, density, stickyHeader, striped, loading, emptyState, onRowClick, mobileBreakpoint, ref, }: TableProps): react_jsx_runtime.JSX.Element;
+declare function Table({ columns, data, className, sortable, sortKey: controlledSortKey, sortDir: controlledSortDir, onSortChange, selectable, selectedRows, onSelectionChange, expandable, renderExpanded, density, stickyHeader, striped, loading, emptyState, onRowClick, mobileBreakpoint: mobileBreakpointProp, ref, }: TableProps): react_jsx_runtime.JSX.Element;
 
 interface CalendarEvent {
     id: string;
@@ -769,9 +776,15 @@ interface EmptyStateProps {
      * frame (the old default) is what FileUpload uses to mean "drop here".
      */
     bordered?: boolean;
+    /**
+     * The customer's emptyStates.emptyStyle (Sprint 25.6): `illustration` frames an icon above the title (the default),
+     * `text` shows the title, description and action alone. Read from the shell when not passed; a `redirect` preference
+     * renders as `text` here — the page itself decides to navigate.
+     */
+    style?: "illustration" | "text";
     className?: string;
 }
-declare function EmptyState({ icon, iconFrame, title, description, action, variant, bordered, className }: EmptyStateProps): react_jsx_runtime.JSX.Element;
+declare function EmptyState({ icon, iconFrame, title, description, action, variant, bordered, style: styleProp, className }: EmptyStateProps): react_jsx_runtime.JSX.Element;
 
 interface EntityCellProps {
     /** A ready-made element (an Avatar with a status, an icon), or a string: initials, or a URL when it looks like one. */
@@ -785,7 +798,7 @@ interface EntityCellProps {
     size?: "sm" | "md";
     className?: string;
 }
-declare function EntityCell({ avatar, src, initials, primary, secondary, size, className }: EntityCellProps): react_jsx_runtime.JSX.Element;
+declare function EntityCell({ avatar, src, initials, primary, secondary, size: sizeProp, className }: EntityCellProps): react_jsx_runtime.JSX.Element;
 
 interface SkipLinkProps {
     /** The id of the main region (AppShell names its <main> "main"). */
@@ -1446,7 +1459,7 @@ interface PaginationProps {
     onPageSizeChange?: (size: number) => void;
     className?: string;
 }
-declare function Pagination({ currentPage, totalPages, onPageChange, pageSize, pageSizeOptions, onPageSizeChange, className }: PaginationProps): react_jsx_runtime.JSX.Element;
+declare function Pagination({ currentPage, totalPages, onPageChange, pageSize: pageSizeProp, pageSizeOptions, onPageSizeChange, className }: PaginationProps): react_jsx_runtime.JSX.Element;
 
 interface Step {
     label: string;
@@ -1752,7 +1765,8 @@ interface DialogProps {
     open: boolean;
     onClose: () => void;
     title: string;
-    description?: string;
+    /** Under the title. Rich text is allowed so a confirmation can emphasise the thing it acts on (round 17, F-7): `<>Revoke <strong>{email}</strong>?</>`. */
+    description?: ReactNode;
     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). */
@@ -2030,6 +2044,8 @@ interface ToastOptions {
     action?: ToastAction;
     /** Supply to update an existing toast in place instead of adding a new one. */
     id?: string;
+    /** Coalescing key (round 15): while the visible slots are full, a new toast replaces the queued toast with the same key instead of joining the queue behind it. Defaults to the variant. */
+    key?: string;
 }
 interface PromiseToastMessages<T> {
     loading: ReactNode;
@@ -2051,25 +2067,33 @@ interface ToastApi {
 }
 interface ToastProviderProps {
     children: ReactNode;
-    /** Maximum toasts shown at once; further toasts queue until one dismisses. Default 3. */
+    /** Maximum toasts shown at once; further toasts queue until one dismisses. Default 1 — the house rule (feedback-notifications rule 4: one at a time, the rest queued). */
     maxVisible?: number;
     /** Where the stack is anchored. Default "bottom-right". */
     position?: ToastPosition;
-    /** Default auto-dismiss duration in ms. Default 3000. */
+    /** Default auto-dismiss duration in ms. Default 5000. */
     duration?: number;
+    /**
+     * Round 15 (the owner's 52.4): ten toggle flips queued ten toasts, each waiting its full duration. While the visible
+     * slots are full, a new toast replaces the queued toast that shares its key (the variant by default) — the user sees
+     * the current one and the latest, never a backlog. Default true.
+     */
+    coalesce?: boolean;
     /** Independent colour mode for toasts, when the theme configures one. */
     mode?: "light" | "dark";
     /** Pause a toast's timer while hovered. Default true. */
     pauseOnHover?: boolean;
 }
 declare function useToast(): ToastApi;
+/** The toast API when a ToastProvider is above, else null — for components that can do without one (useDestructiveAction in dialog mode). */
+declare function useToastOptional(): ToastApi | null;
 /**
  * Queue-backed toast manager. Wrap the app once (get_app_shell does this),
  * then call useToast() anywhere. Enforces the configured maximum visible
  * count, stacks toasts at the configured position, and provides success /
  * error / promise helpers so pages never hand-roll their own queue.
  */
-declare function ToastProvider({ children, maxVisible, position, duration, mode, pauseOnHover }: ToastProviderProps): react_jsx_runtime.JSX.Element;
+declare function ToastProvider({ children, maxVisible, position, duration, mode, pauseOnHover, coalesce }: ToastProviderProps): react_jsx_runtime.JSX.Element;
 
 type ProgressVariant = "default" | "success" | "warning" | "error";
 interface ProgressProps {
@@ -2115,6 +2139,45 @@ interface ScrollAreaProps {
 }
 declare function ScrollArea({ children, className, orientation, maxHeight, maxWidth, }: ScrollAreaProps): react_jsx_runtime.JSX.Element;
 
+type PreferenceValidationTiming = "onBlur" | "onSubmit" | "onChange";
+type PreferenceBreakpoint = "sm" | "md" | "lg";
+type PreferenceEmptyStyle = "illustration-cta" | "text-cta" | "redirect";
+type PreferenceLoadingStyle = "skeleton" | "spinner" | "progress-bar";
+type PreferenceDestructiveMode = "dialog" | "undo";
+interface AppShellPreferences {
+    /** forms.validationTiming — when a field first shows its error. */
+    validationTiming?: PreferenceValidationTiming;
+    /** forms.actions — where a form's buttons sit and how they align. */
+    formActions?: {
+        align?: "start" | "end";
+        placement?: "auto" | "inline";
+    };
+    /** dataDisplay.itemsPerPage — the page size of a paged or load-more list. */
+    itemsPerPage?: number;
+    /** responsive.tableToCardsBreakpoint — below this width a Table becomes stacked cards. */
+    tableToCardsBreakpoint?: PreferenceBreakpoint;
+    /** emptyStates.emptyStyle — illustration with an action, text with an action, or redirect to creation. */
+    emptyStyle?: PreferenceEmptyStyle;
+    /** emptyStates.loadingStyle — what a page shows while data loads. */
+    loadingStyle?: PreferenceLoadingStyle;
+    /** destructiveActions.mode — confirm in a dialog, or act now with an Undo toast. */
+    destructiveMode?: PreferenceDestructiveMode;
+    /** destructiveActions.highSeverityActions — always confirm in a dialog, even in undo mode. */
+    highSeverityActions?: string[];
+    /** destructiveActions.typeToConfirmActions — the user types the name before the confirm enables. */
+    typeToConfirmActions?: string[];
+    /** destructiveActions.undoWindowSeconds — how long the Undo toast stays. */
+    undoWindowSeconds?: number;
+}
+declare const PreferencesContext: react.Context<AppShellPreferences | null>;
+/** The shell's preferences, or an empty object outside any shell — so `usePreferences().itemsPerPage ?? 25` reads naturally. */
+declare function usePreferences(): AppShellPreferences;
+/**
+ * "Remove range" → "remove_range": the key the high-severity and type-to-confirm lists use. The engine's `actionKey`
+ * (platform/src/lib/destructive-mode.ts) is the same rule for compliance; a platform test keeps the two identical.
+ */
+declare function preferenceActionKey(label: string): string;
+
 interface AppShellContextValue {
     hasSidebar: boolean;
     hasMobileMenu: boolean;
@@ -2205,6 +2268,8 @@ interface AppShellProps {
     scrollable?: boolean;
     /** The theme's shell-level decisions: what the generated shell passes once so pages carry nothing (Sprint 25). */
     theme?: AppShellTheme;
+    /** The customer's UX preferences, passed once by the generated shell so pages and components carry nothing (Sprint 25.6). */
+    preferences?: AppShellPreferences;
     /** The current route's path, so the shell knows which page is home. */
     currentPath?: string;
     /** The home page's path. Default "/". */
@@ -2212,6 +2277,51 @@ interface AppShellProps {
 }
 declare const AppShell: react.ForwardRefExoticComponent<AppShellProps & react.RefAttributes<HTMLDivElement>>;
 
+interface DestructiveActionOptions {
+    /** The action's key as the preference lists name it ("remove_range"); derived from `title` when omitted. */
+    action?: string;
+    /** The confirmation's title ("Remove range?"). */
+    title: string;
+    /** What will be lost and whether it can be recovered — shown in the dialog; the Undo toast says it briefly. */
+    description?: ReactNode;
+    /** The destructive confirm's label ("Remove"); the title's first word when omitted. */
+    confirmLabel?: string;
+    /** The text the user must type when the action is on the type-to-confirm list (the item's name). */
+    typeToConfirm?: string;
+    /** Performs the action. In undo mode it runs at once. */
+    onConfirm: () => void | Promise<void>;
+    /** Restores what the action removed; the Undo toast's action in undo mode. Without it the toast has no Undo. */
+    onUndo?: () => void;
+    /** The toast's message in undo mode ("Office removed"). */
+    undoMessage?: ReactNode;
+    /** `high` always confirms in a dialog, even in undo mode; the preference's high-severity list does the same by key. */
+    severity?: "low" | "high";
+}
+interface DestructiveActionHandle {
+    /** Call from the trigger's onClick: opens the dialog (dialog mode) or acts at once with an Undo toast (undo mode). */
+    run: () => void;
+    /** Render once on the page: the confirmation dialog, mounted only while open. */
+    element: ReactNode;
+    /** True while the dialog is open. */
+    open: boolean;
+}
+/**
+ * The destructive safety net as the customer configured it (Sprint 25.6 B10). The hook reads the mode, the
+ * high-severity and type-to-confirm lists and the undo window from the shell's preferences, so a page never decides:
+ *
+ * - dialog mode: `run()` opens a Dialog (variant destructive) whose confirm performs the action; an action on the
+ *   type-to-confirm list adds an input the user must match before the confirm enables;
+ * - undo mode: `run()` performs the action, waits for it, and shows a toast with an Undo action for the configured
+ *   window; a high-severity action (by `severity` or by the preference's list) still confirms in a dialog, and so does an
+ *   action with no `onUndo` — a toast that cannot undo is not a safety net.
+ *
+ * A listed or high-severity action (by the prop or by the preference's list) with no `typeToConfirm` asks for the confirm
+ * word in capitals. A rejected `onConfirm` keeps the dialog
+ * open (dialog mode) or skips the success toast (undo mode) and reports the failure as an error toast.
+ * Outside any shell the mode is dialog and the lists are empty.
+ */
+declare function useDestructiveAction(options: DestructiveActionOptions): DestructiveActionHandle;
+
 type MaxWidth = "sm" | "md" | "lg" | "xl" | "full";
 type PageContainerWidth = "constrained" | "full" | "narrow";
 type Padding = "none" | "default" | "wide";
@@ -2221,6 +2331,13 @@ interface PageContainerProps {
     width?: PageContainerWidth;
     /** Lower-level max-width escape hatch. Use `width` for standard cases. */
     maxWidth?: MaxWidth;
+    /**
+     * Caps the content under the header without narrowing the page: the header and tab strip keep the page's width, the
+     * content column below is capped at this width and left-aligned. For a form tab inside a tabbed area (round 17,
+     * 54.1) — `contentWidth="narrow"`; a layout pattern that wraps PageContainer passes it through. Never a hand-rolled
+     * `max-w-` wrapper around the form.
+     */
+    contentWidth?: PageContainerWidth;
     padding?: Padding;
     /**
      * Vertical padding of the content column. With a PageHeader as a direct child the header owns the space under the
@@ -2237,6 +2354,12 @@ interface PageContainerProps {
      */
     renderHeader?: (header: ReactNode) => ReactNode;
 }
+/**
+ * Ask the nearest PageContainer to cap its content (left-aligned, the header and tab strip keep the page's width) —
+ * for a form page that is an Outlet route under a layout pattern, which cannot set `contentWidth` on the container itself.
+ * `useContentWidth("narrow")` at the top of the page; the cap lifts when the page unmounts.
+ */
+declare function useContentWidth(width: PageContainerWidth): void;
 /**
  * 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
@@ -2329,4 +2452,4 @@ interface UseTextOverflowResult {
  */
 declare function useTextOverflow(options?: UseTextOverflowOptions): UseTextOverflowResult;
 
-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 BadgeSeverity, 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, type ControlSize, ControlSizeContext, 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, EntityCell, 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, type SectionHeadingProps, 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, StackedList, type StackedListVariant, 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 };
+export { Accordion, ActionPanel, ActionPanelGroup, Alert, type AlertPlacement, AppShell, type AppShellContextValue, type AppShellPreferences, type AppShellTheme, AsidePanel, type AsidePanelProps, type AsidePanelSide, Avatar, AvatarGroup, type AvatarGroupItem, type AvatarGroupProps, type AvatarStatus, Badge, type BadgePaletteColor, type BadgeSeverity, 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, type ControlSize, ControlSizeContext, 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, type DestructiveActionHandle, type DestructiveActionOptions, Dialog, Divider, Dock, Drawer, Dropdown, DropdownMenu, type DropdownMenuDivider, type DropdownMenuEntry, type DropdownMenuItem, EmptyState, EntityCell, 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, PreferencesContext, Progress, type PromiseToastMessages, RadioGroup, Rating, ScrollArea, SectionHeading, type SectionHeadingProps, 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, StackedList, type StackedListVariant, 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, preferenceActionKey, useAppShell, useContentWidth, useDestructiveAction, useFormContext, usePreferences, useSidebar, useTextOverflow, useToast, useToastOptional };