@dashforge/tw 0.5.0-beta → 0.6.0-beta

package/src/components/Table/_internal/useTableSelection.test.ts

@@ -0,0 +1,100 @@
+// @vitest-environment jsdom
+import { describe, it, expect } from 'vitest';
+import { renderHook, act } from '@testing-library/react';
+import { useState } from 'react';
+import { useTableSelection } from './useTableSelection.js';
+
+function setup(mode: 'none' | 'single' | 'multiple', initial: string[] = []) {
+  return renderHook(() => {
+    const [ids, setIds] = useState<string[]>(initial);
+    const setIdsWithFn = (next: string[] | ((prev: string[]) => string[])) =>
+      setIds((prev) => (typeof next === 'function' ? next(prev) : next));
+    const selection = useTableSelection(mode, ids, setIdsWithFn);
+    return { ids, selection };
+  });
+}
+
+describe('useTableSelection — single mode', () => {
+  it('toggleRow selects when not selected', () => {
+    const { result } = setup('single');
+    act(() => result.current.selection.toggleRow('a'));
+    expect(result.current.ids).toEqual(['a']);
+  });
+
+  it('toggleRow on a different row REPLACES', () => {
+    const { result } = setup('single', ['a']);
+    act(() => result.current.selection.toggleRow('b'));
+    expect(result.current.ids).toEqual(['b']);
+  });
+
+  it('toggleRow on same row DESELECTS', () => {
+    const { result } = setup('single', ['a']);
+    act(() => result.current.selection.toggleRow('a'));
+    expect(result.current.ids).toEqual([]);
+  });
+});
+
+describe('useTableSelection — multiple mode', () => {
+  it('toggleRow ADDS to selection', () => {
+    const { result } = setup('multiple');
+    act(() => result.current.selection.toggleRow('a'));
+    act(() => result.current.selection.toggleRow('b'));
+    expect(result.current.ids.sort()).toEqual(['a', 'b']);
+  });
+
+  it('toggleRow on selected row REMOVES', () => {
+    const { result } = setup('multiple', ['a', 'b']);
+    act(() => result.current.selection.toggleRow('a'));
+    expect(result.current.ids).toEqual(['b']);
+  });
+
+  it('toggleAll selects all when none selected', () => {
+    const { result } = setup('multiple');
+    act(() => result.current.selection.toggleAll(['a', 'b', 'c']));
+    expect(result.current.ids).toEqual(['a', 'b', 'c']);
+  });
+
+  it('toggleAll deselects all when all already selected', () => {
+    const { result } = setup('multiple', ['a', 'b', 'c']);
+    act(() => result.current.selection.toggleAll(['a', 'b', 'c']));
+    expect(result.current.ids).toEqual([]);
+  });
+
+  it('toggleAll selects all when SOME already selected', () => {
+    const { result } = setup('multiple', ['a']);
+    act(() => result.current.selection.toggleAll(['a', 'b', 'c']));
+    expect(result.current.ids).toEqual(['a', 'b', 'c']);
+  });
+
+  it('isAllSelected reflects state', () => {
+    const { result } = setup('multiple', ['a', 'b']);
+    expect(result.current.selection.isAllSelected(['a', 'b'])).toBe(true);
+    expect(result.current.selection.isAllSelected(['a', 'b', 'c'])).toBe(false);
+  });
+
+  it('isIndeterminate is true when some but not all selected', () => {
+    const { result } = setup('multiple', ['a']);
+    expect(result.current.selection.isIndeterminate(['a', 'b', 'c'])).toBe(true);
+    expect(result.current.selection.isIndeterminate(['a'])).toBe(false); // all selected → false
+  });
+
+  it('clearSelection resets to empty', () => {
+    const { result } = setup('multiple', ['a', 'b', 'c']);
+    act(() => result.current.selection.clearSelection());
+    expect(result.current.ids).toEqual([]);
+  });
+});
+
+describe('useTableSelection — none mode', () => {
+  it('toggleRow is no-op', () => {
+    const { result } = setup('none');
+    act(() => result.current.selection.toggleRow('a'));
+    expect(result.current.ids).toEqual([]);
+  });
+
+  it('toggleAll is no-op', () => {
+    const { result } = setup('none');
+    act(() => result.current.selection.toggleAll(['a', 'b']));
+    expect(result.current.ids).toEqual([]);
+  });
+});

