@pharos-ds/core 0.1.9

package/src/Table/useBaseTablePlugins.ts

@@ -0,0 +1,250 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useBaseTablePlugins.ts
+ * @input React, types.ts
+ * @output Exports useBaseTablePlugins hook
+ * @position Utility hook; used by Table to convert named plugin records to stable arrays
+ *
+ * ## Plugin Ordering
+ *
+ * First-party plugins are sorted into a canonical order so that plugin
+ * interactions are deterministic regardless of how the consumer writes
+ * their `plugins={{ ... }}` record. Unknown/custom plugin names are
+ * appended after the known set in their original record order.
+ *
+ * Canonical order:
+ *   1. columnSettings — column filtering (future: transformColumns)
+ *   2. sort           — header cell sort controls
+ *   3. tree           — indent + expander on the tree column
+ *   4. selection      — checkbox column + row selection
+ *   5. pagination     — pagination controls around the table
+ *
+ * Rationale:
+ * - columnSettings filters columns before sort/selection see them
+ * - sort adds header cell UI before selection adds its header column
+ * - tree wraps the first *user* column before selection prepends its
+ *   checkbox column, so the expander never lands in the checkbox column
+ * - selection adds its column after sort so the checkbox header
+ *   doesn't get a sort button
+ * - pagination wraps the table in context last (outermost provider)
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/Table/index.ts (exports)
+ * - /packages/core/src/Table/Table.tsx (primary consumer)
+ */
+
+import {useRef} from 'react';
+import type {TablePlugin} from './types';
+import {devWarn} from '../utils/devWarning';
+
+// ======================================================================// Canonical Plugin Order
+// ======================================================================
+/**
+ * Canonical ordering for first-party plugin names.
+ * Plugins are sorted by their position in this array.
+ * Unknown names are appended after the known set.
+ */
+const PLUGIN_ORDER: ReadonlyArray<string> = [
+  'columnSettings',
+  'sort',
+  'tree',
+  'selection',
+  'pagination',
+];
+
+/** Lookup map for O(1) ordering checks. */
+const PLUGIN_ORDER_MAP = new Map(
+  PLUGIN_ORDER.map((name, index) => [name, index]),
+);
+
+/**
+ * Sort plugin entries into canonical order.
+ * Known plugins are sorted by PLUGIN_ORDER; unknown plugins preserve
+ * their original record insertion order and appear after all known plugins.
+ */
+function sortPluginEntries<T extends Record<string, unknown>>(
+  entries: [string, TablePlugin<T>][],
+): [string, TablePlugin<T>][] {
+  // Sentinel value for unknown plugins — higher than any known index
+  const unknownBase = PLUGIN_ORDER.length;
+
+  return entries.sort(([a], [b]) => {
+    const orderA = PLUGIN_ORDER_MAP.get(a) ?? unknownBase;
+    const orderB = PLUGIN_ORDER_MAP.get(b) ?? unknownBase;
+
+    // If both are unknown, preserve original order (sort is stable)
+    return orderA - orderB;
+  });
+}
+
+// ======================================================================// Hook
+// ======================================================================
+// Plugin Validation (dev mode only)
+// ======================================================================
+/** Known transform method names on the TablePlugin interface. */
+const VALID_TRANSFORM_KEYS = new Set([
+  'transformColumns',
+  'transformTable',
+  'transformHeaderRow',
+  'transformHeaderCell',
+  'transformBodyRow',
+  'transformBodyCell',
+  'transformScrollWrapper',
+  'transformTableContext',
+]);
+
+/**
+ * Validate a plugin object in development mode.
+ * Warns about common mistakes like misspelled transform names,
+ * non-function values where functions are expected, or
+ * completely empty plugins that add pipeline overhead for nothing.
+ */
+function validatePlugin<T extends Record<string, unknown>>(
+  name: string,
+  plugin: TablePlugin<T>,
+): void {
+  // Validation always runs — warnings are cheap and help catch plugin bugs
+
+  const keys = Object.keys(plugin);
+
+  // Warn about unknown keys (likely misspelled transform names)
+  for (const key of keys) {
+    if (!VALID_TRANSFORM_KEYS.has(key)) {
+      devWarn(
+        'Table',
+        `Plugin "${name}" has unknown key "${key}". ` +
+          `Valid keys: ${[...VALID_TRANSFORM_KEYS].join(', ')}. ` +
+          `This key will be ignored.`,
+      );
+    }
+  }
+
+  // Warn about non-function values on known transform keys
+  for (const key of keys) {
+    if (VALID_TRANSFORM_KEYS.has(key)) {
+      const value = (plugin as Record<string, unknown>)[key];
+      if (value != null && typeof value !== 'function') {
+        devWarn(
+          'Table',
+          `Plugin "${name}" has non-function value for "${key}" ` +
+            `(got ${typeof value}). Transform will be skipped.`,
+        );
+      }
+    }
+  }
+
+  // Warn about empty plugins that add pipeline overhead
+  const hasTransforms = keys.some(
+    key =>
+      VALID_TRANSFORM_KEYS.has(key) &&
+      typeof (plugin as Record<string, unknown>)[key] === 'function',
+  );
+  if (!hasTransforms) {
+    devWarn(
+      'Table',
+      `Plugin "${name}" has no transform methods. ` +
+        `It will be included in the pipeline but won't do anything.`,
+    );
+  }
+}
+
+/**
+ * Converts a named plugin record (`Record<string, TablePlugin>`) to a stable
+ * memoized array for `BaseTable`. Compares plugin values by identity so
+ * that inline `plugins={{ selection: stablePlugin }}` doesn't break row
+ * memoization — only produces a new array when a plugin value actually changes.
+ *
+ * Plugins are sorted into a canonical order (see PLUGIN_ORDER) so that
+ * interactions between first-party plugins are deterministic.
+ *
+ * @param basePlugins - Stable array of built-in plugins (e.g. Pharos style plugin)
+ * @param userPlugins - Named plugin record from the consumer
+ * @returns Stable array of plugins suitable for BaseTable
+ *
+ * @example
+ * ```
+ * const plugins = useBaseTablePlugins([tablePlugin], userPlugins);
+ * <BaseTable plugins={plugins} ... />
+ * ```
+ */
+export function useBaseTablePlugins<T extends Record<string, unknown>>(
+  basePlugins: TablePlugin<T>[],
+  userPlugins: Record<string, TablePlugin<T>> | undefined,
+): TablePlugin<T>[] {
+  const prevRef = useRef<{
+    basePlugins: TablePlugin<T>[];
+    userPlugins: Record<string, TablePlugin<T>> | undefined;
+    result: TablePlugin<T>[];
+  } | null>(null);
+
+  // Check if we can reuse the previous result
+  if (prevRef.current != null) {
+    const prev = prevRef.current;
+
+    // Fast path: same references
+    if (prev.basePlugins === basePlugins && prev.userPlugins === userPlugins) {
+      return prev.result;
+    }
+
+    // Deep identity comparison: check if all plugin values are the same
+    if (
+      prev.basePlugins === basePlugins &&
+      arePluginRecordsEqual(prev.userPlugins, userPlugins)
+    ) {
+      // Update stored reference but return same result array
+      prev.userPlugins = userPlugins;
+      return prev.result;
+    }
+  }
+
+  // Sort user plugins into canonical order
+  const sortedUserPlugins = userPlugins
+    ? sortPluginEntries(Object.entries(userPlugins)).map(([, plugin]) => plugin)
+    : [];
+
+  const result = [...basePlugins, ...sortedUserPlugins];
+
+  // Validate plugins in dev mode
+  if (userPlugins) {
+    for (const [name, plugin] of Object.entries(userPlugins)) {
+      validatePlugin(name, plugin);
+    }
+  }
+
+  prevRef.current = {basePlugins, userPlugins, result};
+  return result;
+}
+
+/**
+ * Compares two plugin records by checking that they have the same keys
+ * and each key maps to the same plugin instance (by reference).
+ */
+function arePluginRecordsEqual<T extends Record<string, unknown>>(
+  a: Record<string, TablePlugin<T>> | undefined,
+  b: Record<string, TablePlugin<T>> | undefined,
+): boolean {
+  if (a === b) {
+    return true;
+  }
+  if (a == null || b == null) {
+    return false;
+  }
+
+  const keysA = Object.keys(a);
+  const keysB = Object.keys(b);
+
+  if (keysA.length !== keysB.length) {
+    return false;
+  }
+
+  for (const key of keysA) {
+    if (a[key] !== b[key]) {
+      return false;
+    }
+  }
+
+  return true;
+}

