@customafk/lunas-ui 0.2.4 → 0.2.6

package/dist/features/tables/index.d.cts

@@ -1,79 +1,219 @@
-import { t as AnyEntity } from "../../types-Bd0JePtp.cjs";
-import { t as Input } from "../../input-DhQmoNrK.cjs";
-import * as react_jsx_runtime346 from "react/jsx-runtime";
-import * as react267 from "react";
+import { t as AnyEntity } from "../../types-CDYHkcOk.cjs";
+import { t as Input } from "../../input-DPLvx5x8.cjs";
+import * as react_jsx_runtime332 from "react/jsx-runtime";
+import * as react273 from "react";
 import { AccessorKeyColumnDef, CellContext, Column, ColumnPinningPosition, ColumnPinningState, Header, HeaderGroup, Row, RowSelectionState, Table } from "@tanstack/react-table";
 import { VirtualItem, Virtualizer } from "@tanstack/react-virtual";
 
 //#region packages/components/features/tables/components/atoms/badge-display.d.ts
+
+/**
+ * Renders a pill-shaped badge for a table cell that optionally supports a click
+ * action and an inline remove button; falls back to {@link UITableEmpty} when
+ * `label` is falsy.
+ *
+ * @example
+ * import { UITableBadgeDisplay } from '@customafk/lunas-ui/features/tables';
+ *
+ * <UITableBadgeDisplay
+ *   label="Active"
+ *   onClick={() => console.log('badge clicked')}
+ *   onRemove={() => console.log('remove clicked')}
+ * />
+ */
 declare const UITableBadgeDisplay: React.FC<{
+  /** The text or number to display inside the badge. */
   label: string | number | null | undefined;
+  /** Optional callback fired when the badge itself is clicked. */
   onClick?: () => void;
+  /** When provided, renders a remove (×) button and fires this callback on click. */
   onRemove?: () => void;
 }>;
 //#endregion
 //#region packages/components/features/tables/components/atoms/boolean-display.d.ts
+/**
+ * Displays a green check icon for `true`, a red X icon for `false`, and a
+ * double-dash placeholder via {@link UITableEmpty} when the value is
+ * `null` or `undefined`.
+ *
+ * @example
+ * import { UITableBooleanDisplay } from '@customafk/lunas-ui/features/tables';
+ *
+ * <UITableBooleanDisplay value={isActive} />
+ */
 declare const UITableBooleanDisplay: React.FC<{
+  /** The boolean value to visualise; `null`/`undefined` renders an empty state. */
   value: boolean | null | undefined;
 }>;
 //#endregion
 //#region packages/components/features/tables/components/atoms/date-display.d.ts
+/** Props for the {@link UITableDateDisplay} component. */
 type Props$2 = {
+  /** The date value to format and display; `null`/`undefined` renders an empty state. */
   date: Date | string | number | null | undefined;
 };
+/**
+ * Displays a date as a compact badge in a table cell with a tooltip that shows
+ * the full date and time on hover; renders {@link UITableEmpty} when `date` is
+ * `null` or `undefined`.
+ *
+ * @example
+ * import { UITableDateDisplay } from '@customafk/lunas-ui/features/tables';
+ *
+ * <UITableDateDisplay date={new Date('2024-06-15T10:30:00Z')} />
+ */
 declare const UITableDateDisplay: React.FC<Props$2>;
 //#endregion
 //#region packages/components/features/tables/components/atoms/description-display.d.ts
+/**
+ * Renders a two-line-clamped description in a table cell with a tooltip that
+ * reveals the full text and its character count; falls back to
+ * {@link UITableEmpty} when `content` is `null` or `undefined`.
+ *
+ * @example
+ * import { UITableDescriptionDisplay } from '@customafk/lunas-ui/features/tables';
+ *
+ * <UITableDescriptionDisplay content="A detailed description of this record." />
+ */
 declare const UITableDescriptionDisplay: React.FC<{
+  /** The text or numeric value to display; `null`/`undefined` renders an empty state. */
   content: string | null | undefined | number;
 }>;
 //#endregion
 //#region packages/components/features/tables/components/atoms/more-button.d.ts
+/**
+ * A vertical-ellipsis icon button that opens a dropdown menu populated from the
+ * `items` array; intended for use in table row action columns.
+ *
+ * @example
+ * import { UITableMoreButton } from '@customafk/lunas-ui/features/tables';
+ *
+ * <UITableMoreButton
+ *   items={[
+ *     { id: 'edit', label: 'Edit', onClick: (id) => console.log(id) },
+ *     { id: 'delete', label: 'Delete', onClick: (id) => console.log(id) },
+ *   ]}
+ * />
+ */
 declare const UITableMoreButton: React.FC<{
+  /**
+   * List of menu items to render inside the dropdown.
+   * Each item must have a unique `id`, a display `label`, and an `onClick`
+   * handler that receives the item's `id`.
+   */
   items?: {
     id: string;
     label: string;
     onClick: (id: string) => void;
   }[];
+  /** Reserved for future use; currently unused by the component. */
   onClick?: () => void;
 }>;
 //#endregion
 //#region packages/components/features/tables/components/atoms/name-display.d.ts
+/** Props for the {@link UITableNameDisplay} component. */
 type NameDisplayProps = {
+  /** The name string to display; renders an empty placeholder when falsy. */
   name?: string | null | undefined;
 };
+/**
+ * Renders a clamped, truncated name string inside a tooltip that shows the full
+ * text and character count on hover; falls back to {@link UITableEmpty} when the
+ * value is absent.
+ *
+ * @example
+ * import { UITableNameDisplay } from '@customafk/lunas-ui/features/tables';
+ *
+ * <UITableNameDisplay name="John Doe" />
+ */
 declare const UITableNameDisplay: React.FC<NameDisplayProps>;
 //#endregion
 //#region packages/components/features/tables/components/atoms/permalink.d.ts
