@dashforge/tw 0.5.0-beta → 0.6.0-beta

package/src/components/Table/cells/RenderTwoLine.tsx

@@ -0,0 +1,34 @@
+import type { ReactNode } from 'react';
+import { cn } from '../../../utils/cn.js';
+
+export interface RenderTwoLineProps {
+  primary: ReactNode;
+  secondary: ReactNode;
+  className?: string;
+}
+
+/**
+ * Two-line cell renderer: a bold primary line stacked above a muted
+ * secondary line. Useful for `Name + email`, `Title + ID`, etc.
+ *
+ * Replaces the MUI-side `RenderTwoLineCell` without the magic-number
+ * vertical-align fudges (`mt: 0.8 / 0.2`) — flexbox handles the
+ * vertical layout cleanly.
+ *
+ * Dashforge identity rule: text colors auto-invert via the
+ * `dashforgePreset()` CSS-variable swap. No `dark:` variants needed
+ * on neutral palette.
+ */
+export function RenderTwoLine(props: RenderTwoLineProps) {
+  const { primary, secondary, className } = props;
+  return (
+    <div className={cn('flex flex-col leading-tight', className)}>
+      <span className="font-medium text-neutral-900">
+        {primary}
+      </span>
+      <span className="text-xs text-neutral-500 mt-0.5">
+        {secondary}
+      </span>
+    </div>
+  );
+}

package/src/components/Table/cells/RowActionsMenu.tsx

