@utilitywarehouse/hearth-react-native 0.5.0 → 0.6.0

package/src/components/ProgressStepper/ProgressStepper.props.ts

@@ -1,6 +1,6 @@
 import { ViewProps } from 'react-native';
 
-export type StepState = 'complete' | 'active' | 'incomplete';
+export type StepStatus = 'complete' | 'active' | 'incomplete';
 
 export interface ProgressStepperProps extends ViewProps {
   /**
@@ -15,9 +15,9 @@ export interface ProgressStepProps extends ViewProps {
    */
   id: string;
   /**
-   * Current state of the step
+   * Current status of the step
    */
-  state: StepState;
+  status: StepStatus;
 }
 
 export interface ProgressStepperRootProps extends ViewProps {

package/src/components/ProgressStepper/ProgressStepper.stories.tsx

@@ -22,26 +22,26 @@ export const Playground: Story = {
     children: (
       <Flex space="xl" direction="column" align="center" style={{ flex: 1, minWidth: 200 }}>
         <ProgressStepper>
-          <ProgressStep id={'1'} state="complete" />
-          <ProgressStep id={'2'} state="complete" />
-          <ProgressStep id={'3'} state="active" />
-          <ProgressStep id={'4'} state="incomplete" />
+          <ProgressStep id={'1'} status="complete" />
+          <ProgressStep id={'2'} status="complete" />
+          <ProgressStep id={'3'} status="active" />
+          <ProgressStep id={'4'} status="incomplete" />
         </ProgressStepper>
         <Flex direction="row" space="lg" style={{ width: '100%' }}>
-          <ProgressStep id={'1'} state="complete" />
+          <ProgressStep id={'1'} status="complete" />
         </Flex>
         <Flex direction="row" space="lg" style={{ width: '100%' }}>
-          <ProgressStep id={'3'} state="active" />
+          <ProgressStep id={'3'} status="active" />
         </Flex>
         <Flex direction="row" space="lg" style={{ width: '100%' }}>
-          <ProgressStep id={'5'} state="incomplete" />
+          <ProgressStep id={'5'} status="incomplete" />
         </Flex>
       </Flex>
     ),
   },
 };
 
