@astryxdesign/core 0.0.0-bootstrap.0 → 0.1.0-canary.08d4cf4

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/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'",
+      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'",
+      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/useTablePagination.doc.mjs

@@ -0,0 +1,130 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+  name: 'useTablePagination',
+  subComponentOf: 'Table',
+  displayName: 'useTablePagination',
+  description: 'Headless pagination plugin for Table. Supports client-side slicing, server-side pagination, and cursor-based pagination. Renders Pagination controls automatically above, below, or both.',
+  props: [
+    {
+      name: 'page',
+      type: 'number',
+      description: 'Current page number (1-based).',
+      required: true,
+    },
+    {
+      name: 'onPageChange',
+      type: '(page: number) => void',
+      description: 'Called when the page changes.',
+      required: true,
+    },
+    {
+      name: 'totalItems',
+      type: 'number',
+      description: 'Total number of items across all pages. Used to calculate total page count.',
+    },
+    {
+      name: 'totalPages',
+      type: 'number',
+      description: 'Total number of pages. Use when you know the page count but not item count.',
+    },
+    {
+      name: 'hasMore',
+      type: 'boolean',
+      description: 'Whether more pages exist. Use for cursor-based pagination where the total is unknown.',
+    },
+    {
+      name: 'pageSize',
+      type: 'number',
+      description: 'Number of items per page.',
+      default: '10',
+    },
+    {
+      name: 'onPageSizeChange',
+      type: '(pageSize: number) => void',
+      description: 'Called when the user changes the page size. Shows a page size dropdown when provided with pageSizeOptions.',
+    },
+    {
+      name: 'pageSizeOptions',
+      type: 'number[]',
+      description: 'Available page size options. Shows a page size selector when provided.',
+    },
+    {
+      name: 'variant',
+      type: "'pages' | 'count' | 'compact' | 'dots' | 'none'",
+      description: 'Visual variant for the pagination controls.',
+      default: "'pages'",
+    },
+    {
+      name: 'position',
+      type: "'below' | 'above' | 'both' | 'none'",
+      description: 'Where to render pagination controls relative to the table.',
+      default: "'below'",
+    },
+    {
+      name: 'align',
+      type: "'start' | 'center' | 'end'",
+      description: 'Horizontal alignment of the pagination controls.',
+      default: "'center'",
+    },
+  ],
+};
+
+export const docsZh = {
+  name: 'useTablePagination',
+  displayName: 'useTablePagination',
+  description: '无头分页插件。支持客户端切片、服务器端分页和游标分页。自动渲染 Pagination 控件。',
+  props: [
+    {
+      name: 'page',
+      type: 'number',
+      description: '当前页码（从 1 开始）。',
+      required: true,
+    },
+    {
+      name: 'onPageChange',
+      type: '(page: number) => void',
+      description: '页面更改时调用。',
+      required: true,
+    },
+    {
+      name: 'totalItems',
+      type: 'number',
+      description: '所有页面的总项目数。用于计算总页数。',
+    },
+    {
+      name: 'pageSize',
+      type: 'number',
+      description: '每页项目数。',
+      default: '10',
+    },
+    {
+      name: 'variant',
+      type: "'pages' | 'count' | 'compact' | 'dots' | 'none'",
+      description: '分页控件的视觉变体。',
+      default: "'pages'",
+    },
+    {
+      name: 'position',
+      type: "'below' | 'above' | 'both' | 'none'",
+      description: '分页控件相对于表格的渲染位置。',
+      default: "'below'",
+    },
+  ],
+};
+
+export const docsDense = {
+  name: 'useTablePagination',
+  displayName: 'useTablePagination',
+  description: 'Headless pagination plugin. Client-side slicing, server-side, or cursor-based. Auto-renders Pagination above/below/both.',
+  propDescriptions: {
+    page: 'Current page (1-based).',
+    onPageChange: 'Called on page change.',
+    totalItems: 'Total items across all pages.',
+    pageSize: 'Items per page. Default 10.',
+    variant: "Pagination variant: 'pages'|'count'|'compact'|'dots'|'none'.",
+    position: "Render position: 'below'|'above'|'both'|'none'.",
+  },
+};

package/src/Table/useTableSelection.doc.mjs