@@ -0,0 +1,147 @@
+import { useState, type ReactNode } from 'react';
+import type { AccessRequirement } from '@dashforge/rbac';
+import { Popover } from '../../Popover/Popover.js';
+import { useAccessState } from '../../../hooks/useAccessState.js';
+import { cn } from '../../../utils/cn.js';
+
+/**
+ * Single action definition for `<RowActionsMenu>`.
+ *
+ * `access` (optional) gates the action via RBAC:
+ *  - `onUnauthorized: 'hide'`     → action not rendered
+ *  - `onUnauthorized: 'disable'`  → action visible, disabled
+ *  - `onUnauthorized: 'readonly'` → action visible, disabled
+ */
+export interface TableRowAction<T> {
+  label: ReactNode;
+  onClick: (row: T) => void;
+  icon?: ReactNode;
+  color?: 'default' | 'danger' | 'warning';
+  disabled?: boolean;
+  access?: AccessRequirement;
+}
+
+export interface RowActionsMenuProps<T> {
+  row: T;
+  actions: TableRowAction<T>[];
+  /** Custom trigger element. Defaults to a ⋮ icon button. */
+  trigger?: ReactNode;
+  /** Aria-label for the default trigger. */
+  ariaLabel?: string;
+}
+
+/**
+ * 3-dot row actions menu. Renders a trigger button that opens a
+ * Popover (Sprint 3 component) with a list of action menu items.
+ *
+ * Replaces the MUI-side `RowActions.tsx` (IconButton + Menu) with
+ * the TW equivalents. Per-action RBAC honored: hidden actions are
+ * filtered out, disabled actions render disabled.
+ */
+export function RowActionsMenu<T>(props: RowActionsMenuProps<T>) {
+  const { row, actions, trigger, ariaLabel = 'Row actions' } = props;
+  const [open, setOpen] = useState(false);
+
+  // Filter actions by RBAC (hidden actions removed entirely)
+  const visibleActions = actions.filter((action) => {
+    if (!action.access) return true;
+    return action.access.onUnauthorized !== 'hide';
+  });
+
+  if (visibleActions.length === 0) return null;
+
+  return (
+    <Popover
+      open={open}
+      onOpenChange={setOpen}
+      side="bottom"
+      align="end"
+      content={
+        <ul className="flex flex-col gap-0.5 min-w-[140px]" role="menu">
+          {visibleActions.map((action, idx) => (
+            <RowActionMenuItem
+              key={idx}
+              action={action}
+              row={row}
+              onClose={() => setOpen(false)}
+            />
+          ))}
+        </ul>
+      }
+    >
+      {trigger ?? (
+        <button
+          type="button"
+          aria-label={ariaLabel}
+          aria-haspopup="menu"
+          aria-expanded={open}
+          className={cn(
+            'inline-flex items-center justify-center h-8 w-8 rounded-md',
+            // Neutral palette auto-inverts via the dashforgePreset()
+            // CSS-var swap — no `dark:` variant needed.
+            'text-neutral-500 hover:text-neutral-900',
+            'hover:bg-neutral-100',
+            'focus:outline-none focus-visible:ring-2 focus-visible:ring-primary-500',
+            'transition-colors motion-reduce:transition-none',
+          )}
+        >
+          <svg
+            width="1em"
+            height="1em"
+            viewBox="0 0 16 16"
+            fill="currentColor"
+            aria-hidden="true"
+          >
+            <circle cx="8" cy="3"  r="1.4" />
+            <circle cx="8" cy="8"  r="1.4" />
+            <circle cx="8" cy="13" r="1.4" />
+          </svg>
+        </button>
+      )}
+    </Popover>
+  );
+}
+
+function RowActionMenuItem<T>(props: {
+  action: TableRowAction<T>;
+  row: T;
+  onClose: () => void;
+}) {
+  const { action, row, onClose } = props;
+  const accessState = useAccessState(action.access);
+  const isDisabled = action.disabled || accessState.disabled || accessState.readonly;
+
+  return (
+    <li role="none">
+      <button
+        type="button"
+        role="menuitem"
+        disabled={isDisabled}
+        onClick={() => {
+          onClose();
+          action.onClick(row);
+        }}
+        className={cn(
+          'flex items-center gap-2 w-full text-left',
+          'px-3 py-1.5 rounded-md text-sm',
+          // Neutral palette auto-inverts; danger/warning are color
+          // palettes (no auto-invert) so they keep their `dark:` shift
+          // intentionally — design choice, not a bug.
+          'hover:bg-neutral-100',
+          'focus:outline-none focus-visible:bg-neutral-100',
+          'transition-colors motion-reduce:transition-none',
+          'disabled:opacity-50 disabled:pointer-events-none',
+          action.color === 'danger' && 'text-danger-700 dark:text-danger-300',
+          action.color === 'warning' && 'text-warning-700 dark:text-warning-300',
+        )}
+      >
+        {action.icon && (
+          <span className="inline-flex shrink-0" aria-hidden="true">
+            {action.icon}
+          </span>
+        )}
+        <span>{action.label}</span>
+      </button>
+    </li>
+  );
+}

package/src/components/Table/cells/index.ts

@@ -0,0 +1,14 @@
+export { RenderText } from './RenderText.js';
+export type { RenderTextProps } from './RenderText.js';
+
+export { RenderTwoLine } from './RenderTwoLine.js';
+export type { RenderTwoLineProps } from './RenderTwoLine.js';
+
+export { RenderChip } from './RenderChip.js';
+export type { RenderChipProps } from './RenderChip.js';
+
+export { RenderButton } from './RenderButton.js';
+export type { RenderButtonProps } from './RenderButton.js';
+
+export { RowActionsMenu } from './RowActionsMenu.js';
+export type { RowActionsMenuProps, TableRowAction } from './RowActionsMenu.js';

package/src/components/Table/table.types.ts

