@astryxdesign/core 0.1.9 → 0.2.0-canary.068bda9

package/src/Table/Table.doc.mjs

@@ -93,6 +93,17 @@ export const docs = {
       type: 'Record<string, TablePlugin<T>>',
       description: 'Named plugins that extend table behavior via the transform pipeline. Converted to an ordered array internally.',
     },
+    {
+      name: 'rowIndexStart',
+      type: 'number',
+      description: 'ARIA row index (1-based) for the first rendered body row. The row ordinal is an accessibility concern independent of any visible index column, so setting this (or rowCount) makes the table emit aria-rowindex on body rows and aria-rowcount on the table. For a paginated/windowed view, pass the offset of the first visible row (e.g. (page - 1) * pageSize + 1) so aria-rowindex reflects position in the full dataset. Data-driven mode only.',
+      default: '1',
+    },
+    {
+      name: 'rowCount',
+      type: 'number',
+      description: 'Total number of body rows across all pages/windows, used for aria-rowcount so assistive tech can announce "row X of Y" against the full dataset. When omitted but rowIndexStart is set (windowed view with an unknown total), aria-rowcount is set to -1 per the ARIA unknown-count convention. Data-driven mode only.',
+    },
     {
       name: 'children',
       type: 'ReactNode',

package/src/Table/Table.test.tsx

@@ -1451,3 +1451,88 @@ describe('emptyState', () => {
     });
   });
 });
+
+describe('ARIA row indexing (#3939)', () => {
+  const bodyRows = (container: HTMLElement): HTMLTableRowElement[] =>
+    Array.from(container.querySelectorAll('tbody tr'));
+
+  it('emits no aria-rowindex/aria-rowcount by default', () => {
+    const {container} = render(<Table data={users} columns={columns} />);
+    expect(screen.getByRole('table')).not.toHaveAttribute('aria-rowcount');
+    for (const row of bodyRows(container)) {
+      expect(row).not.toHaveAttribute('aria-rowindex');
+    }
+  });
+
+  it('numbers rows from 1 when rowCount is provided', () => {
+    const {container} = render(
+      <Table data={users} columns={columns} rowCount={users.length} />,
+    );
+    expect(screen.getByRole('table')).toHaveAttribute(
+      'aria-rowcount',
+      String(users.length),
+    );
+    const indices = bodyRows(container).map(r =>
+      r.getAttribute('aria-rowindex'),
+    );
+    expect(indices).toEqual(['1', '2', '3']);
+  });
+
+  it('offsets aria-rowindex by rowIndexStart for a paginated view', () => {
+    // Page 3 of a 10-per-page dataset: first visible row is dataset row 21.
+    const {container} = render(
+      <Table
+        data={users}
+        columns={columns}
+        rowIndexStart={21}
+        rowCount={100}
+      />,
+    );
+    expect(screen.getByRole('table')).toHaveAttribute('aria-rowcount', '100');
+    const indices = bodyRows(container).map(r =>
+      r.getAttribute('aria-rowindex'),
+    );
+    expect(indices).toEqual(['21', '22', '23']);
+  });
+
+  it('sets aria-rowcount to -1 (unknown) when only rowIndexStart is given', () => {
+    // Windowed/cursor pagination: offset known, total unknown.
+    const {container} = render(
+      <Table data={users} columns={columns} rowIndexStart={5} />,
+    );
+    expect(screen.getByRole('table')).toHaveAttribute('aria-rowcount', '-1');
+    const indices = bodyRows(container).map(r =>
+      r.getAttribute('aria-rowindex'),
+    );
+    expect(indices).toEqual(['5', '6', '7']);
+  });
+
+  it('does not assign an ARIA row index to the header row', () => {
+    render(<Table data={users} columns={columns} rowCount={users.length} />);
+    const header = screen.getAllByRole('row')[0];
+    expect(header).not.toHaveAttribute('aria-rowindex');
+  });
+
+  it('lets a plugin override the seeded aria-rowindex', () => {
+    const plugin: TablePlugin<User> = {
+      transformBodyRow(props, _item, index) {
+        return {
+          ...props,
+          htmlProps: {...props.htmlProps, 'aria-rowindex': 100 + index},
+        };
+      },
+    };
+    const {container} = render(
+      <Table
+        data={users}
+        columns={columns}
+        rowCount={users.length}
+        plugins={{custom: plugin}}
+      />,
+    );
+    const indices = bodyRows(container).map(r =>
+      r.getAttribute('aria-rowindex'),
+    );
+    expect(indices).toEqual(['100', '101', '102']);
+  });
+});