package/src/components/Table/_internal/useTableSelection.ts

@@ -0,0 +1,100 @@
+import { useCallback, useMemo } from 'react';
+import type { TableRowSelectionMode } from '../table.types.js';
+
+export interface UseTableSelectionResult {
+  selectedRowIds: string[];
+  isSelected: (rowId: string) => boolean;
+  toggleRow: (rowId: string) => void;
+  toggleAll: (allRowIds: string[]) => void;
+  clearSelection: () => void;
+  /** True when EVERY id in `allRowIds` is selected. */
+  isAllSelected: (allRowIds: string[]) => boolean;
+  /** True when at least one (but not all) of `allRowIds` is selected. */
+  isIndeterminate: (allRowIds: string[]) => boolean;
+}
+
+/**
+ * Selection logic helper. Given the controllable selection state +
+ * the setter (from `useControllableState`), exposes ergonomic
+ * helpers the Table calls from its render path.
+ *
+ *  - `single` mode: at most one row selected. Toggling another
+ *    replaces the previous.
+ *  - `multiple` mode: any subset selectable; toggling adds/removes.
+ *  - `none` mode: every toggle is a no-op (the Table shouldn't
+ *    render the checkbox cells anyway, but this is defensive).
+ */
+export function useTableSelection(
+  mode: TableRowSelectionMode,
+  selectedRowIds: string[],
+  setSelectedRowIds: (next: string[] | ((prev: string[]) => string[])) => void,
+): UseTableSelectionResult {
+  const selectedSet = useMemo(
+    () => new Set(selectedRowIds),
+    [selectedRowIds],
+  );
+
+  const isSelected = useCallback(
+    (rowId: string) => selectedSet.has(rowId),
+    [selectedSet],
+  );
+
+  const toggleRow = useCallback(
+    (rowId: string) => {
+      if (mode === 'none') return;
+      if (mode === 'single') {
+        setSelectedRowIds(selectedSet.has(rowId) ? [] : [rowId]);
+        return;
+      }
+      // multiple
+      setSelectedRowIds((prev) => {
+        const next = new Set(prev);
+        if (next.has(rowId)) next.delete(rowId);
+        else next.add(rowId);
+        return [...next];
+      });
+    },
+    [mode, selectedSet, setSelectedRowIds],
+  );
+
+  const toggleAll = useCallback(
+    (allRowIds: string[]) => {
+      if (mode !== 'multiple') return;
+      const allSelected = allRowIds.every((id) => selectedSet.has(id));
+      setSelectedRowIds(allSelected ? [] : [...allRowIds]);
+    },
+    [mode, selectedSet, setSelectedRowIds],
+  );
+
+  const clearSelection = useCallback(() => {
+    setSelectedRowIds([]);
+  }, [setSelectedRowIds]);
+
+  const isAllSelected = useCallback(
+    (allRowIds: string[]) => {
+      if (allRowIds.length === 0) return false;
+      return allRowIds.every((id) => selectedSet.has(id));
+    },
+    [selectedSet],
+  );
+
+  const isIndeterminate = useCallback(
+    (allRowIds: string[]) => {
+      if (allRowIds.length === 0) return false;
+      const some = allRowIds.some((id) => selectedSet.has(id));
+      const all = allRowIds.every((id) => selectedSet.has(id));
+      return some && !all;
+    },
+    [selectedSet],
+  );
+
+  return {
+    selectedRowIds,
+    isSelected,
+    toggleRow,
+    toggleAll,
+    clearSelection,
+    isAllSelected,
+    isIndeterminate,
+  };
+}