package/src/Table/useTableCellStyles.ts

@@ -0,0 +1,74 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useTableCellStyles.ts
+ * @input React, StyleX, TableContext, theme tokens
+ * @output Exports shared cell styling utilities
+ * @position Utility layer; consumed by TableCell and TableHeaderCell
+ *
+ * Consolidates the shared pattern of building divider style arrays
+ * and merging consumer xstyle. Eliminates structural duplication
+ * between body cells and header cells.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/Table/TableCell.tsx
+ * - /packages/core/src/Table/TableHeaderCell.tsx
+ */
+
+import {use} from 'react';
+import type {StyleXStyles} from '../theme/types';
+import {TableContext, type TableContextValue} from './TableContext';
+
+// =============================================================================
+// Shared Style Builders
+// =============================================================================
+
+/**
+ * Build the divider styles array for a cell based on context.
+ * Shared between body cells and header cells — both apply row/column
+ * dividers the same way.
+ */
+export function buildDividerStyles(
+  ctx: TableContextValue,
+  dividerRowStyle: StyleXStyles,
+  dividerColumnStyle: StyleXStyles,
+): StyleXStyles[] {
+  const result: StyleXStyles[] = [];
+
+  if (ctx.dividers === 'rows' || ctx.dividers === 'grid') {
+    result.push(dividerRowStyle);
+  }
+
+  if (ctx.dividers === 'columns' || ctx.dividers === 'grid') {
+    result.push(dividerColumnStyle);
+  }
+
+  return result;
+}
+
+/**
+ * Merge consumer xstyle (single or array) into a styles array.
+ * Handles the polymorphic xstyle prop that both cell components accept.
+ */
+export function mergeXStyle(
+  styles: StyleXStyles[],
+  xstyle: StyleXStyles | StyleXStyles[] | undefined,
+): StyleXStyles[] {
+  if (!xstyle) {
+    return styles;
+  }
+  if (Array.isArray(xstyle)) {
+    return [...styles, ...xstyle];
+  }
+  return [...styles, xstyle];
+}
+
+/**
+ * Read the TableContext. Returns null when outside Table,
+ * signaling that the component should render unstyled.
+ */
+export function useTableContext(): TableContextValue | null {
+  return use(TableContext);
+}

