feat: structural accessibility for data table

docs/6.x/docs/guides/migration.md

@@ -428,6 +428,146 @@ const theme = {
 />
 ```
 
+### DataTable
+
+The Paper 6.x `DataTable` adds table semantics. The structure it produces and the accessible names it exposes have both changed. Existing tables should still be working.
+
+#### Touch handling
+
+Rows, cells and titles with no touch handler render a plain `View` instead of a disabled touchable
+
+```tsx
+// Before (v5): announced as a disabled control
+<DataTable.Row>
+  <DataTable.Cell>{item.name}</DataTable.Cell>
+</DataTable.Row>
+
+// After (v6): pass a handler if the row is meant to be pressable
+<DataTable.Row onPress={() => select(item)}>
+  <DataTable.Cell>{item.name}</DataTable.Cell>
+</DataTable.Row>
+```
+
+On the web, a pressable row is clickable but is no longer a Tab stop, because a table row cannot also be a button. Put a control in a cell so keyboard and screen reader users can reach the action:
+
+```tsx
+<DataTable.Row onPress={() => toggle(item)}>
+  <DataTable.Cell column="selected">
+    <Checkbox
+      status={selected ? 'checked' : 'unchecked'}
+      onPress={() => toggle(item)}
+      aria-label={`Select ${item.name}`}
+    />
+  </DataTable.Cell>
+  <DataTable.Cell column="name">{item.name}</DataTable.Cell>
+</DataTable.Row>
+```
+
+Pass `tabIndex={0}` on the row to keep it a Tab stop anyway.
+
+#### Screen reader announcements
+
+- new `rowCount` on the table and `index` on each row give the row positions. On a page of a larger set, `index` counts from the start of the whole set
+- new `hasHeader` defaults to `true`. Pass `hasHeader={false}` for a table without a `DataTable.Header`, or every row position on the web is one too high
+- on iOS and Android, a cell is announced with the title of its column, matched by `column`
+- `nativeFocusMode="cell"` gives one stop per cell instead of one per row
+- `accessible={false}` on a row opts that row out
+- `formatRowPosition` replaces the wording, or removes it with `null`
+- the table does not count its children, so rows in a `View`, a fragment or a component of your own get the same position as inline rows
+
+```tsx
+// Before (v5)
+<DataTable>
+  {items.slice(from, to).map((item) => (
+    <DataTable.Row key={item.key}>{/* ... */}</DataTable.Row>
+  ))}
+</DataTable>
+
+// After (v6)
+<DataTable aria-label="Nutrition" rowCount={items.length}>
+  {items.slice(from, to).map((item, i) => (
+    <DataTable.Row key={item.key} index={from + i}>
+      {/* ... */}
+    </DataTable.Row>
+  ))}
+</DataTable>
+```
+
+#### Pagination labels
+
+- `labels` is new, and localizes every control
+- `aria-label="pagination-container"` and `aria-label="Options Select"` were removed: reach the controls by role or text, e.g. `getByRole('button', { name: 'Rows per page, 2' })`
+
+```tsx
+// After (v6)
+<DataTable.Pagination
+  labels={{
+    container: 'Paginacja',
+    previousPage: 'Poprzednia strona',
+    nextPage: 'Następna strona',
+    pageStatus: ({ page, numberOfPages }) =>
+      `Strona ${page} z ${numberOfPages}`,
+  }}
+  /* ... */
+/>
+```
+
+#### Alignment
+
+- `numeric` is unchanged, and now also applies tabular figures
+- `align` is new, accepts `'start'`, `'center'`, `'end'`
+
+```tsx
+// Before (v5): right-aligned
+<DataTable.Cell numeric>{item.calories}</DataTable.Cell>
+
+// After (v6): right-aligned, plus lined-up digits
+<DataTable.Cell numeric>{item.calories}</DataTable.Cell>
+
+// Centred, still with lined-up digits
+<DataTable.Cell numeric align="center">{item.calories}</DataTable.Cell>
+
+// Right-aligned text that is not numeric
+<DataTable.Cell align="end">{item.status}</DataTable.Cell>
+```
+
+`align` defaults to `'end'` for numeric columns and `'start'` otherwise.
+
+#### Text wrapping
+
+- **single line, always** → single line at the default font scale, unclamped above it
+- `numberOfLines` is honoured exactly at every font scale; pass `0` to never clamp
+
+#### Column definitions
+
+- `columns` on `DataTable` is new and optional
+- `column` on a title or cell selects a column by key, and is required when the table has `columns`
+
+```tsx
+// Before (v5)
+const styles = StyleSheet.create({ first: { flex: 2 } });
+
+<DataTable.Title style={styles.first}>Dessert</DataTable.Title>
+<DataTable.Cell style={styles.first}>{item.name}</DataTable.Cell>
+
+// After (v6)
+const columns = [
+  { key: 'name', flex: 2 },
+  { key: 'calories', numeric: true },
+];
+
+<DataTable columns={columns}>
+  <DataTable.Header>
+    <DataTable.Title column="name">Dessert</DataTable.Title>
+    <DataTable.Title column="calories">Calories</DataTable.Title>
+  </DataTable.Header>
+  <DataTable.Row>
+    <DataTable.Cell column="name">{item.name}</DataTable.Cell>
+    <DataTable.Cell column="calories">{item.calories}</DataTable.Cell>
+  </DataTable.Row>
+</DataTable>
+```
+
 ### Card
 
 #### `Card` layout

example/src/Examples/DataTableExample.tsx

@@ -1,7 +1,8 @@
 import * as React from 'react';
 import { StyleSheet } from 'react-native';
 
-import { DataTable, Card } from 'react-native-paper';
+import { Card, Checkbox, DataTable } from 'react-native-paper';
+import type { DataTableColumn } from 'react-native-paper';
 
 import ScreenWrapper from '../ScreenWrapper';
 
@@ -12,9 +13,21 @@ type ItemsState = Array<{
   fat: number;
 }>;
 
+// Declared once, outside the component: every title and cell reads its width
+// and alignment from here, and the reference has to stay stable.
+const columns: readonly DataTableColumn[] = [
+  { key: 'selected', width: 48 },
+  { key: 'name', flex: 2 },
+  { key: 'calories', numeric: true },
+  { key: 'fat', numeric: true },
+];
+
 const DataTableExample = () => {
   const [sortAscending, setSortAscending] = React.useState<boolean>(true);
   const [page, setPage] = React.useState<number>(0);
+  const [selected, setSelected] = React.useState<ReadonlySet<number>>(
+    () => new Set()
+  );
   const [items] = React.useState<ItemsState>([
     {
       key: 1,
@@ -71,29 +84,77 @@ const DataTableExample = () => {
     setPage(0);
   }, [itemsPerPage]);
 
+  const toggle = (key: number) =>
+    setSelected((previous) => {
+      const next = new Set(previous);
+
+      if (!next.delete(key)) {
+        next.add(key);
+      }
+
+      return next;
+    });
+
+  const allSelected = selected.size === items.length;
+
+  const toggleAll = () =>
+    setSelected(
+      allSelected ? new Set() : new Set(items.map((item) => item.key))
+    );
+
   return (
     <ScreenWrapper contentContainerStyle={styles.content}>
       <Card>
-        <DataTable>
+        <DataTable
+          aria-label="Nutrition"
+          columns={columns}
+          rowCount={sortedItems.length}
+        >
           <DataTable.Header>
+            <DataTable.Title column="selected" aria-label="Selected">
+              <Checkbox
+                status={
+                  allSelected
+                    ? 'checked'
+                    : selected.size > 0
+                      ? 'indeterminate'
+                      : 'unchecked'
+                }
+                onPress={toggleAll}
+                aria-label="Select all"
+              />
+            </DataTable.Title>
             <DataTable.Title
+              column="name"
               sortDirection={sortAscending ? 'ascending' : 'descending'}
               onPress={() => setSortAscending(!sortAscending)}
-              style={styles.first}
             >
               Dessert
             </DataTable.Title>
-            <DataTable.Title numberOfLines={2} numeric>
+            <DataTable.Title column="calories" numberOfLines={2}>
               Calories per piece
             </DataTable.Title>
-            <DataTable.Title numeric>Fat (g)</DataTable.Title>
+            <DataTable.Title column="fat">Fat (g)</DataTable.Title>
           </DataTable.Header>
 
-          {sortedItems.slice(from, to).map((item) => (
-            <DataTable.Row key={item.key}>
-              <DataTable.Cell style={styles.first}>{item.name}</DataTable.Cell>
-              <DataTable.Cell numeric>{item.calories}</DataTable.Cell>
-              <DataTable.Cell numeric>{item.fat}</DataTable.Cell>
+          {sortedItems.slice(from, to).map((item, i) => (
+            // The row is a pointer shortcut. On the web it is no Tab stop, so
+            // the checkbox is how keyboard and screen reader users select it.
+            <DataTable.Row
+              key={item.key}
+              index={from + i}
+              onPress={() => toggle(item.key)}
+            >
+              <DataTable.Cell column="selected">
+                <Checkbox
+                  status={selected.has(item.key) ? 'checked' : 'unchecked'}
+                  onPress={() => toggle(item.key)}
+                  aria-label={`Select ${item.name}`}
+                />
+              </DataTable.Cell>
+              <DataTable.Cell column="name">{item.name}</DataTable.Cell>
+              <DataTable.Cell column="calories">{item.calories}</DataTable.Cell>
+              <DataTable.Cell column="fat">{item.fat}</DataTable.Cell>
             </DataTable.Row>
           ))}
 
@@ -120,9 +181,6 @@ const styles = StyleSheet.create({
   content: {
     padding: 8,
   },
-  first: {
-    flex: 2,
-  },
 });
 
 export default DataTableExample;

src/components/Button/Button.tsx

@@ -90,6 +90,11 @@ export type Props = Omit<ViewProps, 'style'> & {
    * Accessibility role for the button. The "button" role is set by default.
    */
   role?: Role;
+  /**
+   * Whether the control the button opens is currently expanded. Set this when
+   * the button anchors a menu or another disclosure.
+   */
+  'aria-expanded'?: boolean;
   /**
    * Function to execute on press.
    */
@@ -171,6 +176,7 @@ const Button = ({
   textColor: customTextColor,
   children,
   'aria-label': ariaLabel,
+  'aria-expanded': ariaExpanded,
   accessibilityHint,
   role = 'button',
   hitSlop,
@@ -330,6 +336,7 @@ const Button = ({
         aria-label={ariaLabel}
         accessibilityHint={accessibilityHint}
         role={role}
+        aria-expanded={ariaExpanded}
         aria-disabled={disabled}
         accessible={accessible}
         hitSlop={hitSlop}