@astryxdesign/core 0.1.1 → 0.1.2-canary.04e71b2

package/src/Table/types.ts

@@ -261,6 +261,26 @@ export interface HeaderCellRenderProps {
   overlay?: ReactNode;
   /** Content rendered below the header label row (e.g. inline filter controls). */
   below?: ReactNode;
+  /**
+   * Right-click context-menu actions for this header cell. Plugins append
+   * their actions in `transformHeaderCell`; BaseTable concatenates the arrays
+   * across plugins (never overridden) and renders one menu per header cell.
+   */
+  contextMenuActions?: TableContextActions;
+  /**
+   * Index of this column within the final, ordered list of rendered columns
+   * (after column injection/reordering by other plugins). Populated by
+   * BaseTable. Optional for backward compatibility with hand-constructed
+   * renders in tests.
+   */
+  columnIndex?: number;
+  /**
+   * The full, final ordered list of columns being rendered (after column
+   * injection/reordering by other plugins). Populated by BaseTable so plugins
+   * can reason about column position — e.g. cumulative sticky offsets. Optional
+   * for backward compatibility.
+   */
+  columns?: ReadonlyArray<TableColumn<Record<string, unknown>>>;
 }
 
 /** Props passed through the plugin pipeline for each body `<tr>` */
@@ -276,8 +296,102 @@ export interface BodyRowRenderProps {
 export interface BodyCellRenderProps {
   htmlProps: TdHTMLAttributes<HTMLTableCellElement>;
   styles: StyleXStyles[];
+  /**
+   * Right-click context-menu actions for this body cell. Plugins append their
+   * actions in `transformBodyCell`; BaseTable concatenates the arrays across
+   * plugins and across the row's cells (never overridden) and renders one menu
+   * per row.
+   */
+  contextMenuActions?: TableContextActions;
+  /**
+   * Index of this cell's column within the final ordered column list.
+   * Mirrors the `columnIndex` passed to `transformHeaderCell`. Populated by
+   * BaseTable. Optional for backward compatibility with hand-constructed
+   * renders in tests.
+   */
+  columnIndex?: number;
+  /**
+   * The full, final ordered list of columns being rendered. Populated by
+   * BaseTable so plugins can reason about column position — e.g. cumulative
+   * sticky offsets. Optional for backward compatibility.
+   */
+  columns?: ReadonlyArray<TableColumn<Record<string, unknown>>>;
+}
+
+/**
+ * Props passed through the plugin pipeline for the scroll-wrapper region — the
+ * `<div>` wrapping the `<table>` element (the horizontal scroll container, see
+ * the `scrollWrapper` prop on `BaseTableProps`). Lets plugins attach a `ref` to
+ * the scrollable element (e.g. for scroll-aware sticky-column shadows or
+ * virtualization) and inject chrome before/after the table.
+ *
+ * Named after `scrollWrapper` (not "layout") to avoid ambiguity: it transforms
+ * the wrapper element, not the internal header/body/footer layout of `<table>`.
+ *
+ * Runs after `transformTable`/cell transforms but inside `transformTableContext`,
+ * so plugin chrome added here stays within any context providers but wraps the
+ * scroll area.
+ */
+export interface ScrollWrapperRenderProps {
+  /**
+   * HTML attributes applied to the scroll container `<div>`, including an
+   * optional `ref`. Plugins compose refs by reading the existing `ref` and
+   * merging their own (see `useTableStickyColumns`).
+   */
+  htmlProps: HTMLAttributes<HTMLDivElement> & {
+    ref?: Ref<HTMLDivElement>;
+  };
+  styles: StyleXStyles[];
+  /** Content rendered before the `<table>`, inside the scroll container. */
+  beforeTable?: ReactNode;
+  /** Content rendered after the `<table>`, inside the scroll container. */
+  afterTable?: ReactNode;
+}
+
+// =============================================================================
+// Context-menu actions
+// =============================================================================
+
+/**
+ * A single right-click context-menu action contributed by a plugin.
+ *
+ * Plugins contribute actions via the `contextMenuActions` field on
+ * `HeaderCellRenderProps` / `BodyCellRenderProps` (set in
+ * `transformHeaderCell` / `transformBodyCell`); the table aggregates actions
+ * from every enabled plugin into a single menu per header cell / row.
+ */
+export interface TableContextAction {
+  /** Stable identifier, unique within a single menu. */
+  id: string;
+  /** Visible label for the menu item. */
+  label: ReactNode;
+  /** Optional leading icon. */
+  icon?: ReactNode;
+  /** Invoked when the item is selected. */
+  onSelect: () => void;
+  /** When true, the item is rendered but not selectable. */
+  disabled?: boolean;
+  /**
+   * Group key used to cluster related actions and insert a divider between
+   * groups (e.g. 'sort', 'selection'). Actions without a group form a trailing
+   * group. Group order follows first-seen order across the aggregated list.
+   */
+  group?: string;
+  /** When true, the item renders as checked (e.g. the active sort direction). */
+  checked?: boolean;
 }
 
+/**
+ * Context-menu actions for a cell — either a static array, or a getter that
+ * returns the actions lazily. Prefer the getter for actions derived from state
+ * (e.g. the active sort direction): it's only invoked when the menu is opened,
+ * so the plugin doesn't build an action array (with closures) for every cell on
+ * every render.
+ */
+export type TableContextActions =
+  | TableContextAction[]
+  | (() => TableContextAction[]);
+
 // =============================================================================
 // Plugin Interface
 // =============================================================================
@@ -294,7 +408,12 @@ export interface BodyCellRenderProps {
  * 4. `transformHeaderCell` — transform each `<th>` props
  * 5. `transformBodyRow` — transform each body `<tr>` props
  * 6. `transformBodyCell` — transform each body `<td>` props
- * 7. `transformTableContext` — wrap the table output in context providers
+ * 7. `transformScrollWrapper` — transform the scroll-container wrapper around the table
+ * 8. `transformTableContext` — wrap the table output in context providers
+ *
+ * Plugins may also contribute right-click menu actions by appending to
+ * `contextMenuActions` in `transformHeaderCell` / `transformBodyCell`
+ * (aggregated into one menu per header cell / row).
  */
 export interface TablePlugin<
   T extends Record<string, unknown> = Record<string, unknown>,
@@ -309,10 +428,17 @@ export interface TablePlugin<
   transformTable?: (props: TableRenderProps) => TableRenderProps;
   /** Transform the header `<tr>` props */
   transformHeaderRow?: (props: HeaderRowRenderProps) => HeaderRowRenderProps;
-  /** Transform each `<th>` props */
+  /**
+   * Transform each `<th>` props.
+   *
+   * `columnIndex` and the full `columns` list are provided for plugins that
+   * need to reason about column position (e.g. cumulative sticky offsets).
+   */
   transformHeaderCell?: (
     props: HeaderCellRenderProps,
     column: TableColumn<T>,
+    columnIndex: number,
+    columns: ReadonlyArray<TableColumn<T>>,
   ) => HeaderCellRenderProps;
   /** Transform each body `<tr>` props */
   transformBodyRow?: (
@@ -320,12 +446,28 @@ export interface TablePlugin<
     item: T,
     index: number,
   ) => BodyRowRenderProps;
-  /** Transform each body `<td>` props */
+  /**
+   * Transform each body `<td>` props.
+   *
+   * `columnIndex` and the full `columns` list are provided for plugins that
+   * need to reason about column position (e.g. cumulative sticky offsets).
+   */
   transformBodyCell?: (
     props: BodyCellRenderProps,
     column: TableColumn<T>,
     item: T,
+    columnIndex: number,
+    columns: ReadonlyArray<TableColumn<T>>,
   ) => BodyCellRenderProps;
+  /**
+   * Transform the scroll-wrapper region — the `<div>` wrapping the `<table>`
+   * (see the `scrollWrapper` prop). Use to attach a `ref` to the scrollable
+   * element (scroll-aware shadows, virtualization) or to inject chrome
+   * before/after the table.
+   */
+  transformScrollWrapper?: (
+    props: ScrollWrapperRenderProps,
+  ) => ScrollWrapperRenderProps;
   /** Wrap the table output in context providers */
   transformTableContext?: (children: ReactNode) => ReactNode;
 }
@@ -340,18 +482,36 @@ export interface TableRowComponentProps extends HTMLAttributes<HTMLTableRowEleme
   ref?: Ref<HTMLTableRowElement>;
   children: ReactNode;
   xstyle?: StyleXStyles[];
+  /**
+   * Whether this row is the header row. Header rows skip the striped/hover
+   * row styling, which is only meant for body rows.
+   */
+  isHeaderRow?: boolean;
 }
 
 /** Props for cell components used in the components prop */
 export interface TableCellComponentProps extends TdHTMLAttributes<HTMLTableCellElement> {
   children?: ReactNode;
   xstyle?: StyleXStyles | StyleXStyles[];
+  /**
+   * Right-click actions to render as a context menu around the cell content.
+   * The cell owns the menu wrapper so it can control how it interacts with
+   * padding / content sizing. Empty/undefined renders no menu (native passes
+   * through).
+   */
+  contextMenuActions?: TableContextActions;
 }
 
 /** Props for header cell components used in the components prop */
 export interface TableHeaderCellComponentProps extends ThHTMLAttributes<HTMLTableCellElement> {
   children?: ReactNode;
   xstyle?: StyleXStyles | StyleXStyles[];
+  /**
+   * Right-click actions to render as a context menu around the header content.
+   * The cell owns the menu wrapper so it can control how it interacts with
+   * padding / content sizing. Empty/undefined renders no menu.
+   */
+  contextMenuActions?: TableContextActions;
 }
 
 // =============================================================================
