Skip to content

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.md
new file mode 100644
index 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".
+@bhamodi
diff --git a/packages/core/locales/en.json b/packages/core/locales/en.json
index 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.tsx
index 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.tsx
index 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')
+ }
isLabelHidden
value={isSelected}
onChange={() =>
diff --git a/packages/core/src/Table/useTableSelection.doc.mjs b/packages/core/src/Table/useTableSelection.doc.mjs
index 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.',
},
};