@@ -0,0 +1,117 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+  name: 'useTableSelection',
+  subComponentOf: 'Table',
+  displayName: 'useTableSelection',
+  description: 'Hook that returns a TablePlugin implementing row selection with checkboxes, select-all, and aria-selected. Uses React Context for independent checkbox re-renders.',
+  props: [
+    {
+      name: 'getIsItemSelected',
+      type: '(item: T) => boolean',
+      description: 'Returns whether the given item is currently selected.',
+      required: true,
+    },
+    {
+      name: 'onSelectItem',
+      type: '(event: {item: T; isSelected: boolean}) => void',
+      description: 'Called when a row checkbox is toggled. isSelected is the new desired state.',
+      required: true,
+    },
+    {
+      name: 'onSelectAll',
+      type: '(event: {isAllSelected: boolean}) => void',
+      description: 'Called when the select-all header checkbox is toggled.',
+      required: true,
+    },
+    {
+      name: 'getIsAllSelected',
+      type: '() => boolean',
+      description: 'Returns whether all selectable items are currently selected.',
+      required: true,
+    },
+    {
+      name: 'getIsIndeterminate',
+      type: '() => boolean',
+      description: 'Returns whether selection is partial (some but not all). Renders the select-all checkbox in indeterminate state.',
+    },
+    {
+      name: 'getIsItemSelectable',
+      type: '(item: T) => boolean',
+      description: 'Returns whether a row should show a checkbox. Non-selectable rows render nothing in the selection cell.',
+      default: '() => true',
+    },
+    {
+      name: 'getIsItemEnabled',
+      type: '(item: T) => boolean',
+      description: 'Returns whether a row checkbox is interactive. Disabled rows show a disabled checkbox.',
+      default: '() => true',
+    },
+  ],
+};
+
+export const docsZh = {
+  name: 'useTableSelection',
+  displayName: 'useTableSelection',
+  description: '返回 TablePlugin 的 Hook，实现带复选框、全选和 aria-selected 的行选择功能。使用 React Context 实现独立的复选框重新渲染。',
+  props: [
+    {
+      name: 'getIsItemSelected',
+      type: '(item: T) => boolean',
+      description: '返回给定项是否当前被选中。',
+      required: true,
+    },
+    {
+      name: 'onSelectItem',
+      type: '(event: {item: T; isSelected: boolean}) => void',
+      description: '当行复选框被切换时调用。isSelected 为新的期望状态。',
+      required: true,
+    },
+    {
+      name: 'onSelectAll',
+      type: '(event: {isAllSelected: boolean}) => void',
+      description: '当全选表头复选框被切换时调用。',
+      required: true,
+    },
+    {
+      name: 'getIsAllSelected',
+      type: '() => boolean',
+      description: '返回所有可选择项是否当前都被选中。',
+      required: true,
+    },
+    {
+      name: 'getIsIndeterminate',
+      type: '() => boolean',
+      description: '返回选择是否为部分选中（部分但非全部）。将全选复选框渲染为不确定状态。',
+    },
+    {
+      name: 'getIsItemSelectable',
+      type: '(item: T) => boolean',
+      description: '返回行是否应显示复选框。不可选择的行在选择单元格中不渲染任何内容。',
+      default: '() => true',
+    },
+    {
+      name: 'getIsItemEnabled',
+      type: '(item: T) => boolean',
+      description: '返回行复选框是否可交互。禁用的行显示禁用状态的复选框。',
+      default: '() => true',
+    },
+  ],
+};
+
+export const docsDense = {
+  name: 'useTableSelection',
+  displayName: 'useTableSelection',
+  description: 'Hook returning TablePlugin for row selection w/ checkboxes, select-all, aria-selected. Uses React Context for independent checkbox re-renders.',
+  propDescriptions: {
+    getIsItemSelected: 'Returns whether item is selected.',
+    onSelectItem: 'Called on row checkbox toggle; isSelected = new desired state.',
+    onSelectAll: 'Called on select-all header checkbox toggle.',
+    getIsAllSelected: 'Returns whether all selectable items are selected.',
+    getIsIndeterminate: 'Returns partial selection state; renders indeterminate checkbox.',
+    getIsItemSelectable: 'Returns whether row shows checkbox; non-selectable rows render nothing.',
+    getIsItemEnabled: 'Returns whether row checkbox is interactive; disabled rows show disabled checkbox.',
+  },
+};

package/src/Table/useTableSelectionState.doc.mjs

