From 6906a8aca99e8cb5f1dba99a6de1bfe9b6db3de1 Mon Sep 17 00:00:00 2001
From: Sarah Higley <sarah.higley@microsoft.com>
Date: Tue, 31 Dec 2024 12:23:12 -0800
Subject: [PATCH] docs: update examples for better accessibility and add a11y
 docs section

---
 .../src/VirtualizerScrollView/Default.stories.tsx        | 7 ++++++-
 .../src/VirtualizerScrollView/ScrollTo.stories.tsx       | 7 ++++++-
 .../VirtualizerScrollView/SnapToAlignment.stories.tsx    | 7 ++++++-
 .../VirtualizerScrollViewAccessibility.md                | 3 +++
 .../stories/src/VirtualizerScrollView/index.stories.ts   | 3 ++-
 .../VirtualizerScrollViewDynamic/AutoMeasure.stories.tsx | 7 ++++++-
 .../src/VirtualizerScrollViewDynamic/Default.stories.tsx | 7 ++++++-
 .../ScrollLoading.stories.tsx                            | 7 ++++++-
 .../VirtualizerScrollViewDynamic/ScrollTo.stories.tsx    | 9 +++++++--
 .../SnapToAlignment.stories.tsx                          | 7 ++++++-
 .../VirtualizerScrollViewDynamicAccessibility.md         | 3 +++
 .../src/VirtualizerScrollViewDynamic/index.stories.ts    | 3 ++-
 12 files changed, 59 insertions(+), 11 deletions(-)
 create mode 100644 packages/react-components/react-virtualizer/stories/src/VirtualizerScrollView/VirtualizerScrollViewAccessibility.md
 create mode 100644 packages/react-components/react-virtualizer/stories/src/VirtualizerScrollViewDynamic/VirtualizerScrollViewDynamicAccessibility.md

