@exxatdesignux/ui 0.2.18 → 0.3.0

package/dist/components/data-views/hub-table.d.ts

@@ -0,0 +1,167 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as React from 'react';
+import { ColumnDef } from '../data-table/types.js';
+import { useTableState } from '../data-table/use-table-state.js';
+import { DataListViewType } from '../../lib/data-list-view.js';
+import { c as DataListViewRenderKind } from '../../data-list-view-registry-CyBoBML4.js';
+import { DataListDisplayOptions } from '../../lib/data-list-display-options.js';
+import { FilterFieldDef, ConditionalRule } from '../../lib/table-properties-types.js';
+import { ListPageBoardColumnDef } from './list-page-board-template.js';
+import { OpenTablePropertiesHandle } from '../../lib/list-page-table-properties.js';
+import '../../lib/row-height.js';
+
+/** Derive `FilterFieldDef[]` from a hub's column defs — preferred to hand-writing both. */
+declare function columnsToFilterFields<TRow>(cols: ColumnDef<TRow>[]): FilterFieldDef[];
+/** Field definitions for the drawer's Sort / Group / Columns panels — excludes utility columns. */
+declare function columnsToFieldDefinitions<TRow>(cols: ColumnDef<TRow>[]): {
+    key: string;
+    label: string;
+    sortable: boolean;
+}[];
+/** Subset of `TablePropertiesDrawerButton` props that `HubTable` owns. Exposed so renderers
+ * that build a custom toolbar (e.g. dashboard with an extra Edit-layout button) can splat
+ * this back into their own `<TablePropertiesDrawerButton {...drawerToolbarProps} state={s} extraActions={…} />`. */
+interface HubDrawerToolbarProps {
+    totalRows: number;
+    filterFields: FilterFieldDef[];
+    fieldDefinitions: {
+        key: string;
+        label: string;
+        sortable: boolean;
+    }[];
+    resolveColumnLabel: (key: string) => string;
+    displayOptions: DataListDisplayOptions;
+    onDisplayOptionsChange: (patch: Partial<DataListDisplayOptions>) => void;
+    conditionalRules: ConditionalRule[];
+    onAddConditionalRule: (rule: Omit<ConditionalRule, "id">) => void;
+    onRemoveConditionalRule: (id: string) => void;
+    onUpdateConditionalRule: (id: string, patch: Partial<ConditionalRule>) => void;
+    currentView: DataListViewType;
+    onViewChange?: (v: DataListViewType) => void;
+    supportedViewTypes: readonly DataListViewType[];
+    lifecycleTabLabel: string;
+    boardGroupByColumnOptions?: {
+        key: string;
+        label: string;
+    }[];
+    renderFilterOptionValue?: (fieldKey: string, value: string) => React.ReactNode;
+    pagination?: boolean;
+    onPaginationChange?: (v: boolean) => void;
+}
+/** Everything a non-table renderer needs. The pre-composed `toolbar` includes search +
+ * filter chips + the Properties button; the renderer just wraps it around its body with
+ * `toolbarShell`. For dashboards or other layouts that own their own toolbar, use
+ * `drawerToolbarProps` to assemble a custom `<TablePropertiesDrawerButton>`. */
+interface HubTableRendererArgs<TRow extends Record<string, unknown>> {
+    state: ReturnType<typeof useTableState<TRow>>;
+    toolbar: React.ReactNode;
+    toolbarShell: (body: React.ReactNode) => React.ReactNode;
+    drawerToolbarProps: HubDrawerToolbarProps;
+    displayOptions: DataListDisplayOptions;
+    patchDisplay: (patch: Partial<DataListDisplayOptions>) => void;
+}
+/** Hubs provide one renderer per `DataListViewRenderKind` they implement. The `data-table`
+ * kind is handled internally by `HubTable` (do not override unless you genuinely need a
+ * different table surface). Missing kinds render `<ListPageViewNotConfigured>` — clear empty
+ * state, never a silent dashboard fallback. */
+type HubTableRenderers<TRow extends Record<string, unknown>> = Partial<Record<DataListViewRenderKind, (args: HubTableRendererArgs<TRow>) => React.ReactNode>>;
+type HubTableHandle = OpenTablePropertiesHandle;
+interface HubTableProps<TRow extends Record<string, unknown>> {
+    /** Full row dataset (already scoped/filtered by the hub client, e.g. by URL nav). */
+    rows: TRow[];
+    /** Column defs — `filter` blocks here become Properties drawer filter fields automatically. */
+    columns: ColumnDef<TRow>[];
+    /** Active view from the `ListPageTemplate` tab. */
+    view: DataListViewType;
+    onViewChange?: (v: DataListViewType) => void;
+    /** Allowlist passed to `TablePropertiesDrawerButton` so Properties cannot offer unsupported views. */
+    supportedViewTypes: readonly DataListViewType[];
+    /** Used by `ListPageViewNotConfigured` when a supported view has no renderer. */
+    hubLabel: string;
+    /** Shown below "Properties" in the drawer header. */
+    lifecycleTabLabel: string;
+    /** Toolbar search input aria-label. */
+    searchAriaLabel: string;
+    getRowId: (row: TRow) => string | number;
+    getRowSelectionLabel: (row: TRow) => string;
+    defaultSort: {
+        key: string;
+        dir: "asc" | "desc";
+    };
+    /** DataTable empty state. Defaults to a muted "No records match your filters." */
+    emptyState?: React.ReactNode;
+    /** Per-view renderers (everything other than `view === "table"`). */
+    renderers: HubTableRenderers<TRow>;
+    /** Bulk-actions slot rendered when one or more rows are selected. */
+    bulkActionsSlot?: (selected: Set<string | number>) => React.ReactNode;
+    /** Board-view group-by column options for the Properties drawer. */
+    boardGroupByColumnOptions?: {
+        key: string;
+        label: string;
+    }[];
+    /** Initial display options (toolbar search visibility, calendar panel, etc.). */
+    displayOptionsInit?: DataListDisplayOptions;
+    /** Custom renderer for filter option values (e.g. status chips). */
+    renderFilterOptionValue?: (fieldKey: string, value: string) => React.ReactNode;
+    /** DataTable: enable "Group by" feature. Default `true`. */
+    groupable?: boolean;
+    /** DataTable: enable row selection checkboxes. Default `true`. */
+    selectable?: boolean;
+    /** DataTable: row click handler (e.g. navigate to detail route). */
+    onRowClick?: (row: TRow) => void;
+    /**
+     * Controlled `displayOptions` — when provided (with `onDisplayOptionsChange`), the hub client
+     * owns persistence (e.g. Placements page persists across tab switches). Otherwise `HubTable`
+     * owns internal state from `displayOptionsInit`.
+     */
+    displayOptions?: DataListDisplayOptions;
+    onDisplayOptionsChange?: (patch: Partial<DataListDisplayOptions>) => void;
+    /**
+     * Pagination toggle forwarded to `TablePropertiesDrawerButton` so the drawer can offer
+     * "Show pagination" on the Display panel. The hub still implements its own pagination chrome
+     * around the table body via `tableRenderer`. Defaults to `false` / no toggle.
+     */
+    pagination?: boolean;
+    onPaginationChange?: (v: boolean) => void;
+    /** Imperative handle (`openPropertiesDrawer`) for hub clients that pass `tablePropertiesRef`. */
+    handleRef?: React.Ref<HubTableHandle>;
+    /** Optional override for the `data-table` view. Default mounts `<DataTable {…}>`. */
+    tableRenderer?: (args: HubTableRendererArgs<TRow>) => React.ReactNode;
+    /**
+     * Forwarded to `useTableState` so the hub can switch on server-style pagination
+     * (e.g. Placements toggles between paged and unpaged tables).
+     */
+    paginationOverride?: {
+        page: number;
+        pageSize: number;
+    };
+    /**
+     * Forwarded to `useTableState` to sync toolbar search from `?q=` (Question bank search routes).
+     * Defining as `""` enables sync without an initial query.
+     */
+    syncedSearchFromUrl?: string;
+    /** Default `list-with-toolbar` renderer body — `HubTable` wraps with toolbar + `DataRowList`. */
+    renderListRow?: (row: TRow) => React.ReactNode;
+    /** Override the `aria-label` on the `<ul>` from `renderListRow`. Defaults to `hubLabel`. */
+    listAriaLabel?: string;
+    /** Empty-state for the default list renderer. Defaults to "No records match your filters." */
+    listEmptyState?: React.ReactNode;
+    /** Virtualise after N rows in the default list renderer. Default 100; pass `0` to disable. */
+    listVirtualizeThreshold?: number;
+    /** Estimated row height (px) for the default list virtualiser. Default 96. */
+    listEstimatedRowHeight?: number;
+    /** Default `board-with-toolbar` renderer body — `HubTable` wraps with toolbar + `ListPageBoardTemplate`. */
+    renderBoardCard?: (row: TRow) => React.ReactNode;
+    /** Required if `renderBoardCard` is set: how rows group into columns. */
+    boardGroups?: ListPageBoardColumnDef<TRow>[];
+    /** Per-column count badge tint classes for the default board renderer. */
+    boardColumnCountBadgeClassName?: Record<string, string>;
+    /** Empty column copy for the default board renderer. Defaults to "No items". */
+    boardEmptyColumnLabel?: string;
+}
+declare function HubTable<TRow extends Record<string, unknown>>({ rows, columns, view, onViewChange, supportedViewTypes, hubLabel, lifecycleTabLabel, searchAriaLabel, getRowId, getRowSelectionLabel, defaultSort, emptyState, renderers, bulkActionsSlot, boardGroupByColumnOptions, displayOptionsInit, renderFilterOptionValue, groupable, selectable, onRowClick, displayOptions: displayOptionsControlled, onDisplayOptionsChange: onDisplayOptionsChangeControlled, pagination, onPaginationChange, handleRef, tableRenderer, paginationOverride, syncedSearchFromUrl, renderListRow, listAriaLabel, listEmptyState, listVirtualizeThreshold, listEstimatedRowHeight, renderBoardCard, boardGroups, boardColumnCountBadgeClassName, boardEmptyColumnLabel, }: HubTableProps<TRow>): react_jsx_runtime.JSX.Element;
+declare namespace HubTable {
+    var displayName: string;
+}
+
+export { type HubDrawerToolbarProps, HubTable, type HubTableHandle, type HubTableProps, type HubTableRendererArgs, type HubTableRenderers, columnsToFieldDefinitions, columnsToFilterFields };