package/src/Table/useTableColumnResize.doc.mjs

@@ -0,0 +1,96 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+  name: 'useTableColumnResize',
+  subComponentOf: 'Table',
+  displayName: 'useTableColumnResize',
+  description:
+    'Hook that returns a TablePlugin adding draggable resize handles to column header borders. Supports pointer + keyboard (WAI-ARIA window splitter) resizing, RTL, per-column min/max widths, and proportional-column preservation (resizes the neighbor so the table stays full-width). Commits widths on release.',
+  props: [
+    {
+      name: 'columnWidths',
+      type: 'Record<string, number>',
+      description:
+        'Controlled pixel-width overrides keyed by column key. When a key is present it overrides the column\'s declared width.',
+    },
+    {
+      name: 'onColumnResizeEnd',
+      type: '(updates: Record<string, number>) => void',
+      description:
+        'Called when a resize completes (pointerup / Enter). Receives a map of every column key whose width changed; merge it into your columnWidths state.',
+    },
+    {
+      name: 'minWidth',
+      type: 'number',
+      description:
+        'Global minimum column width in pixels during resize. Overrides per-column defaults when set.',
+    },
+    {
+      name: 'maxWidth',
+      type: 'number',
+      description: 'Global maximum column width in pixels during resize.',
+      default: 'Infinity',
+    },
+    {
+      name: 'columns',
+      type: 'TableColumn<T>[]',
+      description:
+        'Column definitions, needed to derive per-column min widths and detect proportional vs pixel columns for neighbor/last-column resize behavior.',
+    },
+  ],
+};
+
+export const docsZh = {
+  name: 'useTableColumnResize',
+  displayName: 'useTableColumnResize',
+  description:
+    '返回 TablePlugin 的 Hook，为列表头边框添加可拖动的调整手柄。支持指针 + 键盘（WAI-ARIA 窗口分隔符）调整、RTL、每列最小/最大宽度，以及比例列保留（调整相邻列以保持表格全宽）。在释放时提交宽度。',
+  props: [
+    {
+      name: 'columnWidths',
+      type: 'Record<string, number>',
+      description: '受控的像素宽度覆盖，按列键索引。存在某键时会覆盖该列声明的宽度。',
+    },
+    {
+      name: 'onColumnResizeEnd',
+      type: '(updates: Record<string, number>) => void',
+      description:
+        '调整完成时（pointerup / Enter）调用。接收所有宽度发生变化的列键的映射——将其合并到你的 columnWidths 状态中。',
+    },
+    {
+      name: 'minWidth',
+      type: 'number',
+      description: '调整期间的全局最小列宽（像素）。设置后覆盖每列默认值。',
+    },
+    {
+      name: 'maxWidth',
+      type: 'number',
+      description: '调整期间的全局最大列宽（像素）。',
+      default: 'Infinity',
+    },
+    {
+      name: 'columns',
+      type: 'TableColumn<T>[]',
+      description:
+        '列定义——用于推导每列最小宽度，并区分比例列与像素列以确定相邻列/末列的调整行为。',
+    },
+  ],
+};
+
+export const docsDense = {
+  name: 'useTableColumnResize',
+  displayName: 'useTableColumnResize',
+  description:
+    'Hook returning TablePlugin w/ draggable column resize handles. Pointer + keyboard (WAI-ARIA splitter), RTL, per-column min/max, proportional-preserving (resizes neighbor). Commits on release.',
+  propDescriptions: {
+    columnWidths: 'Controlled pixel-width overrides keyed by column key.',
+    onColumnResizeEnd:
+      'Called on resize end; receives map of all changed column widths to merge into state.',
+    minWidth: 'Global min column width (px) during resize.',
+    maxWidth: 'Global max column width (px) during resize. Default Infinity.',
+    columns:
+      'Column defs: derive per-column mins + proportional/pixel detection for neighbor/last-column behavior.',
+  },
+};

