gridsmith-ui 0.11.0 → 0.13.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,20 @@ 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). A list that
+     * grows (load more, loading on scroll) reads "Showing 40 of 120 members" until every row is shown (round 22).
+     */
+    pagination?: {
+        page: number;
+        pageSize: number;
+        totalItems?: number;
+        style?: "pagination" | "load-more" | "infinite-scroll";
+        shown?: number;
+    };
     /** Utility actions on the right — an overflow DropdownMenu, an export button. Primary actions belong in the PageHeader. */
     actions?: ReactNode;
     size?: "sm" | "md";
@@ -865,12 +889,13 @@ 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;
     description?: string;
     timestamp?: string;
+    /** Takes the dot's place — the actor's Avatar (size="sm") on an activity feed, or an Icon. `variant` colours the dot only. */
     icon?: ReactNode;
     variant?: "default" | "success" | "warning" | "error";
 }
@@ -1457,9 +1482,21 @@ interface PaginationProps {
     pageSize?: number;
     pageSizeOptions?: number[];
     onPageSizeChange?: (size: number) => void;
+    /**
+     * How the list shows more (round 22): page numbers, a Load more button, or loading as the user scrolls (with the
+     * button kept for keyboard users). `usePagination` passes the project's dataDisplay.paginationStyle here in
+     * `pager.props`, so `<Pagination {...pager.props} />` follows the project's style with nothing written on the page.
+     */
+    mode?: "pagination" | "load-more" | "infinite-scroll";
+    /** Rows left to load (load-more and infinite-scroll). */
+    hasMore?: boolean;
+    /** Load the next rows (load-more and infinite-scroll). */
+    onLoadMore?: () => void;
+    /** The Load more button's label (default "Load more"). */
+    loadMoreLabel?: string;
     className?: string;
 }
-declare function Pagination({ currentPage, totalPages, onPageChange, pageSize: pageSizeProp, pageSizeOptions, onPageSizeChange, className }: PaginationProps): react_jsx_runtime.JSX.Element;
+declare function Pagination(props: PaginationProps): react_jsx_runtime.JSX.Element;
 
 interface Step {
     label: string;
@@ -2144,6 +2181,8 @@ type PreferenceBreakpoint = "sm" | "md" | "lg";
 type PreferenceEmptyStyle = "illustration-cta" | "text-cta" | "redirect";
 type PreferenceLoadingStyle = "skeleton" | "spinner" | "progress-bar";
 type PreferenceDestructiveMode = "dialog" | "undo";
+/** dataDisplay.paginationStyle — how a long list shows more: page numbers, a Load more button, or loading as the user scrolls. */
+type PreferencePaginationStyle = "pagination" | "load-more" | "infinite-scroll";
 interface AppShellPreferences {
     /** forms.validationTiming — when a field first shows its error. */
     validationTiming?: PreferenceValidationTiming;
@@ -2154,6 +2193,8 @@ interface AppShellPreferences {
     };
     /** dataDisplay.itemsPerPage — the page size of a paged or load-more list. */
     itemsPerPage?: number;
+    /** dataDisplay.paginationStyle — page numbers, a Load more button, or loading on scroll; usePagination and Pagination follow it (round 22). */
+    paginationStyle?: PreferencePaginationStyle;
     /** 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. */
@@ -2170,8 +2211,30 @@ 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;
+    paginationStyle: PreferencePaginationStyle;
+    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 +2340,68 @@ interface AppShellProps {
 }
 declare const AppShell: react.ForwardRefExoticComponent<AppShellProps & react.RefAttributes<HTMLDivElement>>;
 
+/**
+ * A long list in one hook (round 21; all three list styles since round 22). The page size and the list style are the
+ * project's `dataDisplay.itemsPerPage` and `dataDisplay.paginationStyle`, read from the shell, so a mid-build
+ * `update_rule` on either reaches every list with no page edited. The page gets what to show, the props for
+ * `<Pagination>` — page numbers, a Load more button or loading on scroll, whichever the project's style is — and the
+ * numbers the count line needs ("Showing 51–100 of 200 events", or "Showing 40 of 120 members" while a list grows).
+ *
+ * Run 58 hand-wrote the paging; runs 59 and 60 hand-wrote load-more and scroll loading — an IntersectionObserver, a
+ * visible count and a page size copied in as a constant, twice in one app — because the library had no way to.
+ *
+ *   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> {
+    /** The list style this list follows: the project's, unless `style` was passed. */
+    style: PreferencePaginationStyle;
+    /** What to show: the current page's rows, or every row loaded so far on a list that grows. */
+    items: T[];
+    /** The current page, from 1; on a growing list, how many pages are loaded. */
+    page: number;
+    pageSize: number;
+    totalItems: number;
+    totalPages: number;
+    /** The first and last row numbers on screen, from 1 ("Showing 51–100"); [0, 0] for an empty list. */
+    range: [number, number];
+    /** How many rows are on screen. */
+    shown: number;
+    /** Rows left to show: a next page, or more to load. */
+    hasMore: boolean;
+    /** The next page, or the next `pageSize` rows on a growing list. */
+    loadMore: () => void;
+    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>: it renders page numbers, a Load more button or the scroll trigger, as `style` says. */
+    props: {
+        currentPage: number;
+        totalPages: number;
+        onPageChange: (page: number) => void;
+        pageSize: number;
+        onPageSizeChange: (size: number) => void;
+        mode: PreferencePaginationStyle;
+        hasMore: boolean;
+        onLoadMore: () => 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;
+    /**
+     * A list style for this list only, over the project's. Leave it out: the project's style is the rule. Passing one that
+     * differs is overriding a rule in force — ask the user first, and put `// @gridsmith-override
+     * dataDisplay.paginationStyle: <their reason>` above the call.
+     */
+    style?: PreferencePaginationStyle;
+}
+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 +2577,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 };