Adds new accessible <Loading /> component and accompanying docs (#272)

JDMathew · web-flow · commit 41f83f66c631 · 2025-01-19T18:36:14.000-08:00
* Add initial Loading component

* Add initial LoadingScreen

* Add LoadingScreens to example apps

* export AutofocusContainerProps from core

* Autofocus Loading

* Add Loading to home screen examples

* Added busy state to Loading Comp

* Add initial Loading Doc

* add style prop to Loading container style array

* Add zIndex to ensure absolute position height

* Update Loading docs

* Add `touchableContainerAccessibilityProps` workaround to Loading comp

* Added changesets

* bump version
diff --git a/.changeset/honest-shirts-guess.md b/.changeset/honest-shirts-guess.md
@@ -0,0 +1,5 @@
+---
+'@react-native-ama/extras': minor
+---
+
+Added new `<Loading />` component to `extras` package
diff --git a/.changeset/metal-poets-whisper.md b/.changeset/metal-poets-whisper.md
@@ -0,0 +1,5 @@
+---
+'@react-native-ama/core': patch
+---
+
+add export for `AutofocusContainerProps` type from `core` package
diff --git a/.changeset/sharp-mugs-poke.md b/.changeset/sharp-mugs-poke.md
@@ -0,0 +1,7 @@
+---
+'@examples/shared-ui': minor
+'amaexample': minor
+'ama-expo-example': minor
+---
+
+Added `<Loading />` component example screens
diff --git a/examples/bare/src/AppNavigator.tsx b/examples/bare/src/AppNavigator.tsx
@@ -9,6 +9,7 @@ import {
   FormScreen,
   Header,
   HomeScreen,
+  LoadingScreen,
   PressableScreen,
   SwitchListItemScreen,
   TextScreen,
@@ -195,6 +196,14 @@ export const AppNavigator = () => {
             headerTitle: () => <Header title={'Carousel Demo'} autofocus />,
           }}
         />
+        <Stack.Screen
+          name="Loading"
+          component={LoadingScreen}
+          options={{
+            headerLeft: () => <BackButton />,
+            headerTitle: () => <Header title={'Carousel Demo'} autofocus />,
+          }}
+        />
         <Stack.Screen
           name="UseTimedAction"
           component={UseTimedActionScreen}
@@ -245,6 +254,7 @@ type StackParamList = {
   FlatListStatic: undefined;
   BottomSheet: undefined;
   Carousel: undefined;
+  Loading: undefined;
   UseTimedAction: undefined;
   UseAMAContext: undefined;
 };
diff --git a/examples/expo/src/AppNavigation.tsx b/examples/expo/src/AppNavigation.tsx
@@ -9,6 +9,7 @@ import {
   FormScreen,
   Header,
   HomeScreen,
+  LoadingScreen,
   PressableScreen,
   SwitchListItemScreen,
   TextScreen,
@@ -195,6 +196,14 @@ export const AppNavigator = () => {
             headerTitle: () => <Header title={'Carousel Demo'} autofocus />,
           }}
         />
+        <Stack.Screen
+          name="Loading"
+          component={LoadingScreen}
+          options={{
+            headerLeft: () => <BackButton />,
+            headerTitle: () => <Header title={'Carousel Demo'} autofocus />,
+          }}
+        />
         <Stack.Screen
           name="UseTimedAction"
           component={UseTimedActionScreen}
@@ -245,6 +254,7 @@ type StackParamList = {
   FlatListStatic: undefined;
   BottomSheet: undefined;
   Carousel: undefined;
+  Loading: undefined;
   UseTimedAction: undefined;
   UseAMAContext: undefined;
 };
diff --git a/examples/shared/index.ts b/examples/shared/index.ts
@@ -7,6 +7,7 @@ export { Header } from './src/components/Header';
 export { Spacer } from './src/components/Spacer';
 
 // Screens
+export { LoadingScreen } from './src/screens/Loading.screen';
 export { CarouselScreen } from './src/screens/Carousel.screen';
 export { BottomSheetScreen } from './src/screens/BottomSheet.screen';
 export { ExpandablePressableScreen } from './src/screens/ExpandablePressableScreen';
diff --git a/examples/shared/package.json b/examples/shared/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@examples/shared-ui",
-  "version": "0.0.1",
+  "version": "1.0.1",
   "description": "Example Apps shared UI components",
   "private": true,
   "react-native": "index",
diff --git a/examples/shared/src/screens/Home.screen.tsx b/examples/shared/src/screens/Home.screen.tsx
@@ -57,6 +57,8 @@ export const HomeScreen = ({ navigation }) => {
         <Spacer height={'normal'} />
 
         <CTAPressable title="Carousel" onPress={() => navigate('Carousel')} />
+        <Spacer height={'normal'} />
+        <CTAPressable title="Loading" onPress={() => navigate('Loading')} />
 
         {/* */}
         <Spacer height={'big'} />
diff --git a/examples/shared/src/screens/Loading.screen.tsx b/examples/shared/src/screens/Loading.screen.tsx
@@ -0,0 +1,32 @@
+import { Loading } from '@react-native-ama/extras';
+import React from 'react';
+import { StyleSheet, View } from 'react-native';
+
+import { CTAPressable } from '../components/CTAPressable';
+import { theme } from '../theme';
+
+export const LoadingScreen = () => {
+  const [isLoading, setIsLoading] = React.useState(false);
+
+  const triggerLoading = () => {
+    setIsLoading(true);
+    setTimeout(() => {
+      setIsLoading(false);
+    }, 1500);
+  };
+
+  return (
+    <View style={styles.container}>
+      <Loading isLoading={isLoading} />
+      <CTAPressable title="Trigger Loading" onPress={triggerLoading} />
+    </View>
+  );
+};
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    paddingHorizontal: theme.padding.big,
+    paddingTop: theme.padding.big,
+  },
+});
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
@@ -1,5 +1,8 @@
 // Components
