gridsmith-ui 0.10.0 → 0.12.0

package/dist/index.d.ts

@@ -433,6 +433,15 @@ interface FormWrapperProps {
      */
     actions?: ReactNode;
     actionsAlign?: "start" | "end";
+    /**
+     * Renders a secondary Cancel before the actions. Inside a Drawer, Sheet or Dialog it closes the overlay through its
+     * unsaved-changes check — the question Escape and the close control ask while the form is dirty — and the overlay's
+     * onClose runs; anywhere else this function runs. Never hand-wire a Cancel to the overlay's close: it skips the
+     * question (round 21, run 58).
+     */
+    onCancel?: () => void;
+    /** The Cancel button's label (default "Cancel"). */
+    cancelLabel?: string;
     /** After a failed submit, scroll to and focus the first invalid field (default on). */
     focusFirstError?: boolean;
     /**
@@ -443,7 +452,7 @@ interface FormWrapperProps {
     className?: string;
     ref?: React.Ref<HTMLFormElement>;
 }
-declare function FormWrapper({ onSubmit, validationMode: validationModeProp, children, actions, actionsAlign: actionsAlignProp, focusFirstError, errorSummary, className, ref }: FormWrapperProps): react_jsx_runtime.JSX.Element;
+declare function FormWrapper({ onSubmit, validationMode: validationModeProp, children, actions: actionsProp, actionsAlign: actionsAlignProp, onCancel, cancelLabel, focusFirstError, errorSummary, className, ref }: FormWrapperProps): react_jsx_runtime.JSX.Element;
 
 interface TransferItem {
     id: string;
@@ -716,6 +725,7 @@ declare const Tag: react.ForwardRefExoticComponent<TagProps & react.RefAttribute
 type AvatarStatus = "online" | "away" | "busy" | "offline";
 type AvatarColor = "auto" | "accent" | "neutral" | 1 | 2 | 3 | 4 | 5;
 interface AvatarProps {
+    /** One to three letters ("JB"). A name passed here shows its initials ("Amara Haddad" → "AH"), never the whole name. */
     initials?: string;
     src?: string;
     alt?: string;
@@ -791,7 +801,7 @@ interface EntityCellProps {
     avatar?: ReactNode;
     /** An image URL for the avatar. */
     src?: string;
-    /** Initials for the avatar. Absent, and with no src or element, they are derived from `primary` ("Sarah Chen" → "SC"). */
+    /** Leave it out: with no src or element the initials come from `primary` ("Sarah Chen" → "SC"). A name passed here shows its initials too (round 21). */
     initials?: string;
     primary: string;
     secondary?: string;
@@ -850,6 +860,17 @@ interface TableToolbarProps {
     /** How many rows match; shown with `resultNoun`. */
     resultCount?: number;
     resultNoun?: [singular: string, plural: string];
+    /**
+     * The list is paged: pass the `usePagination` result and the count says which rows are showing — "Showing 51–100 of
+     * 200 events" — instead of a bare total the table does not show (round 21, the owner's call); one page reads
+     * "12 events". Under tabs that carry the counts, pass the pager alone (no resultCount): the line then shows only the
+     * range, and only while the list spans pages — the tabs already say how many (gs:count-duplicated-by-tabs).
+     */
+    pagination?: {
+        page: number;
+        pageSize: number;
+        totalItems?: number;
+    };
     /** Utility actions on the right — an overflow DropdownMenu, an export button. Primary actions belong in the PageHeader. */
     actions?: ReactNode;
     size?: "sm" | "md";
@@ -865,7 +886,7 @@ interface TableToolbarProps {
  * 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;
+declare function TableToolbar({ search, primaryFilter, filters, filtersOpen, onFiltersOpenChange, activeFilterCount, activeFilters, onClearAll, resultCount, resultNoun, pagination, actions, size, compactBreakpoint, className, }: TableToolbarProps): react_jsx_runtime.JSX.Element | null;
 
 interface TimelineItem {
     title: string;
@@ -2170,8 +2191,29 @@ interface AppShellPreferences {
     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;
+/** Every preference in force, the shell's value or the house default — what app code reads. */
+interface ResolvedPreferences {
+    validationTiming: PreferenceValidationTiming;
+    formActions: {
+        align: "start" | "end";
+        placement: "auto" | "inline";
+    };
+    itemsPerPage: number;
+    tableToCardsBreakpoint: PreferenceBreakpoint;
+    emptyStyle: PreferenceEmptyStyle;
+    loadingStyle: PreferenceLoadingStyle;
+    destructiveMode: PreferenceDestructiveMode;
+    highSeverityActions: string[];
+    typeToConfirmActions: string[];
+    undoWindowSeconds: number;
+}
+/**
+ * For app code: every preference in force — the shell's value, else the house default — so a page never writes a
+ * fallback of its own. Round 21 (run 58): with every field optional, TypeScript made the builder write
+ * `const { itemsPerPage = 20 } = usePreferences()`, a second copy of the preference it then edited by hand when the
+ * rule changed. Paged lists use `usePagination`, which reads the page size itself.
+ */
+declare function usePreferences(): ResolvedPreferences;
 /**
  * "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.
@@ -2277,6 +2319,49 @@ interface AppShellProps {
 }
 declare const AppShell: react.ForwardRefExoticComponent<AppShellProps & react.RefAttributes<HTMLDivElement>>;
 
+/**
+ * A paged list in one hook (round 21). The page size is the project's `dataDisplay.itemsPerPage`, read from the
+ * shell, so a mid-build `update_rule` reaches every paged list with no page edited; the page gets its slice, the
+ * props for `<Pagination>` and the numbers the count line needs ("Showing 51–100 of 200 events").
+ *
+ * Run 58 showed why: both pages hand-wrote the same slicing, a `totalPages` sum and a fallback page size of their
+ * own, and the count line above the table said "200 events" while the table showed fifty.
+ *
+ *   const pager = usePagination(sortedEvents, { resetOn: [sortKey, sortDir] })
+ *   <TableToolbar resultCount={sortedEvents.length} resultNoun={["event", "events"]} pagination={pager} />
+ *   <Table columns={columns} data={pager.items.map(toRow)} />
+ *   <Pagination {...pager.props} />
+ */
+interface Pager<T> {
+    /** This page's slice of the list. */
+    items: T[];
+    /** The current page, from 1. */
+    page: number;
+    pageSize: number;
+    totalItems: number;
+    totalPages: number;
+    /** The first and last item numbers on this page, from 1 ("Showing 51–100"); [0, 0] for an empty list. */
+    range: [number, number];
+    setPage: (page: number) => void;
+    /** A page-size selector's choice; it wins over the project's page size and starts again at page 1. */
+    setPageSize: (size: number) => void;
+    /** Spread onto <Pagination>. */
+    props: {
+        currentPage: number;
+        totalPages: number;
+        onPageChange: (page: number) => void;
+        pageSize: number;
+        onPageSizeChange: (size: number) => void;
+    };
+}
+interface PaginationOptions {
+    /** A fixed page size for this list, over the project's. Leave it out: the project's page size is the rule. */
+    pageSize?: number;
+    /** Values that start the list again at page 1 when they change — the sort column and direction, a search query. */
+    resetOn?: unknown;
+}
+declare function usePagination<T>(list: readonly T[], options?: PaginationOptions): Pager<T>;
+
 interface DestructiveActionOptions {
     /** The action's key as the preference lists name it ("remove_range"); derived from `title` when omitted. */
     action?: string;
@@ -2452,4 +2537,4 @@ interface UseTextOverflowResult {
  */
 declare function useTextOverflow(options?: UseTextOverflowOptions): UseTextOverflowResult;
 
-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 };
+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, type Pager, Pagination, type PaginationOptions, PinInput, Popover, PreferencesContext, Progress, type PromiseToastMessages, RadioGroup, Rating, type ResolvedPreferences, 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, usePagination, usePreferences, useSidebar, useTextOverflow, useToast, useToastOptional };