package/src/components/Table/_internal/useTableSort.test.ts

@@ -0,0 +1,150 @@
+// @vitest-environment jsdom
+import { describe, it, expect } from 'vitest';
+import { renderHook } from '@testing-library/react';
+import { useTableSort, cycleSortFor } from './useTableSort.js';
+import type { TableColumn, TableSortModel } from '../table.types.js';
+
+interface Row {
+  id: string;
+  name: string;
+  age: number | null;
+  joinedAt: Date | null;
+}
+
+const cols: TableColumn<Row>[] = [
+  { field: 'name',     header: 'Name',     sortable: true },
+  { field: 'age',      header: 'Age',      sortable: true },
+  { field: 'joinedAt' as never, header: 'Joined', sortable: true },
+];
+
+const rows: Row[] = [
+  { id: '1', name: 'Charlie', age: 30,   joinedAt: new Date('2024-01-15') },
+  { id: '2', name: 'Alice',   age: 25,   joinedAt: new Date('2024-03-01') },
+  { id: '3', name: 'Bob',     age: null, joinedAt: null },
+  { id: '4', name: 'alice',   age: 40,   joinedAt: new Date('2024-02-10') },
+];
+
+describe('useTableSort', () => {
+  it('returns rows untouched when sortModel is empty', () => {
+    const { result } = renderHook(() => useTableSort(rows, cols, []));
+    expect(result.current.map((r) => r.id)).toEqual(['1', '2', '3', '4']);
+  });
+
+  it('sorts strings asc (case-insensitive)', () => {
+    const sortModel: TableSortModel = [{ field: 'name', direction: 'asc' }];
+    const { result } = renderHook(() => useTableSort(rows, cols, sortModel));
+    // alice < Alice < Bob < Charlie (case-insensitive)
+    expect(result.current.map((r) => r.name.toLowerCase())).toEqual([
+      'alice', 'alice', 'bob', 'charlie',
+    ]);
+  });
+
+  it('sorts numbers desc', () => {
+    const sortModel: TableSortModel = [{ field: 'age', direction: 'desc' }];
+    const { result } = renderHook(() => useTableSort(rows, cols, sortModel));
+    // 40, 30, 25, null-last
+    expect(result.current.map((r) => r.age)).toEqual([40, 30, 25, null]);
+  });
+
+  it('places null values LAST regardless of direction (asc)', () => {
+    const sortModel: TableSortModel = [{ field: 'age', direction: 'asc' }];
+    const { result } = renderHook(() => useTableSort(rows, cols, sortModel));
+    // 25, 30, 40, null-last
+    expect(result.current.map((r) => r.age)).toEqual([25, 30, 40, null]);
+  });
+
+  it('sorts Date asc (epoch ms order)', () => {
+    const sortModel: TableSortModel = [{ field: 'joinedAt', direction: 'asc' }];
+    const { result } = renderHook(() => useTableSort(rows, cols, sortModel));
+    // 2024-01-15 → 2024-02-10 → 2024-03-01 → null-last
+    expect(result.current.map((r) => r.id)).toEqual(['1', '4', '2', '3']);
+  });
+
+  it('supports custom comparator', () => {
+    const colsCustom: TableColumn<Row>[] = [
+      // Sort by length of name ascending
+      { field: 'name', header: 'Name', sortable: (a, b) => a.name.length - b.name.length },
+    ];
+    const sortModel: TableSortModel = [{ field: 'name', direction: 'asc' }];
+    const { result } = renderHook(() => useTableSort(rows, colsCustom, sortModel));
+    expect(result.current.map((r) => r.name)).toEqual(['Bob', 'Alice', 'alice', 'Charlie']);
+  });
+
+  it('falls back to next sort item on tie (multi-column sort)', () => {
+    const sortModel: TableSortModel = [
+      { field: 'name', direction: 'asc' },  // 'alice', 'Alice' tie
+      { field: 'age',  direction: 'asc' },  // then 25 before 40
+    ];
+    const { result } = renderHook(() => useTableSort(rows, cols, sortModel));
+    // 'alice' and 'Alice' tie on name → 25 before 40 → so id=2 before id=4
+    expect(result.current.slice(0, 2).map((r) => r.id)).toEqual(['2', '4']);
+  });
+
+  it('ignores sort items for non-sortable columns', () => {
+    const colsNotSortable: TableColumn<Row>[] = cols.map((c) => ({ ...c, sortable: false }));
+    const sortModel: TableSortModel = [{ field: 'name', direction: 'asc' }];
+    const { result } = renderHook(() => useTableSort(rows, colsNotSortable, sortModel));
+    // Original order preserved
+    expect(result.current.map((r) => r.id)).toEqual(['1', '2', '3', '4']);
+  });
+});
+
+describe('cycleSortFor', () => {
+  it('none → asc on first click', () => {
+    expect(cycleSortFor([], 'name', false)).toEqual([{ field: 'name', direction: 'asc' }]);
+  });
+
+  it('asc → desc on second click', () => {
+    expect(cycleSortFor([{ field: 'name', direction: 'asc' }], 'name', false)).toEqual([
+      { field: 'name', direction: 'desc' },
+    ]);
+  });
+
+  it('desc → none (empty) on third click', () => {
+    expect(cycleSortFor([{ field: 'name', direction: 'desc' }], 'name', false)).toEqual([]);
+  });
+
+  it('single-click on different column REPLACES sort', () => {
+    expect(
+      cycleSortFor([{ field: 'name', direction: 'asc' }], 'age', false),
+    ).toEqual([{ field: 'age', direction: 'asc' }]);
+  });
+
+  it('shift-click on different column APPENDS (multi-sort)', () => {
+    expect(
+      cycleSortFor([{ field: 'name', direction: 'asc' }], 'age', true),
+    ).toEqual([
+      { field: 'name', direction: 'asc' },
+      { field: 'age', direction: 'asc' },
+    ]);
+  });
+
+  it('shift-click on existing column cycles its direction', () => {
+    expect(
+      cycleSortFor(
+        [
+          { field: 'name', direction: 'asc' },
+          { field: 'age', direction: 'asc' },
+        ],
+        'age',
+        true,
+      ),
+    ).toEqual([
+      { field: 'name', direction: 'asc' },
+      { field: 'age', direction: 'desc' },
+    ]);
+  });
+
+  it('shift-click on desc column REMOVES it (preserving rest)', () => {
+    expect(
+      cycleSortFor(
+        [
+          { field: 'name', direction: 'asc' },
+          { field: 'age', direction: 'desc' },
+        ],
+        'age',
+        true,
+      ),
+    ).toEqual([{ field: 'name', direction: 'asc' }]);
+  });
+});

