@utilitywarehouse/hearth-react-native 0.25.0 → 0.27.0

package/src/components/SegmentedControl/SegmentedControl.docs.mdx

@@ -0,0 +1,90 @@
+import { Canvas, Controls, Meta } from '@storybook/addon-docs/blocks';
+import { SegmentedControl, SegmentedControlOption } from '../../';
+import { BackToTopButton, UsageWrap, ViewFigmaButton } from '../../../docs/components';
+import * as Stories from './SegmentedControl.stories';
+
+<Meta title="Components / Segmented Control" />
+
+<BackToTopButton />
+
+<ViewFigmaButton url="https://www.figma.com/design/6NKZXZhFSExXrcbBgc6zTR/Hearth-Components---Tokens?node-id=6185-1021&t=c7xg5X0N2EL0t87h-4" />
+
+# Segmented Control
+
+Segmented Control lets users switch between a small set of related options.
+Each option is presented as an equal-priority segment in a single horizontal group.
+
+- [Playground](#playground)
+- [Usage](#usage)
+- [Sizes](#sizes)
+- [Props](#props)
+- [Accessibility](#accessibility)
+
+## Playground
+
+<Canvas of={Stories.Playground} />
+
+<Controls of={Stories.Playground} />
+
+## Usage
+
+<UsageWrap>
+  <SegmentedControl defaultValue="day">
+    <SegmentedControlOption value="day">Day</SegmentedControlOption>
+    <SegmentedControlOption value="week">Week</SegmentedControlOption>
+    <SegmentedControlOption value="month">Month</SegmentedControlOption>
+  </SegmentedControl>
+</UsageWrap>
+
+```tsx
+import { SegmentedControl, SegmentedControlOption } from '@utilitywarehouse/hearth-react-native';
+
+const Example = () => {
+  return (
+    <SegmentedControl defaultValue="day">
+      <SegmentedControlOption value="day">Day</SegmentedControlOption>
+      <SegmentedControlOption value="week">Week</SegmentedControlOption>
+      <SegmentedControlOption value="month">Month</SegmentedControlOption>
+    </SegmentedControl>
+  );
+};
+```
+
+## Sizes
+
+Figma defines two size variants for Segmented Control:
+
+- `sm` maps to `SM-32`
+- `md` maps to `MD-48`
+
+<Canvas of={Stories.Sizes} />
+
+## Props
+
+### SegmentedControl
+
+| Property        | Type                      | Description                            | Default      |
+| --------------- | ------------------------- | -------------------------------------- | ------------ |
+| `value`         | `string`                  | Controlled selected option value.      | -            |
+| `defaultValue`  | `string`                  | Initial selected value (uncontrolled). | first option |
+| `onValueChange` | `(value: string) => void` | Called when selected option changes.   | -            |
+| `size`          | `'sm' \| 'md'`            | Size variant (`SM-32` / `MD-48`).      | `'sm'`       |
+| `disabled`      | `boolean`                 | Disables all options in the group.     | `false`      |
+| `children`      | `ReactNode`               | `SegmentedControlOption` children.     | required     |
+
+### SegmentedControlOption
+
+| Property   | Type        | Description                    | Default  |
+| ---------- | ----------- | ------------------------------ | -------- |
+| `value`    | `string`    | Unique value for this segment. | required |
+| `children` | `ReactNode` | Option label/content.          | required |
+| `disabled` | `boolean`   | Disables only this option.     | `false`  |
+
+## Accessibility
+
+SegmentedControl uses radio semantics so assistive technologies can understand it as a single-choice group.
+
+- SegmentedControl root uses `accessibilityRole="radiogroup"`.
+- Each SegmentedControlOption uses `accessibilityRole="radio"`.
+- Option state is communicated with `accessibilityState={{ checked, disabled }}`.
+- If `accessibilityLabel` is not provided on an option, the component falls back to the option text content and then to the option `value`.

package/src/components/SegmentedControl/SegmentedControl.figma.tsx

@@ -0,0 +1,40 @@
+import figma from '@figma/code-connect';
+import { SegmentedControl, SegmentedControlOption } from '../';
+
+figma.connect(
+  SegmentedControl,
+  'https://www.figma.com/design/6NKZXZhFSExXrcbBgc6zTR/Hearth-Components---Tokens?node-id=6185-1021&t=c7xg5X0N2EL0t87h-4',
+  {
+    props: {
+      size: figma.enum('Size', {
+        'SM-32': 'sm',
+        'MD-48': 'md',
+      }),
+      disabled: figma.enum('State', {
+        Disabled: true,
+      }),
+      options: figma.children('Option'),
+    },
+    example: props => (
+      <SegmentedControl defaultValue="option-1" size={props.size} disabled={props.disabled}>
+        {props.options}
+      </SegmentedControl>
+    ),
+  }
+);
+
+figma.connect(
+  SegmentedControlOption,
+  'https://www.figma.com/design/6NKZXZhFSExXrcbBgc6zTR/Hearth-Components---Tokens?node-id=4340-1252&t=c7xg5X0N2EL0t87h-4',
+  {
+    props: {
+      label: figma.string('Label'),
+      value: figma.string('Value'),
+    },
+    example: props => (
+      <SegmentedControlOption value={props.value ?? 'option'}>
+        {props.label ?? 'Option'}
+      </SegmentedControlOption>
+    ),
+  }
+);

package/src/components/SegmentedControl/SegmentedControl.props.ts

@@ -0,0 +1,20 @@
+import type { ReactNode } from 'react';
+import type { ViewProps } from 'react-native';
+import type { FlexLayoutProps } from '../../types';
+
+export interface SegmentedControlProps extends ViewProps, FlexLayoutProps {
+  /** Controlled selected option value. */
+  value?: string;
+  /** Initial selected option value for uncontrolled mode. */
+  defaultValue?: string;
+  /** Called when selected option changes. */
+  onValueChange?: (value: string) => void;
+  /** Size variant. */
+  size?: 'sm' | 'md';
+  /** Disables all options in the control. */
+  disabled?: boolean;
+  /** SegmentedControlOption children. */
+  children: ReactNode;
+}
+
+export default SegmentedControlProps;

package/src/components/SegmentedControl/SegmentedControl.stories.tsx

@@ -0,0 +1,77 @@
+import { useState } from 'react';
+import { BodyText, Flex, SegmentedControl, SegmentedControlOption } from '../';
+
+const meta = {
+  title: 'Stories / Segmented Control',
+  component: SegmentedControl,
+  parameters: {
+    layout: 'centered',
+  },
+  args: {
+    size: 'sm',
+    disabled: false,
+  },
+  argTypes: {
+    size: {
+      control: 'radio',
+      options: ['sm', 'md'],
+    },
+    disabled: {
+      control: 'boolean',
+    },
+  },
+};
+
+export default meta;
+
+export const Playground = {
+  render: (args: { size?: 'sm' | 'md'; disabled?: boolean }) => (
+    <SegmentedControl defaultValue="day" {...args}>
+      <SegmentedControlOption value="day">Day</SegmentedControlOption>
+      <SegmentedControlOption value="week">Week</SegmentedControlOption>
+      <SegmentedControlOption value="month">Month</SegmentedControlOption>
+    </SegmentedControl>
+  ),
+};
+
+export const Sizes = {
+  render: () => (
+    <Flex spacing="sm" align="center">
+      <SegmentedControl defaultValue="one" size="sm">
+        <SegmentedControlOption value="one">Label</SegmentedControlOption>
+        <SegmentedControlOption value="two">Label</SegmentedControlOption>
+        <SegmentedControlOption value="three">Label</SegmentedControlOption>
+      </SegmentedControl>
+      <SegmentedControl defaultValue="one" size="md">
+        <SegmentedControlOption value="one">Label</SegmentedControlOption>
+        <SegmentedControlOption value="two">Label</SegmentedControlOption>
+        <SegmentedControlOption value="three">Label</SegmentedControlOption>
+      </SegmentedControl>
+    </Flex>
+  ),
+};
+
+export const Controlled = {
+  render: () => {
+    const [value, setValue] = useState('annual');
+    return (
+      <Flex spacing="sm" align="center">
+        <SegmentedControl value={value} onValueChange={setValue}>
+          <SegmentedControlOption value="monthly">Monthly</SegmentedControlOption>
+          <SegmentedControlOption value="annual">Annual</SegmentedControlOption>
+        </SegmentedControl>
+        <BodyText size="sm">Selected: {value}</BodyText>
+      </Flex>
+    );
+  },
+};
+
+export const Disabled = {
+  render: () => (
+    <SegmentedControl defaultValue="left" disabled>
+      <SegmentedControlOption value="left">Left</SegmentedControlOption>
+      <SegmentedControlOption value="center">Center</SegmentedControlOption>
+      <SegmentedControlOption value="right">Right</SegmentedControlOption>
+    </SegmentedControl>
+  ),
+};

package/src/components/SegmentedControl/SegmentedControl.tsx

@@ -0,0 +1,257 @@
+import { Children, isValidElement, useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { View } from 'react-native';
+import Animated, {
+    Easing,
+    useAnimatedStyle,
+    useReducedMotion,
+    useSharedValue,
+    withTiming,
+} from 'react-native-reanimated';
+import { StyleSheet } from 'react-native-unistyles';
+import { useStyleProps } from '../../hooks';
+import { SegmentedControlContext } from './SegmentedControl.context';
+import type SegmentedControlProps from './SegmentedControl.props';
+
+const Indicator = Animated.createAnimatedComponent(View);
+const GROUP_BORDER_WIDTH = 1;
+
+const SegmentedControl = ({
+  value: controlledValue,
+  defaultValue,
+  onValueChange,
+  size = 'sm',
+  disabled = false,
+  children,
+  style,
+  ...props
+}: SegmentedControlProps) => {
+  const { computedStyles, remainingProps } = useStyleProps(props);
+  const isReducedMotion = useReducedMotion();
+  const indicatorPositionOffset = GROUP_BORDER_WIDTH;
+
+  const optionValues = useMemo(() => {
+    const values: string[] = [];
+
+    const walk = (node: any) => {
+      Children.forEach(node, child => {
+        if (!isValidElement(child)) return;
+
+        const childType: any = child.type;
+        const childProps: any = child.props;
+
+        if (
+          childType?.displayName === 'SegmentedControlOption' &&
+          typeof childProps?.value === 'string'
+        ) {
+          values.push(childProps.value);
+        }
+
+        if (childProps?.children) {
+          walk(childProps.children);
+        }
+      });
+    };
+
+    walk(children);
+    return values;
+  }, [children]);
+  const optionValuesKey = useMemo(() => optionValues.join('|'), [optionValues]);
+  const optionValuesRef = useRef<string[]>(optionValues);
+
+  useEffect(() => {
+    optionValuesRef.current = optionValues;
+  }, [optionValues]);
+
+  const getInitialValue = () => {
+    if (controlledValue !== undefined) return controlledValue;
+    if (defaultValue !== undefined) return defaultValue;
+    return optionValues[0];
+  };
+
+  const [uncontrolledValue, setUncontrolledValue] = useState<string | undefined>(getInitialValue);
+
+  useEffect(() => {
+    if (controlledValue !== undefined) {
+      setUncontrolledValue(controlledValue);
+    }
+  }, [controlledValue]);
+
+  useEffect(() => {
+    const currentOptionValues = optionValuesRef.current;
+    setUncontrolledValue(prev => {
+      if (!prev) return currentOptionValues[0];
+      if (!currentOptionValues.includes(prev)) return currentOptionValues[0];
+      return prev;
+    });
+  }, [optionValuesKey]);
+
+  const currentValue = controlledValue !== undefined ? controlledValue : uncontrolledValue;
+
+  const indicatorX = useSharedValue(0);
+  const indicatorWidth = useSharedValue(0);
+  const indicatorY = useSharedValue(0);
+  const indicatorHeight = useSharedValue(0);
+  const [hasIndicator, setHasIndicator] = useState(false);
+  const layoutsRef = useRef<Map<string, { x: number; y: number; width: number; height: number }>>(
+    new Map()
+  );
+  const prevValueRef = useRef<string | undefined>(undefined);
+  const initialisedRef = useRef(false);
+
+  const select = useCallback(
+    (nextValue: string) => {
+      if (disabled) return;
+      if (controlledValue === undefined) {
+        setUncontrolledValue(nextValue);
+      }
+      onValueChange?.(nextValue);
+    },
+    [controlledValue, disabled, onValueChange]
+  );
+
+  const registerOptionLayout = useCallback(
+    (value: string, layout: { x: number; y: number; width: number; height: number }) => {
+      layoutsRef.current.set(value, layout);
+      const activeValue = controlledValue !== undefined ? controlledValue : uncontrolledValue;
+      if (!activeValue || activeValue !== value) return;
+
+      if (!initialisedRef.current) {
+        indicatorX.value = Math.max(0, layout.x - indicatorPositionOffset);
+        indicatorWidth.value = layout.width;
+        indicatorY.value = Math.max(0, layout.y - indicatorPositionOffset);
+        indicatorHeight.value = layout.height;
+        prevValueRef.current = activeValue;
+        initialisedRef.current = true;
+        setHasIndicator(true);
+        return;
+      }
+
+      if (prevValueRef.current === activeValue) return;
+
+      const config = {
+        delay: 200,
+        duration: isReducedMotion ? 0 : 220,
+        easing: Easing.out(Easing.cubic),
+      } as const;
+
+      indicatorX.value = withTiming(Math.max(0, layout.x - indicatorPositionOffset), config);
+      indicatorWidth.value = withTiming(layout.width, config);
+      indicatorY.value = withTiming(Math.max(0, layout.y - indicatorPositionOffset), config);
+      indicatorHeight.value = withTiming(layout.height, config);
+      prevValueRef.current = activeValue;
+    },
+    [
+      controlledValue,
+      indicatorHeight,
+      indicatorWidth,
+      indicatorX,
+      indicatorY,
+      indicatorPositionOffset,
+      isReducedMotion,
+      uncontrolledValue,
+    ]
+  );
+
+  useEffect(() => {
+    if (!currentValue || !initialisedRef.current) return;
+    if (prevValueRef.current === undefined || prevValueRef.current === currentValue) return;
+    const layout = layoutsRef.current.get(currentValue);
+    if (!layout) return;
+    const config = {
+      duration: isReducedMotion ? 0 : 220,
+      easing: Easing.out(Easing.cubic),
+    } as const;
+
+    indicatorX.value = withTiming(Math.max(0, layout.x - indicatorPositionOffset), config);
+    indicatorWidth.value = withTiming(layout.width, config);
+    indicatorY.value = withTiming(Math.max(0, layout.y - indicatorPositionOffset), config);
+    indicatorHeight.value = withTiming(layout.height, config);
+    prevValueRef.current = currentValue;
+  }, [
+    currentValue,
+    indicatorHeight,
+    indicatorWidth,
+    indicatorX,
+    indicatorY,
+    indicatorPositionOffset,
+    isReducedMotion,
+    optionValuesKey,
+  ]);
+
+  const indicatorStyle = useAnimatedStyle(() => ({
+    transform: [{ translateX: indicatorX.value }, { translateY: indicatorY.value }],
+    width: indicatorWidth.value,
+    height: indicatorHeight.value,
+  }));
+
+  styles.useVariants({ disabled, size });
+
+  const contextValue = useMemo(
+    () => ({
+      value: currentValue,
+      select,
+      disabled,
+      size,
+      registerOptionLayout,
+    }),
+    [currentValue, select, disabled, size, registerOptionLayout]
+  );
+
+  return (
+    <SegmentedControlContext.Provider value={contextValue}>
+      <View
+        accessibilityRole="radiogroup"
+        accessibilityState={{ disabled }}
+        style={[styles.container, computedStyles, style]}
+        {...remainingProps}
+      >
+        {hasIndicator ? (
+          <Indicator pointerEvents="none" style={[styles.indicator, indicatorStyle]} />
+        ) : null}
+        {children}
+      </View>
+    </SegmentedControlContext.Provider>
+  );
+};
+
+SegmentedControl.displayName = 'SegmentedControl';
+
+const styles = StyleSheet.create(theme => ({
+  container: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    alignSelf: 'flex-start',
+    gap: theme.components.segmentedControl.group.gap,
+    height: theme.components.segmentedControl.group.height,
+    borderRadius: theme.components.segmentedControl.group.borderRadius,
+    borderWidth: theme.components.segmentedControl.group.borderWidth,
+    backgroundColor: theme.color.surface.neutral.subtle,
+    borderColor: theme.color.border.strong,
+    variants: {
+      size: {
+        sm: {
+          height: 32,
+          padding: 2,
+        },
+        md: {
+          height: theme.components.segmentedControl.group.height,
+          padding: 2,
+        },
+      },
+      disabled: {
+        true: {
+          opacity: theme.opacity.disabled,
+        },
+      },
+    },
+  },
+  indicator: {
+    position: 'absolute',
+    left: 0,
+    top: 0,
+    borderRadius: theme.components.segmentedControl.borderRadius,
+    backgroundColor: theme.color.interactive.brand.surface.strong.default,
+  },
+}));
+
+export default SegmentedControl;

package/src/components/SegmentedControl/SegmentedControlOption.props.ts

@@ -0,0 +1,14 @@
+import type { ReactNode } from 'react';
+import type { PressableProps, ViewProps } from 'react-native';
+
+export interface SegmentedControlOptionProps extends Omit<PressableProps, 'children'> {
+  /** Unique option value. */
+  value: string;
+  /** Option label/content. */
+  children: ReactNode;
+  /** Disables only this option. */
+  disabled?: boolean;
+  style?: ViewProps['style'];
+}
+
+export default SegmentedControlOptionProps;