@sebgroup/green-core 3.9.0 → 3.11.0

package/components/table/table.types.d.ts

@@ -3,47 +3,121 @@
  *  TABLE TYPES
  * ============================================================================
  */
+/**
+ * Column definition describing how a row field is rendered and behaves.
+ */
 export interface Column {
+    /** Property key in the row object and the basis for generated slot names. */
     key: string;
+    /**
+     * Optional raw value extractor used for display, sorting, and search when a
+     * simple row[key] lookup is not sufficient.
+     */
     value?: (row: any) => string;
+    /** Text shown in the column header. */
     label: string;
+    /** Enables click-to-sort for the column header. */
     sortable?: boolean;
+    /** Vertical alignment for cell content. */
     align?: 'start' | 'center' | 'stretch' | 'end';
+    /** Horizontal justification for cell content. */
     justify?: 'start' | 'center' | 'space-between' | 'end';
+    /** Controls whether the column is shown in the table and settings UI. */
     visible?: boolean;
+    /** Fixed CSS width for the column. */
     width?: string;
+    /** Keeps the column pinned to the left or right while horizontally scrolling. */
+    sticky?: 'left' | 'right';
 }
-export interface Actions {
-    label?: string;
-    align?: 'start' | 'center' | 'stretch' | 'end';
-    justify?: 'start' | 'center' | 'space-between' | 'end';
-    width?: string;
-    sticky?: boolean;
-}
+/**
+ * Footer row configuration for aggregated or summary content rendered through
+ * `tfoot:columnKey` slots.
+ */
 export interface Tfoot {
+    /** Optional first-cell label rendered as a row header for accessibility. */
     label?: string;
+    /** Pins the footer row to the bottom of the scroll area. */
     sticky?: boolean;
 }
-export interface Row {
-    [key: string]: any;
-}
+/**
+ * Built-in expandable metadata available on each row.
+ */
+export type RowMeta<T extends Record<string, unknown> = Record<string, unknown>> = {
+    /** Marks whether this row should render an expand toggle. */
+    isExpandable?: boolean;
+    /** Optional per-row label for collapsed state toggle action. */
+    expandLabel?: string;
+    /** Optional per-row label for expanded state toggle action. */
+    collapseLabel?: string;
+    /**
+     * Async readiness signal for slotted full-width expanded content.
+     * Called when the row is expanded. The table shows a loading skeleton
+     * until the returned promise resolves, then reveals the
+     * `expand:ROW_KEY:full` slot. Consumers can resolve immediately or
+     * after fetching dynamic data into the slot.
+     */
+    fullContent?: () => Promise<boolean>;
+    /**
+     * Optional expected number of sub rows, used to size loading placeholders
+     * while async sub rows are being resolved.
+     */
+    subRowCount?: number;
+    /**
+     * Async sub row provider called when the parent row is expanded.
+     * The table shows skeleton placeholder rows (sized by `subRowCount`)
+     * until the returned promise resolves, then renders the child rows
+     * using the same column structure. Consumers can resolve immediately
+     * with pre-fetched data or after a dynamic fetch.
+     */
+    subRows?: () => Promise<Row<T>[]>;
+};
+/**
+ * Generic table row shape. Consumers extend this with application-specific
+ * fields while keeping built-in row metadata strongly typed.
+ */
+export type Row<T extends Record<string, unknown> = Record<string, unknown>> = Omit<T, keyof RowMeta<T>> & RowMeta<T>;
+/**
+ * Internal table state used to drive paging, sorting, searching, and column
+ * visibility.
+ */
 export interface State {
+    /** Current page number, using 1-based indexing. */
     page: number;
+    /** Number of rows requested per page. */
     rows: number;
+    /** Column key currently used for sorting. */
     sortColumn?: string;
+    /** Active sort direction for the current sort column. */
     sortDirection?: 'asc' | 'desc';
+    /** Current search term applied to the dataset. */
     searchQuery: string;
+    /** Set of column keys currently visible in the table. */
     visibleColumns: Set<string>;
 }
+/**
+ * Request object sent from the table to the data provider for fetching the
+ * current page of rows.
+ */
 export interface Request {
+    /** Current page number, using 1-based indexing. */
     page: number;
+    /** Number of rows requested per page. */
     rows: number;
+    /** Column key to sort by. */
     sortColumn?: string;
+    /** Requested sort direction. */
     sortDirection?: 'asc' | 'desc';
+    /** Optional search term to filter the dataset. */
     searchQuery?: string;
 }
+/**
+ * Data provider response containing the current page rows and the total number
+ * of matching rows for pagination.
+ */
 export interface Response<T> {
+    /** Rows to render for the current page. */
     rows: T[];
+    /** Total number of matching rows across all pages. */
     total: number;
 }
 /**
@@ -65,25 +139,37 @@ export declare const DENSITY_CONFIG: {
         readonly dropdown: "medium";
     };
 };
+/** Density options for the table's built-in controls. */
 export type Density = 'comfortable' | 'compact' | 'spacious';
+/** Cached data provider result keyed by page, rows, sort, and search state. */
 export interface CacheEntry<T> {
+    /** Cached rows for the request key. */
     rows: T[];
+    /** Cached total matching row count. */
     total: number;
+    /** Timestamp in milliseconds used to expire stale cache entries. */
     timestamp: number;
 }
+/** Map of cache keys to cached table responses. */
 export interface Cache<T> {
     [key: string]: CacheEntry<T>;
 }
+/**
+ * Slot-enabled cell value used to compose rich cell content while preserving a
+ * fallback value for sorting, searching, and string coercion.
+ */
 export type SlotValue = {
+    /** Fallback plain value used for display, search, and sort comparisons. */
     value?: unknown;
+    /** Ordered slot ids that define the cell layout. Use `value` for inline text. */
     slots: string[];
+    /** Optional row key override used when generating slot names. */
     key?: string | number;
 };
 export declare const isSlotValue: (value: unknown) => value is SlotValue;
 export declare function Slot(config: SlotValue): SlotValue;
 export declare function Slot(value?: unknown, slots?: string[], key?: string | number): SlotValue;
 export declare function Slot(value?: unknown, key?: string | number, slots?: string[]): SlotValue;
-export type TableActions = Actions;
 export type TableColumn = Column;
 export type TableRow = Row;
 export type TableState = State;