react-os-shell 0.3.9 → 0.3.11

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 import { W as WindowRegistry } from './types-D_4ifuf-.js';
 export { M as ModalRegistryEntry, P as PageRegistryEntry, a as WindowRegistryEntry, i as isEntityEntry, b as isPageEntry, s as setShellWindowRegistry } from './types-D_4ifuf-.js';
 import * as react from 'react';
-import { ReactNode, CSSProperties, RefObject } from 'react';
+import react__default, { ReactNode, CSSProperties, Dispatch, SetStateAction, RefObject } from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as _tanstack_query_core from '@tanstack/query-core';
 import { AxiosInstance } from 'axios';
 
 /**
@@ -736,6 +737,230 @@ declare function StartMenu({ open, onClose, openPage, profile, user, onLogout, t
 
 declare function Customization(): react_jsx_runtime.JSX.Element;
 
+interface EntityListColumn {
+    key: string;
+    label: string;
+    defaultWidth?: number;
+    minWidth?: number;
+    defaultHidden?: boolean;
+    sortField?: string;
+    headerNode?: ReactNode;
+}
+interface EntityListProps<T> {
+    items: T[];
+    isLoading: boolean;
+    emptyState: ReactNode;
+    totalCount?: number;
+    tableId: string;
+    columns: EntityListColumn[];
+    renderCell: (item: T, colKey: string) => ReactNode;
+    getRowId?: (item: T) => string | number;
+    sort?: {
+        field: string;
+        direction: 'asc' | 'desc';
+    };
+    onSort?: (field: string) => void;
+    selected: Set<string | number>;
+    setSelected: Dispatch<SetStateAction<Set<string | number>>>;
+    onRowClick: (item: T) => void;
+    onRowHover?: (item: T) => void;
+    getRowClassName?: (item: T) => string;
+    footerLabel: string;
+    footerExtra?: ReactNode;
+    sentinelRef?: RefObject<any>;
+    isFetchingNextPage?: boolean;
+    /** Perm codenames that gate "Save as default for all users" in the column
+     *  picker. Defaults to `['change_numberingconfig']` (admin-portal's proxy
+     *  for admin access). Pass `[]` to hide the link entirely. */
+    saveDefaultPerms?: string[];
+}
+/**
+ * The canonical pageless data grid for both portals. Wraps `<ResizableTable>`
+ * with selection-checkbox logic, keyboard navigation, the standardized list
+ * footer, and an infinite-scroll sentinel hook-up.
+ *
+ * Usage:
+ *
+ *   const { sort, onSort } = useSort('mid');
+ *   const { items, totalCount, isLoading, isFetchingNextPage, sentinelRef } =
+ *     useInfiniteScroll<Supplier>({ queryKey: ['suppliers', filters],
+ *                                   fetchFn: (p) => getSuppliers(p) });
+ *
+ *   <EntityList
+ *     items={items}
+ *     totalCount={totalCount}
+ *     isLoading={isLoading}
+ *     sentinelRef={sentinelRef}
+ *     isFetchingNextPage={isFetchingNextPage}
+ *     tableId="suppliers"
+ *     columns={SUPPLIER_COLUMNS}
+ *     renderCell={(s, k) => …}
+ *     sort={sort} onSort={onSort}
+ *     selected={selected} setSelected={setSelected}
+ *     onRowClick={(s) => openEntity('supplier', s.id, s, s.mid, '/suppliers')}
+ *     footerLabel="suppliers"
+ *     emptyState={<EmptyState message="No suppliers yet." />}
+ *   />
+ */
+declare function EntityList<T>(props: EntityListProps<T>): react_jsx_runtime.JSX.Element;
+
+interface PaginatedResponse<T> {
+    count: number;
+    next: string | null;
+    previous: string | null;
+    results: T[];
+}
+interface ColumnDef {
+    key: string;
+    label: string;
+    defaultWidth?: number;
+    minWidth?: number;
+    defaultHidden?: boolean;
+    /** Optional rich header node (e.g. icon-only column). Falls back to label. */
+    headerNode?: React.ReactNode;
+    /** Optional override for the field used to sort against. */
+    sortField?: string;
+}
+interface SortState {
+    field: string;
+    direction: 'asc' | 'desc';
+}
+
+interface ResizableTableProps {
+    tableId: string;
+    columns: ColumnDef[];
+    sort?: SortState;
+    onSort?: (field: string) => void;
+    footer?: React.ReactNode;
+    afterBody?: React.ReactNode;
+    /** Permission codename(s) that gate the "Save as default for all users" link
+     *  in the column picker. The shell's `useShellAuth().hasAnyPerm` is queried
+     *  against this list. Defaults to a single placeholder permission; consumers
+     *  with no admin gate can pass `[]` to hide the link entirely. */
+    saveDefaultPerms?: string[];
+    children: (orderedColumns: (ColumnDef & {
+        width: number;
+    })[]) => React.ReactNode;
+}
+/**
+ * Sticky-header, scrollable-body table primitive with:
+ * - drag-to-reorder columns (with a blue drop-indicator line)
+ * - resize columns by the right-edge handle
+ * - hide/show columns via a glass popover picker
+ * - admin-only "Save as default for all users" link in the picker
+ * - per-user persistence (via the shell-registered apiClient)
+ * - mobile-aware selection mode toggle
+ */
+declare function ResizableTable({ tableId, columns, sort, onSort, footer, afterBody, saveDefaultPerms, children, }: ResizableTableProps): react_jsx_runtime.JSX.Element;
+
+interface ListFooterProps {
+    selectedCount: number;
+    loadedCount: number;
+    totalCount?: number;
+    label: string;
+    isFetchingMore?: boolean;
+    extra?: ReactNode;
+}
+/**
+ * Standardized footer for `EntityList`. Shows:
+ *   "[X selected — ] Y records"
+ *   "Y of Z records · Loading more..."
+ *   "All N records loaded"
+ */
+declare function ListFooter({ selectedCount, loadedCount, totalCount, label, isFetchingMore, extra, }: ListFooterProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Keyboard + shift-click navigation for table rows.
+ *
+ * - J/K or Arrow keys to move focus
+ * - Enter to open the focused row (calls `onSelect`)
+ * - Space to toggle the focused row's checkbox (calls `onToggle`)
+ * - Shift+J/K to extend selection while moving
+ * - Shift+click to range-select (calls `onSelectRange`)
+ * - Cmd/Ctrl+A to select/deselect all (calls `onSelectAll`)
+ *
+ * Each list instance gates its document-level listeners on `useModalActive`
+ * so two open lists don't both react to the same shift-click.
+ */
+declare function useTableNav<T>(items: T[], onSelect: (item: T) => void, onToggle?: (item: T) => void, onSelectAll?: () => void, onSelectRange?: (from: number, to: number) => void): number;
+
+/**
+ * Resizable + reorderable + hideable column state for `<ResizableTable>`.
+ *
+ * Persists per-user via `PATCH /auth/me/` (`preferences.columns_{tableId}`)
+ * with a 1-second debounce, and per-viewport admin defaults via
+ * `GET /auth/default-columns/{tableId}?viewport=…`. The consumer wires these
+ * endpoints on its backend; the shell's `apiClient` proxy resolves to the
+ * consumer-registered axios instance (`setShellApiClient`).
+ */
+declare function useColumnConfig(tableId: string, defaultColumns: ColumnDef[]): {
+    orderedColumns: {
+        width: number;
+        key: string;
+        label: string;
+        defaultWidth?: number;
+        minWidth?: number;
+        defaultHidden?: boolean;
+        headerNode?: react__default.ReactNode;
+        sortField?: string;
+    }[];
+    allColumns: {
+        key: string;
+        label: string;
+        hidden: boolean;
+    }[];
+    onResizeStart: (idx: number, e: react__default.MouseEvent) => void;
+    onDragStart: (idx: number) => void;
+    onDragOver: (visIdx: number, e: react__default.DragEvent) => void;
+    onDrop: (_visIdx: number, e: react__default.DragEvent) => void;
+    onDragEnd: () => void;
+    toggleColumn: (key: string) => void;
+    resetColumns: () => void;
+    draggedIdx: number | null;
+    dropGap: number | null;
+};
+
+interface UseInfiniteScrollOptions<T> {
+    /** queryKey segments — arbitrary cache shapes (filters often include booleans,
+     *  dates, undefined). Callers pass their natural filter shape. */
+    queryKey: (string | Record<string, unknown>)[];
+    fetchFn: (params: Record<string, string>) => Promise<PaginatedResponse<T>>;
+    /** Extra query-string params. Undefined values are dropped so axios doesn't
+     *  serialise them as "?key=undefined". */
+    extraParams?: Record<string, string | undefined>;
+    pageSize?: number;
+}
+/**
+ * Wraps TanStack `useInfiniteQuery` with an IntersectionObserver-driven
+ * sentinel so attaching `sentinelRef` to a div near the bottom of a scrollable
+ * container auto-fires `fetchNextPage` as the user scrolls.
+ *
+ * Works inside modal windows too — the observer roots itself on the nearest
+ * scrollable ancestor rather than the viewport.
+ */
+declare function useInfiniteScroll<T>({ queryKey, fetchFn, extraParams, pageSize: _pageSize, }: UseInfiniteScrollOptions<T>): {
+    items: T[];
+    totalCount: number;
+    isLoading: boolean;
+    isFetchingNextPage: boolean;
+    hasNextPage: boolean;
+    sentinelRef: react.RefObject<HTMLDivElement>;
+    refetch: (options?: _tanstack_query_core.RefetchOptions) => Promise<_tanstack_query_core.QueryObserverResult<_tanstack_query_core.InfiniteData<PaginatedResponse<T>, unknown>, Error>>;
+};
+
+/**
+ * Tiny sort-state hook used by list pages. Returns:
+ * - `sort` — current `{ field, direction }`
+ * - `onSort(field)` — toggle direction if same field, else activate asc
+ * - `ordering` — DRF-style string (`'-mid'` for desc, `'mid'` for asc) ready
+ *    to drop into a query-string param.
+ */
+declare function useSort(defaultField: string, defaultDir?: 'asc' | 'desc'): {
+    sort: SortState;
+    onSort: (field: string) => void;
+    ordering: string;
+};
+
 /** Package version, injected by tsup at build time. Stays as an empty
  *  string when the source is consumed without a build (e.g. tests). */
 declare const VERSION: string;
@@ -905,4 +1130,4 @@ declare function useNewHotkey(callback: () => void): void;
  */
 declare function useEditHotkey(callback: (() => void) | null): void;
 
-export { ALT, ALT_SHIFT_D, ALT_SHIFT_E, ALT_SHIFT_N, type BugReport, type BugReportConfig, BugReportConfigProvider, BugReportDetail, type BugReportExtraField, type BugReportExtraSelectField, BugReportProvider, type BugReportSubmission, type BugReportSubmitPayload, CMD_A, CMD_DOT, CMD_ENTER, CMD_K, CMD_S, CancelButton, type CellStyle, type ChangelogEntry, ConfirmProvider, CopyButton, Customization, Desktop, type DesktopHostConfig, DesktopHostProvider, DocFavStar, ENTER, EditableGrid, type EditableGridProps, type EntityFetcher, GLASS_DIVIDER, GLASS_INPUT_BG, GlobalSearch, type GridColumn, Layout, type LayoutProps, type LoginPayload, MOD, type MailCapabilities, MailConnectModal, type MailUser, Modal, ModalActions, NotificationBell, type NotificationsConfig, PopupMenu, PopupMenuDivider, PopupMenuItem, PopupMenuLabel, type ReportType, SHIFT, type SearchConfig, type SearchProvider, type SearchResult, type SemanticGroup, type ShellAuth, ShellAuthProvider, ShellEntityFetcherProvider, type ShellNotification, type ShellPrefsAdapter, ShellPrefsProvider, ShortcutHelp, StartMenu, StatusBadge, StatusBadgeProvider, type StickyEntityRef, type StickyResolver, VERSION, WindowManagerProvider, WindowRegistry, WindowTitle, commitExposeHighlight, confirm, confirmDestructive, createWindowRegistry, exitExposeMode, formatDate, getActiveWindowRoute, getExposeHighlight, glassStyle, isMac, openBugReportDialog, prompt, reportBug, setExposeHighlight, setShellApiClient, setShellAuthBridge, setShellMailServer, setShellNavIcons, setWindowDefaultPosition, subscribeExposeHighlight, toast, toggleExposeMode, useBugReport, useClickOutside, useDesktopHost, useEditHotkey, useLocalStoragePrefs, useMailAuth, useModalActive, useNewHotkey, useShellAuth, useShellEntityFetcher, useShellPrefs, useWidgetSettings, useWindowManager, useWindowMenuItem, useWindowTitle };
+export { ALT, ALT_SHIFT_D, ALT_SHIFT_E, ALT_SHIFT_N, type BugReport, type BugReportConfig, BugReportConfigProvider, BugReportDetail, type BugReportExtraField, type BugReportExtraSelectField, BugReportProvider, type BugReportSubmission, type BugReportSubmitPayload, CMD_A, CMD_DOT, CMD_ENTER, CMD_K, CMD_S, CancelButton, type CellStyle, type ChangelogEntry, type ColumnDef, ConfirmProvider, CopyButton, Customization, Desktop, type DesktopHostConfig, DesktopHostProvider, DocFavStar, ENTER, EditableGrid, type EditableGridProps, type EntityFetcher, EntityList, type EntityListColumn, type EntityListProps, GLASS_DIVIDER, GLASS_INPUT_BG, GlobalSearch, type GridColumn, Layout, type LayoutProps, ListFooter, type LoginPayload, MOD, type MailCapabilities, MailConnectModal, type MailUser, Modal, ModalActions, NotificationBell, type NotificationsConfig, type PaginatedResponse, PopupMenu, PopupMenuDivider, PopupMenuItem, PopupMenuLabel, type ReportType, ResizableTable, SHIFT, type SearchConfig, type SearchProvider, type SearchResult, type SemanticGroup, type ShellAuth, ShellAuthProvider, ShellEntityFetcherProvider, type ShellNotification, type ShellPrefsAdapter, ShellPrefsProvider, ShortcutHelp, type SortState, StartMenu, StatusBadge, StatusBadgeProvider, type StickyEntityRef, type StickyResolver, VERSION, WindowManagerProvider, WindowRegistry, WindowTitle, commitExposeHighlight, confirm, confirmDestructive, createWindowRegistry, exitExposeMode, formatDate, getActiveWindowRoute, getExposeHighlight, glassStyle, isMac, openBugReportDialog, prompt, reportBug, setExposeHighlight, setShellApiClient, setShellAuthBridge, setShellMailServer, setShellNavIcons, setWindowDefaultPosition, subscribeExposeHighlight, toast, toggleExposeMode, useBugReport, useClickOutside, useColumnConfig, useDesktopHost, useEditHotkey, useInfiniteScroll, useLocalStoragePrefs, useMailAuth, useModalActive, useNewHotkey, useShellAuth, useShellEntityFetcher, useShellPrefs, useSort, useTableNav, useWidgetSettings, useWindowManager, useWindowMenuItem, useWindowTitle };