package/src/Table/TableCell.tsx

@@ -161,12 +161,12 @@ const dividerRowStyles = stylex.create({
 
 const dividerColumnStyles = stylex.create({
   cell: {
-    borderRightWidth: {
+    borderInlineEndWidth: {
       default: borderVars['--border-width'],
       ':last-child': '0',
     },
-    borderRightStyle: 'solid',
-    borderRightColor: colorVars['--color-border'],
+    borderInlineEndStyle: 'solid',
+    borderInlineEndColor: colorVars['--color-border'],
   },
 });
 

package/src/Table/TableHeaderCell.tsx

@@ -91,12 +91,12 @@ const headerDividerStyles = stylex.create({
 
 const dividerColumnStyles = stylex.create({
   cell: {
-    borderRightWidth: {
+    borderInlineEndWidth: {
       default: borderVars['--border-width'],
       ':last-child': '0',
     },
-    borderRightStyle: 'solid',
-    borderRightColor: colorVars['--color-border'],
+    borderInlineEndStyle: 'solid',
+    borderInlineEndColor: colorVars['--color-border'],
   },
 });
 

package/src/Table/plugins/groupedRows/useTableGroupedRows.tsx

@@ -20,6 +20,7 @@ import {
   fontWeightVars,
 } from '../../../theme/tokens.stylex';
 import {Icon} from '../../../Icon';
+import {rtlStyles} from '../../../utils';
 import type {TablePlugin} from '../../types';
 import {useTranslator} from '../../../i18n';
 
@@ -333,12 +334,14 @@ export function useTableGroupedRows<T extends Record<string, unknown>>(
                         })
                   }
                   aria-expanded={!collapsed}>
-                  <span
-                    {...stylex.props(
-                      styles.chevronIcon,
-                      !collapsed && styles.chevronExpanded,
-                    )}>
-                    <Icon icon="chevronRight" size="xsm" />
+                  <span {...stylex.props(rtlStyles.mirror)}>
+                    <span
+                      {...stylex.props(
+                        styles.chevronIcon,
+                        !collapsed && styles.chevronExpanded,
+                      )}>
+                      <Icon icon="chevronRight" size="xsm" />
+                    </span>
                   </span>
                 </button>
                 {content}

package/src/Table/plugins/rowExpansion/useTableRowExpansion.test.tsx

@@ -9,6 +9,7 @@ import {
   useTableRowExpansion,
   useTableRowExpansionState,
 } from './useTableRowExpansion';
+import {InternationalizationProvider} from '../../../i18n';
 
 // popover mock for context-menu tests
 beforeEach(() => {
@@ -118,6 +119,24 @@ describe('useTableRowExpansion', () => {
     expect(items.length).toBeGreaterThan(0);
   });
 
+  it('localizes the context-menu action label through the i18n catalog', () => {
+    render(
+      <InternationalizationProvider
+        locale="fr"
+        overrides={{
+          fr: {'@astryx.tableRowExpansion.expandRow': 'Développer la ligne'},
+        }}>
+        <Harness />
+      </InternationalizationProvider>,
+    );
+    fireEvent.contextMenu(screen.getByText('Folder A'));
+    const items = screen.getAllByRole('menuitem', {
+      name: /Développer la ligne/,
+      hidden: true,
+    });
+    expect(items.length).toBeGreaterThan(0);
+  });
+
   it('does not show chevron for leaf nodes', () => {
     render(<Harness />);
     // Leaf C has no children

package/src/Table/plugins/rowExpansion/useTableRowExpansion.tsx

@@ -16,6 +16,7 @@ import {useCallback, useMemo, useRef, type ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {spacingVars, colorVars, radiusVars} from '../../../theme/tokens.stylex';
 import {Icon} from '../../../Icon';
+import {rtlStyles} from '../../../utils';
 import {resolveContextActions} from '../../tableContextMenu';
 import {useTranslator} from '../../../i18n';
 import type {
@@ -361,12 +362,14 @@ function ExpansionChevron({
       }}
       aria-label={ariaLabel}
       aria-expanded={isExpanded}>
-      <span
-        {...stylex.props(
-          expansionStyles.chevronIcon,
-          isExpanded && expansionStyles.chevronExpanded,
-        )}>
-        <Icon icon="chevronRight" size="xsm" />
+      <span {...stylex.props(rtlStyles.mirror)}>
+        <span
+          {...stylex.props(
+            expansionStyles.chevronIcon,
+            isExpanded && expansionStyles.chevronExpanded,
+          )}>
+          <Icon icon="chevronRight" size="xsm" />
+        </span>
       </span>
     </button>
   );
@@ -533,12 +536,14 @@ export function useTableRowExpansion<T extends Record<string, unknown>>(
                     ? t('@astryx.tableRowExpansion.collapseAllRows')
                     : t('@astryx.tableRowExpansion.expandAllRows')
                 }>
-                <span
-                  {...stylex.props(
-                    expansionStyles.chevronIcon,
-                    allExpanded && expansionStyles.chevronExpanded,
-                  )}>
-                  <Icon icon="chevronRight" size="xsm" />
+                <span {...stylex.props(rtlStyles.mirror)}>
+                  <span
+                    {...stylex.props(
+                      expansionStyles.chevronIcon,
+                      allExpanded && expansionStyles.chevronExpanded,
+                    )}>
+                    <Icon icon="chevronRight" size="xsm" />
+                  </span>
                 </span>
               </button>
             ),
@@ -571,13 +576,17 @@ export function useTableRowExpansion<T extends Record<string, unknown>>(
             {
               id: 'row-expansion-toggle',
               group: 'row-expansion',
-              label: isExpanded ? 'Collapse row' : 'Expand row',
+              label: isExpanded
+                ? t('@astryx.tableRowExpansion.collapseRow')
+                : t('@astryx.tableRowExpansion.expandRow'),
               icon: (
-                <Icon
-                  icon={isExpanded ? 'chevronDown' : 'chevronRight'}
-                  size="xsm"
-                  aria-hidden
-                />
+                <span {...stylex.props(rtlStyles.mirror)}>
+                  <Icon
+                    icon={isExpanded ? 'chevronDown' : 'chevronRight'}
+                    size="xsm"
+                    aria-hidden
+                  />
+                </span>
               ),
               onSelect: () => onToggle(key),
             },

package/src/Table/plugins/selection/useTableSelection.test.tsx

@@ -7,13 +7,13 @@
  * @position Test file; validates selection behavior (checkboxes, aria, select-all)
  */
 
-import {describe, it, expect} from 'vitest';
+import {describe, it, expect, vi} from 'vitest';
 import {useState} from 'react';
-import {render, screen, within} from '@testing-library/react';
+import {act, render, renderHook, screen, within} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {Table} from '../../Table';
 import {useTableSelection} from './useTableSelection';
-import type {TableColumn} from '../../types';
+import type {BodyRowRenderProps, TableColumn} from '../../types';
 
 // =============================================================================
 // Test Data
@@ -210,4 +210,62 @@ describe('useTableSelection', () => {
     const headers = within(headerRow).getAllByRole('columnheader');
     expect(headers).toHaveLength(3);
   });
+
+  it('unsubscribes detached row refs instead of accumulating listeners', () => {
+    const getIsItemSelected = vi.fn(() => false);
+    const {result, rerender} = renderHook(() =>
+      useTableSelection<SelectableUser>({
+        getIsItemSelected,
+        onSelectItem: vi.fn(),
+        onSelectAll: vi.fn(),
+        getIsAllSelected: () => false,
+      }),
+    );
+
+    const initialProps: BodyRowRenderProps = {
+      htmlProps: {},
+      xstyle: [],
+      children: null,
+    };
+    const row = document.createElement('tr');
+    document.body.append(row);
+
+    let detach: (() => void) | undefined;
+
+    // Simulate React replacing the callback ref as this row re-renders.
+    // Each detach must unsubscribe the previous ref before the next attaches.
+    for (let i = 0; i < 3; i++) {
+      act(() => {
+        detach?.();
+      });
+
+      const transformed = result.current.transformBodyRow?.(
+        initialProps,
+        selectableUsers[0],
+        0,
+      );
+      expect(transformed?.ref).toBeTypeOf('function');
+
+      act(() => {
+        const cleanup = (
+          transformed?.ref as React.RefCallback<HTMLTableRowElement>
+        )(row);
+        expect(cleanup).toBeTypeOf('function');
+        detach = cleanup as () => void;
+      });
+    }
+
+    getIsItemSelected.mockClear();
+    rerender();
+    expect(getIsItemSelected).toHaveBeenCalledTimes(1);
+
+    act(() => {
+      detach?.();
+    });
+    getIsItemSelected.mockClear();
+    rerender();
+    expect(getIsItemSelected).not.toHaveBeenCalled();
+
+    row.remove();
+  });
 });

package/src/Table/plugins/selection/useTableSelection.tsx

@@ -371,6 +371,9 @@ export function useTableSelection<T extends Record<string, unknown>>(
               store.getConfig().getIsItemSelected(item),
             );
           });
+          return () => {
+            unsub();
+          };
         };
 
         return {

package/src/Table/plugins/stickyColumns/useTableStickyColumns.tsx

@@ -205,7 +205,7 @@ const stickyStyles = stylex.create({
   },
 });
 
-// Soft drop shadow over the scrolling region (matches the EPS sticky treatment).
+// Soft drop shadow over the scrolling region (a standard sticky-column shadow treatment).
 // border-collapse tables don't paint box-shadow on cells in Chromium, so it's a
 // ::after gradient strip just past the pinned edge (visible thanks to the cell's
 // overflow: visible). Opacity is gated by the scroll-state variable above.
@@ -213,7 +213,12 @@ const SHADOW_WIDTH = '6px';
 // --color-shadow is only ~10% alpha (too faint here); use a slightly stronger soft tint.
 const SHADOW_TINT = 'light-dark(rgba(0, 0, 0, 0.12), rgba(0, 0, 0, 0.32))';
 const shadowStyles = stylex.create({
-  // start-pinned: shadow falls to the right (inline-end), over scrolled content
+  // start-pinned: shadow falls toward inline-end (over scrolled content).
+  // insetInlineEnd anchors the strip to the column's inline-end edge; the strip
+  // must then be nudged one full width OUTWARD (past that edge) into the
+  // scrolled region. Outward is +X under LTR (inline-end = right) but −X under
+  // RTL (inline-end = left), and the fade must run from the pinned edge toward
+  // content in each direction — hence both transform and gradient flip on dir.
   start: {
     '::after': {
       content: '""',
@@ -222,14 +227,24 @@ const shadowStyles = stylex.create({
       bottom: 0,
       insetInlineEnd: 0,
       width: SHADOW_WIDTH,
-      transform: 'translateX(100%)',
+      transform: {
+        default: 'translateX(100%)',
+        ':is([dir="rtl"] *)': 'translateX(-100%)',
+      },
       pointerEvents: 'none',
       transition: 'opacity 150ms ease',
       opacity: `var(${SHADOW_VAR_START}, 0)`,
-      backgroundImage: `linear-gradient(to right, ${SHADOW_TINT}, transparent)`,
+      backgroundImage: {
+        default: `linear-gradient(to right, ${SHADOW_TINT}, transparent)`,
+        ':is([dir="rtl"] *)': `linear-gradient(to left, ${SHADOW_TINT}, transparent)`,
+      },
     },
   },
-  // end-pinned: shadow falls to the left (inline-start), over scrolled content
+  // end-pinned: shadow falls toward inline-start (over scrolled content).
+  // insetInlineStart anchors the strip to the column's inline-start edge; the
+  // strip is nudged one full width OUTWARD into content — −X under LTR
+  // (inline-start = left) but +X under RTL (inline-start = right) — with the
+  // gradient fading from the pinned edge toward content in each direction.
   end: {
     '::after': {
       content: '""',
@@ -238,11 +253,17 @@ const shadowStyles = stylex.create({
       bottom: 0,
       insetInlineStart: 0,
       width: SHADOW_WIDTH,
-      transform: 'translateX(-100%)',
+      transform: {
+        default: 'translateX(-100%)',
+        ':is([dir="rtl"] *)': 'translateX(100%)',
+      },
       pointerEvents: 'none',
       transition: 'opacity 150ms ease',
       opacity: `var(${SHADOW_VAR_END}, 0)`,
-      backgroundImage: `linear-gradient(to left, ${SHADOW_TINT}, transparent)`,
+      backgroundImage: {
+        default: `linear-gradient(to left, ${SHADOW_TINT}, transparent)`,
+        ':is([dir="rtl"] *)': `linear-gradient(to right, ${SHADOW_TINT}, transparent)`,
+      },
     },
   },
 });
@@ -289,16 +310,24 @@ export function useTableStickyColumns<T extends Record<string, unknown>>(
       const {hasStart: hs, hasEnd: he} = stateRef.current;
       const maxScroll = el.scrollWidth - el.clientWidth;
       const hasOverflow = maxScroll > 1;
+      // RTL-safe scroll position. Spec-compliant browsers report a NEGATIVE
+      // scrollLeft under RTL (0 at the inline-start edge, decreasing toward the
+      // inline-end edge), so a raw `scrollLeft > 1` start test would never fire
+      // and the end test would be wrong-signed. Math.abs collapses both
+      // conventions to a distance-from-inline-start, matching the repo's own
+      // useScrollOverflow (overflowStart/overflowEnd use Math.abs, tolerance 1).
+      // No-op under LTR where scrollLeft is already >= 0.
+      const pos = Math.abs(el.scrollLeft);
       if (hs) {
         el.style.setProperty(
           SHADOW_VAR_START,
-          hasOverflow && el.scrollLeft > 1 ? '1' : '0',
+          hasOverflow && pos > 1 ? '1' : '0',
         );
       }
       if (he) {
         el.style.setProperty(
           SHADOW_VAR_END,
-          hasOverflow && el.scrollLeft < maxScroll - 1 ? '1' : '0',
+          hasOverflow && pos < maxScroll - 1 ? '1' : '0',
         );
       }
     };

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} from '../../../utils';
+import {mergeRefs, rtlStyles} from '../../../utils';
 import type {
   TablePlugin,
   TableColumn,
@@ -299,12 +299,14 @@ function TreeExpander({
           : t('@astryx.tableTree.expandRow')
       }
       aria-expanded={isExpanded}>
-      <span
-        {...stylex.props(
-          treeStyles.chevron,
-          isExpanded && treeStyles.chevronExpanded,
-        )}>
-        <Icon icon="chevronRight" size="xsm" />
+      <span {...stylex.props(rtlStyles.mirror)}>
+        <span
+          {...stylex.props(
+            treeStyles.chevron,
+            isExpanded && treeStyles.chevronExpanded,
+          )}>
+          <Icon icon="chevronRight" size="xsm" />
+        </span>
       </span>
     </button>
   );
@@ -346,12 +348,14 @@ function TreeExpandAllToggle({
           : t('@astryx.tableTree.expandAllRows')
       }
       aria-expanded={allExpanded}>
-      <span
-        {...stylex.props(
-          treeStyles.chevron,
-          allExpanded && treeStyles.chevronExpanded,
-        )}>
-        <Icon icon="chevronRight" size="xsm" />
+      <span {...stylex.props(rtlStyles.mirror)}>
+        <span
+          {...stylex.props(
+            treeStyles.chevron,
+            allExpanded && treeStyles.chevronExpanded,
+          )}>
+          <Icon icon="chevronRight" size="xsm" />
+        </span>
       </span>
     </button>
   );

package/src/Table/types.ts

@@ -540,6 +540,39 @@ export interface BaseTableProps<
   /** Plugins to transform render props at each level */
   plugins?: TablePlugin<T>[];
 
+  /**
+   * ARIA row index (1-based) assigned to the **first** rendered body row.
+   *
+   * The row ordinal is an accessibility concern independent of any visible
+   * index column: `aria-rowindex` on each `<tr>` should reflect the row's
+   * position in the **full** dataset, not just the current page. For a
+   * paginated / windowed view, pass the offset of the first visible row,
+   * e.g. `(page - 1) * pageSize + 1`.
+   *
+   * Setting this (or {@link rowCount}) opts the table into emitting
+   * `aria-rowindex` on body rows and `aria-rowcount` on the `<table>`. Data
+   * rows are numbered from this value; the header row keeps native table
+   * semantics and is not assigned an ARIA row index (so the visible
+   * `useTableRowIndex` numbering and `aria-rowindex` stay in agreement).
+   *
+   * Applies to data-driven mode only (ignored in children mode).
+   *
+   * @default 1
+   */
+  rowIndexStart?: number;
+  /**
+   * Total number of body rows across **all** pages/windows, used for
+   * `aria-rowcount` on the `<table>`. Provide this for paginated data so
+   * assistive tech can announce "row X of Y" against the full dataset.
+   *
+   * When omitted but {@link rowIndexStart} is set (a windowed view with an
+   * unknown total, e.g. cursor pagination), `aria-rowcount` is set to `-1`
+   * per the ARIA convention for an unknown row count.
+   *
+   * Applies to data-driven mode only (ignored in children mode).
+   */
+  rowCount?: number;
+
   /** Children mode — render `<tr>`/`<td>` directly instead of data-driven */
   children?: ReactNode;
   /**

package/src/Table/useTableRowStatus.doc.mjs

@@ -13,7 +13,7 @@ export const docs = {
       name: 'getStatus',
       type: "(item: T) => { color: 'accent' | 'success' | 'error' | 'warning' | 'red' | 'orange' | 'green' | 'yellow' | 'blue' | 'gray' | string; icon?: IconName; label: string } | null",
       description:
-        'Derive the status indicator for a row: a semantic color (accent, success, error, warning, red, orange, green, yellow, blue, gray — mapped to a theme token) or a raw CSS color as an escape hatch; an optional icon to signal status by shape instead of the dot (recommended when multiple statuses coexist; valid names: close, chevronDown, chevronLeft, chevronRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone); and a required accessible label (announced via role="img" and shown in a tooltip on hover, so a status is never conveyed by color alone). Return null for rows with no status. Memoize with useCallback for a stable plugin identity.',
+        'Derive the status indicator for a row: a semantic color (accent, success, error, warning, red, orange, green, yellow, blue, gray, each mapped to a theme token) or a raw CSS color as an escape hatch; an optional icon to signal status by shape instead of the dot (recommended when multiple statuses coexist; valid names: close, chevronDown, chevronLeft, chevronRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone); and a required accessible label (announced via role="img" and shown in a tooltip on hover, so a status is never conveyed by color alone). Return null for rows with no status. Memoize with useCallback for a stable plugin identity.',
       required: true,
     },
   ],

package/src/Text/Heading.doc.mjs

@@ -33,7 +33,7 @@ export const docs = {
     {
       name: 'color',
       type: "'primary' | 'secondary' | 'disabled' | 'placeholder' | 'accent' | 'inherit'",
-      description: 'Text color.',
+      description: 'Text color. Themes may add custom colors.',
       default: "'primary'",
     },
     {
@@ -120,7 +120,7 @@ export const docsZh = {
     {
       name: 'color',
       type: "'primary' | 'secondary' | 'disabled' | 'placeholder' | 'accent' | 'inherit'",
-      description: '文本颜色。',
+      description: '文本颜色。主题可添加自定义颜色。',
       default: "'primary'",
     },
     {
@@ -186,7 +186,7 @@ export const docsDense = {
     type: 'Display variant (display-1/2/3); overrides visual styling from level with display-scale sizing.',
     children: 'Heading content.',
     accessibilityLevel: 'aria-level override when different from level for document outline.',
-    color: 'Text color.',
+    color: 'Text color. Themes may add custom colors.',
     display: "Display type; overridden to 'block' when maxLines>0 or hasCapsize.",
     maxLines: 'Max lines before truncation; 0=none. Shows tooltip if truncated.',
     hasTruncateTooltip: "Tooltip for truncated text; true=default position, false=disabled, or a placement ('above' | 'below' | 'start' | 'end').",

package/src/Text/Text.doc.mjs

@@ -41,7 +41,7 @@ export const docs = {
     {
       name: 'color',
       type: "'primary' | 'secondary' | 'disabled' | 'placeholder' | 'accent' | 'inherit'",
-      description: "Text color. Defaults to 'secondary' for the 'supporting' type, 'primary' for all others.",
+      description: "Text color. Defaults to 'secondary' for the 'supporting' type, 'primary' for all others. Themes may add custom colors.",
     },
     {
       name: 'weight',

package/src/Text/Text.test.tsx

@@ -9,6 +9,7 @@ import {render, screen} from '@testing-library/react';
 import {describe, it, expect} from 'vitest';
 import {Text} from './Text';
 import type {TextType} from './Text';
+import type {TextColor} from '../theme/types';
 
 describe('Text', () => {
   describe('rendering', () => {
@@ -233,3 +234,44 @@ describe('Text custom types', () => {
     expect(screen.getByText('Muted').className).toContain('secondary');
   });
 });
+
+describe('Text custom colors', () => {
+  it('renders a custom color as a stable class for theme CSS to target', () => {
+    // A theme adds a custom color (e.g. via TextColorMap augmentation +
+    // defineTheme). The rendered element carries the color as a class
+    // (astryx-text.<color>) so `.astryx-text.brand { color: ... }` from the
+    // theme applies — mirroring how custom `type`s work.
+    render(<Text color={'brand' as TextColor}>Branded</Text>);
+    const el = screen.getByText('Branded');
+    expect(el.className).toContain('astryx-text');
+    expect(el.className).toContain('brand');
+  });
+
+  it('does not crash on a custom color (falls back to the primary StyleX baseline)', () => {
+    // colorStyles has no entry for a custom color; the component must resolve a
+    // built-in baseline instead of indexing undefined. Built-in `primary` is
+    // the baseline, so both share its StyleX color class.
+    render(
+      <>
+        <Text color={'brand' as TextColor}>Custom</Text>
+        <Text color="primary">Builtin</Text>
+      </>,
+    );
+    const custom = screen.getByText('Custom');
+    const builtin = screen.getByText('Builtin');
+    // Neither throws, and the custom color reuses primary's baseline StyleX
+    // class (the real color comes from theme CSS via the `brand` class).
+    const primaryAtomic = builtin.className
+      .split(/\s+/)
+      .filter(c => c.startsWith('x'));
+    expect(primaryAtomic.length).toBeGreaterThan(0);
+    for (const cls of primaryAtomic) {
+      expect(custom.className).toContain(cls);
+    }
+  });
+
+  it('still applies built-in colors directly', () => {
+    render(<Text color="accent">Accent</Text>);
+    expect(screen.getByText('Accent').className).toContain('accent');
+  });
+});