@geomak/ui 1.7.1 → 1.7.3

package/dist/index.d.cts

@@ -588,16 +588,44 @@ declare function useNotification(): {
 };
 
 interface LoadingSpinnerProps {
-    /** Text animated letter by letter */
+    /** Text revealed letter-by-letter beneath the spinner. */
     prompt: string;
+    /**
+     * Optional override for the spinner ring colour. Accepts any CSS colour.
+     * Defaults to the accent token so it picks up theme overrides.
+     */
+    spinnerColor?: string;
+    /**
+     * Optional override for the prompt text colour.
+     * Defaults to the foreground token (light/dark aware).
+     */
+    textColor?: string;
+    /**
+     * Backdrop opacity (0 – 1). Defaults to 0.92 — close enough to opaque to
+     * block UI underneath while still hinting at the previous state.
+     */
+    backdropOpacity?: number;
 }
 /**
- * Full-screen loading overlay with a spinning shape and staggered text reveal.
+ * Full-screen loading overlay with a spinning ring and a staggered text
+ * reveal. Portaled into `document.body` so it always covers the actual
+ * viewport regardless of where it's rendered in the React tree.
+ *
+ * Honours `prefers-reduced-motion`: the spinner still rotates (continuous
+ * spin is informative, not decorative) but the letter stagger collapses to
+ * an instant reveal.
  *
  * @example
- * {isLoading && <LoadingSpinner prompt="Loading data..." />}
+ * {isLoading && <LoadingSpinner prompt="Loading vessels…" />}
+ *
+ * @example
+ * <LoadingSpinner
+ *   prompt="Saving"
+ *   spinnerColor="#10b981"
+ *   backdropOpacity={0.7}
+ * />
  */