+/**
+ * Renders an external-link anchor with an icon for use in table cells, opening
+ * the target URL in a new tab with safe `rel` attributes.
+ *
+ * @example
+ * import { UITablePermalink } from '@customafk/lunas-ui/features/tables';
+ *
+ * <UITablePermalink href="https://example.com/records/42" label="View record" />
+ */
 declare const UITablePermalink: React.FC<{
+  /** The destination URL the anchor navigates to. */
   href: string;
+  /** Optional display text; falls back to the raw `href` when omitted. */
   label?: string;
 }>;
 //#endregion
 //#region packages/components/features/tables/components/atoms/phone-number.d.ts
+/**
+ * Formats and displays a phone number string in a table cell using the
+ * `(NXX) NXX-XXXX` pattern, with a tooltip that shows the full international
+ * dialling representation.
+ *
+ * @example
+ * import { UITablePhoneNumberDisplay } from '@customafk/lunas-ui/features/tables';
+ *
+ * <UITablePhoneNumberDisplay value="0843456789" />
+ */
 declare const UITablePhoneNumberDisplay: React.FC<React.PropsWithChildren<{
+  /** The raw phone number string to format and display. */
   value: string;
 }>>;
 //#endregion
 //#region packages/components/features/tables/components/atoms/remove-button.d.ts
+/**
+ * A ghost danger icon button with a trash icon that triggers an async removal
+ * handler; displays a descriptive tooltip on hover to confirm the action intent.
+ *
+ * @example
+ * import { UITableRemoveButton } from '@customafk/lunas-ui/features/tables';
+ *
+ * <UITableRemoveButton
+ *   title="Remove member from project"
+ *   onClick={async () => await deleteRow(rowId)}
+ * />
+ */
 declare const UITableRemoveButton: React.FC<{
+  /** Tooltip label describing what will be removed; defaults to a generic message. */
   title?: string;
+  /** Async-compatible callback invoked when the button is clicked. */
   onClick?: () => void | Promise<void>;
 }>;
 //#endregion
 //#region packages/components/features/tables/components/atoms/statistic.d.ts
+/** Props for the {@link UITableStatisticDisplay} component. */
 type Props$1 = {
+  /** Character used to separate the integer and fractional parts (default: `'.'`). */
   decimalSeparator?: string;
+  /** Character used to separate thousands groups (default: `','`). */
   groupSeparator?: string;
+  /** Optional node rendered before the formatted number (e.g. a currency symbol). */
   prefix?: React.ReactNode;
+  /** Optional node rendered after the formatted number (e.g. a unit label). */
   suffix?: React.ReactNode;
+  /** Number of decimal digits to display. */
   precision?: number;
+  /** Rounding strategy applied before formatting (default: `'round'`). */
   roundingMode?: 'round' | 'floor' | 'ceil';
+  /** When `true`, pads the fractional part with trailing zeros up to `precision` digits. */
   showTrailingZeros?: boolean;
+  /** Font-size variant for the displayed number (default: `'lg'`). */
   size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+  /** The numeric or string value to format; falsy / invalid values render an empty state. */
   value: number | string | null | undefined;
 };
