@customafk/lunas-ui 0.2.11 → 0.2.13

package/dist/index-B5wgYino.d.cts

@@ -0,0 +1,1009 @@
+import { t as AnyEntity } from "./types-CDYHkcOk.cjs";
+import { t as Input } from "./input-BLyJp8UZ.cjs";
+import * as react_jsx_runtime332 from "react/jsx-runtime";
+import * as react257 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/currency-display.d.ts
+/** Props for the {@link UITableCurrencyDisplay} component. */
+type Props$7 = {
+  /** The numeric value to format as currency; falsy / `NaN` renders an empty state. */
+  value: number | string | null | undefined;
+  /** ISO 4217 currency code (default: `'USD'`). */
+  currency?: string;
+  /**
+   * BCP 47 locale used for number formatting (default: `'en-US'`).
+   * Controls digit grouping and decimal separators.
+   */
+  locale?: string;
+  /** How to display the currency symbol — `'symbol'` (default), `'code'`, or `'name'`. */
+  display?: 'symbol' | 'code' | 'name';
+  /** Font-size variant (default: `'md'`). */
+  size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+  /** When `true`, applies a green tint for positive and red tint for negative values. */
+  colorize?: boolean;
+};
+/**
+ * Formats a numeric value as a locale-aware currency string in a table cell.
+ * Always shows exactly two decimal places and uses the browser's `Intl` API for
+ * symbol placement.  Renders {@link UITableEmpty} when the value is absent or
+ * invalid.
+ *
+ * @example
+ * import { UITableCurrencyDisplay } from '@customafk/lunas-ui/features/tables';
+ *
+ * <UITableCurrencyDisplay value={1234.5} currency="USD" colorize />
+ */
+declare const UITableCurrencyDisplay: react257.MemoExoticComponent<({
+  value,
+  currency,
+  locale,
+  display,
+  size,
+  colorize
+}: Props$7) => react_jsx_runtime332.JSX.Element>;
+//#endregion
+//#region packages/components/features/tables/components/atoms/date-display.d.ts
+/** Props for the {@link UITableDateDisplay} component. */
+type Props$6 = {
+  /** 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$6>;
+//#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/email-display.d.ts
+/** Props for the {@link UITableEmailDisplay} component. */
+type Props$5 = {
+  /** The email address to display; `null`/`undefined`/empty renders an empty state. */
+  email: string | null | undefined;
+  /** When `true`, a `mailto:` anchor wraps the address (default: `true`). */
+  linkable?: boolean;
+};
+/**
+ * Displays an email address in a table cell with a copy-to-clipboard button.
+ * Shows a brief checkmark confirmation after copying.  Optionally wraps the
+ * address in a `mailto:` link.  Renders {@link UITableEmpty} when `email` is
+ * absent.
+ *
+ * @example
+ * import { UITableEmailDisplay } from '@customafk/lunas-ui/features/tables';
+ *
+ * <UITableEmailDisplay email="jane@example.com" />
+ */
+declare const UITableEmailDisplay: React.FC<Props$5>;
+//#endregion
+//#region packages/components/features/tables/components/atoms/list-display.d.ts
+/** Props for the {@link UITableListDisplay} component. */
+type Props$4 = {
+  /** Array of strings or numbers to render as inline pills. */
+  items: (string | number)[] | null | undefined;
+  /**
+   * Maximum number of pills shown before a `+N more` overflow badge appears
+   * (default: `3`).
+   */
+  maxVisible?: number;
+};
+/**
+ * Renders an array of values as compact inline pills in a table cell.  When the
+ * list exceeds `maxVisible`, a `+N more` badge is shown; hovering it reveals all
+ * remaining items in a tooltip.  Renders {@link UITableEmpty} for empty or absent
+ * arrays.
+ *
+ * @example
+ * import { UITableListDisplay } from '@customafk/lunas-ui/features/tables';
+ *
+ * <UITableListDisplay items={['React', 'TypeScript', 'TailwindCSS', 'Vite']} maxVisible={3} />
+ */
+declare const UITableListDisplay: React.FC<Props$4>;
+//#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/progress-display.d.ts
+/** Props for the {@link UITableProgressDisplay} component. */
+type Props$3 = {
+  /** Percentage value between 0 and 100; `null`/`undefined` renders an empty state. */
+  value: number | null | undefined;
+  /** When `true`, shows the numeric percentage next to the bar (default: `true`). */
+  showLabel?: boolean;
+  /**
+   * Color thresholds applied to the progress indicator.
+   * - `≥ successThreshold` → green
+   * - `≥ warningThreshold` → yellow
+   * - otherwise → red
+   *
+   * Defaults: `successThreshold = 70`, `warningThreshold = 40`.
+   */
+  successThreshold?: number;
+  warningThreshold?: number;
+};
+/**
+ * Renders a horizontal progress bar with an optional percentage label for a
+ * table cell.  The bar color shifts from red → yellow → green based on
+ * configurable thresholds.  Renders {@link UITableEmpty} when `value` is absent.
+ *
+ * @example
+ * import { UITableProgressDisplay } from '@customafk/lunas-ui/features/tables';
+ *
+ * <UITableProgressDisplay value={75} />
+ */
+declare const UITableProgressDisplay: react257.MemoExoticComponent<({
+  value,
+  showLabel,
+  successThreshold,
+  warningThreshold
+}: Props$3) => react_jsx_runtime332.JSX.Element>;
+//#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$2 = {
+  /** 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;
+};
+/**
+ * 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: react257.MemoExoticComponent<({
+  decimalSeparator,
+  groupSeparator,
+  prefix: Prefix,
+  suffix: Suffix,
+  precision,
+  roundingMode,
+  showTrailingZeros,
+  size,
+  value
+}: Props$2) => react_jsx_runtime332.JSX.Element>;
+//#endregion
+//#region packages/components/features/tables/components/atoms/status-display.d.ts
+type BadgeColor = 'primary' | 'secondary' | 'muted' | 'accent' | 'info' | 'success' | 'warning' | 'danger';
+/** Props for the {@link UITableStatusDisplay} component. */
+type Props$1 = {
+  /** The status string to display; `null`/`undefined` renders an empty state. */
+  value: string | null | undefined;
+  /**
+   * Maps each status string to a badge color.  Any key not present in the map
+   * falls back to `defaultColor`.
+   */
+  colorMap?: Record<string, BadgeColor>;
+  /** Color used when `value` is not found in `colorMap` (default: `'muted'`). */
+  defaultColor?: BadgeColor;
+  /** Badge variant forwarded to the underlying {@link Badge} (default: `'soft'`). */
+  variant?: 'solid' | 'soft' | 'outline';
+};
+/**
+ * Renders a color-coded status badge for a table cell.  The mapping from status
+ * string to badge color is fully configurable via `colorMap`; unknown statuses
+ * fall back to `defaultColor`.
+ *
+ * @example
+ * import { UITableStatusDisplay } from '@customafk/lunas-ui/features/tables';
+ *
+ * <UITableStatusDisplay
+ *   value="active"
+ *   colorMap={{ active: 'success', inactive: 'danger', pending: 'warning' }}
+ * />
+ */
+declare const UITableStatusDisplay: React.FC<Props$1>;
+//#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;
+  /** When `true` a "Refetching data..." message is shown below the spinner to indicate a background refresh. */
+  isRefetching?: boolean;
+  /** CSS height of the overlay container. Defaults to `384px` (`min-h-96`) when omitted. */
+  height?: React.CSSProperties['height'];
+};
+/** 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;
+  };
+};
+/** A single cell in a CSV export row. */
+type CsvCell = {
+  /** Column header label for this cell. */
+  label: string;
+  /** Cell value — numbers render right-aligned in spreadsheet editors. */
+  value: string | number | boolean | null | undefined;
+};
+/**
+ * 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;
+  /** `true` while any data fetch is in-flight; deprecated in favor of `isFetching` and `isRefetching`. */
+  isLoading?: boolean;
+  /** The rows currently visible when loading data */
+  loadingDisplayRow?: number;
+  /** 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>;
+  /** CSS height of the `UITableEmptyDisplay` overlay. Defaults to `384px` when omitted. */
+  emptyDisplayHeight?: React.CSSProperties['height'];
+  /** CSV export rows; each row is an ordered array of `{ label, value }` cells. */
+  csvData?: CsvCell[][];
+  /** File name (without `.csv`) for the downloaded file. Defaults to the table title. */
+  csvFileName?: string;
+  /** Definitions of all filterable fields shown in the "Add Filter" dropdown. */
+  filterDefinitions?: FilterDefinition[];
+  /** Called with the full list of active filters whenever filters are added, removed, or updated. */
+  onFilterChange?: (filters: ActiveFilter[]) => 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` while a background refetch is running; passed to `UITableEmptyDisplay`. */
+  isRefetching: 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;
+  /** Pass `true` while any data fetch is in-flight; deprecated in favor of `isFetching` and `isRefetching`. */
+  isLoading?: boolean;
+  /** The rows currently visible when loading data */
+  loadingDisplayRow?: number;
+  /** 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;
+  /** CSS height of the `UITableEmptyDisplay` overlay. Defaults to `384px` when omitted. */
+  emptyDisplayHeight?: React.CSSProperties['height'];
+  /** CSV export rows; each row is an ordered array of `{ label, value }` cells. */
+  csvData?: CsvCell[][];
+  /** File name (without `.csv`) for the downloaded file. Defaults to the table title. */
+  csvFileName?: string;
+  /** Definitions of all filterable fields shown in the "Add Filter" dropdown. */
+  filterDefinitions?: FilterDefinition[];
+  /** Called with the full list of active filters whenever filters are added, removed, or updated. */
+  onFilterChange?: (filters: ActiveFilter[]) => void;
+};
+type FilterType = 'tag' | 'date-range' | 'number' | 'text' | 'boolean';
+/** A selectable option for tag/enum filters. */
+type FilterOption = {
+  label: string;
+  value: string;
+};
+/**
+ * Declares a filterable field available in the "Add Filter" dropdown.
+ * `options` is required when `type === 'tag'`.
+ */
+type FilterDefinition = {
+  id: string;
+  label: string;
+  type: FilterType;
+  options?: FilterOption[];
+};
+type TagFilterValue = {
+  type: 'tag';
+  values: string[];
+};
+type DateRangeFilterValue = {
+  type: 'date-range';
+  /** ISO date string, e.g. `"2024-01-01"`. */
+  from?: string;
+  to?: string;
+};
+type NumberFilterValue = {
+  type: 'number';
+  operator: 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'between';
+  value?: number;
+  valueTo?: number;
+};
+type TextFilterValue = {
+  type: 'text';
+  operator: 'contains' | 'equals' | 'starts-with' | 'ends-with';
+  value: string;
+};
+type BooleanFilterValue = {
+  type: 'boolean';
+  value: boolean | null;
+};
+type FilterValue = TagFilterValue | DateRangeFilterValue | NumberFilterValue | TextFilterValue | BooleanFilterValue;
+/** An active (added) filter instance with its current value. */
+type ActiveFilter = {
+  /** Unique instance id for this filter entry. */
+  id: string;
+  /** References a `FilterDefinition.id`. */
+  definitionId: string;
+  value: FilterValue;
+};
+/** Context value exposed by `UITableProvider` for the filter panel. */
+type TTableFilterContext = {
+  filterDefinitions: FilterDefinition[];
+  activeFilters: ActiveFilter[];
+  addFilter: (definitionId: string) => void;
+  removeFilter: (filterId: string) => void;
+  updateFilter: (filterId: string, value: FilterValue) => void;
+};
+//#endregion
+//#region packages/components/features/tables/components/commons/body.d.ts
+declare const UITableBody: react257.NamedExoticComponent<TUITableBody>;
+//#endregion
+//#region packages/components/features/tables/components/commons/cell.d.ts
+declare const UITableCell: react257.NamedExoticComponent<TUITableCell>;
+//#endregion
+//#region packages/components/features/tables/components/commons/cell-actions.d.ts
+declare const UITableCellActions: react257.NamedExoticComponent<TUITableCellActions>;
+//#endregion
+//#region packages/components/features/tables/components/commons/cell-select.d.ts
+declare const UITableCellSelect: react257.NamedExoticComponent<TUITableCellSelect>;
+//#endregion
+//#region packages/components/features/tables/components/commons/empty-display.d.ts
+declare const UITableEmptyDisplay: react257.NamedExoticComponent<TUITableEmptyDisplay>;
+//#endregion
+//#region packages/components/features/tables/components/commons/footer.d.ts
+declare const UITableFooter: react257.NamedExoticComponent<TUITableFooter>;
+//#endregion
+//#region packages/components/features/tables/components/commons/head.d.ts
+declare const UITableHead: react257.NamedExoticComponent<TUITableHead>;
+//#endregion
+//#region packages/components/features/tables/components/commons/head-cell.d.ts
+declare const UITableHeadCell: react257.NamedExoticComponent<TUITableHeadCell>;
+//#endregion
+//#region packages/components/features/tables/components/commons/head-cell-option.d.ts
+declare const UITableHeadCellOption: react257.NamedExoticComponent<TUITableHeadCellOption>;
+//#endregion
+//#region packages/components/features/tables/components/commons/head-cell-select.d.ts
+declare const UITableHeadCellSelect: react257.NamedExoticComponent<TUITableHeadCellSelect>;
+//#endregion
+//#region packages/components/features/tables/components/commons/head-row.d.ts
+declare const UITableHeadRow: react257.NamedExoticComponent<TUITableHeadRow>;
+//#endregion
+//#region packages/components/features/tables/components/commons/inner-table.d.ts
+declare const UITableInnerTable: react257.NamedExoticComponent<TUITableInnerTable>;
+//#endregion
+//#region packages/components/features/tables/components/commons/inner-wrapper.d.ts
+declare const UITableInnerWrapper: react257.NamedExoticComponent<TUITableInnerWrapper>;
+//#endregion
+//#region packages/components/features/tables/components/commons/load-more.d.ts
+declare const UITableLoadMore: react257.NamedExoticComponent<TUITableLoadMore>;
+//#endregion
+//#region packages/components/features/tables/components/commons/row.d.ts
+declare const UITableRow: react257.NamedExoticComponent<TUITableRow>;
+//#endregion
+//#region packages/components/features/tables/components/commons/wrapper.d.ts
+declare const UITableWrapper: react257.NamedExoticComponent<TUITableWrapper>;
+//#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
+/**
+ * Collapsible side-panel that lets users toggle column visibility and build
+ * 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.
+ *
+ * Wire filter capability by passing `filterDefinitions` and `onFilterChange` to
+ * the parent `UITableProvider`.
+ *
+ * @example
+ * ```tsx
+ * <UITableProvider
+ *   filterDefinitions={[
+ *     { id: 'status', label: 'Status', type: 'tag', options: [{ label: 'Active', value: 'active' }] },
+ *     { id: 'created', label: 'Created At', type: 'date-range' },
+ *     { id: 'amount', label: 'Amount', type: 'number' },
+ *   ]}
+ *   onFilterChange={filters => console.log(filters)}
+ * >
+ *   <ResizablePanelGroup direction="horizontal">
+ *     <ResizablePanel><UITable /></ResizablePanel>
+ *     <ResizableHandle />
+ *     <UITableFilter />
+ *   </ResizablePanelGroup>
+ * </UITableProvider>
+ * ```
+ */
+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,
+  isRefetching,
+  isLoading,
+  loadingDisplayRow,
+  data,
+  columns,
+  totalRows,
+  leftPinnedColumns,
+  rightPinnedColumns,
+  keyOfClickRow,
+  onClickRow,
+  onRowSelection,
+  onColumnPinning,
+  fetchMoreData,
+  emptyDisplayHeight,
+  csvData,
+  csvFileName,
+  filterDefinitions,
+  onFilterChange,
+  children
+}: 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 { TUITableInnerTable as $, FilterValue as A, TTableVirtualizerContext as B, ActiveFilter as C, FilterDefinition as D, DateRangeFilterValue as E, TTableFilterContext as F, TUITableColumn as G, TUITableCell as H, TTableHeadRowContext as I, TUITableHead as J, TUITableEmptyDisplay as K, TTableInnerTableContext as L, RowData as M, TTableBodyContext as N, FilterOption as O, TTableContext as P, TUITableHeadRow as Q, TTableInnerWrapperContext as R, UITableBody as S, UITableBadgeDisplay as St, CsvCell as T, TUITableCellActions as U, TUITableBody as V, TUITableCellSelect as W, TUITableHeadCellOption as X, TUITableHeadCell as Y, TUITableHeadCellSelect as Z, UITableFooter as _, UITableEmailDisplay as _t, UITableFilter as a, TagFilterValue as at, UITableCellActions as b, UITableCurrencyDisplay as bt, UITableRow as c, UITableStatusDisplay as ct, UITableInnerTable as d, UITableProgressDisplay as dt, TUITableInnerWrapper as et, UITableHeadRow as f, UITablePhoneNumberDisplay as ft, UITableHead as g, UITableListDisplay as gt, UITableHeadCell as h, UITableMoreButton as ht, UITableProvider as i, TableProviderProps as it, NumberFilterValue as j, FilterType as k, UITableLoadMore as l, UITableStatisticDisplay as lt, UITableHeadCellOption as m, UITableNameDisplay as mt, UITableTooltipActions as n, TUITableRow as nt, UITableContainer as o, TextFilterValue as ot, UITableHeadCellSelect as p, UITablePermalink as pt, TUITableFooter as q, UITableTooltipFilter as r, TUITableWrapper as rt, UITableWrapper as s, UITableUserDataDisplay as st, UITableTooltip as t, TUITableLoadMore as tt, UITableInnerWrapper as u, UITableRemoveButton as ut, UITableEmptyDisplay as v, UITableDescriptionDisplay as vt, BooleanFilterValue as w, UITableCell as x, UITableBooleanDisplay as xt, UITableCellSelect as y, UITableDateDisplay as yt, TTableRowContext as z };
+//# sourceMappingURL=index-B5wgYino.d.cts.map