@astryxdesign/core 0.3.0 → 0.4.0

package/src/Table/plugins/sortable/useTableSortable.tsx

@@ -16,6 +16,7 @@
 import {useRef, useMemo, type ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {colorVars, spacingVars, radiusVars} from '../../../theme/tokens.stylex';
+import {focusOutlineProps} from '../../../utils/focusOutline.stylex';
 import {Icon} from '../../../Icon';
 import {resolveContextActions} from '../../tableContextMenu';
 import {useTranslator, type TranslatorFn} from '../../../i18n';
@@ -130,11 +131,6 @@ const sortStyles = stylex.create({
     width: '100%',
     height: '100%',
     textAlign: 'inherit',
-    outline: {
-      default: 'none',
-      ':focus-visible': `2px solid ${colorVars['--color-accent']}`,
-    },
-    outlineOffset: '2px',
     borderRadius: radiusVars['--radius-inner'],
   },
   iconWrapperUnsorted: {
@@ -307,7 +303,7 @@ function SortHeaderButton<T extends Record<string, unknown>>({
   return (
     <button
       type="button"
-      {...stylex.props(sortStyles.button)}
+      {...focusOutlineProps.focusVisible(sortStyles.button)}
       aria-label={ariaLabel}
       onClick={handleClick}>
       <span>{children}</span>

package/src/Table/plugins/tree/useTableTreeData.tsx

@@ -42,7 +42,7 @@ import {
 import * as stylex from '@stylexjs/stylex';
 import {colorVars, radiusVars, spacingVars} from '../../../theme/tokens.stylex';
 import {Icon} from '../../../Icon';
-import {mergeRefs, rtlStyles} from '../../../utils';
+import {mergeRefs} from '../../../utils';
 import type {
   TablePlugin,
   TableColumn,
@@ -259,14 +259,26 @@ const treeStyles = stylex.create({
       color: colorVars['--color-icon-primary'],
     },
   },
-  chevron: {
-    display: 'inline-flex',
+  chevronIcon: {
     transitionProperty: 'transform',
     transitionDuration: '150ms',
-    transform: 'rotate(0deg)',
   },
-  chevronExpanded: {
-    transform: 'rotate(90deg)',
+  // The RTL mirror is folded into each state's transform rather than living on
+  // a parent span. Both are `transform`, so on one element the later value
+  // would win — spelling out `scaleX(-1) rotate(...)` per state composes them
+  // exactly as the nested elements did, while leaving a single element to
+  // carry the glyph's theme target.
+  chevronIconCollapsed: {
+    transform: {
+      default: 'rotate(0deg)',
+      ':is([dir="rtl"] *)': 'scaleX(-1) rotate(0deg)',
+    },
+  },
+  chevronIconExpanded: {
+    transform: {
+      default: 'rotate(90deg)',
+      ':is([dir="rtl"] *)': 'scaleX(-1) rotate(90deg)',
+    },
   },
   /** Keeps leaf content aligned with expandable siblings. */
   leafSpacer: {
@@ -314,15 +326,19 @@ function TreeExpander({
           : t('@astryx.tableTree.expandRow')
       }
       aria-expanded={isExpanded}>
-      <span {...stylex.props(rtlStyles.mirror)}>
-        <span
-          {...stylex.props(
-            treeStyles.chevron,
-            isExpanded && treeStyles.chevronExpanded,
-          )}>
-          <Icon icon="chevronRight" size="xsm" />
-        </span>
-      </span>
+      <Icon
+        icon="chevronRight"
+        size="xsm"
+        // The rotation rides on the glyph rather than a wrapper span so the
+        // theme target below reaches both the mark and its open/closed
+        // transform.
+        xstyle={[
+          treeStyles.chevronIcon,
+          isExpanded
+            ? treeStyles.chevronIconExpanded
+            : treeStyles.chevronIconCollapsed,
+        ]}
+      />
     </button>
   );
 }
@@ -363,15 +379,18 @@ function TreeExpandAllToggle({
           : t('@astryx.tableTree.expandAllRows')
       }
       aria-expanded={allExpanded}>
-      <span {...stylex.props(rtlStyles.mirror)}>
-        <span
-          {...stylex.props(
-            treeStyles.chevron,
-            allExpanded && treeStyles.chevronExpanded,
-          )}>
-          <Icon icon="chevronRight" size="xsm" />
-        </span>
-      </span>
+      <Icon
+        icon="chevronRight"
+        size="xsm"
+        // Same one-element treatment as the row expander: the glyph carries
+        // both the rotation and the theme target.
+        xstyle={[
+          treeStyles.chevronIcon,
+          allExpanded
+            ? treeStyles.chevronIconExpanded
+            : treeStyles.chevronIconCollapsed,
+        ]}
+      />
     </button>
   );
 }

package/src/Table/tableContextMenu.test.tsx

@@ -116,6 +116,33 @@ describe('Table header context menu', () => {
       screen.queryByRole('menuitem', {hidden: true}),
     ).not.toBeInTheDocument();
   });
+
+  it('forwards a destructive action variant to the menu item', () => {
+    const plugin: TablePlugin<Row> = {
+      transformHeaderCell: props => ({
+        ...props,
+        contextMenuActions: [
+          {
+            id: 'delete',
+            label: 'Delete column',
+            variant: 'destructive',
+            onSelect: () => {},
+          },
+          {id: 'pin', label: 'Pin column', onSelect: () => {}},
+        ],
+      }),
+    };
+    render(
+      <Table data={data} columns={columns} idKey="id" plugins={{plugin}} />,
+    );
+    fireEvent.contextMenu(screen.getByText('Name'));
+    expect(
+      screen.getAllByRole('menuitem', {name: 'Delete column', hidden: true})[0],
+    ).toHaveAttribute('data-variant', 'destructive');
+    expect(
+      screen.getAllByRole('menuitem', {name: 'Pin column', hidden: true})[0],
+    ).not.toHaveAttribute('data-variant');
+  });
 });
 
 // =============================================================================

package/src/Table/tableContextMenu.tsx

@@ -79,6 +79,7 @@ function toContextMenuOptions(
         ),
         isDisabled: action.disabled,
         onClick: action.onSelect,
+        variant: action.variant,
       });
     }
   });

package/src/Table/types.ts

@@ -290,6 +290,12 @@ export interface BodyRowRenderProps {
   children: ReactNode;
   /** Ref for the `<tr>` element. Plugins can set this to access the row DOM node. */
   ref?: Ref<HTMLTableRowElement>;
+  /**
+   * Extra content rendered as a sibling immediately after this row's `<tr>`.
+   * Plugins use it to append a full-width detail-panel `<tr>` (e.g. row
+   * expansion). Multiple plugins compose by wrapping the previous `afterRow`.
+   */
+  afterRow?: ReactNode;
 }
 
 /** Props passed through the plugin pipeline for each body `<td>` */
@@ -379,6 +385,11 @@ export interface TableContextAction {
   group?: string;
   /** When true, the item renders as checked (e.g. the active sort direction). */
   checked?: boolean;
+  /**
+   * Visual variant. `'destructive'` renders the action in the error color for
+   * dangerous operations (e.g. Delete row). @default 'default'
+   */
+  variant?: 'default' | 'destructive';
 }
 
 /**

package/src/Table/useTableGroupedRows.doc.mjs

@@ -7,7 +7,7 @@ export const docs = {
   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).',
+    '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 useTableTreeState: 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',

package/src/Table/useTableRowExpansion.doc.mjs

@@ -7,18 +7,19 @@ export const docs = {
   subComponentOf: 'Table',
   displayName: 'useTableRowExpansion',
   description:
-    'Deprecated: use useTableTreeData + useTableTreeState instead. Hook that returns a TablePlugin implementing expandable rows with inherited columns. Child rows use the same columns as their parents, indented by depth. Clicking the chevron (or right-click context menu) toggles expansion. Pair with useTableRowExpansionState, which flattens the tree and derives this config (expand/collapse handlers + expand-all state) from a single expandedKeys set. Converging with useTableTreeData: new tree tables should prefer useTableTreeData + useTableTreeState, which cover the same affordances with a cycle guard and fine-grained re-render. See the migration example below.',
+    'Hook that returns a TablePlugin which expands a full-width detail panel below a row, rendered by the consumer via renderExpanded(item). Adds a leading chevron column and a right-click "Expand/Collapse row" action; the consumer owns the expandedKeys set. Use it for master-detail rows (order details, forms, charts, nested tables). For hierarchical data where child rows reuse the parent columns, use useTableTreeData + useTableTreeState instead.',
   props: [
     {
       name: 'expandedKeys',
       type: 'Set<string>',
-      description: 'Set of currently-expanded row keys.',
+      description: 'Set of currently-expanded row keys. Consumer-owned.',
       required: true,
     },
     {
       name: 'onToggle',
       type: '(key: string) => void',
-      description: 'Called when a row expansion is toggled.',
+      description:
+        'Called with a row key when its expansion is toggled (chevron click or context-menu action).',
       required: true,
     },
     {
@@ -28,48 +29,44 @@ export const docs = {
       required: true,
     },
     {
-      name: 'getChildren',
-      type: '(item: T) => T[]',
-      description: 'Return the children of a row (determines expandability).',
+      name: 'renderExpanded',
+      type: '(item: T) => ReactNode',
+      description:
+        'Render the detail content shown in a full-width panel below the row when it is expanded. Receives the row item.',
       required: true,
     },
-    {
-      name: 'getDepth',
-      type: '(item: T) => number',
-      description: 'Return the depth of a row in the hierarchy (0 = top-level). Used for indentation.',
-    },
     {
       name: 'getIsItemExpandable',
       type: '(item: T) => boolean',
-      description: 'Control which rows are expandable. Defaults to checking getChildren length.',
-    },
-    {
-      name: 'hasRowClickExpansion',
-      type: 'boolean',
-      description: 'When true, clicking anywhere on the row toggles expansion.',
-      default: 'false',
-    },
-    {
-      name: 'isAllExpanded',
-      type: "boolean | 'indeterminate'",
-      description: 'State of the expand-all toggle in the header. Enables the header toggle button.',
-    },
-    {
-      name: 'onToggleExpandAll',
-      type: '(expand: boolean) => void',
-      description: 'Callback when the expand-all header toggle is clicked.',
+      description:
+        'Control which rows are expandable. Non-expandable rows show no chevron, no context-menu action, and never render a panel. Defaults to all rows expandable.',
     },
   ],
   examples: [
     {
-      label: 'Migrating to useTableTreeData + useTableTreeState',
-      code: `// useTableRowExpansion and useTableTreeData are converging onto one tree
-// plugin. useTableTreeData is the destination: it adds a cycle guard,
-// per-row fine-grained re-render, and imperative row ARIA, and now covers
-// the same affordances (expand-all header control, whole-row click).
+      label: 'Master-detail order rows',
+      code: `const [expandedKeys, setExpandedKeys] = useState(new Set());
+const expansion = useTableRowExpansion({
+  expandedKeys,
+  onToggle: key =>
+    setExpandedKeys(prev => {
+      const next = new Set(prev);
+      next.has(key) ? next.delete(key) : next.add(key);
+      return next;
+    }),
+  getRowKey: item => item.id,
+  renderExpanded: item => <OrderDetails order={item} />,
+});
+
+<Table data={orders} columns={columns} idKey="id" plugins={{expansion}} />;`,
+    },
+    {
+      label: 'Migrating from tree rows to the tree plugin',
+      code: `// useTableRowExpansion is now for DETAIL PANELS, not tree rows. If you used
+// it to render nested child rows that reuse the parent columns, move to
+// useTableTreeData + useTableTreeState.
 
-// BEFORE: useTableRowExpansion + useTableRowExpansionState
-const [expandedKeys, setExpandedKeys] = useState(new Set(['root']));
+// BEFORE (tree rows via useTableRowExpansion + useTableRowExpansionState):
 const {data, expansionConfig} = useTableRowExpansionState({
   baseData: tree,
   getChildren: item => item.children ?? [],
@@ -80,12 +77,12 @@ const {data, expansionConfig} = useTableRowExpansionState({
 const expansion = useTableRowExpansion(expansionConfig);
 <Table data={data} columns={columns} idKey="id" plugins={{expansion}} />;
 
-// AFTER: useTableTreeState + useTableTreeData
+// AFTER (tree rows via the tree plugin):
 const {visibleData, treeConfig} = useTableTreeState({
-  data: tree,                   // nested data, not a flat array
+  data: tree,                   // nested data
   idKey: 'id',                  // or a function: idKey={item => item.id}
-  childrenKey: 'children',      // replaces getChildren (default 'children')
-  defaultExpandedIds: ['root'], // uncontrolled; or expandedIds + onExpandedIdsChange
+  childrenKey: 'children',      // replaces getChildren
+  defaultExpandedIds: ['root'], // or controlled: expandedIds + onExpandedIdsChange
 });
 const tree = useTableTreeData({
   ...treeConfig,
@@ -94,40 +91,20 @@ const tree = useTableTreeData({
 });
 <Table data={visibleData} columns={columns} idKey="id" plugins={{tree}} />;`,
     },
-    {
-      label: 'Config mapping',
-      code: `// useTableRowExpansion(State)         ->  useTableTreeState / useTableTreeData
-
-// baseData: T[] (nested)              ->  data: T[]                (useTableTreeState)
-// getChildren: item => item.children  ->  childrenKey: 'children'  (property name)
-// getRowKey: item => item.id          ->  idKey: 'id' | (item => item.id)
-// getIsItemExpandable                 ->  isItemExpandable         (same shape)
-// expandedKeys + setExpandedKeys      ->  defaultExpandedIds       (uncontrolled), or
-//                                         expandedIds + onExpandedIdsChange (controlled)
-// getDepth                            ->  removed; depth derives from nesting
-// isAllExpanded + onToggleExpandAll   ->  hasExpandAllControl      (state is computed)
-// hasRowClickExpansion                ->  hasRowClickExpansion     (unchanged)
-
-// Rendering: useTableRowExpansion prepends a dedicated expander column;
-// useTableTreeData decorates the tree column in place (configurable via
-// treeColumnKey). Keyboard and AT users toggle via the chevron in both.`,
-    },
   ],
 };
 
 /** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
-    'Deprecated: use useTableTreeData + useTableTreeState instead. Returns a TablePlugin for expandable rows w/ inherited columns. Child rows reuse parent columns, indented by depth. Chevron click (or right-click menu) toggles expansion. Pair w/ useTableRowExpansionState, which flattens the tree + derives this config from one expandedKeys set.',
+    'Returns a TablePlugin that expands a full-width detail panel below a row via renderExpanded(item). Adds a chevron column + right-click expand/collapse action; consumer owns expandedKeys. For nested child rows that reuse parent columns, use useTableTreeData + useTableTreeState instead.',
   propDescriptions: {
-    expandedKeys: 'Set of currently-expanded row keys.',
-    onToggle: 'Called when a row expansion is toggled.',
+    expandedKeys: 'Set of currently-expanded row keys. Consumer-owned.',
+    onToggle: 'Called with a row key when its expansion is toggled.',
     getRowKey: 'Derive a stable unique key from a row item.',
-    getChildren: 'Return children of a row; determines expandability.',
-    getDepth: 'Return depth of a row (0 = top-level). Used for indentation.',
-    getIsItemExpandable: 'Control which rows are expandable. Defaults to checking getChildren length.',
-    hasRowClickExpansion: 'If true, clicking anywhere on the row toggles expansion. Default false.',
-    isAllExpanded: 'State of the expand-all header toggle. Enables the header toggle button.',
-    onToggleExpandAll: 'Callback when the expand-all header toggle is clicked.',
+    renderExpanded:
+      'Render the full-width detail panel below an expanded row. Receives the row item.',
+    getIsItemExpandable:
+      'Control which rows are expandable. Defaults to all rows expandable.',
   },
 };

package/src/TextArea/TextArea.doc.mjs

@@ -70,6 +70,13 @@ export const docs = {
       description: 'Disables the textarea, preventing interaction.',
       default: 'false',
     },
+    {
+      name: 'isReadOnly',
+      type: 'boolean',
+      description:
+        'Makes the textarea read-only: the value is shown at full opacity and still submits with the form, but cannot be edited. Unlike isDisabled, a read-only textarea is not dimmed and stays in the tab order. isDisabled takes precedence when both are set.',
+      default: 'false',
+    },
     {
       name: 'disabledMessage',
       type: 'string',
@@ -179,7 +186,19 @@ export const docs = {
   ],
   theming: {
     targets: [
-      {className: 'astryx-textarea', visualProps: ['size', 'status']},
+      {className: 'astryx-textarea', visualProps: ['size', 'status'], states: ['disabled', 'readonly']},
+    ],
+    vars: [
+      {
+        name: '--_textarea-inline-padding',
+        description:
+          "Inline padding of the textarea's text. The wrapper stays flush (padding: 0) so the native resize grip sits in the true corner; this var carries the inset on the inner <textarea>, and the start icon, status/spinner, and character counter align to it.",
+        default: 'var(--spacing-2)',
+        private: true,
+      },
+    ],
+    derived: [
+      {property: 'paddingInline', vars: ['--_textarea-inline-padding'], replaces: true},
     ],
   },
   usage: {
@@ -259,6 +278,13 @@ export const docsZh = {
       description: '禁用文本域，阻止交互。',
       default: 'false',
     },
+    {
+      name: 'isReadOnly',
+      type: 'boolean',
+      description:
+        '将文本域设为只读：值以完整不透明度显示并仍随表单提交，但无法编辑。与 isDisabled 不同，只读文本域不会变暗，并保留在 Tab 顺序中。同时设置时 isDisabled 优先。',
+      default: 'false',
+    },
     {
       name: 'disabledMessage',
       type: 'string',
@@ -355,7 +381,19 @@ export const docsZh = {
   ],
   theming: {
     targets: [
-      {className: 'astryx-textarea', visualProps: ['size', 'status']},
+      {className: 'astryx-textarea', visualProps: ['size', 'status'], states: ['disabled', 'readonly']},
+    ],
+    vars: [
+      {
+        name: '--_textarea-inline-padding',
+        description:
+          '文本域文本的行内内边距。外层容器保持无内边距（padding: 0），使原生缩放手柄位于真正的角落；该变量在内部 <textarea> 上承载内边距，起始图标、状态/加载指示器和字符计数器都与之对齐。',
+        default: 'var(--spacing-2)',
+        private: true,
+      },
+    ],
+    derived: [
+      {property: 'paddingInline', vars: ['--_textarea-inline-padding'], replaces: true},
     ],
   },
   usage: {
@@ -402,6 +440,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.',
+    isReadOnly:
+      'Read-only: value visible + still submits, but not editable. Unlike isDisabled: not dimmed, stays in tab order.',
     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.',