Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(Table): separate semantic row status from custom markers (#5832)

Cindy Zhang4a48880b5c3d
diff --git a/.changeset/table-row-status-compatibility.md b/.changeset/table-row-status-compatibility.md
new file mode 100644
index 0000000000..7ac3c79eb0
--- /dev/null
+++ b/.changeset/table-row-status-compatibility.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] Add semantic Table row statuses while restoring custom-marker compatibility. Named custom icons keep their released Icon color mapping; raw CSS custom icons now use the caller's paint as required by the current contract. Canary users relying on implicit glyphs should switch from `color` to `status`.
+
+@cixzhang
diff --git a/apps/storybook/rtl-audit/verified-not-applicable.json b/apps/storybook/rtl-audit/verified-not-applicable.json
index 824eb7808a..268bc697ef 100644
--- a/apps/storybook/rtl-audit/verified-not-applicable.json
+++ b/apps/storybook/rtl-audit/verified-not-applicable.json
@@ -9,7 +9,7 @@
},
{
"component": "core/Table",
- "reason": "The Core/Table stories render native table rows and cells inside an overflow-x scroll wrapper. Column order, start/end alignment, column dividers and container bleed use table flow, text-align start/end, border-inline-end and logical inline margins, all resolved by CSS for the document direction. Horizontal overflow is native scrolling with no component-owned next/previous control or directional drag behavior, and these stories render no directional glyph or positioned element with a horizontal transform."
+ "reason": "Base Table and row-status indicators have no direction-sensitive glyph, physical positioning, order, or interaction; directional Table plugins are audited separately."
},
{
"component": "core/Text",
diff --git a/apps/storybook/stories/TableRowStatus.stories.tsx b/apps/storybook/stories/TableRowStatus.stories.tsx
index b53660aeae..858ef3ee24 100644
--- a/apps/storybook/stories/TableRowStatus.stories.tsx
+++ b/apps/storybook/stories/TableRowStatus.stories.tsx
@@ -7,17 +7,16 @@ import {
proportional,
pixel,
} from '@astryxdesign/core/Table';
-import type {TableColumn, TableRowStatus} from '@astryxdesign/core/Table';
-
-// =============================================================================
-// Sample Data
-// =============================================================================
+import type {
+ TableColumn,
+ UseTableRowStatusConfig,
+} from '@astryxdesign/core/Table';
interface Job extends Record<string, unknown> {
id: string;
name: string;
owner: string;
- state: 'failed' | 'running' | 'queued' | 'succeeded';
+ state: 'failed' | 'running' | 'queued' | 'succeeded' | 'needsAttention';
}
const jobs: Job[] = [
@@ -26,6 +25,12 @@ const jobs: Job[] = [
{id: 'j3', name: 'unit-tests', owner: 'Zoe', state: 'succeeded'},
{id: 'j4', name: 'docsite-deploy', owner: 'Max', state: 'queued'},
{id: 'j5', name: 'smoke-test', owner: 'Mia', state: 'succeeded'},
+ {
+ id: 'j6',
+ name: 'snapshot-review',
+ owner: 'Noah',
+ state: 'needsAttention',
+ },
];
const columns: TableColumn<Job>[] = [
@@ -34,18 +39,20 @@ const columns: TableColumn<Job>[] = [
{key: 'state', header: 'State', width: pixel(120)},
];
-function jobStatus(job: Job): TableRowStatus | null {
+const jobStatus: UseTableRowStatusConfig<Job>['getStatus'] = job => {
switch (job.state) {
case 'failed':
- return {color: 'error', icon: 'error', label: 'Failed'};
+ return {status: 'error', label: 'Failed'};
case 'running':
- return {color: 'warning', icon: 'warning', label: 'Running'};
+ return {color: 'warning', icon: 'clock', label: 'Running'};
case 'queued':
return {color: 'gray', label: 'Queued'};
- default:
- return null; // succeeded: no indicator
+ case 'succeeded':
+ return {status: 'success', label: 'Succeeded'};
+ case 'needsAttention':
+ return {status: 'warning', label: 'Needs attention'};
}
-}
+};
const meta: Meta = {
title: 'Core/TableRowStatus',
@@ -56,9 +63,9 @@ export default meta;
type Story = StoryObj;
/**
- * A small colored dot in a leading gutter column signals per-row status.
- * Rows whose `getStatus` returns `null` (here: succeeded jobs) show no dot.
- * Hover a dot to see its accessible label.
+ * Semantic status values use the active theme's outcome glyph and tone. Custom
+ * markers keep caller-owned paint: queued renders a dot, while running uses the
+ * explicit clock icon. Each marker has one accessible image name from `label`.
*/
export const Default: Story = {
render: () => {
@@ -76,17 +83,24 @@ export const Default: Story = {
};
/**
- * Any CSS color works: here raw hex values instead of theme tokens.
+ * A custom marker's color never selects its representation. Even colors named
+ * `error` or `success` remain dots unless the caller supplies an explicit icon.
*/
-export const RawColors: Story = {
+export const CustomMarkers: Story = {
render: () => {
const rowStatus = useTableRowStatus<Job>({
getStatus: job =>
job.state === 'failed'
- ? {color: '#dc2626', label: 'Failed'}
+ ? {color: 'error', label: 'Error-colored dot'}
: job.state === 'running'
- ? {color: '#f59e0b', label: 'Running'}
- : null,
+ ? {color: 'warning', icon: 'clock', label: 'Warning-colored clock'}
+ : job.state === 'succeeded'
+ ? {
+ color: 'success',
+ icon: 'check',
+ label: 'Success-colored check',
+ }
+ : {color: '#64748b', label: 'Custom gray dot'},
});
return (
<Table
diff --git a/packages/cli/assets/templates/blocks/components/Table/TableRowStatusTable.doc.mjs b/packages/cli/assets/templates/blocks/components/Table/TableRowStatusTable.doc.mjs
index 04283b623a..d25ebb1afa 100644
--- a/packages/cli/assets/templates/blocks/components/Table/TableRowStatusTable.doc.mjs
+++ b/packages/cli/assets/templates/blocks/components/Table/TableRowStatusTable.doc.mjs
@@ -4,10 +4,10 @@
export const doc = {
type: 'block',
exampleFor: 'useTableRowStatus',
- name: 'useTableRowStatus - Status Icons',
- displayName: 'useTableRowStatus - Status Icons',
+ name: 'useTableRowStatus - Semantic and Custom Markers',
+ displayName: 'useTableRowStatus - Semantic and Custom Markers',
description:
- 'A job table using useTableRowStatus. Semantic outcomes use the themed success, warning, and error icons; a palette-only queued state keeps the neutral dot.',
+ 'A job table using both row-status paths: status resolves themed semantic glyphs and tones, while color stays a custom paint choice with an optional caller-selected icon or the stable dot.',
isReady: true,
aspectRatio: 16 / 9,
componentsUsed: ['Table'],
diff --git a/packages/cli/assets/templates/blocks/components/Table/TableRowStatusTable.tsx b/packages/cli/assets/templates/blocks/components/Table/TableRowStatusTable.tsx
index 8a38d395c6..881e7b17f0 100644
--- a/packages/cli/assets/templates/blocks/components/Table/TableRowStatusTable.tsx
+++ b/packages/cli/assets/templates/blocks/components/Table/TableRowStatusTable.tsx
@@ -8,13 +8,16 @@ import {
proportional,
pixel,
} from '@astryxdesign/core/Table';
-import type {TableColumn, TableRowStatus} from '@astryxdesign/core/Table';
+import type {
+ TableColumn,
+ UseTableRowStatusConfig,
+} from '@astryxdesign/core/Table';
interface Job extends Record<string, unknown> {
id: string;
name: string;
owner: string;
- state: 'failed' | 'running' | 'queued' | 'succeeded';
+ state: 'failed' | 'running' | 'queued' | 'succeeded' | 'needsAttention';
}
const jobs: Job[] = [
@@ -23,6 +26,12 @@ const jobs: Job[] = [
{id: 'j3', name: 'unit-tests', owner: 'Zoe', state: 'succeeded'},
{id: 'j4', name: 'docsite-deploy', owner: 'Max', state: 'queued'},
{id: 'j5', name: 'smoke-test', owner: 'Mia', state: 'succeeded'},
+ {
+ id: 'j6',
+ name: 'snapshot-review',
+ owner: 'Noah',
+ state: 'needsAttention',
+ },
];
const columns: TableColumn<Job>[] = [
@@ -31,18 +40,20 @@ const columns: TableColumn<Job>[] = [
{key: 'state', header: 'State', width: pixel(120)},
];
-function jobStatus(job: Job): TableRowStatus | null {
+const jobStatus: UseTableRowStatusConfig<Job>['getStatus'] = job => {
switch (job.state) {
case 'failed':
- return {color: 'error', label: 'Failed'};
+ return {status: 'error', label: 'Failed'};
case 'running':
- return {color: 'warning', label: 'Running'};
+ return {color: 'warning', icon: 'clock', label: 'Running'};
case 'queued':
return {color: 'gray', label: 'Queued'};
case 'succeeded':
- return {color: 'success', label: 'Succeeded'};
+ return {status: 'success', label: 'Succeeded'};
+ case 'needsAttention':
+ return {status: 'warning', label: 'Needs attention'};
}
-}
+};
export default function TableRowStatusTable() {
const rowStatus = useTableRowStatus<Job>({getStatus: jobStatus});
diff --git a/packages/core/src/Table/Table.perf.test.tsx b/packages/core/src/Table/Table.perf.test.tsx
index dc2056e6d3..dd2db5403b 100644
--- a/packages/core/src/Table/Table.perf.test.tsx
+++ b/packages/core/src/Table/Table.perf.test.tsx
@@ -14,8 +14,10 @@
import {describe, it, expect, vi} from 'vitest';
import {render, screen, act} from '@testing-library/react';
-import {useState} from 'react';
+import {useMemo, useState} from 'react';
import {Table} from './Table';
+import {useTableRowStatus} from './plugins/rowStatus';
+import type {UseTableRowStatusConfig} from './index';
import type {TableColumn} from './types';
// =============================================================================
@@ -466,6 +468,54 @@ describe('Table render performance', () => {
expect(renderTime).toBeLessThan(500 * ciBudgetMultiplier);
});
+ it('keeps mixed row-status rendering and no-op updates within budget', async () => {
+ const data = createTestData(6);
+ const getStatus = vi.fn<UseTableRowStatusConfig<TestRow>['getStatus']>(
+ row =>
+ row.value % 30 === 0
+ ? {status: 'success', label: 'Complete'}
+ : row.value % 20 === 0
+ ? {color: 'warning', icon: 'clock', label: 'Running'}
+ : {color: 'gray', label: 'Queued'},
+ );
+
+ function TestComponent() {
+ const [items, setItems] = useState(data);
+ const rowStatus = useTableRowStatus<TestRow>({getStatus});
+ const plugins = useMemo(() => ({rowStatus}), [rowStatus]);
+
+ return (
+ <div>
+ <button type="button" onClick={() => setItems(prev => [...prev])}>
+ No-op update
+ </button>
+ <Table
+ data={items}
+ columns={testColumns}
+ idKey="id"
+ plugins={plugins}
+ />
+ </div>
+ );
+ }
+
+ const renderStart = performance.now();
+ render(<TestComponent />);
+ const renderTime = performance.now() - renderStart;
+
+ expect(getStatus).toHaveBeenCalledTimes(6);
+ expect(renderTime).toBeLessThan(1500 * ciBudgetMultiplier);
+
+ const updateStart = performance.now();
+ await act(async () => {
+ screen.getByRole('button', {name: 'No-op update'}).click();
+ });
+ const updateTime = performance.now() - updateStart;
+
+ expect(getStatus).toHaveBeenCalledTimes(6);
+ expect(updateTime).toBeLessThan(1000 * ciBudgetMultiplier);
+ });
+
it('should measure update performance', async () => {
const data = createTestData(100);
diff --git a/packages/core/src/Table/index.ts b/packages/core/src/Table/index.ts
index 20e6b4c743..c2f03d7ca8 100644
--- a/packages/core/src/Table/index.ts
+++ b/packages/core/src/Table/index.ts
@@ -9,6 +9,24 @@
* SYNC: When modified, update this header and /packages/core/src/Table/Table.doc.mjs
*/
+import type {IconName} from '../Icon';
+import type {TableRowStatusColor} from './plugins/rowStatus/useTableRowStatus';
+
+/** Stable custom row-status marker contract. */
+export interface TableRowStatus {
+ color: TableRowStatusColor | (string & {});
+ icon?: IconName;
+ label: string;
+}
+
+/** Semantic row outcome resolved through the active theme. */
+export interface TableSemanticRowStatus {
+ status: 'success' | 'warning' | 'error';
+ color?: never;
+ icon?: never;
+ label: string;
+}
+
export {Table} from './Table';
export {TableRow} from './TableRow';
export {TableCell} from './TableCell';
@@ -108,10 +126,7 @@ export type {
UseTableGroupedRowsConfig,
UseTableGroupedRowsResult,
} from './plugins/groupedRows';
-export type {
- UseTableRowStatusConfig,
- TableRowStatus,
-} from './plugins/rowStatus';
+export type {UseTableRowStatusConfig} from './plugins/rowStatus';
export type {
TableTreeRowMeta,
UseTableTreeDataConfig,
diff --git a/packages/core/src/Table/plugins/groupedRows/useTableGroupedRows.test.tsx b/packages/core/src/Table/plugins/groupedRows/useTableGroupedRows.test.tsx
index 305f224f5e..c98cb270d8 100644
--- a/packages/core/src/Table/plugins/groupedRows/useTableGroupedRows.test.tsx
+++ b/packages/core/src/Table/plugins/groupedRows/useTableGroupedRows.test.tsx
@@ -5,7 +5,8 @@ import {render, screen, fireEvent, within} from '@testing-library/react';
import {useState, useCallback} from 'react';
import {Table} from '../../Table';
import type {TableColumn} from '../../types';
-import {useTableRowStatus, type TableRowStatus} from '../rowStatus';
+import type {TableRowStatus} from '../../index';
+import {useTableRowStatus} from '../rowStatus';
import {useTableGroupedRows} from './useTableGroupedRows';
interface Person extends Record<string, unknown> {
diff --git a/packages/core/src/Table/plugins/rowStatus/index.ts b/packages/core/src/Table/plugins/rowStatus/index.ts
index 35ec2f7528..0c96878964 100644
--- a/packages/core/src/Table/plugins/rowStatus/index.ts
+++ b/packages/core/src/Table/plugins/rowStatus/index.ts
@@ -1,7 +1,4 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
export {useTableRowStatus} from './useTableRowStatus';
-export type {
- UseTableRowStatusConfig,
- TableRowStatus,
-} from './useTableRowStatus';
+export type {UseTableRowStatusConfig} from './useTableRowStatus';
diff --git a/packages/core/src/Table/plugins/rowStatus/useTableRowStatus.public.test.ts b/packages/core/src/Table/plugins/rowStatus/useTableRowStatus.public.test.ts
new file mode 100644
index 0000000000..52b8b31116
--- /dev/null
+++ b/packages/core/src/Table/plugins/rowStatus/useTableRowStatus.public.test.ts
@@ -0,0 +1,92 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, expectTypeOf, it} from 'vitest';
+import type {
+ TableRowStatus,
+ TableSemanticRowStatus,
+ UseTableRowStatusConfig,
+} from '@astryxdesign/core/Table';
+
+declare module '@astryxdesign/core/Table' {
+ interface TableRowStatus {
+ consumerNote?: string;
+ }
+}
+
+interface Row extends Record<string, unknown> {
+ id: string;
+}
+
+interface ExtendedCustomStatus extends TableRowStatus {
+ source: 'consumer';
+}
+
+type RowStatusResult = Exclude<
+ ReturnType<UseTableRowStatusConfig<Row>['getStatus']>,
+ null
+>;
+
+describe('useTableRowStatus public contract', () => {
+ it('preserves the custom interface for extension and declaration merging', () => {
+ expectTypeOf<ExtendedCustomStatus>().toMatchTypeOf<TableRowStatus>();
+ expectTypeOf<{
+ color: 'red';
+ label: string;
+ consumerNote: string;
+ }>().toMatchTypeOf<TableRowStatus>();
+
+ const legacyGetStatus = (_item: Row): TableRowStatus | null => ({
+ color: 'red',
+ label: 'Legacy',
+ consumerNote: 'declaration merge stays available',
+ });
+ expectTypeOf(legacyGetStatus).toMatchTypeOf<
+ UseTableRowStatusConfig<Row>['getStatus']
+ >();
+ });
+
+ it('accepts the semantic interface and each exclusive callback branch', () => {
+ expectTypeOf<TableSemanticRowStatus>().toMatchTypeOf<RowStatusResult>();
+ expectTypeOf<{
+ status: 'success';
+ label: string;
+ }>().toMatchTypeOf<RowStatusResult>();
+ expectTypeOf<{
+ color: 'red';
+ label: string;
+ status: undefined;
+ }>().toMatchTypeOf<RowStatusResult>();
+ expectTypeOf<{
+ color: 'rgb(1, 2, 3)';
+ icon: 'check';
+ label: string;
+ }>().toMatchTypeOf<RowStatusResult>();
+ });
+
+ it('rejects mixed, incomplete, and unknown callback results', () => {
+ expectTypeOf<{
+ status: 'success';
+ color: 'green';
+ label: string;
+ }>().not.toMatchTypeOf<RowStatusResult>();
+ expectTypeOf<{
+ status: 'error';
+ icon: 'error';
+ label: string;
+ }>().not.toMatchTypeOf<RowStatusResult>();
+ expectTypeOf<{
+ status: 'info';
+ label: string;
+ }>().not.toMatchTypeOf<RowStatusResult>();
+ expectTypeOf<{label: string}>().not.toMatchTypeOf<RowStatusResult>();
+ expectTypeOf<{status: 'success'}>().not.toMatchTypeOf<RowStatusResult>();
+ expectTypeOf<{color: 'red'}>().not.toMatchTypeOf<RowStatusResult>();
+ });
+
+ it('keeps resolved anatomy off both public interfaces', () => {
+ expectTypeOf<TableRowStatus>().not.toHaveProperty('variant');
+ expectTypeOf<TableRowStatus>().not.toHaveProperty('presentation');
+ expectTypeOf<TableSemanticRowStatus>().not.toHaveProperty('variant');
+ expectTypeOf<TableSemanticRowStatus>().not.toHaveProperty('presentation');
+ });
+});
diff --git a/packages/core/src/Table/plugins/rowStatus/useTableRowStatus.test.tsx b/packages/core/src/Table/plugins/rowStatus/useTableRowStatus.test.tsx
index ff981969d0..74fa8bc824 100644
--- a/packages/core/src/Table/plugins/rowStatus/useTableRowStatus.test.tsx
+++ b/packages/core/src/Table/plugins/rowStatus/useTableRowStatus.test.tsx
@@ -1,12 +1,18 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
-import {describe, it, expect} from 'vitest';
-import {render, screen, within} from '@testing-library/react';
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
+import {render, renderHook, screen, within} from '@testing-library/react';
import {Theme} from '../../../theme/Theme';
import {defineTheme} from '../../../theme/defineTheme';
+import {__resetDevWarnings} from '../../../utils/devWarning';
import {Table} from '../../Table';
-import type {TableColumn} from '../../types';
-import {useTableRowStatus, type TableRowStatus} from './useTableRowStatus';
+import type {TableColumn, TablePlugin} from '../../types';
+import {useTableRowExpansion} from '../rowExpansion';
+import {useTableSelection} from '../selection';
+import {
+ useTableRowStatus,
+ type UseTableRowStatusConfig,
+} from './useTableRowStatus';
interface Row extends Record<string, unknown> {
id: string;
@@ -14,6 +20,11 @@ interface Row extends Record<string, unknown> {
state: 'error' | 'warning' | 'ok' | 'done';
}
+type TableRowStatusResult = Exclude<
+ ReturnType<UseTableRowStatusConfig<Row>['getStatus']>,
+ null
+>;
+
const data: Row[] = [
{id: 'a', name: 'Alice', state: 'error'},
{id: 'b', name: 'Bob', state: 'ok'},
@@ -22,12 +33,12 @@ const data: Row[] = [
const columns: TableColumn<Row>[] = [{key: 'name', header: 'Name'}];
-function getStatus(item: Row): TableRowStatus | null {
+function getStatus(item: Row): TableRowStatusResult | null {
if (item.state === 'error') {
- return {color: 'error', label: 'Error'};
+ return {status: 'error', label: 'Error'};
}
if (item.state === 'warning') {
- return {color: 'warning', label: 'Warning'};
+ return {status: 'warning', label: 'Warning'};
}
return null;
}
@@ -37,7 +48,7 @@ function Harness({
statusFn = getStatus,
}: {
rows?: Row[];
- statusFn?: (item: Row) => TableRowStatus | null;
+ statusFn?: (item: Row) => TableRowStatusResult | null;
}) {
const rowStatus = useTableRowStatus<Row>({getStatus: statusFn});
return (
@@ -45,118 +56,464 @@ function Harness({
);
}
+beforeEach(() => {
+ __resetDevWarnings();
+});
+
+afterEach(() => {
+ vi.restoreAllMocks();
+ vi.unstubAllEnvs();
+});
+
describe('useTableRowStatus', () => {
- it('names the status column header for assistive technology', () => {
+ it('preserves the fixed leading status-column semantics', () => {
render(<Harness />);
- // The gutter looks blank but its th carries a visually hidden name.
const header = screen.getByRole('columnheader', {name: 'Row status'});
+
expect(header).toHaveAttribute('data-column-key', '__rowStatus');
- // Status column is first.
expect(screen.getAllByRole('columnheader')[0]).toBe(header);
- // The name must come from the clipped VisuallyHidden span — bare th text
- // would be a visible header on what should stay a blank gutter.
+ expect(header).toHaveStyle({width: '28px'});
+
const hiddenText = within(header).getByText('Row status');
expect(hiddenText.tagName).toBe('SPAN');
expect(hiddenText.className).not.toBe('');
});
- it('renders themed semantic icons by default', () => {
+ it('preserves plugin identity for a stable getStatus callback', () => {
+ const {result, rerender} = renderHook(() =>
+ useTableRowStatus<Row>({getStatus}),
+ );
+ const initialPlugin = result.current;
+
+ rerender();
+
+ expect(result.current).toBe(initialPlugin);
+ });
+
+ it('resolves every semantic status through the active theme glyph and tone', () => {
const theme = defineTheme({
name: 'table-row-status-semantic-icons',
icons: {
- error: <svg data-testid="themed-error" />,
+ success: <svg data-testid="themed-success" />,
warning: <svg data-testid="themed-warning" />,
+ error: <svg data-testid="themed-error" />,
},
});
render(
<Theme theme={theme}>
- <Harness />
+ <Harness
+ statusFn={item =>
+ item.id === 'a'
+ ? {status: 'error', label: 'Error'}
+ : item.id === 'b'
+ ? {status: 'success', label: 'Success'}
+ : {status: 'warning', label: 'Warning'}
+ }
+ />
</Theme>,
);
- expect(screen.getByRole('img', {name: 'Error'})).toContainElement(
- screen.getByTestId('themed-error'),
- );
- expect(screen.getByRole('img', {name: 'Warning'})).toContainElement(
- screen.getByTestId('themed-warning'),
+ for (const status of ['success', 'warning', 'error'] as const) {
+ const glyph = screen.getByTestId(`themed-${status}`);
+ expect(
+ screen.getByRole('img', {
+ name: status[0].toUpperCase() + status.slice(1),
+ }),
+ ).toContainElement(glyph);
+ expect(glyph.parentElement).toHaveAttribute('data-color', status);
+ }
+ });
+
+ it('keeps every semantic-looking custom color on the stable 8px dot path', () => {
+ render(
+ <Harness
+ statusFn={item =>
+ item.id === 'a'
+ ? {color: 'success', label: 'Success-colored custom marker'}
+ : item.id === 'b'
+ ? {color: 'warning', label: 'Warning-colored custom marker'}
+ : {color: 'error', label: 'Error-colored custom marker'}
+ }
+ />,
);
+
+ const expectedTokens = {
+ 'Success-colored custom marker': '--color-icon-green',
+ 'Warning-colored custom marker': '--color-icon-orange',
+ 'Error-colored custom marker': '--color-icon-red',
+ } as const;
+
+ for (const [label, token] of Object.entries(expectedTokens)) {
+ const indicator = screen.getByRole('img', {name: label});
+ const dot = indicator.firstElementChild;
+
+ expect(indicator.querySelector('svg')).toBeNull();
+ expect(dot).toBeInstanceOf(HTMLElement);
+ expect(getComputedStyle(dot as HTMLElement).width).toBe('8px');
+ expect(getComputedStyle(dot as HTMLElement).height).toBe('8px');
+ expect(dot?.getAttribute('style')).toContain(token);
+ }
});
- it('keeps a dot for palette colors without outcome semantics', () => {
+ it('keeps an explicit undefined status on the custom-marker path', () => {
render(
<Harness
statusFn={item =>
- item.state === 'error' ? {color: 'red', label: 'Red'} : null
+ item.state === 'error'
+ ? {status: undefined, color: 'red', label: 'Custom marker'}
+ : null
}
/>,
);
- const indicator = screen.getByRole('img', {name: 'Red'});
+
+ const indicator = screen.getByRole('img', {name: 'Custom marker'});
expect(indicator.querySelector('svg')).toBeNull();
- expect(indicator.querySelector('span')?.getAttribute('style')).toContain(
+ expect(indicator.firstElementChild?.getAttribute('style')).toContain(
'--color-icon-red',
);
});
- it('renders no indicator for rows returning null', () => {
- render(<Harness />);
- const rows = screen.getAllByRole('row');
- // rows[2] is Bob (state ok): no status indicator in his status cell.
- const bob = rows[2];
- expect(within(bob).getByText('Bob')).toBeInTheDocument();
- expect(within(bob).queryByRole('img')).not.toBeInTheDocument();
+ it('preserves the released paint for a named custom icon', () => {
+ const theme = defineTheme({
+ name: 'table-row-status-custom-icon',
+ icons: {
+ clock: <svg data-testid="caller-clock" />,
+ warning: <svg data-testid="semantic-warning" />,
+ },
+ });
+
+ render(
+ <Theme theme={theme}>
+ <Harness
+ statusFn={item =>
+ item.state === 'warning'
+ ? {color: 'warning', icon: 'clock', label: 'Custom clock'}
+ : null
+ }
+ />
+ </Theme>,
+ );
+
+ const indicator = screen.getByRole('img', {name: 'Custom clock'});
+ const glyph = screen.getByTestId('caller-clock');
+
+ expect(indicator).toContainElement(glyph);
+ expect(screen.queryByTestId('semantic-warning')).not.toBeInTheDocument();
+ expect(indicator.getAttribute('style')).not.toContain('--color-icon');
+ expect(glyph.parentElement).toHaveAttribute('data-color', 'warning');
});
- it('passes through a raw CSS color as an escape hatch', () => {
+ it('applies a raw CSS color to an explicit custom icon', () => {
+ const theme = defineTheme({
+ name: 'table-row-status-raw-custom-icon',
+ icons: {check: <svg data-testid="raw-caller-check" />},
+ });
+
render(
- <Harness
- statusFn={item =>
- item.state === 'error' ? {color: 'rgb(1, 2, 3)', label: 'Raw'} : null
- }
- />,
+ <Theme theme={theme}>
+ <Harness
+ statusFn={item =>
+ item.state === 'error'
+ ? {
+ color: 'rgb(1, 2, 3)',
+ icon: 'check',
+ label: 'Raw custom icon',
+ }
+ : null
+ }
+ />
+ </Theme>,
);
- const indicator = screen.getByRole('img', {name: 'Raw'});
- const dot = indicator.querySelector('span');
- expect(dot?.getAttribute('style')).toContain('rgb(1, 2, 3)');
+
+ const indicator = screen.getByRole('img', {name: 'Raw custom icon'});
+ const glyph = screen.getByTestId('raw-caller-check');
+ expect(indicator).toContainElement(glyph);
+ expect(indicator.getAttribute('style')).toContain('rgb(1, 2, 3)');
+ expect(glyph.parentElement).toHaveAttribute('data-color', 'inherit');
});
- it('renders an icon as the status signifier when icon is provided', () => {
+ it('passes through a raw CSS color to a custom dot', () => {
render(
<Harness
statusFn={item =>
- item.state === 'error'
- ? {color: 'red', icon: 'error', label: 'Error'}
- : null
+ item.state === 'error' ? {color: 'rgb(1, 2, 3)', label: 'Raw'} : null
}
/>,
);
- // Icon-mode still exposes the accessible label via role=img.
- const indicator = screen.getByRole('img', {name: 'Error'});
- expect(indicator).toBeInTheDocument();
- // An SVG icon is rendered inside the indicator (dot mode has no svg).
- expect(indicator.querySelector('svg')).not.toBeNull();
+
+ const indicator = screen.getByRole('img', {name: 'Raw'});
+ expect(indicator.firstElementChild?.getAttribute('style')).toContain(
+ 'rgb(1, 2, 3)',
+ );
+ });
+
+ it('renders no indicator for rows returning null', () => {
+ render(<Harness />);
+ const rows = screen.getAllByRole('row');
+ const bob = rows[2];
+
+ expect(within(bob).getByText('Bob')).toBeInTheDocument();
+ expect(within(bob).queryByRole('img')).not.toBeInTheDocument();
});
- it('exposes the required label as the accessible name in dot mode', () => {
+ it('exposes the required label as one accessible image name', () => {
render(
<Harness
statusFn={item =>
- item.state === 'error' ? {color: 'red', label: 'Error'} : null
+ item.state === 'error' ? {status: 'error', label: 'Failed'} : null
}
/>,
);
- // Label is required, so every dot is announced via role=img with its name.
- const indicator = screen.getByRole('img', {name: 'Error'});
+
+ const indicator = screen.getByRole('img', {name: 'Failed'});
expect(indicator).toBeInTheDocument();
- // Dot mode renders no svg (that is icon mode).
- expect(indicator.querySelector('svg')).toBeNull();
+ expect(within(indicator).queryByRole('img')).not.toBeInTheDocument();
expect(screen.getByText('Alice')).toBeInTheDocument();
});
+ describe.each([
+ [
+ 'row status before expansion',
+ false,
+ ['__expansion', '__rowStatus', '__xds_selection', 'name'],
+ ],
+ [
+ 'expansion before row status',
+ true,
+ ['__rowStatus', '__expansion', '__xds_selection', 'name'],
+ ],
+ ] as const)(
+ 'with selection and expansion plugins: %s',
+ (_label, expansionFirst, expectedColumnKeys) => {
+ function CompositionHarness() {
+ const selection = useTableSelection<Row>({
+ getIsItemSelected: () => false,
+ onSelectItem: () => {},
+ onSelectAll: () => {},
+ getIsAllSelected: () => false,
+ getRowLabel: item => item.name,
+ });
+ const expansion = useTableRowExpansion<Row>({
+ expandedKeys: new Set(),
+ onToggle: () => {},
+ getRowKey: item => item.id,
+ renderExpanded: item => item.name,
+ });
+ const rowStatus = useTableRowStatus<Row>({getStatus});
+ const plugins = expansionFirst
+ ? {selection, expansion, rowStatus}
+ : {selection, rowStatus, expansion};
+
+ return (
+ <Table data={data} columns={columns} idKey="id" plugins={plugins} />
+ );
+ }
+
+ it('keeps each generated column and row control valid', () => {
+ render(<CompositionHarness />);
+
+ expect(
+ screen
+ .getAllByRole('columnheader')
+ .map(header => header.getAttribute('data-column-key')),
+ ).toEqual(expectedColumnKeys);
+ expect(screen.getAllByRole('checkbox')).toHaveLength(4);
+ expect(
+ screen.getAllByRole('button', {name: 'Expand row'}),
+ ).toHaveLength(3);
+ expect(
+ screen.getAllByRole('img', {name: /Error|Warning/}),
+ ).toHaveLength(2);
+ });
+ },
+ );
+
+ describe.each([
+ [
+ 'row status before custom plugin',
+ false,
+ ['__custom', '__rowStatus', 'name'],
+ ],
+ [
+ 'custom plugin before row status',
+ true,
+ ['__rowStatus', '__custom', 'name'],
+ ],
+ ] as const)(
+ 'with a caller-defined plugin: %s',
+ (_label, customFirst, expectedColumnKeys) => {
+ const customPlugin: TablePlugin<Row> = {
+ transformColumns(inputColumns) {
+ return [
+ {
+ key: '__custom',
+ header: 'Custom',
+ renderCell: item => item.id,
+ },
+ ...inputColumns,
+ ];
+ },
+ };
+
+ function CustomPluginHarness() {
+ const rowStatus = useTableRowStatus<Row>({getStatus});
+ const plugins = customFirst
+ ? {customPlugin, rowStatus}
+ : {rowStatus, customPlugin};
+ return (
+ <Table data={data} columns={columns} idKey="id" plugins={plugins} />
+ );
+ }
+
+ it('follows the parent pipeline without dropping or duplicating columns', () => {
+ render(<CustomPluginHarness />);
+
+ expect(
+ screen
+ .getAllByRole('columnheader')
+ .map(header => header.getAttribute('data-column-key')),
+ ).toEqual(expectedColumnKeys);
+ expect(
+ screen.getAllByRole('img', {name: /Error|Warning/}),
+ ).toHaveLength(2);
+ expect(screen.getByText('a')).toBeInTheDocument();
+ expect(screen.getByText('b')).toBeInTheDocument();
+ expect(screen.getByText('c')).toBeInTheDocument();
+ });
+ },
+ );
+
it('renders the status header with empty data and no indicators', () => {
render(<Harness rows={[]} />);
const header = screen.getByRole('columnheader', {name: 'Row status'});
+
expect(header).toHaveAttribute('data-column-key', '__rowStatus');
expect(screen.queryByRole('img')).not.toBeInTheDocument();
});
+
+ it('lets status win every untyped custom-marker conflict and warns once in development', () => {
+ const warning = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const theme = defineTheme({
+ name: 'table-row-status-conflict',
+ icons: {
+ error: <svg data-testid="conflict-semantic-error" />,
+ warning: <svg data-testid="conflict-semantic-warning" />,
+ success: <svg data-testid="conflict-semantic-success" />,
+ check: <svg data-testid="ignored-custom-check" />,
+ },
+ });
+
+ render(
+ <Theme theme={theme}>
+ <Harness
+ statusFn={item =>
+ (item.id === 'a'
+ ? {
+ status: 'error',
+ color: 'blue',
+ label: 'Status plus color',
+ }
+ : item.id === 'b'
+ ? {
+ status: 'warning',
+ icon: 'check',
+ label: 'Status plus icon',
+ }
+ : {
+ status: 'success',
+ color: 'red',
+ icon: 'check',
+ label: 'Status plus color and icon',
+ }) as unknown as TableRowStatusResult
+ }
+ />
+ </Theme>,
+ );
+
+ expect(screen.getByTestId('conflict-semantic-error')).toBeInTheDocument();
+ expect(screen.getByTestId('conflict-semantic-warning')).toBeInTheDocument();
+ expect(screen.getByTestId('conflict-semantic-success')).toBeInTheDocument();
+ expect(
+ screen.queryByTestId('ignored-custom-check'),
+ ).not.toBeInTheDocument();
+ const conflictWarnings = warning.mock.calls.filter(
+ ([message]) =>
+ message ===
+ 'useTableRowStatus: status cannot be combined with color or icon. The semantic status takes precedence and the custom marker fields are ignored.',
+ );
+ expect(conflictWarnings).toHaveLength(1);
+ });
+
+ it('uses the same status-wins fallback without warning in production', () => {
+ vi.stubEnv('NODE_ENV', 'production');
+ const warning = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const theme = defineTheme({
+ name: 'table-row-status-production-conflict',
+ icons: {
+ warning: <svg data-testid="production-semantic-warning" />,
+ check: <svg data-testid="production-ignored-check" />,
+ },
+ });
+ const mixedStatus = {
+ status: 'warning',
+ color: 'red',
+ icon: 'check',
+ label: 'Conflict',
+ } as unknown as TableRowStatusResult;
+
+ render(
+ <Theme theme={theme}>
+ <Harness statusFn={() => mixedStatus} />
+ </Theme>,
+ );
+
+ expect(screen.getAllByTestId('production-semantic-warning')).toHaveLength(
+ 3,
+ );
+ expect(
+ screen.queryByTestId('production-ignored-check'),
+ ).not.toBeInTheDocument();
+ const conflictWarnings = warning.mock.calls.filter(
+ ([message]) =>
+ message ===
+ 'useTableRowStatus: status cannot be combined with color or icon. The semantic status takes precedence and the custom marker fields are ignored.',
+ );
+ expect(conflictWarnings).toHaveLength(0);
+ });
+
+ it('uses the custom branch when an untyped status is unsupported', () => {
+ const warning = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const theme = defineTheme({
+ name: 'table-row-status-unsupported',
+ icons: {check: <svg data-testid="unsupported-custom-check" />},
+ });
+ const unsupportedStatus = {
+ status: 'info',
+ color: 'red',
+ icon: 'check',
+ label: 'Unsupported semantic, valid custom marker',
+ } as unknown as TableRowStatusResult;
+
+ render(
+ <Theme theme={theme}>
+ <Harness statusFn={() => unsupportedStatus} />
+ </Theme>,
+ );
+
+ const indicator = screen.getAllByRole('img', {
+ name: 'Unsupported semantic, valid custom marker',
+ })[0];
+ const unsupportedGlyph = screen.getAllByTestId(
+ 'unsupported-custom-check',
+ )[0];
+ expect(indicator).toContainElement(unsupportedGlyph);
+ expect(unsupportedGlyph.parentElement).toHaveAttribute('data-color', 'red');
+ const conflictWarnings = warning.mock.calls.filter(
+ ([message]) =>
+ message ===
+ 'useTableRowStatus: status cannot be combined with color or icon. The semantic status takes precedence and the custom marker fields are ignored.',
+ );
+ expect(conflictWarnings).toHaveLength(0);
+ });
});
diff --git a/packages/core/src/Table/plugins/rowStatus/useTableRowStatus.tsx b/packages/core/src/Table/plugins/rowStatus/useTableRowStatus.tsx
index b28b0a1031..a62a4d6ebc 100644
--- a/packages/core/src/Table/plugins/rowStatus/useTableRowStatus.tsx
+++ b/packages/core/src/Table/plugins/rowStatus/useTableRowStatus.tsx
@@ -4,12 +4,16 @@
/**
* @file useTableRowStatus.tsx
- * @input React, StyleX, Icon, i18n, VisuallyHidden, Table types
+ * @input React, StyleX, Icon, i18n, dev warnings, VisuallyHidden, Table types
* @output Exports useTableRowStatus hook + config type
* @position Row-status plugin; consumed by Table via plugins prop
*
* SYNC: When modified, update these files to stay in sync:
* - /packages/core/src/Table/index.ts (exports)
+ * - /packages/core/src/Table/useTableRowStatus.doc.mjs
+ * - /packages/core/src/Table/plugins/rowStatus/useTableRowStatus.test.tsx
+ * - /apps/storybook/stories/TableRowStatus.stories.tsx
+ * - /packages/cli/assets/templates/blocks/components/Table/TableRowStatusTable.tsx
*/
import {useMemo} from 'react';
@@ -17,12 +21,14 @@ import * as stylex from '@stylexjs/stylex';
import {Icon, type IconColor, type IconName} from '../../../Icon';
import {Tooltip} from '../../../Tooltip';
import {useTranslator} from '../../../i18n';
+import {warnOnce} from '../../../utils/devWarning';
import {VisuallyHidden} from '../../../VisuallyHidden';
+import type {TableRowStatus, TableSemanticRowStatus} from '../../index';
import type {TableColumn, TablePlugin} from '../../types';
/**
- * Semantic status colors, resolved to the design system's icon color tokens.
- * Prefer these over raw CSS so status colors stay consistent with the theme.
+ * Named colors supported by the custom row-status marker. These resolve to the
+ * design system's icon color tokens; raw CSS colors remain an escape hatch.
*/
export type TableRowStatusColor =
| 'accent'
@@ -36,7 +42,9 @@ export type TableRowStatusColor =
| 'blue'
| 'gray';
-const SEMANTIC_COLORS: Record<TableRowStatusColor, string> = {
+type TableRowSemanticStatus = TableSemanticRowStatus['status'];
+
+const NAMED_COLORS: Record<TableRowStatusColor, string> = {
accent: 'var(--color-icon-accent)',
success: 'var(--color-icon-green)',
error: 'var(--color-icon-red)',
@@ -49,8 +57,8 @@ const SEMANTIC_COLORS: Record<TableRowStatusColor, string> = {
gray: 'var(--color-icon-gray)',
};
-/** Icon colors that map cleanly from a semantic status color. */
-const ICON_COLOR_BY_STATUS: Record<TableRowStatusColor, IconColor> = {
+/** Preserve the released Icon color mapping for named custom-marker colors. */
+const ICON_COLOR_BY_NAMED_COLOR: Record<TableRowStatusColor, IconColor> = {
accent: 'accent',
success: 'success',
error: 'error',
@@ -63,43 +71,6 @@ const ICON_COLOR_BY_STATUS: Record<TableRowStatusColor, IconColor> = {
gray: 'gray',
};
-/**
- * Semantic statuses resolve through the theme-aware icon registry by default, so
- * a theme owns both their shape and color. Palette colors and raw CSS values do
- * not carry outcome semantics, so they retain the neutral dot unless the caller
- * provides an explicit icon.
- */
-const DEFAULT_ICON_BY_STATUS: Partial<Record<TableRowStatusColor, IconName>> = {
- success: 'success',
- error: 'error',
- warning: 'warning',
-};
-
-/**
- * A row's status indicator. Semantic status colors (`success`, `warning`,
- * `error`) resolve to the matching themed semantic icon by default. Palette
- * colors and raw CSS values retain the neutral dot because color alone cannot
- * establish an outcome glyph. Provide `icon` to override either default.
- * `label` is required so the status is never conveyed by color alone — it names
- * the indicator for assistive technology and shows on hover. Return `null` for
- * rows with no status.
- */
-export interface TableRowStatus {
- /** Semantic status color (preferred) or a raw CSS color string. */
- color: TableRowStatusColor | (string & {});
- /**
- * Optional icon override. Semantic status colors use their matching themed
- * icon by default; palette/raw colors use a dot.
- */
- icon?: IconName;
- /**
- * Accessible name for the status, announced to assistive technology and
- * shown in a tooltip on hover. Required: a status must never be conveyed by
- * color alone.
- */
- label: string;
-}
-
/** Configuration for {@link useTableRowStatus}. */
export interface UseTableRowStatusConfig<T extends Record<string, unknown>> {
/**
@@ -109,28 +80,99 @@ export interface UseTableRowStatusConfig<T extends Record<string, unknown>> {
* @example
* ```
* getStatus: row =>
- * row.hasError ? {color: 'error', icon: 'error', label: 'Error'} : null
+ * row.hasError ? {status: 'error', label: 'Error'} : null
* ```
*/
- getStatus: (item: T) => TableRowStatus | null;
+ getStatus: (
+ item: T,
+ ) => (TableRowStatus & {status?: never}) | TableSemanticRowStatus | null;
}
-// The status column holds a small centered dot (or an icon when provided).
-// A fixed narrow width keeps every row's indicator aligned in one gutter.
+type TableRowStatusResult = Exclude<
+ ReturnType<UseTableRowStatusConfig<Record<string, unknown>>['getStatus']>,
+ null
+>;
+
+// The status column holds a small centered dot or icon. A fixed narrow width
+// keeps every row's indicator aligned in one gutter.
const STATUS_COLUMN_WIDTH = {type: 'pixel' as const, value: 28};
-/** Resolve a semantic color name to a token, or pass a raw CSS color through. */
+/** Resolve a named color to a token, or pass a raw CSS color through. */
function resolveColor(color: string): string {
- return (SEMANTIC_COLORS as Record<string, string>)[color] ?? color;
+ return (NAMED_COLORS as Record<string, string>)[color] ?? color;
+}
+
+function isTableRowSemanticStatus(
+ value: unknown,
+): value is TableRowSemanticStatus {
+ return value === 'success' || value === 'warning' || value === 'error';
+}
+
+type ResolvedTableRowStatus =
+ | {variant: 'dot'; color: string}
+ | {variant: 'icon'; icon: IconName; iconColor: IconColor}
+ | {variant: 'icon'; icon: IconName; customColor: string};
+
+function resolveTableRowStatus(
+ value: TableRowStatusResult,
+): ResolvedTableRowStatus | null {
+ const untypedValue = value as {
+ status?: unknown;
+ color?: unknown;
+ icon?: unknown;
+ };
+
+ if (isTableRowSemanticStatus(untypedValue.status)) {
+ if (
+ process.env.NODE_ENV !== 'production' &&
+ (Object.prototype.hasOwnProperty.call(untypedValue, 'color') ||
+ Object.prototype.hasOwnProperty.call(untypedValue, 'icon'))
+ ) {
+ warnOnce(
+ 'useTableRowStatus:semantic-custom-conflict',
+ 'useTableRowStatus',
+ 'status cannot be combined with color or icon. The semantic status takes precedence and the custom marker fields are ignored.',
+ );
+ }
+
+ return {
+ variant: 'icon',
+ icon: untypedValue.status,
+ iconColor: untypedValue.status,
+ };
+ }
+
+ if (typeof untypedValue.color !== 'string') {
+ return null;
+ }
+
+ if (typeof untypedValue.icon === 'string') {
+ const namedIconColor = (
+ ICON_COLOR_BY_NAMED_COLOR as Record<string, IconColor | undefined>
+ )[untypedValue.color];
+ return namedIconColor == null
+ ? {
+ variant: 'icon',
+ icon: untypedValue.icon as IconName,
+ customColor: untypedValue.color,
+ }
+ : {
+ variant: 'icon',
+ icon: untypedValue.icon as IconName,
+ iconColor: namedIconColor,
+ };
+ }
+
+ return {variant: 'dot', color: resolveColor(untypedValue.color)};
}
const styles = stylex.create({
- // Centers the dot or icon within the narrow status column.
wrap: {
display: 'flex',
alignItems: 'center',
justifyContent: 'center',
},
+ customIcon: (color: string) => ({color}),
dot: (color: string) => ({
width: '8px',
height: '8px',
@@ -142,16 +184,16 @@ const styles = stylex.create({
/**
* Returns a {@link TablePlugin} that prepends a narrow column signaling per-row
- * status: a themed semantic icon for `success`, `warning`, and `error`; a
- * colored dot for palette/raw colors; or an explicit icon override.
+ * status. A semantic `status` resolves a themed glyph and tone; a custom
+ * `color` renders the stable dot unless the caller also provides an `icon`.
*
* @example
* ```
* const rowStatus = useTableRowStatus<Row>({
* getStatus: row =>
* row.state === 'error'
- * ? {color: 'error', icon: 'error', label: 'Error'}
- * : null,
+ * ? {status: 'error', label: 'Error'}
+ * : {color: 'blue', icon: 'info', label: 'Informational'},
* });
* <Table data={data} columns={columns} idKey="id" plugins={{rowStatus}} />;
* ```
@@ -162,55 +204,66 @@ export function useTableRowStatus<T extends Record<string, unknown>>(
const t = useTranslator();
const {getStatus} = config;
- return useMemo(
- (): TablePlugin<T> => ({
+ return useMemo((): TablePlugin<T> => {
+ const statusColumn: TableColumn<T> = {
+ key: '__rowStatus',
+ // The gutter stays visually blank, but the th needs a discernible
+ // name for assistive technology (axe: empty-table-header).
+ header: (
+ <VisuallyHidden>
+ {t('@astryx.table.rowStatus.columnHeader')}
+ </VisuallyHidden>
+ ),
+ width: STATUS_COLUMN_WIDTH,
+ resizable: false,
+ renderCell: (item: T) => {
+ const status = getStatus(item);
+ if (!status) {
+ return null;
+ }
+
+ const resolvedStatus = resolveTableRowStatus(status);
+ if (!resolvedStatus) {
+ return null;
+ }
+
+ const signifier =
+ resolvedStatus.variant === 'dot' ? (
+ <span {...stylex.props(styles.dot(resolvedStatus.color))} />
+ ) : (
+ <Icon
+ icon={resolvedStatus.icon}
+ size="xsm"
+ color={
+ 'iconColor' in resolvedStatus
+ ? resolvedStatus.iconColor
+ : 'inherit'
+ }
+ />
+ );
+
+ return (
+ <Tooltip content={status.label}>
+ <span
+ {...stylex.props(
+ styles.wrap,
+ resolvedStatus.variant === 'icon' &&
+ 'customColor' in resolvedStatus &&
+ styles.customIcon(resolvedStatus.customColor),
+ )}
+ role="img"
+ aria-label={status.label}>
+ {signifier}
+ </span>
+ </Tooltip>
+ );
+ },
+ };
+
+ return {
transformColumns(columns) {
- const statusColumn: TableColumn<T> = {
- key: '__rowStatus',
- // The gutter stays visually blank, but the th needs a discernible
- // name for assistive technology (axe: empty-table-header).
- header: (
- <VisuallyHidden>
- {t('@astryx.table.rowStatus.columnHeader')}
- </VisuallyHidden>
- ),
- width: STATUS_COLUMN_WIDTH,
- resizable: false,
- renderCell: (item: T) => {
- const status = getStatus(item);
- if (!status) {
- return null;
- }
- const icon =
- status.icon ??
- DEFAULT_ICON_BY_STATUS[status.color as TableRowStatusColor];
- const signifier = icon ? (
- <Icon
- icon={icon}
- size="xsm"
- color={
- ICON_COLOR_BY_STATUS[status.color as TableRowStatusColor] ??
- 'primary'
- }
- />
- ) : (
- <span {...stylex.props(styles.dot(resolveColor(status.color)))} />
- );
- return (
- <Tooltip content={status.label}>
- <span
- {...stylex.props(styles.wrap)}
- role="img"
- aria-label={status.label}>
- {signifier}
- </span>
- </Tooltip>
- );
- },
- };
return [statusColumn, ...columns];
},
- }),
- [getStatus, t],
- );
+ };
+ }, [getStatus, t]);
}
diff --git a/packages/core/src/Table/useTableRowStatus.doc.mjs b/packages/core/src/Table/useTableRowStatus.doc.mjs
index 4bafc6a782..25e7c2776a 100644
--- a/packages/core/src/Table/useTableRowStatus.doc.mjs
+++ b/packages/core/src/Table/useTableRowStatus.doc.mjs
@@ -7,13 +7,13 @@ export const docs = {
subComponentOf: 'Table',
displayName: 'useTableRowStatus',
description:
- 'Hook that returns a TablePlugin which prepends a narrow column signaling per-row status. Semantic status colors (success, warning, error) use the matching themed semantic icon by default; palette colors and raw CSS values use a colored dot because they do not establish an outcome glyph. getStatus may override either default with an explicit icon and must provide an accessible label (shown in a tooltip on hover and announced to assistive technology, so status is never color-only); return null for no indicator. The column header is visually blank but carries a screen-reader-only localized name ("Row status", i18n key @astryx.table.rowStatus.columnHeader). Memoize getStatus with useCallback for a stable plugin identity.',
+ 'Hook that returns a TablePlugin which prepends a narrow column signaling per-row status. Return {status, label} for a semantic success, warning, or error: Table resolves the matching glyph and tone through the active theme. Return {color, icon?, label} for a custom marker: every color is paint-only, an omitted icon renders the stable 8px dot, and an explicit icon renders that caller-selected glyph. Named custom icons keep their released Icon color mapping; raw CSS custom icons inherit the caller\'s exact paint instead of the previous primary fallback. Existing callers require no source migration. label is required and becomes the accessible image name plus supplemental hover tooltip; return null for no indicator. The column header is visually blank but carries a screen-reader-only localized name ("Row status", i18n key @astryx.table.rowStatus.columnHeader). Memoize getStatus with useCallback for a stable plugin identity.',
props: [
{
name: 'getStatus',
- type: "(item: T) => { color: 'accent' | 'success' | 'error' | 'warning' | 'red' | 'orange' | 'green' | 'yellow' | 'blue' | 'gray' | string; icon?: IconName; label: string } | null",
+ type: "(item: T) => ({ status: 'success' | 'warning' | 'error'; color?: never; icon?: never; label: string } | { status?: never; 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 (success, error, warning) uses its matching themed semantic icon by default; accent, palette colors (red, orange, green, yellow, blue, gray), and raw CSS use a dot unless icon overrides the signifier. Valid icon names: close, chevronDown, chevronLeft, chevronRight, chevronsLeft, chevronsRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone. label is required and is announced via role="img" and shown in a tooltip. Return null for rows with no status. Memoize with useCallback for a stable plugin identity.',
+ 'Derive either a semantic outcome or a custom marker. {status, label} accepts the closed success/error/warning vocabulary and resolves its glyph and tone through the active theme. {color, icon?, label} preserves the stable custom-marker path: color always selects paint, no icon renders an 8px dot, and icon renders the explicit caller glyph. Even color values named success/error/warning remain dots without icon. Valid icon names: close, chevronDown, chevronLeft, chevronRight, chevronsLeft, chevronsRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone. The branches are exclusive, label is required and announced via role="img", and null leaves the row status cell empty. Memoize with useCallback for a stable plugin identity.',
required: true,
},
],
@@ -22,9 +22,9 @@ export const docs = {
/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
export const docsDense = {
description:
- 'Returns a TablePlugin that prepends a narrow per-row status column. success/error/warning use the matching themed semantic icon by default; palette/raw colors use a dot unless icon overrides the signifier. label is required (tooltip + accessible name). Memoize getStatus with useCallback.',
+ 'Returns a TablePlugin with a narrow per-row status column. {status,label} resolves themed success/error/warning glyph + tone. Stable {color,icon?,label} stays custom: color is paint-only, no icon = 8px dot, icon = caller glyph. label is required; null leaves the cell empty. Memoize getStatus.',
propDescriptions: {
getStatus:
- 'Map a row to {color, icon?, label} or null. success/error/warning default to their themed semantic icon; palette/raw colors default to a dot; icon overrides either. label is required (tooltip + role="img"). Memoize with useCallback.',
+ 'Map a row to semantic {status,label}, custom {color,icon?,label}, or null. Semantic status owns themed glyph + tone. Custom color always owns paint; omitted icon = dot, explicit icon = caller glyph. Branches are exclusive and label is required.',
},
};