@@ -390,8 +550,19 @@ export interface BaseTableProps<
    * plugin `transformTableContext` layer. Used by `Table` to add a
    * horizontal scroll container so plugin chrome (pagination, toolbars)
    * stays outside the scrollable area.
+   *
+   * Receives `htmlProps` (including an optional `ref`) and `styles` produced
+   * by the plugin `transformScrollWrapper` pipeline, plus `beforeTable`/`afterTable`
+   * chrome. The wrapper must spread `htmlProps` (and apply `styles`) onto its
+   * scroll-container element so plugins can attach refs / scroll listeners.
    */
-  scrollWrapper?: ComponentType<{children: ReactNode}>;
+  scrollWrapper?: ComponentType<{
+    children: ReactNode;
+    htmlProps?: HTMLAttributes<HTMLDivElement> & {ref?: Ref<HTMLDivElement>};
+    styles?: StyleXStyles[];
+    beforeTable?: ReactNode;
+    afterTable?: ReactNode;
+  }>;
   /**
    * How default-rendered body cell text behaves when it exceeds column width.
    *

package/src/Table/useBaseTablePlugins.ts

@@ -87,6 +87,7 @@ const VALID_TRANSFORM_KEYS = new Set([
   'transformHeaderCell',
   'transformBodyRow',
   'transformBodyCell',
+  'transformScrollWrapper',
   'transformTableContext',
 ]);
 

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/useTableStickyColumns.doc.mjs

@@ -0,0 +1,59 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+  name: 'useTableStickyColumns',
+  subComponentOf: 'Table',
+  displayName: 'useTableStickyColumns',
+  description:
+    'Hook that returns a TablePlugin which pins a contiguous run of columns to the start and/or end edge of the table. Pinned columns get cumulative offsets and a soft, scroll-aware shadow over the scrolling content. An empty config ({}) is a valid no-op that pins nothing.',
+  props: [
+    {
+      name: 'startKeys',
+      type: 'string[]',
+      description:
+        'Column keys pinned to the start (inline-start / left in LTR) edge: the contiguous run from the first column through the last listed key.',
+    },
+    {
+      name: 'endKeys',
+      type: 'string[]',
+      description:
+        'Column keys pinned to the end (inline-end / right in LTR) edge: the contiguous run from the first listed key through the last column.',
+    },
+  ],
+};
+
+export const docsZh = {
+  name: 'useTableStickyColumns',
+  displayName: 'useTableStickyColumns',
+  description:
+    '返回 TablePlugin 的 Hook，将一组连续的列固定到表格的起始和/或结束边缘。固定的列具有累积偏移量，并在滚动内容上方显示柔和的、随滚动感知的阴影。空配置 ({}) 是有效的空操作，不固定任何列。',
+  props: [
+    {
+      name: 'startKeys',
+      type: 'string[]',
+      description:
+        '固定到起始（inline-start / LTR 中为左侧）边缘的列键——从第一列到最后列出的键的连续范围。',
+    },
+    {
+      name: 'endKeys',
+      type: 'string[]',
+      description:
+        '固定到结束（inline-end / LTR 中为右侧）边缘的列键——从第一个列出的键到最后一列的连续范围。',
+    },
+  ],
+};
+
+export const docsDense = {
+  name: 'useTableStickyColumns',
+  displayName: 'useTableStickyColumns',
+  description:
+    'Hook returning TablePlugin that pins contiguous column runs to start/end edges w/ cumulative offsets + scroll-aware shadow. Empty config = no-op.',
+  propDescriptions: {
+    startKeys:
+      'Column keys pinned to the start edge (contiguous run from column 0 through the last listed key).',
+    endKeys:
+      'Column keys pinned to the end edge (contiguous run from the first listed key through the last column).',
+  },
+};

package/src/Text/Heading.doc.mjs

@@ -32,7 +32,7 @@ export const docs = {
     },
     {
       name: 'color',
-      type: "'primary' | 'secondary' | 'disabled' | 'placeholder' | 'active' | 'inherit'",
+      type: "'primary' | 'secondary' | 'disabled' | 'placeholder' | 'accent' | 'inherit'",
       description: 'Text color.',
       default: "'primary'",
     },
@@ -64,6 +64,12 @@ export const docs = {
       type: "'wrap' | 'nowrap' | 'balance' | 'pretty'",
       description: 'Text wrapping behavior.',
     },
+    {
+      name: 'justify',
+      type: "'start' | 'center' | 'end'",
+      description: 'Text alignment (justification). Uses logical values (start/end) for i18n/RTL compatibility.',
+      default: "'start'",
+    },
     {
       name: 'hasCapsize',
       type: 'boolean',
@@ -113,7 +119,7 @@ export const docsZh = {
     },
     {
       name: 'color',
-      type: "'primary' | 'secondary' | 'disabled' | 'placeholder' | 'active' | 'inherit'",
+      type: "'primary' | 'secondary' | 'disabled' | 'placeholder' | 'accent' | 'inherit'",
       description: '文本颜色。',
       default: "'primary'",
     },
@@ -145,6 +151,12 @@ export const docsZh = {
       type: "'wrap' | 'nowrap' | 'balance' | 'pretty'",
       description: '文本换行行为。',
     },
+    {
+      name: 'justify',
+      type: "'start' | 'center' | 'end'",
+      description: '文本对齐（两端对齐）。使用逻辑值（start/end）以兼容 i18n/RTL。',
+      default: "'start'",
+    },
     {
       name: 'hasCapsize',
       type: 'boolean',
@@ -180,6 +192,7 @@ export const docsDense = {
     hasTruncateTooltip: "Tooltip for truncated text; true=default position, false=disabled, or a placement ('above' | 'below' | 'start' | 'end').",
     wordBreak: "Word break behavior; defaults 'break-all' for single-line, 'break-word' otherwise.",
     textWrap: 'Text wrapping behavior.',
+    justify: "Text alignment (justification); logical values 'start' | 'center' | 'end' for RTL.",
     hasCapsize: 'Optical alignment via text-box-trim; forces block display.',
     hasStrikethrough: 'Strikethrough text decoration.',
     id: 'HTML id attribute.',

package/src/Text/Text.doc.mjs

@@ -40,7 +40,7 @@ export const docs = {
     },
     {
       name: 'color',
-      type: "'primary' | 'secondary' | 'disabled' | 'placeholder' | 'active' | 'inherit'",
+      type: "'primary' | 'secondary' | 'disabled' | 'placeholder' | 'accent' | 'inherit'",
       description: "Text color. Defaults to 'secondary' for the 'supporting' type, 'primary' for all others.",
     },
     {
@@ -82,6 +82,12 @@ export const docs = {
       type: "'wrap' | 'nowrap' | 'balance' | 'pretty'",
       description: 'Text wrapping behavior.',
     },
+    {
+      name: 'justify',
+      type: "'start' | 'center' | 'end'",
+      description: 'Text alignment (justification). Uses logical values (start/end) for i18n/RTL compatibility.',
+      default: "'start'",
+    },
     {
       name: 'hasCapsize',
       type: 'boolean',

package/src/Text/text.stylex.ts

@@ -35,8 +35,8 @@ export const colorStyles = stylex.create({
   placeholder: {
     color: colorVars['--color-text-secondary'],
   },
-  active: {
-    color: colorVars['--color-accent'],
+  accent: {
+    color: colorVars['--color-text-accent'],
   },
   inherit: {
     color: 'inherit',

package/src/TextArea/TextArea.doc.mjs

@@ -70,6 +70,12 @@ export const docs = {
       description: 'Disables the textarea, preventing interaction.',
       default: 'false',
     },
+    {
+      name: 'disabledMessage',
+      type: 'string',
+      description:
+        'Explains why the textarea is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the textarea focusable via aria-disabled (the field becomes read-only). Use this instead of wrapping a disabled TextArea in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+    },
     {
       name: 'isLoading',
       type: 'boolean',
@@ -174,6 +180,7 @@ export const docs = {
       { guidance: false, description: 'Avoid using TextArea for short, single-line values like names or emails; use TextInput instead.' },
       { guidance: false, description: 'Don\'t rely solely on placeholder text to communicate the purpose of the field; placeholders disappear on focus and are not accessible labels.' },
       { guidance: false, description: 'Don\'t show a status message without also setting the status type; the colored border and icon are what draw the user\'s attention to the message.' },
+      { guidance: false, description: 'Don\'t wrap a disabled TextArea in Tooltip to explain why it\'s disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },
     ],
   },
 };
@@ -239,6 +246,12 @@ export const docsZh = {
       description: '禁用文本域，阻止交互。',
       default: 'false',
     },
+    {
+      name: 'disabledMessage',
+      type: 'string',
+      description:
+        '说明文本域被禁用的原因。与 isDisabled 一起使用时，在悬停/键盘聚焦时显示工具提示，并通过 aria-disabled 保持文本域可聚焦（字段变为只读）。请使用此属性，而不是用 Tooltip 包裹已禁用的 TextArea。',
+    },
     {
       name: 'isLoading',
       type: 'boolean',
@@ -336,6 +349,7 @@ export const docsZh = {
       { guidance: false, description: 'Avoid using TextArea for short, single-line values like names or emails; use TextInput instead.' },
       { guidance: false, description: 'Don\'t rely solely on placeholder text to communicate the purpose of the field; placeholders disappear on focus and are not accessible labels.' },
       { guidance: false, description: 'Don\'t show a status message without also setting the status type; the colored border and icon are what draw the user\'s attention to the message.' },
+      { guidance: false, description: 'Don\'t wrap a disabled TextArea in Tooltip to explain why it\'s disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },
     ],
   },
 };
@@ -354,6 +368,7 @@ export const docsDense = {
       { guidance: false, description: 'Avoid TextArea for single-line values; use TextInput.' },
       { guidance: false, description: 'Don\'t use placeholder as only label; disappears on focus, not accessible.' },
       { guidance: false, description: 'Don\'t show status message without status type; border and icon draw attention.' },
+      { guidance: false, description: 'Don\'t wrap a disabled TextArea in Tooltip to explain the disabled state; use the disabledMessage prop instead.' },
     ],
   },
   propDescriptions: {
@@ -367,6 +382,8 @@ export const docsDense = {
     isOptional: 'Shows "Optional" indicator. Mutually exclusive w/ isRequired.',
     isRequired: 'Shows "Required" indicator+sets aria-required. Mutually exclusive w/ isOptional.',
     isDisabled: 'Disables textarea, prevents interaction.',
+    disabledMessage:
+      'Explains why textarea is disabled. With isDisabled, shows tooltip on hover/focus + keeps textarea focusable via aria-disabled (field becomes read-only). Use instead of wrapping a disabled TextArea in Tooltip.',
     isLoading: 'Loading state w/ spinner inside input.',
     placeholder: 'Placeholder when textarea empty.',
     rows: 'Visible text rows.',