-export { AutofocusContainer } from './components/AutofocusContainer';
+export {
+  AutofocusContainer,
+  type AutofocusContainerProps,
+} from './components/AutofocusContainer';
 export {
   AMAProvider,
   useAMAContext,
diff --git a/packages/extras/docs/components/Loading.md b/packages/extras/docs/components/Loading.md
@@ -0,0 +1,32 @@
+import { Required } from '@site/src/components';
+
+# Loading
+
+AMA provides an accessible `<Loading ... />` component that auto focuses and announces the accessibility label and busy state. This component wraps the standard [React Native ActivityIndicator](https://reactnative.dev/docs/activityindicator).
+
+:::note
+The `Loading` component by default is absolutely positioned and will fill it's parents container. In the example below this would be the `<View>`. This behaviour can be overridden by the `Loading` components props. See props section below.
+:::
+
+:::tip
+Use the `Loading` component it as a top-level component in your screen while data is being fetched or as a replacement for sections of your screen that are loading to prevent accessibility users from interacting with data that is stale.
+:::
+
+## Example
+
+```tsx {2-15,22-23}
+import { Loading } from '@react-native-ama/extras';
+
+const Screen = () => {
+  const [isLoading, setIsLoading] = React.useState(false);
+
+  // fetch data and set loading state while fetching
+
+  return (
+    <View>
+      <Loading isLoading={isLoading} />
+      <ScreenContent />
+    </View>
+  );
+};
+```
diff --git a/packages/extras/src/components/Loading.tsx b/packages/extras/src/components/Loading.tsx
@@ -0,0 +1,73 @@
+import {
+  AutofocusContainer,
+  AutofocusContainerProps,
+} from '@react-native-ama/core';
+import * as React from 'react';
+import {
+  ActivityIndicator,
+  StyleProp,
+  StyleSheet,
+  Text,
+  ViewStyle,
+} from 'react-native';
+
+type Props = {
+  isLoading: boolean;
+  title?: string;
+  showTitle?: boolean;
+  style?: StyleProp<ViewStyle>;
+  containerProps?: Omit<AutofocusContainerProps, 'children'>;
+  activityIndicatorProps?: React.ComponentProps<typeof ActivityIndicator>;
+};
+
+export const Loading = ({
+  isLoading,
+  title,
+  style,
+  containerProps,
+  showTitle = true,
+  activityIndicatorProps,
+}: Props) => {
+  if (!isLoading) {
+    return null;
+  }
+  return (
+    <AutofocusContainer
+      style={[styles.container, style]}
+      accessibilityState={{ busy: true }}
+      accessibilityLabel={title ?? 'Loading'}
+      touchableContainerAccessibilityProps={{
+        accessibilityState: { busy: true }, // this is a workaround for the issue where the screen reader does not announce the loading state busy when accessibilityState is set on the accessible view
+      }}
+      {...containerProps}>
+      <ActivityIndicator
+        size="large"
+        style={styles.indicator}
+        {...activityIndicatorProps}
+      />
+      {showTitle ? (
+        <Text style={styles.text}>{title ?? 'Loading...'}</Text>
+      ) : null}
+    </AutofocusContainer>
+  );
+};
+
+const styles = StyleSheet.create({
+  container: {
+    position: 'absolute',
+    top: 0,
+    left: 0,
+    right: 0,
+    bottom: 0,
+    justifyContent: 'center',
+    alignItems: 'center',
+    zIndex: 100,
+  },
+  indicator: {
+    alignSelf: 'center',
+  },
+  text: {
+    marginTop: 10,
+    marginBottom: 40,
+  },
+});
diff --git a/packages/extras/src/index.ts b/packages/extras/src/index.ts
@@ -1,6 +1,7 @@
 // Components
 export { BottomSheet } from './components/BottomSheet';
 export { Carousel } from './components/Carousel';
+export { Loading } from './components/Loading';
 
 // Hooks
 export { useBottomSheetGestureHandler } from './hooks/useBottomSheetGestureHandler';

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'@react-native-ama/extras': minor
 +---
++
 +Added new `<Loading />` component to `extras` package
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@examples/shared-ui",`
`3`		`- "version": "0.0.1",`
	`3`	`+ "version": "1.0.1",`
`4`	`4`	`"description": "Example Apps shared UI components",`
`5`	`5`	`"private": true,`
`6`	`6`	`"react-native": "index",`