@@ -0,0 +1,62 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+  name: 'useTableSelectionState',
+  subComponentOf: 'Table',
+  displayName: 'useTableSelectionState',
+  description: 'State management companion for useTableSelection. Handles disabled/selectable row filtering for select-all automatically: disabled rows are frozen (preserved across select-all/deselect-all), non-selectable rows are excluded.',
+  props: [
+    {
+      name: 'data',
+      type: 'T[]',
+      description: 'The full data array rendered in the table.',
+      required: true,
+    },
+    {
+      name: 'idKey',
+      type: '(keyof T & string) | ((item: T) => string)',
+      description: 'Key extractor: property name or function returning a unique string ID.',
+      required: true,
+    },
+    {
+      name: 'selectedKeys',
+      type: 'Set<string>',
+      description: 'Controlled set of selected item IDs.',
+      required: true,
+    },
+    {
+      name: 'setSelectedKeys',
+      type: 'Dispatch<SetStateAction<Set<string>>>',
+      description: 'Setter for the controlled selected keys.',
+      required: true,
+    },
+    {
+      name: 'getIsItemSelectable',
+      type: '(item: T) => boolean',
+      description: 'Should this row show a checkbox? Non-selectable rows are excluded from select-all.',
+      default: '() => true',
+    },
+    {
+      name: 'getIsItemEnabled',
+      type: '(item: T) => boolean',
+      description: 'Is this row checkbox interactive? Disabled rows are frozen: select-all preserves their state.',
+      default: '() => true',
+    },
+  ],
+};
+
+export const docsDense = {
+  name: 'useTableSelectionState',
+  displayName: 'useTableSelectionState',
+  description: 'State companion for useTableSelection. Handles disabled/selectable row filtering for select-all automatically: disabled rows frozen (state preserved across select-all/deselect-all), non-selectable rows excluded.',
+  propDescriptions: {
+    data: 'full data array rendered in table',
+    idKey: 'key extractor: property name or fn returning unique string ID',
+    selectedKeys: 'controlled set of selected item IDs',
+    setSelectedKeys: 'setter for controlled selected keys',
+    getIsItemSelectable: 'Returns whether row shows checkbox; non-selectable rows excluded from select-all. Defaults to () => true.',
+    getIsItemEnabled: 'Returns whether row checkbox is interactive; disabled rows frozen: select-all preserves their state. Defaults to () => true.',
+  },
+};

package/src/Table/useTableSortable.doc.mjs

@@ -0,0 +1,80 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+  name: 'useTableSortable',
+  subComponentOf: 'Table',
+  displayName: 'useTableSortable',
+  description: 'Headless multi-sort plugin for Table. The consumer owns sort state and provides a callback. Shift+click enables secondary sort columns. Sort indicators render in header cells automatically.',
+  props: [
+    {
+      name: 'sort',
+      type: 'TableSortState<TSortKey>',
+      description: 'Current sort state. Ordered array of {sortKey, direction} entries. First entry is the primary sort.',
+      required: true,
+    },
+    {
+      name: 'onSortChange',
+      type: '(sort: TableSortState<TSortKey>) => void',
+      description: 'Called when the user clicks a header cell to change sort.',
+      required: true,
+    },
+    {
+      name: 'allowUnsortedState',
+      type: 'boolean',
+      description: 'Allow cycling back to unsorted. When true: asc, desc, unsorted. When false: asc, desc, asc.',
+      default: 'false',
+    },
+    {
+      name: 'isMultiSortEnabled',
+      type: 'boolean',
+      description: 'Enable multi-sort via Shift+click. Regular click still replaces the entire sort state.',
+      default: 'false',
+    },
+  ],
+};
+
+export const docsZh = {
+  name: 'useTableSortable',
+  displayName: 'useTableSortable',
+  description: '无头多列排序插件。用户拥有排序状态并提供回调。Shift+点击启用二级排序列。排序指示器自动渲染在表头单元格中。',
+  props: [
+    {
+      name: 'sort',
+      type: 'TableSortState<TSortKey>',
+      description: '当前排序状态。{sortKey, direction} 条目的有序数组。第一个条目是主排序。',
+      required: true,
+    },
+    {
+      name: 'onSortChange',
+      type: '(sort: TableSortState<TSortKey>) => void',
+      description: '用户点击表头单元格更改排序时调用。',
+      required: true,
+    },
+    {
+      name: 'allowUnsortedState',
+      type: 'boolean',
+      description: '允许循环回到未排序状态。为 true 时：升序、降序、未排序。为 false 时：升序、降序、升序。',
+      default: 'false',
+    },
+    {
+      name: 'isMultiSortEnabled',
+      type: 'boolean',
+      description: '通过 Shift+点击启用多列排序。普通点击仍替换整个排序状态。',
+      default: 'false',
+    },
+  ],
+};
+
+export const docsDense = {
+  name: 'useTableSortable',
+  displayName: 'useTableSortable',
+  description: 'Headless multi-sort plugin. Consumer owns sort state + callback. Shift+click for secondary sort. Sort indicators auto-render in header cells.',
+  propDescriptions: {
+    sort: 'Current sort state; ordered array of {sortKey, direction} entries.',
+    onSortChange: 'Called on header click to change sort.',
+    allowUnsortedState: 'Allow cycling to unsorted. true: asc>desc>unsorted. false: asc>desc>asc.',
+    isMultiSortEnabled: 'Enable multi-sort via Shift+click. Regular click replaces sort state.',
+  },
+};

package/src/Table/utils.ts

@@ -0,0 +1,23 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file utils.ts
+ * @output Server-safe re-exports of pure Table utility functions
+ * @position Subpath entry point: `@astryxdesign/core/Table/utils`
+ */
+
+export {
+  proportional,
+  pixel,
+  capitalize,
+  generateColumns,
+  resolveColumnWidths,
+  DEFAULT_MIN_COLUMN_WIDTH,
+} from './columnUtils';
+
+export type {
+  ColumnWidth,
+  ProportionalWidth,
+  PixelWidth,
+  TableColumn,
+} from './types';