@utilitywarehouse/hearth-react-native 0.1.0 → 0.3.0

package/src/components/Tabs/Tabs.docs.mdx

@@ -0,0 +1,214 @@
+import { Canvas, Controls, Meta } from '@storybook/addon-docs/blocks';
+import { Badge, BodyText, Tab, TabPanel, Tabs, TabsList } from '../../';
+import { BackToTopButton, UsageWrap, ViewFigmaButton } from '../../../docs/components';
+import * as Stories from './Tabs.stories';
+
+<BackToTopButton />
+
+<ViewFigmaButton url="https://www.figma.com/design/6NKZXZhFSExXrcbBgc6zTR/Hearth-Components---Tokens?node-id=6463-1113" />
+
+<Meta title="Components / Tabs" />
+
+# Tabs
+
+Tabs are a navigational component that allows users to move easily between groups of related content.
+
+- [Playground](#playground)
+- [Usage](#usage)
+- [Examples](#examples)
+  - [Controlled](#controlled)
+  - [Overflow & Scrolling](#overflow--scrolling)
+  - [With Icons](#with-icons)
+- [Props](#props)
+- [Size Variants](#size-variants)
+- [Accessibility](#accessibility)
+
+## Playground
+
+<Canvas of={Stories.Playground} />
+<Controls of={Stories.Playground} />
+
+## Usage
+
+<UsageWrap>
+  <Tabs defaultValue="account">
+    <TabsList>
+      <Tab value="account">Account</Tab>
+      <Tab value="billing">Billing</Tab>
+      <Tab value="usage">Usage</Tab>
+    </TabsList>
+    <TabPanel value="account">
+      <BodyText>Account content</BodyText>
+    </TabPanel>
+    <TabPanel value="billing">
+      <BodyText>Billing content</BodyText>
+    </TabPanel>
+    <TabPanel value="usage">
+      <BodyText>Usage metrics content</BodyText>
+    </TabPanel>
+  </Tabs>
+</UsageWrap>
+
+```tsx
+import { Tabs, TabsList, Tab, TabPanel } from '@utilitywarehouse/hearth-react-native';
+
+<Tabs defaultValue="account">
+  <TabsList>
+    <Tab value="account">Account</Tab>
+    <Tab value="billing">Billing</Tab>
+    <Tab value="usage">Usage</Tab>
+  </TabsList>
+  <TabPanel value="account">
+    <BodyText>Account content</BodyText>
+  </TabPanel>
+  <TabPanel value="billing">
+    <BodyText>Billing content</BodyText>
+  </TabPanel>
+  <TabPanel value="usage">
+    <BodyText>Usage metrics content</BodyText>
+  </TabPanel>
+</Tabs>;
+```
+
+## Examples
+
+### Controlled
+
+Tabs can be controlled by passing `value` and `onValueChange` props to the `Tabs` component.
+This allows you to manage the active tab state externally.
+
+```tsx
+const [tab, setTab] = useState('account');
+<Tabs value={tab} onValueChange={setTab}>
+  <TabsList>
+    <Tab value="account">Account</Tab>
+    <Tab value="billing">Billing</Tab>
+    <Tab value="usage">Usage</Tab>
+  </TabsList>
+  <TabPanel value="account">
+    <BodyText>Account content</BodyText>
+  </TabPanel>
+  <TabPanel value="billing">
+    <BodyText>Billing content</BodyText>
+  </TabPanel>
+  <TabPanel value="usage">
+    <BodyText>Usage metrics content</BodyText>
+  </TabPanel>
+</Tabs>;
+```
+
+### Overflow & Scrolling
+
+<Canvas of={Stories.WithScrolling} />
+
+When the combined tab labels exceed the horizontal space, the list becomes horizontally scrollable.
+Contextual navigation buttons (previous / next) appear just outside the scrollable area. They:
+
+- Scroll by ~60% of the visible width per press (for efficient paging)
+- Are hidden from assistive technology (screen readers) - users rely on the tab structure itself
+- Only render when further scrolling in that direction is possible
+- Honor reduced motion: only the indicator animation is affected (system reduced motion will minimise excessive transitions)
+
+### With Icons
+
+You can add icons to each `Tab` by passing an icon component to the `icon` prop. The icon will be placed to the left of the tab label.
+
+<Canvas of={Stories.WithIcons} />
+
+```tsx
+import { Tabs, TabsList, Tab, TabPanel } from '@utilitywarehouse/hearth-react-native';
+import {
+  ElectricityMediumIcon,
+  MobileMediumIcon,
+  InsuranceMediumIcon,
+} from '@utilitywarehouse/hearth-react-native-icons';
+
+const MyComponent = () => (
+  <Tabs defaultValue="one">
+    <TabsList>
+      <Tab value="one" icon={ElectricityMediumIcon}>
+        Energy
+      </Tab>
+      <Tab value="two" icon={BroadbandMediumIcon}>
+        Broadband
+      </Tab>
+      <Tab value="three" icon={MobileMediumIcon}>
+        Mobile
+      </Tab>
+      <Tab value="four" icon={InsuranceMediumIcon}>
+        Insurance
+      </Tab>
+    </TabsList>
+    <TabPanel value="one">
+      <BodyText>One panel</BodyText>
+    </TabPanel>
+    <TabPanel value="two">
+      <BodyText>Two panel</BodyText>
+    </TabPanel>
+    <TabPanel value="three">
+      <BodyText>Three panel</BodyText>
+    </TabPanel>
+    <TabPanel value="four">
+      <BodyText>Four panel</BodyText>
+    </TabPanel>
+  </Tabs>
+);
+```
+
+## Props
+
+### Tabs
+
+| Prop            | Type                      | Description                                                         | Default    |
+| --------------- | ------------------------- | ------------------------------------------------------------------- | ---------- |
+| `value`         | `string`                  | Controlled active tab value                                         | -          |
+| `defaultValue`  | `string`                  | Uncontrolled initial tab value                                      | first Tab  |
+| `onValueChange` | `(value: string) => void` | Change handler                                                      | -          |
+| `size`          | `'md' \| 'lg'`            | Size variant (affects tab height & list padding)                    | `md`       |
+| `disabled`      | `boolean`                 | Disables all interaction                                            | `false`    |
+| `withPanels`    | `boolean`                 | If true, expects sibling `TabPanel` elements and wires ARIA linkage | `true`\*   |
+| `children`      | `ReactNode`               | Composition (typically `TabsList` + `TabPanel` children)            | (required) |
+
+\*If omitted you can still compose panels manually, but accessibility linkage (`aria-controls` / `id`) is provided when `withPanels` is true.
+
+### TabsList / Tab / TabPanel
+
+#### TabsList
+
+| Prop       | Type        | Description                | Default    |
+| ---------- | ----------- | -------------------------- | ---------- |
+| `children` | `ReactNode` | One or more `Tab` elements | (required) |
+
+#### Tab
+
+| Prop       | Type            | Description                       | Default    |
+| ---------- | --------------- | --------------------------------- | ---------- |
+| `value`    | `string`        | Unique tab value                  | (required) |
+| `children` | `ReactNode`     | Label content (can include badge) | (required) |
+| `icon`     | `ComponentType` | Optional leading icon             | -          |
+| `disabled` | `boolean`       | Disabled state                    | `false`    |
+
+#### TabPanel
+
+| Prop          | Type        | Description                                 | Default    |
+| ------------- | ----------- | ------------------------------------------- | ---------- |
+| `value`       | `string`    | Matches a `Tab` value                       | (required) |
+| `children`    | `ReactNode` | Panel content                               | (required) |
+| `keepMounted` | `boolean`   | Keep hidden panels in tree (preserve state) | `false`    |
+
+## Size Variants
+
+<Canvas of={Stories.Sizes} />
+
+## Accessibility
+
+| Element     | Role                                    | Notes                                           |
+| ----------- | --------------------------------------- | ----------------------------------------------- |
+| `Tabs` root | `tablist`                               | Container for related `tab` elements            |
+| `Tab`       | `tab`                                   | Uses `accessibilityState.selected` & `disabled` |
+| `TabPanel`  | `tabpanel` (web) / hidden view (native) | Inactive panels removed from a11y tree          |
+
+Selection state is communicated through `accessibilityState`. Provide concise labels (children text) for best screen reader clarity.
+Any extra content you compose is read in order unless you explicitly hide it. The animated indicator reflects the active tab;
+reduced motion preferences are respected. Hidden panels are removed from the accessibility tree.
+Overflow scroll buttons are hidden from assistive tech and only appear visually when scrolling is possible.

package/src/components/Tabs/Tabs.props.ts

@@ -0,0 +1,21 @@
+import type { ReactNode } from 'react';
+import type { ViewProps } from 'react-native';
+
+export interface TabsProps extends ViewProps {
+  /** Controlled active tab value */
+  value?: string;
+  /** Uncontrolled initial value */
+  defaultValue?: string;
+  /** Callback when active tab changes */
+  onValueChange?: (value: string) => void;
+  /** Size variant */
+  size?: 'md' | 'lg';
+  /** Tabs (Tab components) */
+  children: ReactNode;
+  /** Disable all tabs */
+  disabled?: boolean;
+  /** If true, expect sibling TabPanel components and manage their rendering/ARIA linkage */
+  withPanels?: boolean;
+}
+
+export default TabsProps;

package/src/components/Tabs/Tabs.stories.tsx

@@ -0,0 +1,270 @@
+import { Meta, StoryObj } from '@storybook/react-vite';
+import {
+  BroadbandMediumIcon,
+  ElectricityMediumIcon,
+  InsuranceMediumIcon,
+  MobileMediumIcon,
+} from '@utilitywarehouse/hearth-react-native-icons';
+import { useState } from 'react';
+import { Platform } from 'react-native';
+import { BodyText, Button, Flex, Tab, TabPanel, Tabs, TabsList } from '../';
+
+const meta = {
+  title: 'Stories / Tabs',
+  component: Tabs,
+  args: {
+    size: 'md',
+    children: undefined,
+  },
+  argTypes: {
+    size: { control: 'radio', options: ['md', 'lg'] },
+  },
+} satisfies Meta<typeof Tabs>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Playground: Story = {
+  args: {
+    children: (
+      <>
+        <Tab value="account">Account</Tab>
+        <Tab value="billing">Billing</Tab>
+        <Tab value="usage">Usage</Tab>
+        <Tab value="settings">Settings</Tab>
+      </>
+    ),
+  },
+  render: ({ children, ...args }) => (
+    <Tabs {...args} defaultValue="account">
+      <TabsList>{children}</TabsList>
+      <TabPanel value="account">
+        <BodyText>Account content</BodyText>
+      </TabPanel>
+      <TabPanel value="billing">
+        <BodyText>Billing content</BodyText>
+      </TabPanel>
+      <TabPanel value="usage">
+        <BodyText>Usage metrics</BodyText>
+      </TabPanel>
+      <TabPanel value="settings">
+        <BodyText>Settings content</BodyText>
+      </TabPanel>
+    </Tabs>
+  ),
+};
+
+export const Sizes: Story = {
+  args: { children: null },
+  render: () => (
+    <>
+      <Tabs size="md" defaultValue="a">
+        <TabsList>
+          <Tab value="a">Medium A</Tab>
+          <Tab value="b">Medium B</Tab>
+          <Tab value="c">Medium C</Tab>
+        </TabsList>
+        <TabPanel value="a">
+          <BodyText>Medium A panel</BodyText>
+        </TabPanel>
+        <TabPanel value="b">
+          <BodyText>Medium B panel</BodyText>
+        </TabPanel>
+        <TabPanel value="c">
+          <BodyText>Medium C panel</BodyText>
+        </TabPanel>
+      </Tabs>
+      <Tabs size="lg" defaultValue="a" style={{ marginTop: 24 }}>
+        <TabsList>
+          <Tab value="a">Large A</Tab>
+          <Tab value="b">Large B</Tab>
+          <Tab value="c">Large C</Tab>
+        </TabsList>
+        <TabPanel value="a">
+          <BodyText>Large A panel</BodyText>
+        </TabPanel>
+        <TabPanel value="b">
+          <BodyText>Large B panel</BodyText>
+        </TabPanel>
+        <TabPanel value="c">
+          <BodyText>Large C panel</BodyText>
+        </TabPanel>
+      </Tabs>
+    </>
+  ),
+};
+
+export const WithScrolling: Story = {
+  args: { children: null },
+  render: () => (
+    <Tabs defaultValue="one">
+      <TabsList>
+        <Tab value="one">One</Tab>
+        <Tab value="two">Two</Tab>
+        <Tab value="three">Three</Tab>
+        <Tab value="four">Four</Tab>
+        <Tab value="five">Five</Tab>
+        <Tab value="six">Six</Tab>
+        <Tab value="seven">Seven</Tab>
+        <Tab value="eight">Eight</Tab>
+        <Tab value="nine">Nine</Tab>
+        <Tab value="ten">Ten</Tab>
+        <Tab value="eleven">Eleven</Tab>
+        <Tab value="twelve">Twelve</Tab>
+        <Tab value="thirteen">Thirteen</Tab>
+        <Tab value="fourteen">Fourteen</Tab>
+        <Tab value="fifteen">Fifteen</Tab>
+        <Tab value="sixteen">Sixteen</Tab>
+        <Tab value="seventeen">Seventeen</Tab>
+        <Tab value="eighteen">Eighteen</Tab>
+        <Tab value="nineteen">Nineteen</Tab>
+        <Tab value="twenty">Twenty</Tab>
+      </TabsList>
+      <TabPanel value="one">
+        <BodyText>One panel</BodyText>
+      </TabPanel>
+      <TabPanel value="two">
+        <BodyText>Two panel</BodyText>
+      </TabPanel>
+      <TabPanel value="three">
+        <BodyText>Three panel</BodyText>
+      </TabPanel>
+      <TabPanel value="four">
+        <BodyText>Four panel</BodyText>
+      </TabPanel>
+      <TabPanel value="five">
+        <BodyText>Five panel</BodyText>
+      </TabPanel>
+      <TabPanel value="six">
+        <BodyText>Six panel</BodyText>
+      </TabPanel>
+      <TabPanel value="seven">
+        <BodyText>Seven panel</BodyText>
+      </TabPanel>
+      <TabPanel value="eight">
+        <BodyText>Eight panel</BodyText>
+      </TabPanel>
+      <TabPanel value="nine">
+        <BodyText>Nine panel</BodyText>
+      </TabPanel>
+      <TabPanel value="ten">
+        <BodyText>Ten panel</BodyText>
+      </TabPanel>
+      <TabPanel value="eleven">
+        <BodyText>Eleven panel</BodyText>
+      </TabPanel>
+      <TabPanel value="twelve">
+        <BodyText>Twelve panel</BodyText>
+      </TabPanel>
+      <TabPanel value="thirteen">
+        <BodyText>Thirteen panel</BodyText>
+      </TabPanel>
+      <TabPanel value="fourteen">
+        <BodyText>Fourteen panel</BodyText>
+      </TabPanel>
+      <TabPanel value="fifteen">
+        <BodyText>Fifteen panel</BodyText>
+      </TabPanel>
+      <TabPanel value="sixteen">
+        <BodyText>Sixteen panel</BodyText>
+      </TabPanel>
+      <TabPanel value="seventeen">
+        <BodyText>Seventeen panel</BodyText>
+      </TabPanel>
+      <TabPanel value="eighteen">
+        <BodyText>Eighteen panel</BodyText>
+      </TabPanel>
+      <TabPanel value="nineteen">
+        <BodyText>Nineteen panel</BodyText>
+      </TabPanel>
+      <TabPanel value="twenty">
+        <BodyText>Twenty panel</BodyText>
+      </TabPanel>
+    </Tabs>
+  ),
+};
+
+export const WithIcons: Story = {
+  args: { children: null },
+  render: () => (
+    <Tabs defaultValue="one">
+      <TabsList>
+        <Tab value="one" icon={ElectricityMediumIcon}>
+          Energy
+        </Tab>
+        <Tab value="two" icon={BroadbandMediumIcon}>
+          Broadband
+        </Tab>
+        <Tab value="three" icon={MobileMediumIcon}>
+          Mobile
+        </Tab>
+        <Tab value="four" icon={InsuranceMediumIcon}>
+          Insurance
+        </Tab>
+      </TabsList>
+      <TabPanel value="one">
+        <BodyText>One panel</BodyText>
+      </TabPanel>
+      <TabPanel value="two">
+        <BodyText>Two panel</BodyText>
+      </TabPanel>
+      <TabPanel value="three">
+        <BodyText>Three panel</BodyText>
+      </TabPanel>
+      <TabPanel value="four">
+        <BodyText>Four panel</BodyText>
+      </TabPanel>
+    </Tabs>
+  ),
+};
+
+export const Disabled: Story = {
+  args: { children: null },
+  render: () => (
+    <Tabs defaultValue="one" disabled>
+      <TabsList>
+        <Tab value="one">One</Tab>
+        <Tab value="two">Two</Tab>
+        <Tab value="three">Three</Tab>
+      </TabsList>
+      <TabPanel value="one">One panel</TabPanel>
+      <TabPanel value="two">Two panel</TabPanel>
+      <TabPanel value="three">Three panel</TabPanel>
+    </Tabs>
+  ),
+};
+
+export const Controlled: Story = {
+  args: { children: null },
+  render: () => {
+    const [value, setValue] = useState('account');
+    const nextTab = () => {
+      const tabs = ['account', 'billing', 'usage'];
+      const currentIndex = tabs.indexOf(value);
+      const nextIndex = (currentIndex + 1) % tabs.length;
+      setValue(tabs[nextIndex]);
+    };
+    return (
+      <Flex align={Platform.OS === 'web' ? 'flex-start' : 'stretch'} space="lg">
+        <Tabs value={value}>
+          <TabsList>
+            <Tab value="account">Account</Tab>
+            <Tab value="billing">Billing</Tab>
+            <Tab value="usage">Usage</Tab>
+          </TabsList>
+          <TabPanel value="account">
+            <BodyText>Account content</BodyText>
+          </TabPanel>
+          <TabPanel value="billing">
+            <BodyText>Billing content</BodyText>
+          </TabPanel>
+          <TabPanel value="usage">
+            <BodyText>Usage metrics content</BodyText>
+          </TabPanel>
+        </Tabs>
+
+        <Button onPress={nextTab}>Next Tab</Button>
+      </Flex>
+    );
+  },
+};

package/src/components/Tabs/Tabs.tsx

@@ -0,0 +1,139 @@
+import { Children, isValidElement, useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { View } from 'react-native';
+import { Easing, useSharedValue, withTiming } from 'react-native-reanimated';
+import { TabsContext } from './Tabs.context';
+import type TabsProps from './Tabs.props';
+
+const Tabs = ({
+  value: controlledValue,
+  defaultValue,
+  onValueChange,
+  size = 'md',
+  disabled,
+  children,
+  withPanels,
+  ...props
+}: TabsProps) => {
+  // Collect child tab values
+  const tabValues = useMemo(() => {
+    const vals: string[] = [];
+    const walk = (node: any) => {
+      Children.forEach(node, child => {
+        if (!isValidElement(child)) return;
+        const props: any = child.props;
+        const type: any = child.type;
+        if (type?.displayName === 'Tab' && typeof props?.value === 'string') {
+          vals.push(props.value);
+        }
+        if (props?.children) walk(props.children);
+      });
+    };
+    walk(children);
+    return vals;
+  }, [children]);
+
+  const getInitial = () => {
+    if (controlledValue !== undefined) return controlledValue;
+    if (defaultValue) return defaultValue;
+    return tabValues[0];
+  };
+
+  const [uncontrolled, setUncontrolled] = useState<string | undefined>(getInitial);
+
+  useEffect(() => {
+    if (controlledValue !== undefined) setUncontrolled(controlledValue);
+  }, [controlledValue]);
+
+  // Ensure value remains valid if tabs change
+  useEffect(() => {
+    setUncontrolled(prev => {
+      if (!prev) return tabValues[0];
+      if (!tabValues.includes(prev)) return tabValues[0];
+      return prev;
+    });
+  }, [tabValues.join('|')]);
+
+  const currentValue = controlledValue !== undefined ? controlledValue : uncontrolled;
+
+  const select = useCallback(
+    (val: string) => {
+      if (disabled) return;
+      if (controlledValue === undefined) setUncontrolled(val);
+      onValueChange?.(val);
+    },
+    [controlledValue, disabled, onValueChange]
+  );
+
+  // Indicator shared values (declared early so registerTabLayout can reference)
+  const indicatorX = useSharedValue(0);
+  const indicatorSize = useSharedValue(0);
+
+  // Layout registry for animated indicator
+  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 registerTabLayout = useCallback(
+    (value: string, layout: { x: number; y: number; width: number; height: number }) => {
+      layoutsRef.current.set(value, layout);
+      const active = controlledValue !== undefined ? controlledValue : uncontrolled;
+      if (!active) return;
+      // Initial active tab: seed indicator & prevValue so first change animates
+      if (!initialisedRef.current && value === active) {
+        indicatorX.value = layout.x;
+        indicatorSize.value = layout.width;
+        prevValueRef.current = active;
+        initialisedRef.current = true;
+      }
+    },
+    [controlledValue, uncontrolled, indicatorX, indicatorSize]
+  );
+  const getTabLayout = useCallback((v: string) => layoutsRef.current.get(v), []);
+
+  const contextValue = useMemo(
+    () => ({
+      value: currentValue,
+      size,
+      select,
+      disabled,
+      registerTabLayout,
+      getTabLayout,
+      indicatorXSV: indicatorX,
+      indicatorSizeSV: indicatorSize,
+    }),
+    [
+      currentValue,
+      size,
+      select,
+      disabled,
+      registerTabLayout,
+      getTabLayout,
+      tabValues,
+      indicatorX,
+      indicatorSize,
+    ]
+  );
+
+  // Animate indicator only on value changes after initialisation
+  useEffect(() => {
+    if (!currentValue || !initialisedRef.current) return;
+    if (prevValueRef.current === undefined || prevValueRef.current === currentValue) return;
+    const layout = getTabLayout(currentValue);
+    if (!layout) return;
+    const cfg = { duration: 250, easing: Easing.out(Easing.ease) } as const;
+    indicatorX.value = withTiming(layout.x, cfg);
+    indicatorSize.value = withTiming(layout.width, cfg);
+    prevValueRef.current = currentValue;
+  }, [currentValue, getTabLayout, indicatorX, indicatorSize, tabValues.join('|')]);
+
+  return (
+    <TabsContext.Provider value={contextValue}>
+      <View {...props}>{children}</View>
+    </TabsContext.Provider>
+  );
+};
+
+Tabs.displayName = 'Tabs';
+
+export default Tabs;

package/src/components/Tabs/TabsList.props.ts

@@ -0,0 +1,8 @@
+import type { ReactNode } from 'react';
+import type { ViewProps } from 'react-native';
+
+export interface TabsListProps extends ViewProps {
+  children: ReactNode;
+}
+
+export default TabsListProps;