package/src/Table/useTableColumnSettings.doc.mjs

@@ -0,0 +1,73 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+  name: 'useTableColumnSettings',
+  subComponentOf: 'Table',
+  displayName: 'useTableColumnSettings',
+  description: 'Headless column visibility and ordering management for Table. Provides filtered columns, toggle helpers, and pre-built MultiSelector options for a column picker UI.',
+  props: [
+    {
+      name: 'columns',
+      type: 'ColumnSettingsOption[]',
+      description: 'All available columns with metadata for the settings UI. Each entry has key, label, optional isAlwaysVisible and group.',
+      required: true,
+    },
+    {
+      name: 'activeColumnKeys',
+      type: 'string[]',
+      description: 'Currently active column keys, in display order. Only columns with keys in this array are shown.',
+      required: true,
+    },
+    {
+      name: 'onChangeActiveColumnKeys',
+      type: '(keys: string[]) => void',
+      description: 'Called when active columns change (toggle, reorder).',
+      required: true,
+    },
+    {
+      name: 'defaultColumnKeys',
+      type: 'string[]',
+      description: 'Default column set for "Reset to default". When omitted, reset shows all columns.',
+    },
+  ],
+};
+
+export const docsZh = {
+  name: 'useTableColumnSettings',
+  displayName: 'useTableColumnSettings',
+  description: '无头列可见性和排序管理。提供筛选后的列、切换帮助方法和 MultiSelector 选项。',
+  props: [
+    {
+      name: 'columns',
+      type: 'ColumnSettingsOption[]',
+      description: '所有可用列及其设置 UI 的元数据。每个条目包含 key、label、可选的 isAlwaysVisible 和 group。',
+      required: true,
+    },
+    {
+      name: 'activeColumnKeys',
+      type: 'string[]',
+      description: '当前活动的列键，按显示顺序排列。',
+      required: true,
+    },
+    {
+      name: 'onChangeActiveColumnKeys',
+      type: '(keys: string[]) => void',
+      description: '活动列更改时调用。',
+      required: true,
+    },
+  ],
+};
+
+export const docsDense = {
+  name: 'useTableColumnSettings',
+  displayName: 'useTableColumnSettings',
+  description: 'Headless column visibility/ordering. Provides filtered columns, toggle helpers, MultiSelector options.',
+  propDescriptions: {
+    columns: 'All available columns w/ metadata (key, label, isAlwaysVisible, group).',
+    activeColumnKeys: 'Active column keys in display order.',
+    onChangeActiveColumnKeys: 'Called on column toggle/reorder.',
+    defaultColumnKeys: 'Default column set for reset. Omit = show all.',
+  },
+};