-declare const UITableStatisticDisplay: react267.MemoExoticComponent<({
+/**
+ * A memoized table-cell component that formats a numeric value with configurable
+ * separators, precision, rounding, and size; renders {@link UITableEmpty} when
+ * the value is zero, invalid, or absent.
+ *
+ * @example
+ * import { UITableStatisticDisplay } from '@customafk/lunas-ui/features/tables';
+ *
+ * <UITableStatisticDisplay value={1234567.89} precision={2} prefix="$" size="md" />
+ */
+declare const UITableStatisticDisplay: react273.MemoExoticComponent<({
   decimalSeparator,
   groupSeparator,
   prefix: Prefix,
@@ -83,183 +223,711 @@ declare const UITableStatisticDisplay: react267.MemoExoticComponent<({
   showTrailingZeros,
   size,
   value
-}: Props$1) => react_jsx_runtime346.JSX.Element>;
+}: Props$1) => react_jsx_runtime332.JSX.Element>;
 //#endregion
 //#region packages/components/features/tables/components/atoms/user.d.ts
+/** Props for the {@link UITableUserDataDisplay} component. */
 type Props = {
+  /** Unique identifier used to deterministically generate the avatar background colour. */
   uuid?: string | null | undefined;
+  /** Display name shown below the avatar; falls back to `'Unknown User'` when absent. */
   username?: string | null | undefined;
+  /** Email address shown as secondary text beneath the username. */
   email?: string | null | undefined;
 };
+/**
+ * Renders a user avatar paired with username and email for use in table cells;
+ * derives a consistent avatar background colour from the user's `uuid` via a
+ * colour-hash utility.
+ *
+ * @example
+ * import { UITableUserDataDisplay } from '@customafk/lunas-ui/features/tables';
+ *
+ * <UITableUserDataDisplay
+ *   uuid="a1b2c3d4-e5f6-7890-abcd-ef1234567890"
+ *   username="Jane Smith"
+ *   email="jane@example.com"
+ * />
+ */
 declare const UITableUserDataDisplay: React.FC<Props>;
 //#endregion
 //#region packages/components/features/tables/types.d.ts
+/**
+ * Base constraint for all row data objects used with UITable.
+ *
+ * Any property key is allowed so that generic column definitions remain
+ * flexible, but the optional `subRows` field is the well-known expansion
+ * hook understood by TanStack Table's grouped-row model.
+ */
 type RowData<TData extends RowData<AnyEntity>> = {
+  /** Allows any property key so column `accessorKey` values type-check. */
   [x: string | number | symbol]: AnyEntity;
+  /** Nested child rows used by the grouped/expanded row model. */
   subRows?: TData[] | undefined;
 };
+/** Props for `UITableEmptyDisplay` — controls which placeholder state is shown. */
 type TUITableEmptyDisplay = {
+  /** When `true` a loading spinner is shown instead of the empty-box illustration. */
   isFetching?: boolean;
+  /** When `true` (and `isFetching` is `false`) the "No data available" illustration is shown. */
   isEmpty?: boolean;
 };
+/** Props for `UITableWrapper` — all native `<div>` attributes are forwarded. */
 type TUITableWrapper = React.PropsWithChildren<React.ComponentProps<'div'>>;
+/** Props for `UITableInnerWrapper` — all native `<div>` attributes are forwarded. */
 type TUITableInnerWrapper = React.PropsWithChildren<React.ComponentProps<'div'>>;
+/** Props for `UITableInnerTable` — all native `<table>` attributes are forwarded. */
 type TUITableInnerTable = React.PropsWithChildren<React.ComponentProps<'table'>>;
+/** Props for `UITableHead` — all native `<thead>` attributes are forwarded. */
 type TUITableHead = React.PropsWithChildren<React.ComponentProps<'thead'>>;
+/** Props for `UITableHeadCellOption` — the pin/unpin dropdown on a header cell. */
 type TUITableHeadCellOption = {
+  /** Current pinning position of the column (`'left'`, `'right'`, or `false`). */
   isPinned?: ColumnPinningPosition;
+  /** Whether the column is currently visible; reserved for future hide/show actions. */
   isVisible?: boolean;
+  /** Additional CSS classes applied to the dropdown trigger button. */
   className?: string;
+  /** Called with `'left'` when the user selects "Pin to Left". */
   onLeftPin?: (pos: ColumnPinningPosition) => void;
+  /** Called with `'right'` when the user selects "Pin to Right". */
   onRightPin?: (pos: ColumnPinningPosition) => void;
+  /** Called with `false` when the user selects "Unpin". */
   onUnpin?: (pos: ColumnPinningPosition) => void;
+  /** Called when the user toggles column visibility via the dropdown. */
   onToggleVisibility?: (props: AnyEntity) => void;
 };
+/** Props for `UITableHeadCellSelect` — the "select all rows" header checkbox cell. */
 type TUITableHeadCellSelect = React.ComponentProps<'th'> & {
+  /** Whether the column is pinned to a side (the select cell is always sticky). */
   isPinned?: ColumnPinningPosition;
+  /** Reflects `table.getIsAllRowsSelected()` to set the checkbox state. */
   isAllRowsSelected?: boolean;
+  /** Calls `table.toggleAllRowsSelected` when the checkbox value changes. */
   onToggleAllRowsSelected?: (value?: boolean) => void;
 };
+/** Props for `UITableHeadRow` — a single header `<tr>` built from a TanStack `HeaderGroup`. */
 type TUITableHeadRow = React.PropsWithChildren<React.ComponentProps<'tr'> & {
+  /** The TanStack `HeaderGroup` whose `headers` are rendered as `<th>` cells. */
   headerGroup: HeaderGroup<unknown>;
+  /** Forwarded to `UITableHeadCellSelect`; toggles all-row selection. */
   onToggleAllRowsSelected?: (value?: boolean) => void;
 }>;
+/** Props for `UITableHeadCell` — a single data `<th>` with pinning and resize support. */
 type TUITableHeadCell = React.PropsWithChildren<React.ComponentProps<'th'> & {
+  /** Whether the column is currently visible (used for future hide/show UI). */
   isVisible?: boolean;
+  /** Current pinning position (`'left'`, `'right'`, or `false`). */
   isPinned?: ColumnPinningPosition;
+  /** `true` when this is the first cell in the right-pinned group (adds a left border). */
   isFirstCell?: boolean;
+  /** `true` when this is the last cell in the left-pinned group (adds a right border). */
   isLastCell?: boolean;
+  /** When `false` the pin/unpin option dropdown is hidden (e.g. `actions` column). */
   isOptionsVisible?: boolean;
+  /** Column id used to look up the CSS custom property `--header-<id>-size`. */
   headerId?: string;
+  /** TanStack `Column` instance used to derive `left`/`right` sticky offsets and size constraints. */
   headerColumn?: Column<unknown, unknown>;
+  /** Calls `column.pin` with the chosen `ColumnPinningPosition`. */
   onColumnPin?: (pos: ColumnPinningPosition) => void;
+  /** Calls `column.toggleVisibility` when hide/show is triggered from the dropdown. */
   onToggleVisibility?: (value?: boolean) => void;
 }>;
+/** Props for `UITableBody` — the virtual-scroll `<tbody>` container. */
 type TUITableBody = React.PropsWithChildren<React.ComponentProps<'tbody'> & {
+  /** When `true` the body renders `null` (loading state is handled by `UITableEmptyDisplay`). */
   isFetching?: boolean;
+  /** When `true` the body renders `null` (empty state is handled by `UITableEmptyDisplay`). */
   isEmpty?: boolean;
+  /** CSS string for the total virtual height of all rows, e.g. `"4200px"`. */
   height: string;
 }>;
+/** Props for `UITableRow` — a single virtualised data `<tr>`. */
 type TUITableRow = React.ComponentProps<'tr'> & {
+  /** The TanStack `Row` object whose visible cells are iterated. */
   row: Row<AnyEntity>;
+  /** Whether this row is currently selected (drives `data-selected` attribute). */
   isSelected?: boolean;
+  /** Zero-based virtual row index used for `data-index` and passed to `onClickRow`. */
   virtualRowIndex: number;
+  /** Pixel offset from the top of the scroll container for the CSS `translateY`. */
   virtualRowStart: number;
 };
+/** Props for `UITableCellSelect` — the per-row selection checkbox `<td>`. */
 type TUITableCellSelect = React.ComponentProps<'td'> & {
+  /** Pinning position; the select cell is always rendered sticky regardless. */
   isPinned?: ColumnPinningPosition;
+  /** Whether the checkbox should appear checked. */
   isSelected?: boolean;
+  /** Calls `row.toggleSelected` when the checkbox value changes. */
   onToggleRowSelected?: (value?: boolean) => void;
 };
+/** Props for `UITableCellActions` — the sticky right-edge actions `<td>`. */
 type TUITableCellActions = React.ComponentProps<'td'> & {
+  /** Virtual row index forwarded to the cell renderer via `data-cell`. */
   virtualRowIndex: number;
+  /** TanStack `Column` whose `columnDef.cell` is rendered inside the `<td>`. */
   column?: Column<unknown, unknown>;
+  /** Returns the `CellContext` passed to `flexRender`. */
   getContext: () => CellContext<unknown, unknown>;
 };
+/** Props for `UITableCell` — a standard data `<td>` with pinning and sizing support. */
 type TUITableCell = React.ComponentProps<'td'> & {
+  /** Current pinning position of the column. */
   isPinned?: ColumnPinningPosition;
+  /** `true` when this is the first cell in the right-pinned group (adds a left border separator). */
   isFirstCell?: boolean;
+  /** `true` when this is the last cell in the left-pinned group (adds a right border separator). */
   isLastCell?: boolean;
+  /** Column id used to read `--col-<id>-size` CSS custom property for width. */
   colId?: string;
+  /** Unused reserved field for a future per-cell identifier. */
   cellId?: string;
+  /** Horizontal alignment of the cell content (`'start'` is the default). */
   position?: 'start' | 'center' | 'end';
+  /** TanStack `Column` instance used to derive sticky offsets and content-fit sizing. */
   column?: Column<unknown, unknown>;
+  /** Returns the `CellContext` passed to `flexRender`. */
   getContext: () => CellContext<unknown, unknown>;
 };
+/** Props for `UITableFooter` — all native `<tfoot>` attributes are forwarded. */
 type TUITableFooter = React.PropsWithChildren<React.ComponentProps<'tfoot'>>;
+/** Props for `UITableLoadMore` — the append-row "load more" trigger. */
 type TUITableLoadMore = React.PropsWithChildren<React.ComponentProps<'tr'> & {
+  /** Virtual index of this synthetic row (appended after the last data row). */
   virtualRowIndex: number;
+  /** Pixel offset used for the CSS `translateY` to position the row correctly. */
   virtualRowStart: number;
+  /**
+   * Async callback that fetches the next page of data.
+   * When omitted the component renders `null`.
+   */
   fetchMoreData?: () => void | Promise<void>;
 }>;
+/**
+ * Typed column definition accepted by `UITableProvider`.
+ *
+ * Extends TanStack's `AccessorKeyColumnDef` with a typed `meta` block so that
+ * the alignment and auto-fit behaviour can be specified in a type-safe manner.
+ */
 type TUITableColumn<TData extends RowData<TData>> = Pick<AccessorKeyColumnDef<TData, AnyEntity>, 'id' | 'accessorKey' | 'size' | 'maxSize' | 'minSize' | 'header' | 'cell' | 'meta'> & {
   meta?: {
+    /** Horizontal alignment of the column's cells and header. Defaults to `'start'`. */
     position?: 'start' | 'center' | 'end';
+    /** When `true`, the cell auto-expands to fit its rendered content width. */
     fitContent?: boolean;
   };
 };
+/**
+ * Value shape of the root `TableContext` consumed by toolbar and body
+ * components via `useUITableContext`.
+ */
 type TTableContext<TData extends RowData<TData>> = {
+  /** Human-readable table title rendered in `UITableTooltip`. */
   title: string;
+  /** The TanStack `Table` instance for the current dataset. */
   table: Table<TData>;
+  /** `true` when no rows exist after a successful (non-loading) fetch. */
   isEmpty: boolean;
+  /** `true` while the initial data fetch is in-flight. */
   isFetching?: boolean;
+  /** `true` while a background refetch is running (data is already present). */
   isRefetching?: boolean;
+  /** Total number of rows in the remote dataset, used for virtual scroll height. */
   totalRows?: number;
+  /** Callback that loads the next page; forwarded to `UITableLoadMore`. */
   fetchMoreData?: () => void | Promise<void>;
 };
+/** Context value provided by `UITableInnerWrapperProvider`. */
 type TTableInnerWrapperContext = {
+  /** Stable `useId`-generated id on the scrollable inner wrapper `<div>`. */
   innerWrapperId: string;
 };
+/** Context value provided by `UITableInnerTableProvider`. */
 type TTableInnerTableContext = {
+  /** The TanStack `Table` instance (typed as `AnyEntity` for the context boundary). */
   table: Table<AnyEntity>;
+  /** Stable `useId`-generated id on the `<table>` element. */
   innerTableId: string;
+  /** Pre-computed sum of all column sizes used as the `<table>` `minWidth`. */
   totalSize: number;
 };
+/** Context value provided by `UITableHeadRowProvider`. */
 type TTableHeadRowContext = {
+  /** Whether every visible row is currently selected. */
   isAllRowsSelected: boolean;
+  /** The current `{ left, right }` column pinning map. */
   columnPinningState: ColumnPinningState;
+  /** Ordered list of `Header` objects in the left-pinned group. */
   leftPinnedHeaders: Header<AnyEntity, unknown>[];
+  /** Ordered list of `Header` objects in the right-pinned group. */
   rightPinnedHeaders: Header<AnyEntity, unknown>[];
+  /** Toggles all-row selection; delegates to `table.toggleAllRowsSelected`. */
   onToggleAllRowsSelected?: (value?: boolean) => void;
 };
+/** Context value provided by `UITableBodyProvider`. */
 type TTableBodyContext = {
+  /** `true` while data is loading; causes `UITableBody` to render `null`. */
   isFetching: boolean;
+  /** `true` when there are no rows after a successful fetch. */
   isEmpty: boolean;
+  /** The current `Record<rowId, boolean>` row-selection map from TanStack state. */
   rowSelectionState: RowSelectionState;
 };
+/** Context value provided by `UITableRowProvider`, consumed by individual `UITableRow` renders. */
 type TTableRowContext<TData extends RowData<TData> = RowData<AnyEntity>, TKey extends keyof TData = keyof TData> = {
+  /** The data key whose value is passed as the second argument to `onClickRow`. */
   keyOfClickRow?: TKey;
+  /** Whether all rows are selected (drives the select cell's checked state). */
   isAllRowsSelected?: boolean;
+  /** The current `{ left, right }` column pinning map used by each cell. */
   columnPinningState: ColumnPinningState;
+  /** Called with the virtual row index and the extracted `keyOfClickRow` value. */
   onClickRow?: (rowIndex: number, rowId?: AnyEntity) => void;
+  /** Left-pinned headers used to determine border separator placement. */
   leftPinnedHeaders?: Header<TData, unknown>[];
+  /** Right-pinned headers used to determine border separator placement. */
   rightPinnedHeaders?: Header<TData, unknown>[];
 };
+/** Context value for the virtualiser, shared between the body and the load-more row. */
 type TTableVirtualizerContext = {
+  /** The TanStack Virtual `Virtualizer` instance driving row windowing. */
   rowVirtualizer: Virtualizer<HTMLDivElement, HTMLTableRowElement>;
+  /** The currently visible `VirtualItem` slice (index + start offset for each row). */
   virtualItems: VirtualItem[];
 };
+/**
+ * Props accepted by `UITableProvider` — the single entry point for configuring
+ * a UITable instance.
+ *
+ * @example
+ * ```tsx
+ * import { UITableProvider } from '@customafk/lunas-ui/features/tables';
+ *
+ * <UITableProvider<User>
+ *   title="Users"
+ *   data={users}
+ *   columns={columns}
+ *   totalRows={total}
+ *   isFetching={isLoading}
+ *   leftPinnedColumns={['name']}
+ *   onClickRow={(index, id) => openDetail(id)}
+ *   onRowSelection={sel => setSelected(sel)}
+ *   fetchMoreData={fetchNextPage}
+ * >
+ *   <UITable />
+ * </UITableProvider>
+ * ```
+ */
 type TableProviderProps<TData extends RowData<TData>, TKey extends keyof TData = keyof TData, TColumns extends ReadonlyArray<TUITableColumn<TData>> = TUITableColumn<TData>[]> = {
+  /** Human-readable label shown in `UITableTooltip`. */
   title: string;
+  /** Pass `true` while the initial page of data is being fetched. */
   isFetching?: boolean;
+  /** Pass `true` while a background refetch is running (stale data remains visible). */
   isRefetching?: boolean;
+  /** The current page / slice of row data. */
   data: TData[];
+  /** Typed column definitions; use `TUITableColumn<TData>` for full type safety. */
   columns: TColumns;
+  /** Total number of rows in the remote dataset; required for accurate virtual-scroll height. */
   totalRows?: number;
+  /**
+   * Async callback invoked by `UITableLoadMore` when the user scrolls to the
+   * bottom or clicks "Load More".  Omit to hide the load-more row entirely.
+   */
   fetchMoreData?: () => void | Promise<void>;
+  /** Column accessor keys to pin on the left (the `select` column is always pinned left). */
   leftPinnedColumns?: Array<TColumns[number]['accessorKey']>;
+  /** Column accessor keys (or plain string ids) to pin on the right. */
   rightPinnedColumns?: Array<TColumns[number]['accessorKey']> | string[];
+  /** Data key whose value is extracted and passed as the second argument of `onClickRow`. */
   keyOfClickRow?: TTableRowContext<TData, TKey>['keyOfClickRow'];
+  /** Called with the virtual row index and the value of `keyOfClickRow` when a row is clicked. */
   onClickRow?: TTableRowContext<TData, TKey>['onClickRow'];
+  /** Called with the updated row-selection map after each selection change. */
   onRowSelection?: (rowSelection: RowSelectionState) => void;
+  /** Called with the updated column-pinning state after each pin/unpin action. */
   onColumnPinning?: (columnPinning: ColumnPinningState) => void;
 };
 //#endregion
 //#region packages/components/features/tables/components/common.d.ts
-declare const UITableHeadCellOption: react267.NamedExoticComponent<TUITableHeadCellOption>;
-declare const UITableHeadCellSelect: react267.NamedExoticComponent<TUITableHeadCellSelect>;
-declare const UITableEmptyDisplay: react267.NamedExoticComponent<TUITableEmptyDisplay>;
-declare const UITableWrapper: react267.NamedExoticComponent<TUITableWrapper>;
-declare const UITableInnerWrapper: react267.NamedExoticComponent<TUITableInnerWrapper>;
-declare const UITableInnerTable: react267.NamedExoticComponent<TUITableInnerTable>;
-declare const UITableHead: react267.NamedExoticComponent<TUITableHead>;
-declare const UITableHeadRow: react267.NamedExoticComponent<TUITableHeadRow>;
-declare const UITableHeadCell: react267.NamedExoticComponent<TUITableHeadCell>;
-declare const UITableBody: react267.NamedExoticComponent<TUITableBody>;
-declare const UITableRow: react267.NamedExoticComponent<TUITableRow>;
-declare const UITableCellSelect: react267.NamedExoticComponent<TUITableCellSelect>;
-declare const UITableCellActions: react267.NamedExoticComponent<TUITableCellActions>;
-declare const UITableCell: react267.NamedExoticComponent<TUITableCell>;
-declare const UITableFooter: react267.NamedExoticComponent<TUITableFooter>;
-declare const UITableLoadMore: react267.NamedExoticComponent<TUITableLoadMore>;
+/**
+ * Ellipsis dropdown menu attached to a header cell that lets the user pin the
+ * column to the left, pin it to the right, or unpin it.
+ *
+ * The trigger button is invisible until the parent `<th>` is hovered
+ * (`group-hover:opacity-100`), keeping the header clean by default.
+ *
+ * @example
+ * ```tsx
+ * import { UITableHeadCellOption } from '@customafk/lunas-ui/features/tables';
+ *
+ * <UITableHeadCellOption
+ *   isPinned="left"
+ *   onLeftPin={col.pin}
+ *   onRightPin={col.pin}
+ *   onUnpin={col.pin}
+ * />
+ * ```
+ */
+declare const UITableHeadCellOption: react273.NamedExoticComponent<TUITableHeadCellOption>;
+/**
+ * Sticky `<th>` cell that renders a "select all rows" checkbox in the leftmost
+ * header position.
+ *
+ * The cell is always pinned at `left: 0` and uses a fixed width of
+ * `SELECT_WIDTH` to align with the corresponding body select cells.
+ *
+ * @example
+ * ```tsx
+ * import { UITableHeadCellSelect } from '@customafk/lunas-ui/features/tables';
+ *
+ * <UITableHeadCellSelect
+ *   isPinned="left"
+ *   isAllRowsSelected={table.getIsAllRowsSelected()}
+ *   onToggleAllRowsSelected={table.toggleAllRowsSelected}
+ * />
+ * ```
+ */
+declare const UITableHeadCellSelect: react273.NamedExoticComponent<TUITableHeadCellSelect>;
+/**
+ * Overlay displayed in place of table rows when the table is loading data or
+ * when the dataset is empty after a successful fetch.
+ *
+ * Returns `null` when neither `isEmpty` nor `isFetching` is true, so it adds
+ * zero DOM overhead during normal rendering.
+ *
+ * @example
+ * ```tsx
+ * import { UITableEmptyDisplay } from '@customafk/lunas-ui/features/tables';
+ *
+ * <UITableEmptyDisplay isFetching={isLoading} isEmpty={data.length === 0} />
+ * ```
+ */
+declare const UITableEmptyDisplay: react273.NamedExoticComponent<TUITableEmptyDisplay>;
+/**
+ * Outermost layout container for the entire UITable composition.
+ *
+ * Renders a full-width, full-height flex column that positions the toolbar,
+ * the scrollable table area, and the footer in a single stack.
+ *
+ * @example
+ * ```tsx
+ * import { UITableWrapper } from '@customafk/lunas-ui/features/tables';
+ *
+ * <UITableWrapper className="h-[600px]">
+ *   {children}
+ * </UITableWrapper>
+ * ```
+ */
+declare const UITableWrapper: react273.NamedExoticComponent<TUITableWrapper>;
+/**
+ * Scrollable `<div>` that wraps the `<table>` element and acts as the
+ * viewport for both horizontal and vertical virtual scrolling.
+ *
+ * Reads its stable id from `UITableInnerWrapperContext` so that other
+ * components (e.g. `UITableLoadMore`) can reference the DOM node via
+ * `document.querySelector` without prop-drilling.
+ *
+ * @example
+ * ```tsx
+ * import { UITableInnerWrapper } from '@customafk/lunas-ui/features/tables';
+ *
+ * <UITableInnerWrapper>
+ *   <UITableInnerTable>…</UITableInnerTable>
+ * </UITableInnerWrapper>
+ * ```
+ */
+declare const UITableInnerWrapper: react273.NamedExoticComponent<TUITableInnerWrapper>;
+/**
+ * The actual `<table>` element that drives the UITable layout.
+ *
+ * Attaches a `ResizeObserver` to the table element and calculates per-column
+ * CSS custom properties (`--header-<id>-size`, `--col-<id>-size`) in a single
+ * pass on every resize, avoiding expensive per-cell `column.getSize()` calls.
+ * Flexible columns share the remaining width equally; fixed-size and pinned
+ * columns are excluded from the distribution.
+ *
+ * @example
+ * ```tsx
+ * import { UITableInnerTable } from '@customafk/lunas-ui/features/tables';
+ *
+ * <UITableInnerTable>
+ *   <UITableHead>…</UITableHead>
+ *   <UITableBody height="600px">…</UITableBody>
+ * </UITableInnerTable>
+ * ```
+ */
+declare const UITableInnerTable: react273.NamedExoticComponent<TUITableInnerTable>;
+/**
+ * Sticky `<thead>` element that stays fixed at the top of the scrollable
+ * table area while the body scrolls beneath it.
+ *
+ * Applies column-border, background, and font styling uniformly to all
+ * descendant `<th>` elements via Tailwind child selectors.
+ *
+ * @example
+ * ```tsx
+ * import { UITableHead } from '@customafk/lunas-ui/features/tables';
+ *
+ * <UITableHead>
+ *   {table.getHeaderGroups().map(hg => (
+ *     <UITableHeadRow key={hg.id} headerGroup={hg} />
+ *   ))}
+ * </UITableHead>
+ * ```
+ */
+declare const UITableHead: react273.NamedExoticComponent<TUITableHead>;
+/**
+ * Renders a single `<tr>` for a TanStack `HeaderGroup`, mapping each header
+ * to either `UITableHeadCellSelect` (for the `select` column) or
+ * `UITableHeadCell` (for all other columns).
+ *
+ * Reads pinning state and "select all" handler from `UITableHeadRowContext`
+ * so the row itself does not need to receive those as props.
+ *
+ * @example
+ * ```tsx
+ * import { UITableHeadRow } from '@customafk/lunas-ui/features/tables';
+ *
+ * {table.getHeaderGroups().map(hg => (
+ *   <UITableHeadRow key={hg.id} headerGroup={hg} />
+ * ))}
+ * ```
+ */
+declare const UITableHeadRow: react273.NamedExoticComponent<TUITableHeadRow>;
+/**
+ * Individual `<th>` cell that supports left/right sticky pinning, dynamic
+ * CSS-variable-driven width, min/max size constraints, and an optional
+ * `UITableHeadCellOption` pin/unpin dropdown.
+ *
+ * Width is driven by the CSS custom property `--header-<headerId>-size` set
+ * by `UITableInnerTable`, avoiding per-cell `column.getSize()` calls.
+ *
+ * @example
+ * ```tsx
+ * import { UITableHeadCell } from '@customafk/lunas-ui/features/tables';
+ *
+ * <UITableHeadCell
+ *   headerId={header.id}
+ *   headerColumn={header.column}
+ *   isPinned="left"
+ *   isLastCell
+ *   onColumnPin={header.column.pin}
+ * >
+ *   {flexRender(header.column.columnDef.header, header.getContext())}
+ * </UITableHeadCell>
+ * ```
+ */
+declare const UITableHeadCell: react273.NamedExoticComponent<TUITableHeadCell>;
+/**
+ * `<tbody>` element that acts as the virtual-scroll container.
+ *
+ * Renders `null` while data is loading or the table is empty (the
+ * `UITableEmptyDisplay` overlay handles those states instead).  The `height`
+ * prop must be supplied as the total height of all virtual rows so that the
+ * scroll track reflects the full dataset length.
+ *
+ * @example
+ * ```tsx
+ * import { UITableBody } from '@customafk/lunas-ui/features/tables';
+ *
+ * <UITableBody height={`${rowVirtualizer.getTotalSize()}px`}>
+ *   {virtualItems.map(vRow => (
+ *     <UITableRow key={vRow.index} … />
+ *   ))}
+ * </UITableBody>
+ * ```
+ */
+declare const UITableBody: react273.NamedExoticComponent<TUITableBody>;
+/**
+ * Virtualised `<tr>` that renders a single data row by translating itself to
+ * the correct vertical position via a CSS `transform`.
+ *
+ * Iterates the row's visible cells and delegates to `UITableCellActions`,
+ * `UITableCellSelect`, or `UITableCell` based on the column id.  Click
+ * handling, pinning state, and the "select all" flag are sourced from
+ * `UITableRowContext`.
+ *
+ * @example
+ * ```tsx
+ * import { UITableRow } from '@customafk/lunas-ui/features/tables';
+ *
+ * {virtualItems.map(vRow => {
+ *   const row = rows[vRow.index];
+ *   return (
+ *     <UITableRow
+ *       key={row.id}
+ *       row={row}
+ *       isSelected={row.getIsSelected()}
+ *       virtualRowIndex={vRow.index}
+ *       virtualRowStart={vRow.start}
+ *     />
+ *   );
+ * })}
+ * ```
+ */
+declare const UITableRow: react273.NamedExoticComponent<TUITableRow>;
+/**
+ * Sticky `<td>` cell in the leftmost column that renders a per-row selection
+ * checkbox.
+ *
+ * The cell stops click-event propagation so that selecting a row does not also
+ * trigger the row's `onClickRow` handler.
+ *
+ * @example
+ * ```tsx
+ * import { UITableCellSelect } from '@customafk/lunas-ui/features/tables';
+ *
+ * <UITableCellSelect
+ *   isPinned="left"
+ *   isSelected={row.getIsSelected()}
+ *   onToggleRowSelected={row.toggleSelected}
+ * />
+ * ```
+ */
+declare const UITableCellSelect: react273.NamedExoticComponent<TUITableCellSelect>;
+/**
+ * Sticky `<td>` cell pinned to the right edge of each row that renders the
+ * column's custom `cell` renderer (typically a row-action menu).
+ *
+ * The cell is always sticky (`right: 0`, `z-index: 50`) and gains a hover
+ * background via the `group-hover` Tailwind variant on the parent `<tr>`.
+ *
+ * @example
+ * ```tsx
+ * import { UITableCellActions } from '@customafk/lunas-ui/features/tables';
+ *
+ * <UITableCellActions
+ *   virtualRowIndex={vRow.index}
+ *   column={cell.column}
+ *   getContext={cell.getContext}
+ * />
+ * ```
+ */
+declare const UITableCellActions: react273.NamedExoticComponent<TUITableCellActions>;
+/**
+ * Standard `<td>` data cell with support for left/right sticky pinning,
+ * CSS-variable-driven width, content-fit auto-sizing, and configurable
+ * horizontal alignment (`start` | `center` | `end`).
+ *
+ * A `ResizeObserver` on the inner content div measures actual rendered content
+ * width and calls `table.setColumnSizing` when the content overflows the
+ * column's current size, but only when the column definition has
+ * `meta.fitContent: true`.
+ *
+ * @example
+ * ```tsx
+ * import { UITableCell } from '@customafk/lunas-ui/features/tables';
+ *
+ * <UITableCell
+ *   colId={cell.column.id}
+ *   isPinned="left"
+ *   position="start"
+ *   column={cell.column}
+ *   getContext={cell.getContext}
+ * />
+ * ```
+ */
+declare const UITableCell: react273.NamedExoticComponent<TUITableCell>;
+/**
+ * `<tfoot>` element rendered below the table body, typically used for
+ * summary rows or pagination controls.
+ *
+ * @example
+ * ```tsx
+ * import { UITableFooter } from '@customafk/lunas-ui/features/tables';
+ *
+ * <UITableFooter>
+ *   <tr><td>Total: {totalRows}</td></tr>
+ * </UITableFooter>
+ * ```
+ */
+declare const UITableFooter: react273.NamedExoticComponent<TUITableFooter>;
+/**
+ * Virtualised `<tr>` appended after the last data row that renders a
+ * "Load More" / "Loading…" / "Error! Retry?" button.
+ *
+ * Returns `null` when `fetchMoreData` is not provided, making it safe to
+ * include unconditionally in the row list.  A `ResizeObserver` on the inner
+ * wrapper ensures the row always matches the current table width.
+ *
+ * @example
+ * ```tsx
+ * import { UITableLoadMore } from '@customafk/lunas-ui/features/tables';
+ *
+ * <UITableLoadMore
+ *   virtualRowIndex={rows.length}
+ *   virtualRowStart={rowVirtualizer.getTotalSize()}
+ *   fetchMoreData={fetchNextPage}
+ * />
+ * ```
+ */
+declare const UITableLoadMore: react273.NamedExoticComponent<TUITableLoadMore>;
 //#endregion
 //#region packages/components/features/tables/components/table.d.ts
 declare const UITableContainer: React.FC<React.PropsWithChildren>;
 //#endregion
 //#region packages/components/features/tables/components/table/filter.d.ts
-declare const UITableFilter: () => react_jsx_runtime346.JSX.Element;
+/**
+ * Collapsible side-panel that lets users toggle column visibility and (in
+ * future) add row filters without leaving the table view.
+ *
+ * The panel collapses to a narrow icon strip when no tab is active and expands
+ * to at least 64 units when the "Columns" or "Filters" tab is selected.  The
+ * `select` and `actions` columns are excluded from the visibility list.
+ *
+ * @example
+ * ```tsx
+ * import { UITableFilter } from '@customafk/lunas-ui/features/tables';
+ *
+ * // Render inside a ResizablePanelGroup alongside UITable
+ * <ResizablePanelGroup direction="horizontal">
+ *   <ResizablePanel>
+ *     <UITable />
+ *   </ResizablePanel>
+ *   <ResizableHandle />
+ *   <UITableFilter />
+ * </ResizablePanelGroup>
+ * ```
+ */
+declare const UITableFilter: () => react_jsx_runtime332.JSX.Element;
 //#endregion
 //#region packages/components/features/tables/components/table/provider.d.ts
+/**
+ * Root context provider for the UITable component family.
+ *
+ * Instantiates a TanStack Table instance with virtualisation-friendly settings
+ * (column pinning, row selection, row grouping, row expansion) and propagates
+ * all derived state through a nested set of memoised context providers so that
+ * each layer only re-renders when its own slice of state changes.
+ *
+ * @example
+ * ```tsx
+ * import { UITableProvider } from '@customafk/lunas-ui/features/tables';
+ *
+ * const columns = [
+ *   { accessorKey: 'name', header: 'Name' },
+ *   { accessorKey: 'email', header: 'Email' },
+ * ];
+ *
+ * function MyPage() {
+ *   return (
+ *     <UITableProvider
+ *       title="Users"
+ *       data={users}
+ *       columns={columns}
+ *       isFetching={isLoading}
+ *       onClickRow={(index, id) => console.log(index, id)}
+ *     >
+ *       <UITable />
+ *     </UITableProvider>
+ *   );
+ * }
+ * ```
+ */
 declare const UITableProvider: <TData extends RowData<TData> = RowData<AnyEntity>, TKey extends keyof TData = keyof TData, TColumns extends ReadonlyArray<TUITableColumn<TData>> = TUITableColumn<TData>[]>({
   title,
   isFetching,
@@ -275,17 +943,71 @@ declare const UITableProvider: <TData extends RowData<TData> = RowData<AnyEntity
   onColumnPinning,
   fetchMoreData,
   children
-}: React.PropsWithChildren<TableProviderProps<TData, TKey, TColumns>>) => react_jsx_runtime346.JSX.Element;
+}: React.PropsWithChildren<TableProviderProps<TData, TKey, TColumns>>) => react_jsx_runtime332.JSX.Element;
 //#endregion
 //#region packages/components/features/tables/components/table/tooltip.d.ts