package/src/components/Table/_internal/useTableSort.ts

@@ -0,0 +1,141 @@
+import { useMemo } from 'react';
+import { getNestedValue } from './getNestedValue.js';
+import type {
+  TableColumn,
+  TableSortModel,
+  TableSortDirection,
+} from '../table.types.js';
+
+/**
+ * Default comparator. Handles the common primitive types in a
+ * sensible way:
+ *
+ *  - `null` / `undefined` always sort LAST (stable across asc/desc)
+ *  - `number` / `bigint`         → numeric comparison
+ *  - `string`                    → locale-aware compare via `Intl.Collator`
+ *  - `Date` / ISO-string-date    → numeric compare on epoch ms
+ *  - `boolean`                   → `false < true`
+ *  - mixed types fall back to string compare
+ *
+ * The locale collator is created once per call (cheap; cached
+ * upstream via memoization).
+ */
+function defaultCompare(a: unknown, b: unknown): number {
+  // Numbers
+  if (typeof a === 'number' && typeof b === 'number') {
+    return a - b;
+  }
+  if (typeof a === 'bigint' && typeof b === 'bigint') {
+    return a < b ? -1 : a > b ? 1 : 0;
+  }
+
+  // Dates
+  if (a instanceof Date && b instanceof Date) {
+    return a.getTime() - b.getTime();
+  }
+
+  // Booleans
+  if (typeof a === 'boolean' && typeof b === 'boolean') {
+    return a === b ? 0 : a ? 1 : -1;
+  }
+
+  // Strings (incl. ISO date strings — natural lexical ordering matches chronology)
+  if (typeof a === 'string' && typeof b === 'string') {
+    return a.localeCompare(b, undefined, { numeric: true, sensitivity: 'base' });
+  }
+
+  // Fallback: stringify and compare
+  return String(a).localeCompare(String(b), undefined, {
+    numeric: true,
+    sensitivity: 'base',
+  });
+}
+
+/**
+ * Applies the `sortModel` to `rows`. Returns a NEW sorted array
+ * (does not mutate input). Stable sort guaranteed by the underlying
+ * `Array.prototype.sort` in modern engines.
+ *
+ * Multi-column sort: items earlier in `sortModel` have higher
+ * precedence. Equal values fall through to the next sort item; if
+ * all sort items tie, the original order is preserved (stable).
+ */
+export function useTableSort<T extends object>(
+  rows: T[],
+  cols: TableColumn<T>[],
+  sortModel: TableSortModel,
+): T[] {
+  return useMemo(() => {
+    if (!sortModel || sortModel.length === 0) return rows;
+
+    const sortConfigs = sortModel
+      .map((item) => {
+        const col = cols.find((c) => (c.field as string) === item.field);
+        if (!col || !col.sortable) return null;
+        const customCompare =
+          typeof col.sortable === 'function' ? col.sortable : undefined;
+        return { item, col, customCompare };
+      })
+      .filter((x): x is NonNullable<typeof x> => x != null);
+
+    if (sortConfigs.length === 0) return rows;
+
+    // Decorate-sort-undecorate for stability across engines.
+    //
+    // Per sort item: null/undefined values always sort LAST, regardless
+    // of direction. This invariant lives outside the comparator so it's
+    // not inverted by `-cmp` when direction is `desc`. (Without this
+    // separation, `desc` flipped null-handling and placed nulls FIRST,
+    // which broke user expectations — fixed in the v1 implementation.)
+    return [...rows].sort((a, b) => {
+      for (const { item, customCompare } of sortConfigs) {
+        const aVal = customCompare ? a : getNestedValue(a, item.field);
+        const bVal = customCompare ? b : getNestedValue(b, item.field);
+
+        // Null-last (direction-independent)
+        const aNull = aVal == null;
+        const bNull = bVal == null;
+        if (aNull && bNull) continue;
+        if (aNull) return 1;
+        if (bNull) return -1;
+
+        const cmp = customCompare ? customCompare(a, b) : defaultCompare(aVal, bVal);
+        if (cmp !== 0) {
+          return item.direction === 'desc' ? -cmp : cmp;
+        }
+      }
+      return 0;
+    });
+  }, [rows, cols, sortModel]);
+}
+
+/**
+ * Three-state sort cycler: `none` → `asc` → `desc` → `none`.
+ *
+ * Used by the header click handler. Returns the next sort model
+ * to apply, given the current model + the clicked field + whether
+ * the user is multi-sorting (shift key).
+ */
+export function cycleSortFor(
+  current: TableSortModel,
+  field: string,
+  multi: boolean,
+): TableSortModel {
+  const existing = current.find((s) => s.field === field);
+  const nextDirection: TableSortDirection | null = !existing
+    ? 'asc'
+    : existing.direction === 'asc'
+      ? 'desc'
+      : null;
+
+  if (multi) {
+    // Multi-sort: keep other entries, update / add / remove this one.
+    const rest = current.filter((s) => s.field !== field);
+    if (nextDirection == null) return rest;
+    return [...rest, { field, direction: nextDirection }];
+  }
+
+  // Single-sort: replace the whole model.
+  if (nextDirection == null) return [];
+  return [{ field, direction: nextDirection }];
+}

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