package/src/Table/useTableFilterState.doc.mjs

@@ -0,0 +1,42 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+  name: 'useTableFilterState',
+  subComponentOf: 'Table',
+  displayName: 'useTableFilterState',
+  isHiddenFromOverview: true,
+  description: 'Managed state hook for table filtering. Returns the current filter map and an onChange handler. Pass the result directly to useTableFiltering.',
+  props: [
+    {
+      name: 'initialState',
+      type: 'TableFilterState',
+      description: 'Optional initial filter state map.',
+    },
+  ],
+};
+
+export const docsZh = {
+  name: 'useTableFilterState',
+  isHiddenFromOverview: true,
+  displayName: 'useTableFilterState',
+  description: '表格筛选的受管状态 hook。返回当前筛选映射和 onChange 处理程序。将结果直接传递给 useTableFiltering。',
+  props: [
+    {
+      name: 'initialState',
+      type: 'TableFilterState',
+      description: '可选的初始筛选状态映射。',
+    },
+  ],
+};
+
+export const docsDense = {
+  name: 'useTableFilterState',
+  isHiddenFromOverview: true,
+  displayName: 'useTableFilterState',
+  description: 'Managed filter state hook. Returns filter map + onChange handler for useTableFiltering.',
+  propDescriptions: {
+    initialState: 'Optional initial filter state map.',
+  },
+};

package/src/Table/useTableFiltering.doc.mjs