-export const StepStates: Story = {
+export const StepStatuses: Story = {
   args: {
     children: <></>,
   },
@@ -53,31 +53,31 @@ export const StepStates: Story = {
       <Flex space="xl" direction="column" align="center">
         <VariantTitle title="All Uncompleted Steps">
           <ProgressStepper {...props}>
-            <ProgressStep id={'1'} state="incomplete" />
-            <ProgressStep id={'2'} state="incomplete" />
-            <ProgressStep id={'3'} state="incomplete" />
+            <ProgressStep id={'1'} status="incomplete" />
+            <ProgressStep id={'2'} status="incomplete" />
+            <ProgressStep id={'3'} status="incomplete" />
           </ProgressStepper>
         </VariantTitle>
         <VariantTitle title="One Active Step">
           <ProgressStepper {...props}>
-            <ProgressStep id={'1'} state="active" />
-            <ProgressStep id={'2'} state="incomplete" />
-            <ProgressStep id={'3'} state="incomplete" />
+            <ProgressStep id={'1'} status="active" />
+            <ProgressStep id={'2'} status="incomplete" />
+            <ProgressStep id={'3'} status="incomplete" />
           </ProgressStepper>
         </VariantTitle>
-        <VariantTitle title="Mixed States">
+        <VariantTitle title="Mixed Statuses">
           <ProgressStepper {...props}>
-            <ProgressStep id={'1'} state="complete" />
-            <ProgressStep id={'2'} state="complete" />
-            <ProgressStep id={'3'} state="active" />
-            <ProgressStep id={'4'} state="incomplete" />
+            <ProgressStep id={'1'} status="complete" />
+            <ProgressStep id={'2'} status="complete" />
+            <ProgressStep id={'3'} status="active" />
+            <ProgressStep id={'4'} status="incomplete" />
           </ProgressStepper>
         </VariantTitle>
         <VariantTitle title="All Completed">
           <ProgressStepper {...props}>
-            <ProgressStep id={'1'} state="complete" />
-            <ProgressStep id={'2'} state="complete" />
-            <ProgressStep id={'3'} state="complete" />
+            <ProgressStep id={'1'} status="complete" />
+            <ProgressStep id={'2'} status="complete" />
+            <ProgressStep id={'3'} status="complete" />
           </ProgressStepper>
         </VariantTitle>
       </Flex>
@@ -95,11 +95,11 @@ export const BasicExample: Story = {
         <Heading size="md">Progress Stepper</Heading>
         <BodyText>Shows progress through multi-step processes</BodyText>
         <ProgressStepper {...props}>
-          <ProgressStep id="services-data" state="complete" />
-          <ProgressStep id="customer-data" state="complete" />
-          <ProgressStep id="shipping-data" state="active" />
-          <ProgressStep id="payment-data" state="incomplete" />
-          <ProgressStep id="summary" state="incomplete" />
+          <ProgressStep id="services-data" status="complete" />
+          <ProgressStep id="customer-data" status="complete" />
+          <ProgressStep id="shipping-data" status="active" />
+          <ProgressStep id="payment-data" status="incomplete" />
+          <ProgressStep id="summary" status="incomplete" />
         </ProgressStepper>
         <BodyText>Step 3 of 5</BodyText>
       </Flex>

package/src/components/ProgressStepper/index.ts

@@ -1,3 +1,3 @@
 export { default as ProgressStepper } from './ProgressStepper';
 export { default as ProgressStep } from './ProgressStep';
-export type { ProgressStepperProps, ProgressStepProps, StepState } from './ProgressStepper.props';
+export type { ProgressStepperProps, ProgressStepProps, StepStatus } from './ProgressStepper.props';

package/src/components/ThemedImage/ThemedImage.docs.mdx

@@ -0,0 +1,208 @@
+import { Canvas, Controls, Meta, Story } from '@storybook/addon-docs/blocks';
+import * as ThemedImageStories from './ThemedImage.stories';
+
+<Meta title="Utility Components / Themed Image" />
+
+# Themed Image
+
+The `ThemedImage` component automatically switches between light and dark mode images or SVG components based on the current theme. It's perfect for illustrations, logos, or any visual assets that need different appearances for light and dark modes.
+
+- [Features](#features)
+- [Basic Usage](#basic-usage)
+- [Props](#props)
+- [Examples](#examples)
+
+## Features
+
+- **Automatic theme switching** - Responds to color mode changes
+- **Flexible sources** - Accepts both regular image sources and React components (like SVGs)
+- **Accessible** - Supports all standard Image accessibility props
+- **Works with svg-assets** - Seamlessly integrates with the `@utilitywarehouse/hearth-svg-assets` package
+
+## Basic Usage
+
+<Canvas of={ThemedImageStories.Playground} />
+
+## Props
+
+| Prop    | Type                                  | Required | Description                                        |
+| ------- | ------------------------------------- | -------- | -------------------------------------------------- |
+| `light` | `ImageSourcePropType \| ReactElement` | Yes      | Image source or component to display in light mode |
+| `dark`  | `ImageSourcePropType \| ReactElement` | Yes      | Image source or component to display in dark mode  |
+| ...rest | `ImageProps`                          | No       | All other standard React Native Image props        |
+
+### Additional Props
+
+`ThemedImage` extends React Native's `Image` component, so it accepts all standard `ImageProps` including:
+
+- `style` - Custom styling for the image container
+- `resizeMode` - How to resize the image when the frame doesn't match the raw image dimensions
+- `accessible` - Whether the element is an accessibility element
+- `accessibilityLabel` - Text to be announced by screen readers
+- `testID` - Used to locate this view in end-to-end tests
+
+## Examples
+
+### With SVG Assets
+
+The most common use case is with SVG components from the `@utilitywarehouse/hearth-svg-assets` package:
+
+```tsx
+import { View } from 'react-native';
+import { ThemedImage } from '@utilitywarehouse/hearth-react-native';
+import SpotBillingDark from '@utilitywarehouse/hearth-svg-assets/lib/spot-billing-dark.svg';
+import SpotBillingLight from '@utilitywarehouse/hearth-svg-assets/lib/spot-billing-light.svg';
+
+function MyComponent() {
+  return <ThemedImage light={SpotBillingLight} dark={SpotBillingDark} width={200} height={200} />;
+}
+```
+
+<Canvas of={ThemedImageStories.WithSpotIllustrations} />
+
+### With Regular Images
+
+You can also use regular image sources (not just SVG components):
+
+```tsx
+import { ThemedImage } from '@utilitywarehouse/hearth-react-native';
+import logoLight from './assets/logo-light.png';
+import logoDark from './assets/logo-dark.png';
+
+function MyComponent() {
+  return <ThemedImage light={logoLight} dark={logoDark} />;
+}
+```
+
+<Canvas of={ThemedImageStories.WithRegularImages} />
+
+### With Custom Sizes
+
+When using SVG components, control the size by passing a `style` prop with `width` and `height` to the component:
+
+<Canvas of={ThemedImageStories.WithCustomSize} />
+
+### With Accessibility
+
+Support screen readers and assistive technologies:
+
+```tsx
+import { View } from 'react-native';
+import { ThemedImage } from '@utilitywarehouse/hearth-react-native';
+import MascotEnergyDark from '@utilitywarehouse/hearth-svg-assets/lib/mascot-energy-dark.svg';
+import MascotEnergyLight from '@utilitywarehouse/hearth-svg-assets/lib/mascot-energy-light.svg';
+
+function MyComponent() {
+  return (
+    <ThemedImage
+      light={MascotEnergyLight}
+      dark={MascotEnergyDark}
+      width={150}
+      height={150}
+      accessible={true}
+      accessibilityLabel="Energy service mascot illustration"
+    />
+  );
+}
+```
+
+<Canvas of={ThemedImageStories.WithAccessibility} />
+
+## Usage with svg-assets Package
+
+The `@utilitywarehouse/hearth-svg-assets` package provides themed illustrations in three categories:
+
+### Spot Illustrations
+
+Small, focused illustrations for specific concepts:
+
+- `spot-billing` - Billing and payments
+- `spot-celebratory` - Success and celebration
+- `spot-error` - Error states
+- `spot-help` - Help and support
+- `spot-innovation` - New features
+- `spot-savings` - Cost savings
+- And more...
+
+### Mascots
+
+Service-specific character illustrations:
+
+- `mascot-energy` - Energy service
+- `mascot-broadband` - Broadband service
+- `mascot-mobile` - Mobile service
+- `mascot-insurance` - Insurance service
+- `mascot-cashback` - Cashback rewards
+
+### Scene Illustrations
+
+Large, detailed illustrations for landing pages:
+
+- `scene-energy` - Energy service scenes
+- `scene-broadband` - Broadband service scenes
+- `scene-mobile` - Mobile service scenes
+- `scene-insurance` - Insurance service scenes
+- `scene-bundle` - Service bundle scenes
+
+All assets come in both `-light.svg` and `-dark.svg` variants.
+
+## Integration with react-native-svg-transformer
+
+To use SVG files as React components in React Native, you'll need `react-native-svg-transformer`:
+
+```bash
+# Install dependencies
+npm install react-native-svg react-native-svg-transformer --save-dev
+```
+
+Configure your `metro.config.js`:
+
+```js
+const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config');
+
+const config = {
+  transformer: {
+    babelTransformerPath: require.resolve('react-native-svg-transformer'),
+  },
+  resolver: {
+    assetExts: getDefaultConfig(__dirname).resolver.assetExts.filter(ext => ext !== 'svg'),
+    sourceExts: [...getDefaultConfig(__dirname).resolver.sourceExts, 'svg'],
+  },
+};
+
+module.exports = mergeConfig(getDefaultConfig(__dirname), config);
+```
+
+Add TypeScript declarations (optional):
+
+```typescript
+// svg.d.ts
+declare module '*.svg' {
+  import React from 'react';
+  import { SvgProps } from 'react-native-svg';
+  const content: React.FC<SvgProps>;
+  export default content;
+}
+```
+
+## Best Practices
+
+1. **Always provide both variants** - Ensure you have both light and dark versions of your assets
+2. **Use appropriate sizes** - Match illustration sizes to your design specifications
+3. **Add accessibility labels** - Make your images accessible to screen readers
+4. **Consider performance** - Large SVG files may impact performance on older devices
+5. **Test in both modes** - Always test your themed images in both light and dark modes
+
+## Troubleshooting
+
+### SVG not displaying
+
+Make sure you have configured `react-native-svg-transformer` correctly and that your SVG files are valid.
+
+### Theme not switching
+
+The component uses `useColorMode` hook which relies on the Unistyles theme system. Ensure your app is properly configured with Unistyles.
+
+### TypeScript errors with SVG imports
+
+Add the TypeScript declaration file for `.svg` modules as shown in the integration section above.

package/src/components/ThemedImage/ThemedImage.props.ts

@@ -0,0 +1,15 @@
+import type { ComponentType, ReactElement } from 'react';
+import type { ImageProps, ImageSourcePropType } from 'react-native';
+
+interface ThemedImageProps extends Omit<ImageProps, 'source'> {
+  /**
+   * Image source or component to display in light mode
+   */
+  light: ImageSourcePropType | ReactElement | ComponentType<any>;
+  /**
+   * Image source or component to display in dark mode
+   */
+  dark: ImageSourcePropType | ReactElement | ComponentType<any>;
+}
+
+export default ThemedImageProps;

package/src/components/ThemedImage/ThemedImage.stories.tsx

@@ -0,0 +1,175 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import MascotEnergyDark from '@utilitywarehouse/hearth-svg-assets/lib/mascot-energy-dark.svg';
+import MascotEnergyLight from '@utilitywarehouse/hearth-svg-assets/lib/mascot-energy-light.svg';
+import SceneBroadbandDark from '@utilitywarehouse/hearth-svg-assets/lib/scene-broadband-dark.svg';
+import SceneBroadbandLight from '@utilitywarehouse/hearth-svg-assets/lib/scene-broadband-light.svg';
+import SpotBillingDark from '@utilitywarehouse/hearth-svg-assets/lib/spot-billing-dark.svg';
+import SpotBillingLight from '@utilitywarehouse/hearth-svg-assets/lib/spot-billing-light.svg';
+import { SvgProps } from 'react-native-svg';
+import pig from '../../../docs/assets/pigs.png';
+import { Box } from '../Box';
+import { ThemedImage } from './';
+
+const meta: Meta<typeof ThemedImage> = {
+  title: 'Stories / ThemedImage',
+  component: ThemedImage,
+  argTypes: {},
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'ThemedImage component that automatically switches between light and dark mode images or SVG components based on the current theme.',
+      },
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof ThemedImage>;
+
+export const Playground: Story = {
+  args: {},
+  render: () => (
+    <Box gap="200">
+      <ThemedImage
+        // @ts-ignore
+        light={<SpotBillingLight width={200} height={200} />}
+        // @ts-ignore
+        dark={<SpotBillingDark width={200} height={200} />}
+      />
+    </Box>
+  ),
+};
+
+export const WithSpotIllustrations: Story = {
+  parameters: {
+    controls: { include: [] },
+  },
+  render: () => (
+    <Box flexDirection="row" flexWrap="wrap" gap="200">
+      <ThemedImage
+        // @ts-ignore
+        light={<SpotBillingLight width={120} height={120} />}
+        // @ts-ignore
+        dark={<SpotBillingDark width={120} height={120} />}
+      />
+    </Box>
+  ),
+};
+
+export const WithMascots: Story = {
+  parameters: {
+    controls: { include: [] },
+  },
+  render: () => (
+    <Box flexDirection="row" flexWrap="wrap" gap="200" alignItems="center">
+      <ThemedImage
+        light={MascotEnergyLight as unknown as React.FC<SvgProps>}
+        dark={MascotEnergyDark as unknown as React.FC<SvgProps>}
+        width={120}
+        height={120}
+      />
+    </Box>
+  ),
+};
+
+export const WithSceneIllustrations: Story = {
+  parameters: {
+    controls: { include: [] },
+  },
+  render: () => (
+    <Box gap="200">
+      <ThemedImage
+        //  @ts-ignore
+        light={<SceneBroadbandLight width={300} height={200} />}
+        //  @ts-ignore
+        dark={<SceneBroadbandDark width={300} height={200} />}
+      />
+    </Box>
+  ),
+};
+
+export const WithRegularImages: Story = {
+  parameters: {
+    controls: { include: [] },
+    docs: {
+      description: {
+        story:
+          'ThemedImage also works with regular image sources (using `require` or `uri`), not just SVG components.',
+      },
+    },
+  },
+  render: () => (
+    <Box gap="200">
+      <ThemedImage
+        light={{
+          uri: pig,
+        }}
+        dark={{
+          uri: pig,
+        }}
+        width={200}
+        height={200}
+        style={{ width: 200, height: 200, borderRadius: 8 }}
+      />
+    </Box>
+  ),
+};
+
+export const WithCustomSize: Story = {
+  parameters: {
+    controls: { include: [] },
+    docs: {
+      description: {
+        story: 'When using SVG components, control their size with width and height props.',
+      },
+    },
+  },
+  render: () => (
+    <Box flexDirection="row" flexWrap="wrap" gap="200" alignItems="center">
+      <ThemedImage
+        // @ts-ignore
+        light={<SpotBillingLight width={80} height={80} />}
+        // @ts-ignore
+        dark={<SpotBillingDark width={80} height={80} />}
+      />
+      <ThemedImage
+        // @ts-ignore
+        light={<SpotBillingLight width={120} height={120} />}
+        // @ts-ignore
+        dark={<SpotBillingDark width={120} height={120} />}
+      />
+      <ThemedImage
+        // @ts-ignore
+        light={<SpotBillingLight width={160} height={160} />}
+        // @ts-ignore
+        dark={<SpotBillingDark width={160} height={160} />}
+      />
+    </Box>
+  ),
+};
+
+export const WithAccessibility: Story = {
+  parameters: {
+    controls: { include: [] },
+    docs: {
+      description: {
+        story:
+          'ThemedImage supports all standard Image accessibility props like `accessibilityLabel` and `accessible`.',
+      },
+    },
+  },
+  render: () => (
+    <Box gap="200">
+      <ThemedImage
+        // @ts-ignore
+        light={<MascotEnergyLight width={150} height={150} />}
+        // @ts-ignore
+        dark={<MascotEnergyDark width={150} height={150} />}
+        accessible={true}
+        accessibilityLabel="Energy service mascot illustration"
+      />
+    </Box>
+  ),
+};

package/src/components/ThemedImage/ThemedImage.tsx

@@ -0,0 +1,34 @@
+import { isValidElement } from 'react';
+import { Image } from 'react-native';
+import useColorMode from '../../hooks/useColorMode';
+import type ThemedImageProps from './ThemedImage.props';
+
+/**
+ * ThemedImage component that displays different images or components based on the current theme
+ * @param light - Image source or SVG component to display in light mode
+ * @param dark - Image source or SVG component to display in dark mode
+ * @param ...rest - All other Image props including width/height for SVG components
+ */
+const ThemedImage = ({ light, dark, ...props }: ThemedImageProps) => {
+  const [colorMode] = useColorMode();
+
+  const source = colorMode === 'light' ? light : dark;
+
+  // If the source is a React element (like an SVG component), render it directly
+  if (isValidElement(source)) {
+    return source;
+  }
+
+  // If the source is a component type (function/class), instantiate it with props
+  if (typeof source === 'function') {
+    const Source = source as React.ComponentType<any>;
+    return <Source {...props} />;
+  }
+
+  // Otherwise, render as a regular Image with the source
+  return <Image source={source} {...props} />;
+};
+
+ThemedImage.displayName = 'ThemedImage';
+
+export default ThemedImage;

package/src/components/ThemedImage/index.tsx

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

package/src/components/index.ts

@@ -10,6 +10,7 @@ export * from './Card';
 export * from './Carousel';
 export * from './Center';
 export * from './Checkbox';
+export * from './Container';
 export * from './CurrencyInput';
 export * from './DatePicker';
 export * from './DatePickerInput';
@@ -42,6 +43,7 @@ export * from './Spinner';
 export * from './Switch';
 export * from './Tabs';
 export * from './Textarea';
+export * from './ThemedImage';
 export * from './ToggleButtonCard';
 
 export {

package/src/hooks/useStyleProps.ts

@@ -1,7 +1,7 @@
 import { useMemo } from 'react';
 import { ViewStyle } from 'react-native';
-import useTheme from './useTheme';
 import { propStyleMapping, resolveThemeValue, themeStyleMapping, viewStyleProps } from '../utils';
+import useTheme from './useTheme';
 
 /**
  * Type for the return value from useStyleProps

package/src/vite-env.d.ts

@@ -4,3 +4,9 @@ declare module '*.png' {
   const value: any;
   export default value;
 }
+declare module '*.svg' {
+  import React from 'react';
+  import { SvgProps } from 'react-native-svg';
+  const content: React.FC<SvgProps>;
+  export default content;
+}