@@ -0,0 +1,337 @@
+import type { ReactNode } from 'react';
+import type { AccessRequirement } from '@dashforge/rbac';
+import type { TableVariants } from './table.variants.js';
+
+// ───── Nested key util ─────
+
+/**
+ * Type-level dotted path through an object's nested structure.
+ *
+ * `NestedKeyOf<{ user: { name: string } }>` → `'user' | 'user.name'`.
+ *
+ * Used as the `field` of a column to give autocomplete on nested
+ * paths. The runtime lookup happens via `getNestedValue` in
+ * `_internal/getNestedValue.ts` (split on `.` and walk).
+ */
+export type NestedKeyOf<T extends object> = {
+  [K in keyof T & (string | number)]: T[K] extends object | undefined
+    ? T[K] extends ReadonlyArray<unknown>
+      ? `${K}`
+      : NonNullable<T[K]> extends object
+        ? `${K}` | `${K}.${NestedKeyOf<NonNullable<T[K]>>}`
+        : `${K}`
+    : `${K}`;
+}[keyof T & (string | number)];
+
+// ───── Column types ─────
+
+/**
+ * Auto-detected primitive type for a column. Drives smart defaults:
+ *  - `number`  → align right + monospace (`tabular-nums`)
+ *  - `date`    → align left + monospace (consistent ISO width)
+ *  - `boolean` → align center
+ *  - `string`  → align left (default)
+ *  - `unknown` → fallback to left, no monospace
+ */
+export type TableColumnInferredType =
+  | 'number'
+  | 'date'
+  | 'boolean'
+  | 'string'
+  | 'unknown';
+
+/**
+ * Context passed to a custom `cellRenderer`. Mirrors what the consumer
+ * needs to render a cell: row, resolved value, position, selection
+ * state, expand state, and the resolved RBAC access state for THIS
+ * column.
+ */
+export interface TableCellContext<T> {
+  row: T;
+  value: unknown;
+  rowIndex: number;
+  isSelected: boolean;
+  isExpanded: boolean;
+  /** Resolved RBAC state for this column. `null` if no `access` set. */
+  access: { hidden: boolean; disabled: boolean; readonly: boolean } | null;
+}
+
+/**
+ * One column definition for `<Table>`.
+ *
+ * **i18n**: pass `t('users.name')` directly to `header` — `header`
+ * accepts `string` for the common case. Use the function form
+ * `header: () => <span>…</span>` only when you need richer JSX.
+ *
+ * **Smart defaults**: when `align` / `monospace` are omitted, the
+ * Table auto-detects the column type from the first non-null value
+ * across the visible rows and applies `right + tabular-nums` for
+ * numbers, `center` for booleans, etc. Explicit props always win.
+ */
+export interface TableColumn<T extends object> {
+  /**
+   * Dotted path to the value in each row. Supports nested keys
+   * (`'address.city.zipCode'`) thanks to `NestedKeyOf<T>` typing +
+   * runtime `getNestedValue()`.
+   */
+  field: NestedKeyOf<T> | (string & {});
+
+  /**
+   * Visible header. Pass a translation string directly:
+   * `header: t('users.name')`. Use the function form for richer
+   * JSX (e.g. header with an icon).
+   */
+  header: string | (() => ReactNode);
+
+  /** Pixel width (`px`). Mutually informative with `flex`. */
+  width?: number;
+  /** Flex grow factor (CSS `flex: <n> 1 0`). */
+  flex?: number;
+  /** Minimum pixel width (for resizable columns — deferred to v1-bis). */
+  minWidth?: number;
+
+  /**
+   * Horizontal alignment. Default is auto-detected from value type
+   * (number → right, boolean → center, otherwise left).
+   */
+  align?: 'left' | 'right' | 'center';
+
+  /**
+   * Opt-in to a monospace **font family** for this column. The
+   * library never auto-applies `font-mono` — it would override the
+   * consumer's theme `font-sans`. Set `true` explicitly only when
+   * the design calls for a typewriter font (e.g. raw hex IDs).
+   *
+   * The dashforgePreset does NOT own the `fontFamily` axis; the
+   * consumer configures the mono stack in their own
+   * `tailwind.config.ts` (`theme.extend.fontFamily.mono`).
+   */
+  monospace?: boolean;
+
+  /**
+   * Apply `font-variant-numeric: tabular-nums` so every digit
+   * occupies the same width — clean alignment for currency / metric
+   * columns. Does NOT change the font family. Auto-applied for
+   * `number` and `date` columns; pass `false` explicitly to opt out
+   * or `true` to force on a string column.
+   */
+  tabularNums?: boolean;
+
+  /**
+   * Make the column sortable. Pass `true` for default comparator
+   * (works for string/number/date/boolean) or a custom
+   * `(a, b) => number`.
+   */
+  sortable?: boolean | ((a: T, b: T) => number);
+
+  /**
+   * Include this column in the global search filter.
+   * @default false
+   */
+  searchable?: boolean;
+
+  /**
+   * Enable per-column quick filter (text-based in v1).
+   * @default false
+   */
+  filterable?: boolean;
+
+  /**
+   * Custom cell renderer. Receives the full row + the resolved
+   * (potentially nested) value, the row index, selection state,
+   * expansion state, and the RBAC access state.
+   */
+  cellRenderer?: (ctx: TableCellContext<T>) => ReactNode;
+
+  /**
+   * Per-column RBAC. `onUnauthorized: 'hide'` removes the column
+   * entirely from header AND every row cell (a11y-correct).
+   * `disable` / `readonly` are forwarded to `cellRenderer` via
+   * `ctx.access` — the renderer is expected to honor them.
+   */
+  access?: AccessRequirement;
+
+  /** Reserved for v1-bis (column-visibility dialog). */
+  hideable?: boolean;
+  defaultHidden?: boolean;
+}
+
+// ───── State models ─────
+
+export type TableSortDirection = 'asc' | 'desc';
+
+export interface TableSortItem {
+  field: string;
+  direction: TableSortDirection;
+}
+
+/**
+ * Sort model. Single-column sort = array of length 1. Multi-column
+ * sort = array of N (typically up to 3). The order matters: first
+ * item is the primary sort key, subsequent items break ties.
+ */
+export type TableSortModel = TableSortItem[];
+
+export interface TableFilterItem {
+  field: string;
+  /** Text substring match. Future ops: `equals`, `in`, `gte`, `lte`, `between`. */
+  op: 'contains';
+  value: string;
+}
+
+export type TableFilterModel = TableFilterItem[];
+
+export type TableRowSelectionMode = 'none' | 'single' | 'multiple';
+
+// ───── i18n labels ─────
+
+/**
+ * Internal default strings used by the Table for accessibility
+ * announcements, density toggle, search placeholder, etc. Pass the
+ * subset you need to translate; the rest fall back to English.
+ *
+ * For column headers, empty state, bulk actions and row action
+ * labels — pass the translated value directly via the matching
+ * prop (`header`, `emptyState`, `bulkActions`, `rowActions`).
+ */
+export interface TableLabels {
+  searchPlaceholder?: string;
+  noData?: string;
+  loading?: string;
+  ariaSortNone?: string;
+  ariaSortAscending?: string;
+  ariaSortDescending?: string;
+  ariaSelectRow?: string;
+  ariaSelectAllRows?: string;
+  ariaExpandRow?: string;
+  ariaCollapseRow?: string;
+  /** "X selected" — `{count}` placeholder gets replaced. */
+  selectedCount?: string;
+  clearSelection?: string;
+  /** Per-column filter Popover. */
+  filterColumn?: string;
+  filterApply?: string;
+  filterClear?: string;
+  /** Density toggle. */
+  density?: string;
+  densityCompact?: string;
+  densityComfortable?: string;
+  densitySpacious?: string;
+}
+
+// ───── Slot props ─────
+
+export interface TableSlotProps {
+  root?: { className?: string };
+  toolbar?: { className?: string };
+  search?: { className?: string };
+  scroll?: { className?: string };
+  table?: { className?: string };
+  thead?: { className?: string };
+  tbody?: { className?: string };
+  headerRow?: { className?: string };
+  headerCell?: { className?: string };
+  row?: { className?: string };
+  cell?: { className?: string };
+  emptyState?: { className?: string };
+  loadingOverlay?: { className?: string };
+  selectionCell?: { className?: string };
+  expandToggleCell?: { className?: string };
+  expandedRow?: { className?: string };
+  rowActionsCell?: { className?: string };
+  bulkActionFooter?: { className?: string };
+}
+
+// ───── Expandable rows config ─────
+
+export interface TableExpandableConfig<T> {
+  render: (row: T) => ReactNode;
+  expandedRowIds?: string[];
+  onExpandChange?: (ids: string[]) => void;
+}
+
+// ───── Main props ─────
+
+/**
+ * Props for `<Table>`.
+ *
+ * Hybrid declarative-first architecture: by default every state piece
+ * (sort, filter, search, selection, expansion) is internal. Pass the
+ * matching controlled prop + change handler to lift state up.
+ *
+ * Smart defaults: column types are auto-detected on first render —
+ * number columns get right-align + tabular-nums, dates get monospace,
+ * booleans get center-align, etc. Override via explicit `align` /
+ * `monospace` per column.
+ *
+ * Visual style: Stripe-inspired clean lines by default
+ * (`variant="lines"`), row actions revealed on hover, sticky header,
+ * `comfortable` density. Switch via variant / density / size props.
+ *
+ * i18n: column `header` accepts plain strings (use `t('...')`
+ * directly). All internal label strings configurable via `labels`
+ * prop with English defaults.
+ */
+export interface TableProps<T extends object>
+  extends Pick<TableVariants, 'variant' | 'size' | 'density'> {
+  // ───── Data ─────
+  rows: T[];
+  cols: TableColumn<T>[];
+  /** Stable row id resolver. Default: positional index. */
+  getRowId?: (row: T, index: number) => string;
+
+  // ───── Sort ─────
+  sortModel?: TableSortModel;
+  onSortChange?: (model: TableSortModel) => void;
+  /** Default sort applied when uncontrolled. */
+  defaultSortModel?: TableSortModel;
+
+  // ───── Search ─────
+  enableSearch?: boolean;
+  searchQuery?: string;
+  onSearchQueryChange?: (q: string) => void;
+  searchPlaceholder?: string;
+  searchDebounceMs?: number;
+
+  // ───── Per-column filter ─────
+  filterModel?: TableFilterModel;
+  onFilterChange?: (model: TableFilterModel) => void;
+
+  // ───── Selection ─────
+  rowSelection?: TableRowSelectionMode;
+  selectedRowIds?: string[];
+  onSelectionChange?: (ids: string[]) => void;
+  /** Sticky bulk action footer (visible only when selection > 0). */
+  bulkActions?: (selectedRows: T[]) => ReactNode;
+
+  // ───── Expandable rows ─────
+  expandable?: TableExpandableConfig<T>;
+
+  // ───── Row actions (revealed on hover) ─────
+  rowActions?: (row: T) => ReactNode;
+
+  // ───── States ─────
+  loading?: boolean;
+  /** Number of skeleton rows shown while `loading=true`. @default 5 */
+  loadingRowCount?: number;
+  emptyState?: ReactNode;
+
+  // ───── A11Y ─────
+  /** Sticky header. @default true */
+  stickyHeader?: boolean;
+  /** Optional caption for screen readers. */
+  caption?: ReactNode;
+  /** Renders the caption visually too (otherwise sr-only). @default false */
+  showCaption?: boolean;
+
+  // ───── RBAC ─────
+  /** Table-level RBAC. `hide` returns null; `disable` greys everything. */
+  access?: AccessRequirement;
+
+  // ───── i18n ─────
+  labels?: TableLabels;
+
+  // ───── Customization escape hatches ─────
+  sx?: string;
+  slotProps?: TableSlotProps;
+}