@@ -0,0 +1,70 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+  name: 'useTableFiltering',
+  subComponentOf: 'Table',
+  displayName: 'useTableFiltering',
+  isHiddenFromOverview: true,
+  description: 'Table plugin that adds inline column filters with popover or inline controls. Pairs with useTableFilterState for managed state. Supports text, select, multi-select, date, and number filter types via PowerSearch field definitions.',
+  props: [
+    {
+      name: 'filters',
+      type: 'TableFilterState',
+      description: 'Current filter state: map from column key to filter value.',
+      required: true,
+    },
+    {
+      name: 'onFilterChange',
+      type: '(columnKey: string, value: TableFilterValue | null) => void',
+      description: 'Called when the user changes a filter value. null clears the filter.',
+      required: true,
+    },
+    {
+      name: 'variant',
+      type: "'popover' | 'inline' | 'inline-compact'",
+      description: 'Display variant for filter controls.',
+      default: "'popover'",
+    },
+  ],
+};
+
+export const docsZh = {
+  name: 'useTableFiltering',
+  isHiddenFromOverview: true,
+  displayName: 'useTableFiltering',
+  description: '表格筛选插件，添加内联列过滤器（弹出式或内联控件）。与 useTableFilterState 配合使用管理状态。',
+  props: [
+    {
+      name: 'filters',
+      type: 'TableFilterState',
+      description: '当前筛选状态——列键到筛选值的映射。',
+      required: true,
+    },
+    {
+      name: 'onFilterChange',
+      type: '(columnKey: string, value: TableFilterValue | null) => void',
+      description: '用户更改筛选值时调用。null 清除筛选。',
+      required: true,
+    },
+    {
+      name: 'variant',
+      type: "'popover' | 'inline' | 'inline-compact'",
+      description: '筛选控件的显示变体。',
+      default: "'popover'",
+    },
+  ],
+};
+
+export const docsDense = {
+  name: 'useTableFiltering',
+  isHiddenFromOverview: true,
+  displayName: 'useTableFiltering',
+  description: 'Table filtering plugin: inline column filters (popover/inline). Pairs w/ useTableFilterState.',
+  propDescriptions: {
+    filters: 'Current filter state map (columnKey → value).',
+    onFilterChange: 'Called on filter change. null clears.',
+    variant: 'Filter control display variant.',
+  },
+};

package/src/Table/useTableGroupedRows.doc.mjs

@@ -0,0 +1,71 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+  name: 'useTableGroupedRows',
+  subComponentOf: 'Table',
+  displayName: 'useTableGroupedRows',
+  description:
+    'Hook that groups a flat data array into collapsible section rows. Each distinct groupBy value becomes a full-width section-header row with a chevron toggle, the group label, and a member count; collapsing hides that group\'s data rows while keeping the header visible. Mirrors useTableRowExpansionState: the consumer owns the collapsedGroups set and the hook returns {data, plugin, idKey}: pass all three to Table (data, plugins, and idKey respectively).',
+  props: [
+    {
+      name: 'data',
+      type: 'T[]',
+      description: 'The flat data to group.',
+      required: true,
+    },
+    {
+      name: 'groupBy',
+      type: '(item: T) => string',
+      description:
+        'Derive the group key for a row. Rows with the same key share a section.',
+      required: true,
+    },
+    {
+      name: 'collapsedGroups',
+      type: 'Set<string>',
+      description: 'Set of currently-collapsed group keys.',
+      required: true,
+    },
+    {
+      name: 'onToggleGroup',
+      type: '(groupKey: string) => void',
+      description: 'Called with a group key when its header is toggled.',
+      required: true,
+    },
+    {
+      name: 'renderGroupHeader',
+      type: '(groupKey: string, count: number, collapsed: boolean) => ReactNode',
+      description:
+        "Custom renderer for a group header's content (right of the chevron). Defaults to `<groupKey> (<count>)`.",
+    },
+    {
+      name: 'getRowKey',
+      type: '(item: T) => string',
+      description:
+        'Stable key for a real row. Falls back to a positional key when omitted.',
+    },
+    {
+      name: 'groupOrder',
+      type: 'string[]',
+      description:
+        'Explicit group ordering; groups not listed keep first-seen order after these.',
+    },
+  ],
+};
+
+/** @type {import('../docs-types').TranslationDoc} */
+export const docsDense = {
+  description:
+    'Groups a flat data array into collapsible section rows. Each groupBy value becomes a full-width header (chevron + label + count); collapsing hides its rows. Returns {data, plugin, idKey}: pass to Table data / plugins / idKey. Consumer owns the collapsedGroups set.',
+  propDescriptions: {
+    data: 'The flat data to group.',
+    groupBy: 'Derive a row\'s group key. Same key = same section.',
+    collapsedGroups: 'Set of currently-collapsed group keys.',
+    onToggleGroup: 'Called with the group key when a header is toggled.',
+    renderGroupHeader: "Custom header content (right of chevron). Default '<key> (<count>)'.",
+    getRowKey: 'Stable key for a real row; positional fallback when omitted.',
+    groupOrder: 'Pin these group keys first; others keep first-seen order.',
+  },
+};