+/**
+ * Debounced search input rendered inside the table toolbar.
+ *
+ * Fires `onSearch` 500 ms after the user stops typing and delegates all other
+ * native input events via the spread `props`.
+ *
+ * @example
+ * ```tsx
+ * import { UITableTooltipFilter } from '@customafk/lunas-ui/features/tables';
+ *
+ * <UITableTooltipFilter
+ *   placeholder="Search users…"
+ *   onSearch={value => setQuery(value)}
+ * />
+ * ```
+ */
 declare const UITableTooltipFilter: React.FC<Omit<React.ComponentProps<typeof Input>, 'className'> & {
   onSearch?: (value: string) => void;
 }>;
+/**
+ * Grouped action buttons (create, refresh, download) displayed in the table
+ * toolbar.
+ *
+ * Each button is disabled automatically when the corresponding handler prop is
+ * omitted, so only the actions relevant to a given table need to be provided.
+ *
+ * @example
+ * ```tsx
+ * import { UITableTooltipActions } from '@customafk/lunas-ui/features/tables';
+ *
+ * <UITableTooltipActions
+ *   onCreate={() => setOpenCreate(true)}
+ *   onRefresh={() => refetch()}
+ * />
+ * ```
+ */
 declare const UITableTooltipActions: React.FC<{
   onCreate?: () => void;
   onRefresh?: () => void;
   onDownload?: () => void;
 }>;
