@utilitywarehouse/hearth-react-native 0.6.0 → 0.8.0

package/src/components/Expandable/Expandable.docs.mdx

@@ -0,0 +1,201 @@
+import { Canvas, Controls, Meta } from '@storybook/addon-docs/blocks';
+import { BodyText, Button, Card, Center } from '../../';
+import { BackToTopButton, UsageWrap } from '../../../docs/components';
+import * as Stories from './Expandable.stories';
+
+<Meta title="Utility Components / Expandable" />
+
+<BackToTopButton />
+
+# Expandable
+
+The Expandable component is a primitive for creating expandable content with smooth animations. It's commonly used as a building block for components like accordions, collapsible sections, and other interactive content that needs to expand and collapse.
+
+- [Playground](#playground)
+- [Usage](#usage)
+- [Props](#props)
+- [Animation Duration](#animation-duration)
+- [Examples](#examples)
+  - [Basic Example](#basic-example)
+  - [With Different Animation Speeds](#with-different-animation-speeds)
+  - [Multiple Expandables](#multiple-expandables)
+  - [Controlled Example](#controlled-example)
+- [Accessibility](#accessibility)
+
+## Playground
+
+<Canvas of={Stories.Playground} />
+
+<Controls of={Stories.Playground} />
+
+## Usage
+
+<Canvas of={Stories.BasicExample} />
+
+```tsx
+import { useState } from 'react';
+import { View } from 'react-native';
+import { Expandable, Button, Card, BodyText } from '@utilitywarehouse/hearth-react-native';
+
+const MyComponent = () => {
+  const [expanded, setExpanded] = useState(false);
+
+  return (
+    <View>
+      <Button onPress={() => setExpanded(!expanded)}>Toggle Content</Button>
+      <Expandable expanded={expanded}>
+        <Card>
+          <BodyText>This content expands and collapses with a smooth animation.</BodyText>
+        </Card>
+      </Expandable>
+    </View>
+  );
+};
+```
+
+## Props
+
+| Prop                 | Type                          | Default | Description                                          |
+| -------------------- | ----------------------------- | ------- | ---------------------------------------------------- |
+| `expanded`           | `boolean`                     | `false` | Whether the content is expanded                      |
+| `onExpandedChange`   | `(expanded: boolean) => void` | -       | Callback when expanded state changes                 |
+| `children`           | `ReactNode`                   | -       | The content to expand/collapse                       |
+| `duration`           | `number`                      | `200`   | Duration of the animation in milliseconds            |
+| `animateOpacity`     | `boolean`                     | `true`  | Whether to animate opacity during expansion/collapse |
+| `style`              | `ViewStyle`                   | -       | Additional style for the container                   |
+| `accessibilityLabel` | `string`                      | -       | Accessibility label for screen readers               |
+| `testID`             | `string`                      | -       | Test ID for testing purposes                         |
+
+## Animation Duration
+
+The `duration` prop controls how long the expand/collapse animation takes. The default is 200ms, which provides a smooth, natural feel. You can adjust this for faster or slower animations.
+
+<Canvas of={Stories.FastAnimation} />
+
+```tsx
+// Fast animation (150ms)
+<Expandable expanded={expanded} duration={150}>
+  <Card>
+    <BodyText>Quick animation</BodyText>
+  </Card>
+</Expandable>
+
+// Slow animation (600ms)
+<Expandable expanded={expanded} duration={600}>
+  <Card>
+    <BodyText>Slow animation</BodyText>
+  </Card>
+</Expandable>
+```
+
+## Examples
+
+### Basic Example
+
+<Canvas of={Stories.BasicExample} />
+
+### With Different Animation Speeds
+
+<Canvas of={Stories.FastAnimation} />
+<Canvas of={Stories.SlowAnimation} />
+
+### Multiple Expandables
+
+<Canvas of={Stories.MultipleExpandables} />
+
+```tsx
+import { useState } from 'react';
+import { View } from 'react-native';
+import { Expandable, Button, Card, BodyText } from '@utilitywarehouse/hearth-react-native';
+
+const MyComponent = () => {
+  const [expanded1, setExpanded1] = useState(false);
+  const [expanded2, setExpanded2] = useState(false);
+  const [expanded3, setExpanded3] = useState(false);
+
+  return (
+    <View style={{ gap: 16 }}>
+      <View>
+        <Button onPress={() => setExpanded1(!expanded1)}>Section 1 {expanded1 ? '▲' : '▼'}</Button>
+        <Expandable expanded={expanded1}>
+          <Card>
+            <BodyText>Content for section 1</BodyText>
+          </Card>
+        </Expandable>
+      </View>
+
+      <View>
+        <Button onPress={() => setExpanded2(!expanded2)}>Section 2 {expanded2 ? '▲' : '▼'}</Button>
+        <Expandable expanded={expanded2}>
+          <Card>
+            <BodyText>Content for section 2</BodyText>
+          </Card>
+        </Expandable>
+      </View>
+
+      <View>
+        <Button onPress={() => setExpanded3(!expanded3)}>Section 3 {expanded3 ? '▲' : '▼'}</Button>
+        <Expandable expanded={expanded3}>
+          <Card>
+            <BodyText>Content for section 3</BodyText>
+          </Card>
+        </Expandable>
+      </View>
+    </View>
+  );
+};
+```
+
+### Controlled Example
+
+<Canvas of={Stories.ControlledExample} />
+
+```tsx
+import { useState } from 'react';
+import { View } from 'react-native';
+import { Expandable, Button, Card, BodyText } from '@utilitywarehouse/hearth-react-native';
+
+const MyComponent = () => {
+  const [expanded, setExpanded] = useState(false);
+
+  return (
+    <View>
+      <View style={{ flexDirection: 'row', gap: 8 }}>
+        <Button onPress={() => setExpanded(true)}>Expand</Button>
+        <Button onPress={() => setExpanded(false)}>Collapse</Button>
+      </View>
+      <Expandable
+        expanded={expanded}
+        onExpandedChange={setExpanded}
+        accessibilityLabel="Expandable content section"
+      >
+        <Card>
+          <BodyText>Controlled expandable content</BodyText>
+        </Card>
+      </Expandable>
+    </View>
+  );
+};
+```
+
+## Accessibility
+
+The Expandable component includes built-in accessibility support:
+
+- Uses `accessibilityState` to communicate expanded/collapsed state to screen readers
+- Set `accessibilityLabel` to provide context about the expandable content
+- Automatically announces state changes to assistive technologies
+
+```tsx
+<Expandable expanded={expanded} accessibilityLabel="Additional information section">
+  {/* content */}
+</Expandable>
+```
+
+### Screen Reader Announcements
+
+When using the Expandable component:
+
+- The `accessibilityState` prop automatically includes the `expanded` state
+- Screen readers will announce "expanded" or "collapsed" based on the current state
+- Provide descriptive `accessibilityLabel` values to give users context

package/src/components/Expandable/Expandable.props.ts

@@ -0,0 +1,46 @@
+import { ReactNode } from 'react';
+import { ViewProps, ViewStyle } from 'react-native';
+
+export interface ExpandableProps extends ViewProps {
+  /**
+   * Whether the content is expanded
+   */
+  expanded?: boolean;
+
+  /**
+   * Callback when expanded state changes
+   */
+  onExpandedChange?: (expanded: boolean) => void;
+
+  /**
+   * The content to expand/collapse
+   */
+  children: ReactNode;
+
+  /**
+   * Duration of the animation in milliseconds
+   * @default 200
+   */
+  duration?: number;
+
+  /**
+   * Additional style for the container
+   */
+  style?: ViewStyle;
+
+  /**
+   * Accessibility label for screen readers
+   */
+  accessibilityLabel?: string;
+
+  /**
+   * Test ID for testing
+   */
+  testID?: string;
+
+  /**
+   * Whether to animate opacity during expansion/collapse
+   * @default true
+   */
+  animateOpacity?: boolean;
+}

package/src/components/Expandable/Expandable.stories.tsx

@@ -0,0 +1,284 @@
+import { Meta, StoryObj } from '@storybook/react-native';
+import {
+  ChevronDownMediumIcon,
+  ChevronUpMediumIcon,
+} from '@utilitywarehouse/hearth-react-native-icons';
+import { useState } from 'react';
+import { View } from 'react-native';
+import { BodyText, Button, Card } from '../../components';
+import Expandable from './Expandable';
+
+const meta = {
+  title: 'Stories / Expandable',
+  component: Expandable,
+  parameters: {
+    // layout: 'centered',
+  },
+  argTypes: {
+    expanded: {
+      control: 'boolean',
+      description: 'Whether the content is expanded',
+    },
+    duration: {
+      control: { type: 'number', min: 100, max: 1000, step: 50 },
+      description: 'Animation duration in milliseconds',
+    },
+    accessibilityLabel: {
+      control: 'text',
+      description: 'Accessibility label for screen readers',
+    },
+  },
+  args: {
+    expanded: false,
+    duration: 300,
+  },
+} satisfies Meta<typeof Expandable>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Playground: Story = {
+  render: (args: typeof meta.args) => {
+    const [expanded, setExpanded] = useState(args.expanded ?? false);
+
+    return (
+      <>
+        <Button onPress={() => setExpanded(!expanded)} style={{ marginBottom: 16 }}>
+          {expanded ? 'Collapse' : 'Expand'}
+        </Button>
+        <Expandable {...args} expanded={expanded}>
+          <Card>
+            <BodyText>
+              This is expandable content. It animates smoothly when toggled. You can put any content
+              here, and it will expand and collapse with animation.
+            </BodyText>
+          </Card>
+        </Expandable>
+      </>
+    );
+  },
+};
+
+export const BasicExample: Story = {
+  render: () => {
+    const [expanded, setExpanded] = useState(false);
+
+    return (
+      <>
+        <Button onPress={() => setExpanded(!expanded)} style={{ marginBottom: 16 }}>
+          Toggle Content
+        </Button>
+        <Expandable expanded={expanded}>
+          <Card>
+            <BodyText>This content expands and collapses with a smooth animation.</BodyText>
+          </Card>
+        </Expandable>
+      </>
+    );
+  },
+};
+
+export const FastAnimation: Story = {
+  render: () => {
+    const [expanded, setExpanded] = useState(false);
+
+    return (
+      <>
+        <Button onPress={() => setExpanded(!expanded)} style={{ marginBottom: 16 }}>
+          Fast Toggle
+        </Button>
+        <Expandable expanded={expanded} duration={150}>
+          <Card>
+            <BodyText>This expands and collapses quickly with a 150ms duration.</BodyText>
+          </Card>
+        </Expandable>
+      </>
+    );
+  },
+};
+
+export const SlowAnimation: Story = {
+  render: () => {
+    const [expanded, setExpanded] = useState(false);
+
+    return (
+      <>
+        <Button onPress={() => setExpanded(!expanded)} style={{ marginBottom: 16 }}>
+          Slow Toggle
+        </Button>
+        <Expandable expanded={expanded} duration={600}>
+          <Card>
+            <BodyText>This expands and collapses slowly with a 600ms duration.</BodyText>
+          </Card>
+        </Expandable>
+      </>
+    );
+  },
+};
+
+export const LongContent: Story = {
+  render: () => {
+    const [expanded, setExpanded] = useState(false);
+
+    return (
+      <>
+        <Button onPress={() => setExpanded(!expanded)} style={{ marginBottom: 16 }}>
+          {expanded ? 'Hide Details' : 'Show Details'}
+        </Button>
+        <Expandable expanded={expanded}>
+          <Card>
+            <BodyText>
+              This is a longer piece of content that demonstrates how the Expandable component
+              handles larger amounts of text. The animation smoothly transitions regardless of
+              content length.
+            </BodyText>
+            <BodyText style={{ marginTop: 12 }}>
+              You can include multiple paragraphs, and the component will measure the full height
+              and animate accordingly.
+            </BodyText>
+            <BodyText style={{ marginTop: 12 }}>
+              The animation uses Reanimated for optimal performance and smooth transitions.
+            </BodyText>
+          </Card>
+        </Expandable>
+      </>
+    );
+  },
+};
+
+export const MultipleExpandables: Story = {
+  render: () => {
+    const [expanded1, setExpanded1] = useState(false);
+    const [expanded2, setExpanded2] = useState(false);
+    const [expanded3, setExpanded3] = useState(false);
+
+    return (
+      <View style={{ width: 300, gap: 16 }}>
+        <View>
+          <Button
+            onPress={() => setExpanded1(!expanded1)}
+            style={{ marginBottom: 8 }}
+            iconPosition="right"
+            icon={expanded1 ? ChevronUpMediumIcon : ChevronDownMediumIcon}
+          >
+            Section 1
+          </Button>
+          <Expandable expanded={expanded1}>
+            <Card>
+              <BodyText>Content for section 1</BodyText>
+            </Card>
+          </Expandable>
+        </View>
+
+        <View>
+          <Button
+            onPress={() => setExpanded2(!expanded2)}
+            style={{ marginBottom: 8 }}
+            iconPosition="right"
+            icon={expanded2 ? ChevronUpMediumIcon : ChevronDownMediumIcon}
+          >
+            Section 2
+          </Button>
+          <Expandable expanded={expanded2}>
+            <Card>
+              <BodyText>Content for section 2 with more detailed information.</BodyText>
+            </Card>
+          </Expandable>
+        </View>
+
+        <View>
+          <Button
+            onPress={() => setExpanded3(!expanded3)}
+            style={{ marginBottom: 8 }}
+            iconPosition="right"
+            icon={expanded3 ? ChevronUpMediumIcon : ChevronDownMediumIcon}
+          >
+            Section 3
+          </Button>
+          <Expandable expanded={expanded3}>
+            <Card>
+              <BodyText>
+                Content for section 3 with even more information that spans multiple lines.
+              </BodyText>
+            </Card>
+          </Expandable>
+        </View>
+      </View>
+    );
+  },
+};
+
+export const ControlledExample: Story = {
+  render: () => {
+    const [expanded, setExpanded] = useState(false);
+
+    return (
+      <View style={{ width: 300 }}>
+        <View style={{ flexDirection: 'row', gap: 8, marginBottom: 16 }}>
+          <Button onPress={() => setExpanded(true)} style={{ flex: 1 }}>
+            Expand
+          </Button>
+          <Button onPress={() => setExpanded(false)} style={{ flex: 1 }}>
+            Collapse
+          </Button>
+        </View>
+        <Expandable
+          expanded={expanded}
+          onExpandedChange={setExpanded}
+          accessibilityLabel="Expandable content section"
+        >
+          <Card>
+            <BodyText>
+              This is a controlled expandable with separate expand and collapse buttons.
+            </BodyText>
+          </Card>
+        </Expandable>
+      </View>
+    );
+  },
+};
+
+export const DefaultExpanded: Story = {
+  render: () => {
+    const [expanded, setExpanded] = useState(true);
+
+    return (
+      <View style={{ width: 300 }}>
+        <Button onPress={() => setExpanded(!expanded)} style={{ marginBottom: 16 }}>
+          Toggle
+        </Button>
+        <Expandable expanded={expanded}>
+          <Card>
+            <BodyText>This content starts expanded by default.</BodyText>
+          </Card>
+        </Expandable>
+      </View>
+    );
+  },
+};
+
+export const WithCallback: Story = {
+  render: () => {
+    const [expanded, setExpanded] = useState(false);
+    const [message, setMessage] = useState('Content is collapsed');
+
+    const handleExpandedChange = (newExpanded: boolean) => {
+      console.log(newExpanded);
+      setMessage(newExpanded ? 'Content is expanded' : 'Content is collapsed');
+    };
+
+    return (
+      <View style={{ width: 300 }}>
+        <BodyText style={{ marginBottom: 8 }}>{message}</BodyText>
+        <Button onPress={() => setExpanded(!expanded)} style={{ marginBottom: 16 }}>
+          Toggle
+        </Button>
+        <Expandable expanded={expanded} onExpandedChange={handleExpandedChange}>
+          <Card>
+            <BodyText>This example demonstrates the onExpandedChange callback.</BodyText>
+          </Card>
+        </Expandable>
+      </View>
+    );
+  },
+};

package/src/components/Expandable/Expandable.tsx

@@ -0,0 +1,92 @@
+import { useEffect } from 'react';
+import { View } from 'react-native';
+import Animated, {
+  useAnimatedStyle,
+  useDerivedValue,
+  useSharedValue,
+  withTiming,
+} from 'react-native-reanimated';
+import { StyleSheet } from 'react-native-unistyles';
+import { ExpandableProps } from './Expandable.props';
+
+const Expandable = ({
+  expanded = false,
+  onExpandedChange,
+  children,
+  duration = 200,
+  style,
+  accessibilityLabel,
+  testID,
+  animateOpacity = true,
+  ...props
+}: ExpandableProps) => {
+  const height = useSharedValue(0);
+  const open = useSharedValue(expanded);
+
+  // Update open value when expanded prop changes and call callback
+  useEffect(() => {
+    if (open.value !== expanded) {
+      open.value = expanded;
+      onExpandedChange?.(expanded);
+    }
+  }, [expanded, onExpandedChange, open]);
+
+  const derivedHeight = useDerivedValue(() =>
+    withTiming(height.value * Number(open.value), {
+      duration,
+    })
+  );
+
+  const derivedOpacity = useDerivedValue(() =>
+    animateOpacity
+      ? withTiming(Number(open.value), {
+          duration,
+        })
+      : 1
+  );
+
+  const heightStyle = useAnimatedStyle(() => ({
+    height: derivedHeight.value,
+  }));
+
+  const opacityStyle = useAnimatedStyle(() => ({
+    opacity: derivedOpacity.value,
+  }));
+
+  return (
+    <Animated.View
+      style={[styles.container, heightStyle, style]}
+      accessible={true}
+      accessibilityLabel={accessibilityLabel}
+      accessibilityRole="none"
+      accessibilityState={{ expanded }}
+      testID={testID}
+      {...props}
+    >
+      <Animated.View style={opacityStyle}>
+        <View
+          onLayout={e => {
+            height.value = e.nativeEvent.layout.height;
+          }}
+          style={styles.content}
+        >
+          {children}
+        </View>
+      </Animated.View>
+    </Animated.View>
+  );
+};
+
+Expandable.displayName = 'Expandable';
+
+const styles = StyleSheet.create(() => ({
+  container: {
+    overflow: 'hidden',
+  },
+  content: {
+    position: 'absolute',
+    width: '100%',
+  },
+}));
+
+export default Expandable;

package/src/components/Expandable/index.ts

@@ -0,0 +1,2 @@
+export { default as Expandable } from './Expandable';
+export type { ExpandableProps } from './Expandable.props';