An open source design system that's fully customizable and agent ready
TypeScript
fix(core): per-row accessible names for Table selection checkboxes (#3997)
Baraa Hamodi80be94939c23
diff --git a/.changeset/table-selection-row-names.md b/.changeset/table-selection-row-names.mdnew file mode 100644index 0000000000..f9671e87c9--- /dev/null+++ b/.changeset/table-selection-row-names.md@@ -0,0 +1,6 @@+---+'@astryxdesign/core': patch+---++[fix] Table: the selection plugin accepts getRowLabel so row checkboxes announce which row they select, instead of an undifferentiated "Select row".+@bhamodidiff --git a/packages/core/locales/en.json b/packages/core/locales/en.jsonindex 79cc55c319..65c7d25e01 100644--- a/packages/core/locales/en.json+++ b/packages/core/locales/en.json@@ -411,6 +411,10 @@"defaultMessage": "Select row","description": "Aria label for the \"select row\" checkbox on a Table row."},+ "@astryx.table.selection.selectRowNamed": {+ "defaultMessage": "Select {label}",+ "description": "Aria label for a Table row's selection checkbox when a per-row label is available (via getRowLabel). `label` is the row's human-readable identity, e.g. \"Alice\"."+ },"@astryx.table.sort.ascending": {"defaultMessage": "Sort ascending","description": "Screen-reader-only label on a column header button that will sort the column ascending. Part of a set with `sort.descending` and `sort.clear` — keep parallel."diff --git a/packages/core/src/Table/plugins/selection/useTableSelection.test.tsx b/packages/core/src/Table/plugins/selection/useTableSelection.test.tsxindex 381be6b8e5..8d14f4cc5e 100644--- a/packages/core/src/Table/plugins/selection/useTableSelection.test.tsx+++ b/packages/core/src/Table/plugins/selection/useTableSelection.test.tsx@@ -40,9 +40,11 @@ const selectableColumns: TableColumn<SelectableUser>[] = [function SelectionTable({getIsItemSelectable,getIsItemEnabled,+ getRowLabel,}: {getIsItemSelectable?: (item: SelectableUser) => boolean;getIsItemEnabled?: (item: SelectableUser) => boolean;+ getRowLabel?: (item: SelectableUser) => string;}) {const [selectedKeys, setSelectedKeys] = useState<Set<string>>(new Set());@@ -75,6 +77,7 @@ function SelectionTable({},getIsItemSelectable,getIsItemEnabled,+ getRowLabel,});return (@@ -109,6 +112,19 @@ describe('useTableSelection', () => {expect(rowCheckboxes).toHaveLength(3);});+ it('derives per-row accessible names from getRowLabel', () => {+ render(<SelectionTable getRowLabel={item => item.name} />);+ expect(screen.getByLabelText('Select Alice')).toBeInTheDocument();+ expect(screen.getByLabelText('Select Bob')).toBeInTheDocument();+ expect(screen.getByLabelText('Select Charlie')).toBeInTheDocument();+ expect(screen.queryByLabelText('Select row')).not.toBeInTheDocument();+ });++ it('keeps the "Select all rows" header label when getRowLabel is provided', () => {+ render(<SelectionTable getRowLabel={item => item.name} />);+ expect(screen.getByLabelText('Select all rows')).toBeInTheDocument();+ });+it('toggles individual row selection on click', async () => {const user = userEvent.setup();render(<SelectionTable />);diff --git a/packages/core/src/Table/plugins/selection/useTableSelection.tsx b/packages/core/src/Table/plugins/selection/useTableSelection.tsxindex c0beb02e1a..e61909e335 100644--- a/packages/core/src/Table/plugins/selection/useTableSelection.tsx+++ b/packages/core/src/Table/plugins/selection/useTableSelection.tsx@@ -68,6 +68,18 @@ export interface UseTableSelectionConfig<T extends Record<string, unknown>> {getIsItemSelectable?: (item: T) => boolean;/** Is this row's checkbox interactive? Disabled rows show disabled checkbox. @default () => true */getIsItemEnabled?: (item: T) => boolean;+ /**+ * Derive a human-readable identity for a row, used in the row checkbox's+ * hidden label as `Select ${getRowLabel(item)}`. Without it, every row+ * checkbox announces an undifferentiated "Select row" to screen readers.+ *+ * @example+ * ```+ * getRowLabel: item => item.name+ * // Checkbox accessible names: "Select Alice", "Select Bob", ...+ * ```+ */+ getRowLabel?: (item: T) => string;}// =============================================================================@@ -235,6 +247,7 @@ function SelectionCellContentInner<T extends Record<string, unknown>>({const isSelected = useIsItemSelected(store, item);const selectable = config.getIsItemSelectable?.(item) ?? true;const enabled = config.getIsItemEnabled?.(item) ?? true;+ const rowLabel = config.getRowLabel?.(item);if (!selectable) {return null;@@ -242,7 +255,11 @@ function SelectionCellContentInner<T extends Record<string, unknown>>({return (<CheckboxInput- label={t('@astryx.table.selection.selectRow')}+ label={+ rowLabel != null+ ? t('@astryx.table.selection.selectRowNamed', {label: rowLabel})+ : t('@astryx.table.selection.selectRow')+ }isLabelHiddenvalue={isSelected}onChange={() =>diff --git a/packages/core/src/Table/useTableSelection.doc.mjs b/packages/core/src/Table/useTableSelection.doc.mjsindex b110fe8015..fd564aef06 100644--- a/packages/core/src/Table/useTableSelection.doc.mjs+++ b/packages/core/src/Table/useTableSelection.doc.mjs@@ -6,7 +6,8 @@ export const docs = {name: 'useTableSelection',subComponentOf: 'Table',displayName: 'useTableSelection',- description: 'Hook that returns a TablePlugin implementing row selection with checkboxes, select-all, and aria-selected. Uses React Context for independent checkbox re-renders.',+ description:+ 'Hook that returns a TablePlugin implementing row selection with checkboxes, select-all, and aria-selected. Uses React Context for independent checkbox re-renders.',props: [{name: 'getIsItemSelected',@@ -17,7 +18,8 @@ export const docs = {{name: 'onSelectItem',type: '(event: {item: T; isSelected: boolean}) => void',- description: 'Called when a row checkbox is toggled. isSelected is the new desired state.',+ description:+ 'Called when a row checkbox is toggled. isSelected is the new desired state.',required: true,},{@@ -29,33 +31,67 @@ export const docs = {{name: 'getIsAllSelected',type: '() => boolean',- description: 'Returns whether all selectable items are currently selected.',+ description:+ 'Returns whether all selectable items are currently selected.',required: true,},{name: 'getIsIndeterminate',type: '() => boolean',- description: 'Returns whether selection is partial (some but not all). Renders the select-all checkbox in indeterminate state.',+ description:+ 'Returns whether selection is partial (some but not all). Renders the select-all checkbox in indeterminate state.',},{name: 'getIsItemSelectable',type: '(item: T) => boolean',- description: 'Returns whether a row should show a checkbox. Non-selectable rows render nothing in the selection cell.',+ description:+ 'Returns whether a row should show a checkbox. Non-selectable rows render nothing in the selection cell.',default: '() => true',},{name: 'getIsItemEnabled',type: '(item: T) => boolean',- description: 'Returns whether a row checkbox is interactive. Disabled rows show a disabled checkbox.',+ description:+ 'Returns whether a row checkbox is interactive. Disabled rows show a disabled checkbox.',default: '() => true',},+ {+ name: 'getRowLabel',+ type: '(item: T) => string',+ description:+ 'Derives a human-readable identity for a row; the row checkbox\'s hidden label becomes `Select ${getRowLabel(item)}` so screen readers announce which row each checkbox selects. Falls back to "Select row" when omitted.',+ },+ ],+ examples: [+ {+ label: 'Accessible per-row checkbox names',+ code: `+const selectionPlugin = useTableSelection({+ getIsItemSelected: item => selectedIds.has(item.id),+ onSelectItem: ({item, isSelected}) => toggle(item.id, isSelected),+ onSelectAll: ({isAllSelected}) => selectAll(isAllSelected),+ getIsAllSelected: () => selectedIds.size === users.length,+ // Screen readers announce "Select Alice", "Select Bob", ...+ // instead of an undifferentiated "Select row" for every checkbox.+ getRowLabel: item => item.name,+});++<Table+ data={users}+ columns={columns}+ idKey="id"+ plugins={{selection: selectionPlugin}}+/>;+`,+ },],};export const docsZh = {name: 'useTableSelection',displayName: 'useTableSelection',- description: '返回 TablePlugin 的 Hook,实现带复选框、全选和 aria-selected 的行选择功能。使用 React Context 实现独立的复选框重新渲染。',+ description:+ '返回 TablePlugin 的 Hook,实现带复选框、全选和 aria-selected 的行选择功能。使用 React Context 实现独立的复选框重新渲染。',props: [{name: 'getIsItemSelected',@@ -84,12 +120,14 @@ export const docsZh = {{name: 'getIsIndeterminate',type: '() => boolean',- description: '返回选择是否为部分选中(部分但非全部)。将全选复选框渲染为不确定状态。',+ description:+ '返回选择是否为部分选中(部分但非全部)。将全选复选框渲染为不确定状态。',},{name: 'getIsItemSelectable',type: '(item: T) => boolean',- description: '返回行是否应显示复选框。不可选择的行在选择单元格中不渲染任何内容。',+ description:+ '返回行是否应显示复选框。不可选择的行在选择单元格中不渲染任何内容。',default: '() => true',},{@@ -98,20 +136,33 @@ export const docsZh = {description: '返回行复选框是否可交互。禁用的行显示禁用状态的复选框。',default: '() => true',},+ {+ name: 'getRowLabel',+ type: '(item: T) => string',+ description:+ '为行派生人类可读的标识;行复选框的隐藏标签变为 `Select ${getRowLabel(item)}`,让屏幕阅读器播报每个复选框选择的是哪一行。省略时回退为 "Select row"。',+ },],};export const docsDense = {name: 'useTableSelection',displayName: 'useTableSelection',- description: 'Hook returning TablePlugin for row selection w/ checkboxes, select-all, aria-selected. Uses React Context for independent checkbox re-renders.',+ description:+ 'Hook returning TablePlugin for row selection w/ checkboxes, select-all, aria-selected. Uses React Context for independent checkbox re-renders.',propDescriptions: {getIsItemSelected: 'Returns whether item is selected.',- onSelectItem: 'Called on row checkbox toggle; isSelected = new desired state.',+ onSelectItem:+ 'Called on row checkbox toggle; isSelected = new desired state.',onSelectAll: 'Called on select-all header checkbox toggle.',getIsAllSelected: 'Returns whether all selectable items are selected.',- getIsIndeterminate: 'Returns partial selection state; renders indeterminate checkbox.',- getIsItemSelectable: 'Returns whether row shows checkbox; non-selectable rows render nothing.',- getIsItemEnabled: 'Returns whether row checkbox is interactive; disabled rows show disabled checkbox.',+ getIsIndeterminate:+ 'Returns partial selection state; renders indeterminate checkbox.',+ getIsItemSelectable:+ 'Returns whether row shows checkbox; non-selectable rows render nothing.',+ getIsItemEnabled:+ 'Returns whether row checkbox is interactive; disabled rows show disabled checkbox.',+ getRowLabel:+ 'Derives row identity for the checkbox\'s hidden label: `Select ${getRowLabel(item)}`. Falls back to "Select row" when omitted.',},};