+/**
+ * Outer toolbar shell for the UITable component.
+ *
+ * Reads the table `title` from `UITableContext` and renders it as a heading
+ * above the `children` slot, which typically contains a
+ * `UITableTooltipFilter` and/or `UITableTooltipActions`.
+ *
+ * @example
+ * ```tsx
+ * import {
+ *   UITableTooltip,
+ *   UITableTooltipFilter,
+ *   UITableTooltipActions,
+ * } from '@customafk/lunas-ui/features/tables';
+ *
+ * <UITableTooltip>
+ *   <UITableTooltipFilter onSearch={setQuery} />
+ *   <UITableTooltipActions onCreate={handleCreate} onRefresh={refetch} />
+ * </UITableTooltip>
+ * ```
+ */
 declare const UITableTooltip: React.FC<React.PropsWithChildren>;
 //#endregion
 export { RowData, TTableBodyContext, TTableContext, TTableHeadRowContext, TTableInnerTableContext, TTableInnerWrapperContext, TTableRowContext, TTableVirtualizerContext, TUITableBody, TUITableCell, TUITableCellActions, TUITableCellSelect, TUITableColumn, TUITableEmptyDisplay, TUITableFooter, TUITableHead, TUITableHeadCell, TUITableHeadCellOption, TUITableHeadCellSelect, TUITableHeadRow, TUITableInnerTable, TUITableInnerWrapper, TUITableLoadMore, TUITableRow, TUITableWrapper, TableProviderProps, UITableBadgeDisplay, UITableBody, UITableBooleanDisplay, UITableCell, UITableCellActions, UITableCellSelect, UITableContainer, UITableDateDisplay, UITableDescriptionDisplay, UITableEmptyDisplay, UITableFilter, UITableFooter, UITableHead, UITableHeadCell, UITableHeadCellOption, UITableHeadCellSelect, UITableHeadRow, UITableInnerTable, UITableInnerWrapper, UITableLoadMore, UITableMoreButton, UITableNameDisplay, UITablePermalink, UITablePhoneNumberDisplay, UITableProvider, UITableRemoveButton, UITableRow, UITableStatisticDisplay, UITableTooltip, UITableTooltipActions, UITableTooltipFilter, UITableUserDataDisplay, UITableWrapper };