-declare function LoadingSpinner({ prompt }: LoadingSpinnerProps): react_jsx_runtime.JSX.Element;
+declare function LoadingSpinner({ prompt, spinnerColor, textColor, backdropOpacity, }: LoadingSpinnerProps): react_jsx_runtime.JSX.Element;
 
 interface FadingBaseProps {
     className?: string;
@@ -857,11 +885,34 @@ interface WizardProps {
 declare function Wizard({ children, steps, storageKey }: WizardProps): react_jsx_runtime.JSX.Element;
 
 /** ─────────────────── types ─────────────────── */
-interface TableColumn {
-    key: string | number;
+/**
+ * Column descriptor for the Table.
+ *
+ * The generic `T` is the shape of a row — `keyBind` must be one of T's
+ * string-keyed properties, and `component(cellValue, row)` receives the
+ * matching value with full type inference. When used without a generic
+ * (`TableColumn[]`), `T` falls back to `Record<string, any>` for backwards
+ * compatibility — narrower typing is preferred whenever possible:
+ *
+ * ```ts
+ * type Vessel = { id: number; name: string; status: 'At Sea' | 'In Port' }
+ * const cols: TableColumn<Vessel>[] = [
+ *   { key: 'name', label: 'Name', keyBind: 'name' }, // cellValue inferred as string
+ * ]
+ * ```
+ */
+interface TableColumn<T extends Record<string, any> = Record<string, any>> {
+    /** React reconciliation key for the column itself. */
+    key: React$1.Key;
     label: React$1.ReactNode;
-    keyBind: string;
-    component?: (cellValue: any, row: any) => React$1.ReactNode;
+    /** Property on the row to read for this column. */
+    keyBind: keyof T & string;
+    /** Custom cell renderer. Receives the cell value and the full row. */
+    component?: (cellValue: T[keyof T], row: T) => React$1.ReactNode;
+    /** Explicit column width (CSS length or px number). Optional — defaults to auto. */
+    width?: string | number;
+    /** Text alignment for both header and cells. Defaults to `'center'`. */
+    align?: 'left' | 'center' | 'right';
 }
 interface PaginationOptions {
     enabled?: boolean;
@@ -882,36 +933,70 @@ interface PaginationOptions {
     onPageChange?: (page: number) => void;
     onPerPageChange?: (perPage: number) => void;
 }
-interface ExpandRowOptions {
+interface ExpandRowOptions<T extends Record<string, any> = Record<string, any>> {
     enabled?: boolean;
     expandIcon?: React$1.ReactNode;
-    expandComponent?: (row: any) => React$1.ReactNode;
+    expandComponent?: (row: T) => React$1.ReactNode;
 }
-interface TableProps {
-    columns?: TableColumn[];
-    rows?: any[];
+interface TableProps<T extends Record<string, any> = Record<string, any>> {
+    columns?: TableColumn<T>[];
+    rows?: T[];
+    /**
+     * Returns a stable key for each row, used for React reconciliation AND
+     * for tracking expanded state when `expandRow.enabled` is true.
+     * Defaults to the row index — fine for static lists, but pass an
+     * explicit getter (e.g. `(row) => row.id`) if rows can be reordered or
+     * filtered while expand state should persist.
+     */
+    getRowKey?: (row: T, index: number) => React$1.Key;
     pagination?: PaginationOptions;
-    expandRow?: ExpandRowOptions;
+    expandRow?: ExpandRowOptions<T>;
     hasSearch?: boolean;
     footer?: React$1.ReactNode;
     header?: React$1.ReactNode;
-    tableRef?: React$1.Ref<any>;
-    [key: string]: any;
 }
 /** ─────────────────── main component ─────────────────── */
 /**
  * Data table with optional search, pagination, and expandable rows.
  *
- * Supports both client-side and server-side pagination.
+ * - **Typed rows**: pass a generic `T` for full type inference on columns
+ *   and cell renderers (`<Table<Vessel> ... />`).
+ * - **Real `<table>` semantics**: keeps row / col / cell context intact for
+ *   screen readers and lets the browser handle column sizing natively.
+ *   Per-column widths via `column.width`.
+ * - **Search**: client-side filter across ALL row values; result is
+ *   memoized so each keystroke costs O(n) once per term change, not per
+ *   render. Set `pagination.serverSide` to skip client-side filter and
+ *   pagination entirely.
+ * - **Expand**: each row gets a real `<button>` with `aria-expanded`.
+ *   Expand state is keyed by `getRowKey(row, i)` so it survives reorders.
+ *
+ * @example Static, fully typed
+ * ```tsx
+ * type Vessel = { id: number; name: string; status: string }
+ * <Table<Vessel>
+ *   columns={[
+ *     { key: 'name', label: 'Name', keyBind: 'name' },
+ *     { key: 'status', label: 'Status', keyBind: 'status', width: 120 },
+ *   ]}
+ *   rows={vessels}
+ *   getRowKey={(row) => row.id}
+ * />
+ * ```
  *
- * @example
+ * @example Server-side pagination
+ * ```tsx
  * <Table
- *   columns={[{ key: 'name', label: 'Name', keyBind: 'name' }]}
- *   rows={data}
- *   pagination={{ enabled: true, perPage: 15 }}
+ *   columns={cols}
+ *   rows={pageRows}
+ *   pagination={{
+ *     enabled: true, serverSide: true, perPage: 20,
+ *     page: currentPage, totalCount, onPageChange, onPerPageChange,
+ *   }}
  * />
+ * ```
  */
-declare function Table({ columns, rows, pagination, expandRow, hasSearch, footer, header, }: TableProps): react_jsx_runtime.JSX.Element;
+declare function Table<T extends Record<string, any> = Record<string, any>>({ columns, rows, getRowKey, pagination, expandRow, hasSearch, footer, header, }: TableProps<T>): react_jsx_runtime.JSX.Element;
 
 interface ThemeSwitchProps {
     checked: boolean;

package/dist/index.d.ts

@@ -588,16 +588,44 @@ declare function useNotification(): {
 };
 
 interface LoadingSpinnerProps {
-    /** Text animated letter by letter */
+    /** Text revealed letter-by-letter beneath the spinner. */
     prompt: string;
+    /**
+     * Optional override for the spinner ring colour. Accepts any CSS colour.
+     * Defaults to the accent token so it picks up theme overrides.
+     */
+    spinnerColor?: string;
+    /**
+     * Optional override for the prompt text colour.
+     * Defaults to the foreground token (light/dark aware).
+     */
+    textColor?: string;
+    /**
+     * Backdrop opacity (0 – 1). Defaults to 0.92 — close enough to opaque to
+     * block UI underneath while still hinting at the previous state.
+     */
+    backdropOpacity?: number;
 }
 /**
- * Full-screen loading overlay with a spinning shape and staggered text reveal.
+ * Full-screen loading overlay with a spinning ring and a staggered text
+ * reveal. Portaled into `document.body` so it always covers the actual
+ * viewport regardless of where it's rendered in the React tree.
+ *
+ * Honours `prefers-reduced-motion`: the spinner still rotates (continuous
+ * spin is informative, not decorative) but the letter stagger collapses to
+ * an instant reveal.
  *
  * @example
- * {isLoading && <LoadingSpinner prompt="Loading data..." />}
+ * {isLoading && <LoadingSpinner prompt="Loading vessels…" />}
+ *
+ * @example
+ * <LoadingSpinner
+ *   prompt="Saving"
+ *   spinnerColor="#10b981"
+ *   backdropOpacity={0.7}
+ * />
  */
-declare function LoadingSpinner({ prompt }: LoadingSpinnerProps): react_jsx_runtime.JSX.Element;
+declare function LoadingSpinner({ prompt, spinnerColor, textColor, backdropOpacity, }: LoadingSpinnerProps): react_jsx_runtime.JSX.Element;
 
 interface FadingBaseProps {
     className?: string;
@@ -857,11 +885,34 @@ interface WizardProps {
 declare function Wizard({ children, steps, storageKey }: WizardProps): react_jsx_runtime.JSX.Element;
 
 /** ─────────────────── types ─────────────────── */
-interface TableColumn {
-    key: string | number;
+/**
+ * Column descriptor for the Table.
+ *
+ * The generic `T` is the shape of a row — `keyBind` must be one of T's
+ * string-keyed properties, and `component(cellValue, row)` receives the
+ * matching value with full type inference. When used without a generic
+ * (`TableColumn[]`), `T` falls back to `Record<string, any>` for backwards
+ * compatibility — narrower typing is preferred whenever possible:
+ *
+ * ```ts
+ * type Vessel = { id: number; name: string; status: 'At Sea' | 'In Port' }
+ * const cols: TableColumn<Vessel>[] = [
+ *   { key: 'name', label: 'Name', keyBind: 'name' }, // cellValue inferred as string
+ * ]
+ * ```
+ */
+interface TableColumn<T extends Record<string, any> = Record<string, any>> {
+    /** React reconciliation key for the column itself. */
+    key: React$1.Key;
     label: React$1.ReactNode;
-    keyBind: string;
-    component?: (cellValue: any, row: any) => React$1.ReactNode;
+    /** Property on the row to read for this column. */
+    keyBind: keyof T & string;
+    /** Custom cell renderer. Receives the cell value and the full row. */
+    component?: (cellValue: T[keyof T], row: T) => React$1.ReactNode;
+    /** Explicit column width (CSS length or px number). Optional — defaults to auto. */
+    width?: string | number;
+    /** Text alignment for both header and cells. Defaults to `'center'`. */
+    align?: 'left' | 'center' | 'right';
 }
 interface PaginationOptions {
     enabled?: boolean;
@@ -882,36 +933,70 @@ interface PaginationOptions {
     onPageChange?: (page: number) => void;
     onPerPageChange?: (perPage: number) => void;
 }
-interface ExpandRowOptions {
+interface ExpandRowOptions<T extends Record<string, any> = Record<string, any>> {
     enabled?: boolean;
     expandIcon?: React$1.ReactNode;
-    expandComponent?: (row: any) => React$1.ReactNode;
+    expandComponent?: (row: T) => React$1.ReactNode;
 }
-interface TableProps {
-    columns?: TableColumn[];
-    rows?: any[];
+interface TableProps<T extends Record<string, any> = Record<string, any>> {
+    columns?: TableColumn<T>[];
+    rows?: T[];
+    /**
+     * Returns a stable key for each row, used for React reconciliation AND
+     * for tracking expanded state when `expandRow.enabled` is true.
+     * Defaults to the row index — fine for static lists, but pass an
+     * explicit getter (e.g. `(row) => row.id`) if rows can be reordered or
+     * filtered while expand state should persist.
+     */
+    getRowKey?: (row: T, index: number) => React$1.Key;
     pagination?: PaginationOptions;
-    expandRow?: ExpandRowOptions;
+    expandRow?: ExpandRowOptions<T>;
     hasSearch?: boolean;
     footer?: React$1.ReactNode;
     header?: React$1.ReactNode;
-    tableRef?: React$1.Ref<any>;
-    [key: string]: any;
 }
 /** ─────────────────── main component ─────────────────── */
 /**
  * Data table with optional search, pagination, and expandable rows.
  *
- * Supports both client-side and server-side pagination.
+ * - **Typed rows**: pass a generic `T` for full type inference on columns
+ *   and cell renderers (`<Table<Vessel> ... />`).
+ * - **Real `<table>` semantics**: keeps row / col / cell context intact for
+ *   screen readers and lets the browser handle column sizing natively.
+ *   Per-column widths via `column.width`.
+ * - **Search**: client-side filter across ALL row values; result is
+ *   memoized so each keystroke costs O(n) once per term change, not per
+ *   render. Set `pagination.serverSide` to skip client-side filter and
+ *   pagination entirely.
+ * - **Expand**: each row gets a real `<button>` with `aria-expanded`.
+ *   Expand state is keyed by `getRowKey(row, i)` so it survives reorders.
+ *
+ * @example Static, fully typed
+ * ```tsx
+ * type Vessel = { id: number; name: string; status: string }
+ * <Table<Vessel>
+ *   columns={[
+ *     { key: 'name', label: 'Name', keyBind: 'name' },
+ *     { key: 'status', label: 'Status', keyBind: 'status', width: 120 },
+ *   ]}
+ *   rows={vessels}
+ *   getRowKey={(row) => row.id}
+ * />
+ * ```
  *
- * @example
+ * @example Server-side pagination
+ * ```tsx
  * <Table
- *   columns={[{ key: 'name', label: 'Name', keyBind: 'name' }]}
- *   rows={data}
- *   pagination={{ enabled: true, perPage: 15 }}
+ *   columns={cols}
+ *   rows={pageRows}
+ *   pagination={{
+ *     enabled: true, serverSide: true, perPage: 20,
+ *     page: currentPage, totalCount, onPageChange, onPerPageChange,
+ *   }}
  * />
+ * ```
  */
-declare function Table({ columns, rows, pagination, expandRow, hasSearch, footer, header, }: TableProps): react_jsx_runtime.JSX.Element;
+declare function Table<T extends Record<string, any> = Record<string, any>>({ columns, rows, getRowKey, pagination, expandRow, hasSearch, footer, header, }: TableProps<T>): react_jsx_runtime.JSX.Element;
 
 interface ThemeSwitchProps {
     checked: boolean;