@@ -0,0 +1,23 @@
+import type { MouseEvent, ReactNode } from 'react';
+import { Button } from '../../Button/Button.js';
+import type { ButtonProps } from '../../Button/button.types.js';
+
+export interface RenderButtonProps
+  extends Pick<ButtonProps, 'variant' | 'color' | 'size' | 'disabled' | 'access'> {
+  label: ReactNode;
+  onClick?: (event: MouseEvent<HTMLButtonElement>) => void;
+}
+
+/**
+ * Inline button cell renderer. Thin wrapper over `<Button>` with
+ * the size narrowed to `sm` by default (table density expects compact
+ * controls).
+ */
+export function RenderButton(props: RenderButtonProps) {
+  const { label, onClick, variant = 'ghost', size = 'sm', ...rest } = props;
+  return (
+    <Button variant={variant} size={size} onClick={onClick} {...rest}>
+      {label}
+    </Button>
+  );
+}

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

@@ -0,0 +1,103 @@
+import type { ReactNode } from 'react';
+import { tv, type VariantProps } from 'tailwind-variants';
+import { cn } from '../../../utils/cn.js';
+
+/**
+ * Internal mini-chip used by the cell renderer library. Not exported
+ * from `@dashforge/tw` as a standalone component (per Sprint 4.1
+ * scope decision — a standalone `<Chip>` may ship in Sprint 5 if
+ * demand emerges).
+ *
+ * Variants:
+ *  - `color`: 7 intents (neutral / primary / success / warning /
+ *    danger / info / secondary)
+ *  - `variant`: `soft` (default) / `solid` / `outline`
+ *  - `size`: `sm` / `md`
+ */
+const chipVariants = tv({
+  base: [
+    'inline-flex items-center gap-1 rounded-full font-medium',
+    'whitespace-nowrap',
+  ],
+  variants: {
+    color: {
+      neutral: '',
+      primary: '',
+      success: '',
+      warning: '',
+      danger: '',
+      info: '',
+      secondary: '',
+    },
+    variant: {
+      soft: '',
+      solid: '',
+      outline: '',
+    },
+    size: {
+      sm: 'h-5 px-2 text-xs',
+      md: 'h-6 px-2.5 text-xs',
+    },
+  },
+  compoundVariants: [
+    // soft = subtle bg + dark text.
+    // Neutral row uses NO `dark:` variants — the dashforgePreset()
+    // CSS-var swap auto-inverts the neutral palette already.
+    // Color rows below KEEP `dark:` variants because color palettes
+    // don't auto-invert: the `dark:` shift is an intentional design
+    // choice (darker bg + lighter text in dark mode for visual cohesion).
+    { variant: 'soft', color: 'neutral',   class: 'bg-neutral-100 text-neutral-700' },
+    { variant: 'soft', color: 'primary',   class: 'bg-primary-100 dark:bg-primary-950 text-primary-700 dark:text-primary-300' },
+    { variant: 'soft', color: 'success',   class: 'bg-success-100 dark:bg-success-950 text-success-700 dark:text-success-300' },
+    { variant: 'soft', color: 'warning',   class: 'bg-warning-100 dark:bg-warning-950 text-warning-700 dark:text-warning-300' },
+    { variant: 'soft', color: 'danger',    class: 'bg-danger-100 dark:bg-danger-950 text-danger-700 dark:text-danger-300' },
+    { variant: 'soft', color: 'info',      class: 'bg-info-100 dark:bg-info-950 text-info-700 dark:text-info-300' },
+    { variant: 'soft', color: 'secondary', class: 'bg-secondary-100 dark:bg-secondary-950 text-secondary-700 dark:text-secondary-300' },
+    // solid = full bg + light text
+    // solid neutral: bg + text both anchored to neutral palette
+    // (auto-inverts). `text-white` would not invert and would break
+    // contrast in light mode against a `bg-neutral-700` dark bg, so
+    // we stick to `text-neutral-50` (light text in light mode, dark
+    // in dark — wait, that's wrong too). Actually `text-neutral-50`
+    // auto-inverts: light text in light mode (against dark bg) is
+    // what we want; in dark mode `bg-neutral-700` becomes light AND
+    // `text-neutral-50` becomes dark — contrast preserved.
+    { variant: 'solid', color: 'neutral',   class: 'bg-neutral-700 text-neutral-50' },
+    { variant: 'solid', color: 'primary',   class: 'bg-primary-500 text-white' },
+    { variant: 'solid', color: 'success',   class: 'bg-success-500 text-white' },
+    { variant: 'solid', color: 'warning',   class: 'bg-warning-500 text-white' },
+    { variant: 'solid', color: 'danger',    class: 'bg-danger-500 text-white' },
+    { variant: 'solid', color: 'info',      class: 'bg-info-500 text-white' },
+    { variant: 'solid', color: 'secondary', class: 'bg-secondary-500 text-white' },
+    // outline = border + colored text
+    // outline neutral: both border + text auto-invert via CSS-var swap.
+    { variant: 'outline', color: 'neutral',   class: 'border border-neutral-300 text-neutral-700' },
+    { variant: 'outline', color: 'primary',   class: 'border border-primary-500 text-primary-700 dark:text-primary-300' },
+    { variant: 'outline', color: 'success',   class: 'border border-success-500 text-success-700 dark:text-success-300' },
+    { variant: 'outline', color: 'warning',   class: 'border border-warning-500 text-warning-700 dark:text-warning-300' },
+    { variant: 'outline', color: 'danger',    class: 'border border-danger-500 text-danger-700 dark:text-danger-300' },
+    { variant: 'outline', color: 'info',      class: 'border border-info-500 text-info-700 dark:text-info-300' },
+    { variant: 'outline', color: 'secondary', class: 'border border-secondary-500 text-secondary-700 dark:text-secondary-300' },
+  ],
+  defaultVariants: {
+    color: 'neutral',
+    variant: 'soft',
+    size: 'sm',
+  },
+});
+
+type ChipVariants = VariantProps<typeof chipVariants>;
+
+export interface RenderChipProps extends ChipVariants {
+  children: ReactNode;
+  className?: string;
+}
+
+export function RenderChip(props: RenderChipProps) {
+  const { children, color, variant, size, className } = props;
+  return (
+    <span className={cn(chipVariants({ color, variant, size }), className)}>
+      {children}
+    </span>
+  );
+}

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

@@ -0,0 +1,37 @@
+import type { ReactNode } from 'react';
+import { cn } from '../../../utils/cn.js';
+
+export interface RenderTextProps {
+  value: ReactNode;
+  /** Truncate to one line with ellipsis on overflow. @default false */
+  truncate?: boolean;
+  /** Secondary text color (less prominent). @default false */
+  muted?: boolean;
+  /** Extra class merged via `tailwind-merge`. */
+  className?: string;
+}
+
+/**
+ * Plain text cell renderer. Wraps the value in a `<span>` and
+ * optionally truncates on overflow. Use this for the most common
+ * case: render a single string value.
+ *
+ * The Table component does NOT use this by default for plain
+ * string columns — it just renders `{value}` directly. Use
+ * `RenderText` when you need the truncate / muted styling.
+ */
+export function RenderText(props: RenderTextProps) {
+  const { value, truncate, muted, className } = props;
+  return (
+    <span
+      className={cn(
+        truncate && 'block max-w-full truncate',
+        // Neutral palette auto-inverts via dashforgePreset() CSS-var swap.
+        muted && 'text-neutral-500',
+        className,
+      )}
+    >
+      {value}
+    </span>
+  );
+}