docs: update examples for better accessibility and add a11y docs section

microsoft · Dec 31, 2024 · 6906a8a · 6906a8a
1 parent bf1b91f
commit 6906a8a
Show file tree

Hide file tree

Showing 12 changed files with 59 additions and 11 deletions.
diff --git a/.../react-components/react-virtualizer/stories/src/VirtualizerScrollView/Default.stories.tsx b/.../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/...react-components/react-virtualizer/stories/src/VirtualizerScrollView/ScrollTo.stories.tsx b/...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/...omponents/react-virtualizer/stories/src/VirtualizerScrollView/SnapToAlignment.stories.tsx b/...omponents/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/...ualizer/stories/src/VirtualizerScrollView/VirtualizerScrollViewAccessibility.md b/...ualizer/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/...ges/react-components/react-virtualizer/stories/src/VirtualizerScrollView/index.stories.ts b/...ges/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/...onents/react-virtualizer/stories/src/VirtualizerScrollViewDynamic/AutoMeasure.stories.tsx b/...onents/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/...components/react-virtualizer/stories/src/VirtualizerScrollViewDynamic/Default.stories.tsx b/...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/...ents/react-virtualizer/stories/src/VirtualizerScrollViewDynamic/ScrollLoading.stories.tsx b/...ents/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/...omponents/react-virtualizer/stories/src/VirtualizerScrollViewDynamic/ScrollTo.stories.tsx b/...omponents/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/...ts/react-virtualizer/stories/src/VirtualizerScrollViewDynamic/SnapToAlignment.stories.tsx b/...ts/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/...s/src/VirtualizerScrollViewDynamic/VirtualizerScrollViewDynamicAccessibility.md b/...s/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/...ct-components/react-virtualizer/stories/src/VirtualizerScrollViewDynamic/index.stories.ts b/...ct-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'),
       },
     },
   },
Original file line number	Diff line number	Diff line change
		@@ -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.