diff --git a/packages/react-components/react-virtualizer/stories/src/VirtualizerScrollView/Default.stories.tsx b/packages/react-components/react-virtualizer/stories/src/VirtualizerScrollView/Default.stories.tsx
index b3253bb6930ee9..cd501df2b69156 100644
--- a/packages/react-components/react-virtualizer/stories/src/VirtualizerScrollView/Default.stories.tsx
+++ b/packages/react-components/react-virtualizer/stories/src/VirtualizerScrollView/Default.stories.tsx
@@ -18,7 +18,12 @@ export const Default = () => {
     <VirtualizerScrollView
       numItems={childLength}
       itemSize={100}
-      container={{ role: 'list', style: { maxHeight: '80vh' } }}
+      container={{
+        role: 'list',
+        'aria-label': `Virtualized list with ${childLength} children`,
+        tabIndex: 0,
+        style: { maxHeight: '80vh' },
+      }}
     >
       {(index: number) => {
         return (
diff --git a/packages/react-components/react-virtualizer/stories/src/VirtualizerScrollView/ScrollTo.stories.tsx b/packages/react-components/react-virtualizer/stories/src/VirtualizerScrollView/ScrollTo.stories.tsx
index bc5bcd0bcf1837..d9a9a58cb8f1b6 100644
--- a/packages/react-components/react-virtualizer/stories/src/VirtualizerScrollView/ScrollTo.stories.tsx
+++ b/packages/react-components/react-virtualizer/stories/src/VirtualizerScrollView/ScrollTo.stories.tsx
@@ -42,7 +42,12 @@ export const ScrollTo = () => {
       <VirtualizerScrollView
         numItems={childLength}
         itemSize={100}
-        container={{ role: 'list', style: { maxHeight: '80vh' } }}
+        container={{
+          role: 'list',
+          'aria-label': `Virtualized list with ${childLength} children`,
+          tabIndex: 0,
+          style: { maxHeight: '80vh' },
+        }}
         imperativeRef={scrollRef}
       >
         {(index: number) => {
diff --git a/packages/react-components/react-virtualizer/stories/src/VirtualizerScrollView/SnapToAlignment.stories.tsx b/packages/react-components/react-virtualizer/stories/src/VirtualizerScrollView/SnapToAlignment.stories.tsx
index cb1621b11c55b7..40ef03e4dab4ee 100644
--- a/packages/react-components/react-virtualizer/stories/src/VirtualizerScrollView/SnapToAlignment.stories.tsx
+++ b/packages/react-components/react-virtualizer/stories/src/VirtualizerScrollView/SnapToAlignment.stories.tsx
@@ -24,7 +24,12 @@ export const SnapToAlignment = () => {
       numItems={childLength}
       itemSize={100}
       axis={'horizontal'}
-      container={{ role: 'list', className: styles.container }}
+      container={{
+        role: 'list',
+        'aria-label': `Virtualized list with ${childLength} children`,
+        tabIndex: 0,
+        className: styles.container,
+      }}
       enablePagination
     >
       {(index: number) => {
diff --git a/packages/react-components/react-virtualizer/stories/src/VirtualizerScrollView/VirtualizerScrollViewAccessibility.md b/packages/react-components/react-virtualizer/stories/src/VirtualizerScrollView/VirtualizerScrollViewAccessibility.md
new file mode 100644
index 00000000000000..c6ac70514fc04a
--- /dev/null
+++ b/packages/react-components/react-virtualizer/stories/src/VirtualizerScrollView/VirtualizerScrollViewAccessibility.md
@@ -0,0 +1,3 @@
+## Accessibility
+
+When the ScrollView has no focusable children, the container itself should be given `tabIndex: 0` so that it can be scrolled with the keyboard. If it does contain focusable descendants, this is not necessary.
diff --git a/packages/react-components/react-virtualizer/stories/src/VirtualizerScrollView/index.stories.ts b/packages/react-components/react-virtualizer/stories/src/VirtualizerScrollView/index.stories.ts
index 9114b2abdc3538..0110a824b0ee40 100644
--- a/packages/react-components/react-virtualizer/stories/src/VirtualizerScrollView/index.stories.ts
+++ b/packages/react-components/react-virtualizer/stories/src/VirtualizerScrollView/index.stories.ts
@@ -1,5 +1,6 @@
 import { VirtualizerScrollView } from '@fluentui/react-virtualizer';
 import descriptionMd from './VirtualizerScrollViewDescription.md';
+import accessibilityMd from './VirtualizerScrollViewAccessibility.md';
 
 export { Default } from './Default.stories';
 export { ScrollTo } from './ScrollTo.stories';
@@ -11,7 +12,7 @@ export default {
   parameters: {
     docs: {
       description: {
-        component: [descriptionMd].join('\n'),
+        component: [descriptionMd, accessibilityMd].join('\n'),
       },
     },
   },
diff --git a/packages/react-components/react-virtualizer/stories/src/VirtualizerScrollViewDynamic/AutoMeasure.stories.tsx b/packages/react-components/react-virtualizer/stories/src/VirtualizerScrollViewDynamic/AutoMeasure.stories.tsx
index a8e6587a149f12..74d1144e1a7052 100644
--- a/packages/react-components/react-virtualizer/stories/src/VirtualizerScrollViewDynamic/AutoMeasure.stories.tsx
+++ b/packages/react-components/react-virtualizer/stories/src/VirtualizerScrollViewDynamic/AutoMeasure.stories.tsx
@@ -37,7 +37,12 @@ export const AutoMeasure = () => {
       numItems={childLength}
       // We can use itemSize to set average height and reduce unknown whitespace
       itemSize={minHeight + maxHeightIncrease / 2.0 + 100}
-      container={{ role: 'list', style: { maxHeight: '80vh', gap: '20px' } }}
+      container={{
+        role: 'list',
+        'aria-label': `Virtualized list with ${childLength} children`,
+        tabIndex: 0,
+        style: { maxHeight: '80vh', gap: '20px' },
+      }}
       bufferItems={1}
       bufferSize={minHeight / 2.0}
       gap={20}
diff --git a/packages/react-components/react-virtualizer/stories/src/VirtualizerScrollViewDynamic/Default.stories.tsx b/packages/react-components/react-virtualizer/stories/src/VirtualizerScrollViewDynamic/Default.stories.tsx
index c5f241979527fd..ecd85ebe39d1cb 100644
--- a/packages/react-components/react-virtualizer/stories/src/VirtualizerScrollViewDynamic/Default.stories.tsx
+++ b/packages/react-components/react-virtualizer/stories/src/VirtualizerScrollViewDynamic/Default.stories.tsx
@@ -42,7 +42,12 @@ export const Default = () => {
       numItems={childLength}
       itemSize={minHeight + maxHeightMod / 2.0}
       getItemSize={getItemSizeCallback}
-      container={{ role: 'list', style: { maxHeight: '80vh' } }}
+      container={{
+        role: 'list',
+        'aria-label': `Virtualized list with ${childLength} children`,
+        tabIndex: 0,
+        style: { maxHeight: '80vh' },
+      }}
       bufferItems={1}
       bufferSize={minHeight / 2.0}
     >
diff --git a/packages/react-components/react-virtualizer/stories/src/VirtualizerScrollViewDynamic/ScrollLoading.stories.tsx b/packages/react-components/react-virtualizer/stories/src/VirtualizerScrollViewDynamic/ScrollLoading.stories.tsx
index 423c9b3a4e8003..5a3d38ff980bbe 100644
--- a/packages/react-components/react-virtualizer/stories/src/VirtualizerScrollViewDynamic/ScrollLoading.stories.tsx
+++ b/packages/react-components/react-virtualizer/stories/src/VirtualizerScrollViewDynamic/ScrollLoading.stories.tsx
@@ -41,7 +41,12 @@ export const ScrollLoading = () => {
       numItems={childLength}
       itemSize={minHeight}
       getItemSize={getItemSizeCallback}
-      container={{ role: 'list', style: { maxHeight: '80vh' } }}
+      container={{
+        role: 'list',
+        'aria-label': `Virtualized list with ${childLength} children`,
+        tabIndex: 0,
+        style: { maxHeight: '80vh' },
+      }}
       enableScrollLoad={true}
     >
       {(index: number, isScrolling = false) => {
diff --git a/packages/react-components/react-virtualizer/stories/src/VirtualizerScrollViewDynamic/ScrollTo.stories.tsx b/packages/react-components/react-virtualizer/stories/src/VirtualizerScrollViewDynamic/ScrollTo.stories.tsx
index 94904d936c80d2..3d903cf42b9e42 100644
--- a/packages/react-components/react-virtualizer/stories/src/VirtualizerScrollViewDynamic/ScrollTo.stories.tsx
+++ b/packages/react-components/react-virtualizer/stories/src/VirtualizerScrollViewDynamic/ScrollTo.stories.tsx
@@ -62,14 +62,19 @@ export const ScrollTo = () => {
     <div>
       <Input defaultValue={'0'} onChange={onChangeGoToIndex} />
       <Button onClick={scrollToIndex}>{'GoTo'}</Button>
-      <Text>{message}</Text>
+      <Text aria-live="polite">{message}</Text>
       <VirtualizerScrollViewDynamic
         numItems={childLength}
         itemSize={100}
         getItemSize={getItemSizeCallback}
         imperativeRef={scrollRef}
         imperativeVirtualizerRef={sizeRef}
-        container={{ role: 'list', style: { maxHeight: '80vh' } }}
+        container={{
+          role: 'list',
+          'aria-label': `Virtualized list with ${childLength} children`,
+          tabIndex: 0,
+          style: { maxHeight: '80vh' },
+        }}
       >
         {(index: number) => {
           const backgroundColor = index % 2 ? '#FFFFFF' : '#ABABAB';
diff --git a/packages/react-components/react-virtualizer/stories/src/VirtualizerScrollViewDynamic/SnapToAlignment.stories.tsx b/packages/react-components/react-virtualizer/stories/src/VirtualizerScrollViewDynamic/SnapToAlignment.stories.tsx
index ab593c20e09b2a..cf64b832489c5b 100644
--- a/packages/react-components/react-virtualizer/stories/src/VirtualizerScrollViewDynamic/SnapToAlignment.stories.tsx
+++ b/packages/react-components/react-virtualizer/stories/src/VirtualizerScrollViewDynamic/SnapToAlignment.stories.tsx
@@ -32,7 +32,12 @@ export const SnapToAlignment = () => {
       numItems={childLength}
       // We can use itemSize to set an average height for minimal size change impact
       itemSize={minHeight + maxHeightIncrease / 2}
-      container={{ role: 'list', style: { maxHeight: '80vh' } }}
+      container={{
+        role: 'list',
+        'aria-label': `Virtualized list with ${childLength} children`,
+        tabIndex: 0,
+        style: { maxHeight: '80vh' },
+      }}
       enablePagination
     >
       {(index: number) => {
diff --git a/packages/react-components/react-virtualizer/stories/src/VirtualizerScrollViewDynamic/VirtualizerScrollViewDynamicAccessibility.md b/packages/react-components/react-virtualizer/stories/src/VirtualizerScrollViewDynamic/VirtualizerScrollViewDynamicAccessibility.md
new file mode 100644
index 00000000000000..c6ac70514fc04a
--- /dev/null
+++ b/packages/react-components/react-virtualizer/stories/src/VirtualizerScrollViewDynamic/VirtualizerScrollViewDynamicAccessibility.md
@@ -0,0 +1,3 @@
+## Accessibility
+
+When the ScrollView has no focusable children, the container itself should be given `tabIndex: 0` so that it can be scrolled with the keyboard. If it does contain focusable descendants, this is not necessary.
diff --git a/packages/react-components/react-virtualizer/stories/src/VirtualizerScrollViewDynamic/index.stories.ts b/packages/react-components/react-virtualizer/stories/src/VirtualizerScrollViewDynamic/index.stories.ts
index 9dee7b7a992166..7d9d6866dcdddf 100644
--- a/packages/react-components/react-virtualizer/stories/src/VirtualizerScrollViewDynamic/index.stories.ts
+++ b/packages/react-components/react-virtualizer/stories/src/VirtualizerScrollViewDynamic/index.stories.ts
@@ -1,5 +1,6 @@
 import { VirtualizerScrollViewDynamic } from '@fluentui/react-virtualizer';
 import descriptionMd from './VirtualizerScrollViewDynamicDescription.md';
+import accessibilityMd from './VirtualizerScrollViewDynamicAccessibility.md';
 
 export { AutoMeasure } from './AutoMeasure.stories';
 export { Default } from './Default.stories';
@@ -13,7 +14,7 @@ export default {
   parameters: {
     docs: {
       description: {
-        component: [descriptionMd].join('\n'),
+        component: [descriptionMd, accessibilityMd].join('\n'),
       },
     },
   },