@utilitywarehouse/hearth-react-native 0.16.2 → 0.18.0

package/src/components/IconButton/IconButton.docs.mdx

@@ -22,6 +22,7 @@ The `IconButton` component is used to trigger an action or event, such as openin
 - [Usage](#usage)
 - [Props](#props)
 - [Variants](#variants)
+- [Custom Color Overrides](#custom-color-overrides)
 
 ## Playground
 
@@ -63,16 +64,97 @@ const MyComponent = () => {
 
 ## Props
 
-| Property      | Type                                                                     | Description                                                | Default     |
-| ------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------- | ----------- |
-| `onPress`     | `() => void`                                                             | Callback function to be called when the button is pressed. | -           |
-| `variant`     | `'emphasis' \| 'solid' \| 'outline' \| 'ghost'`                          | The variant of the button.                                 | 'solid'     |
-| `size`        | `'xs' \| 'md' `                                                          | The size of the button.                                    | 'md'        |
-| `colorScheme` | `'highlight' \| 'affirmative \| 'destructive' \| 'functional' \| 'gold'` | The colour scheme of the button.                           | 'highlight' |
-| `loading`     | `boolean`                                                                | Changes the button to a loading state.                     | `false`     |
-| `disabled`    | `boolean`                                                                | Disables the button.                                       | `false`     |
-| `pressed`     | `boolean`                                                                | Changes the button to a pressed state.                     | `false`     |
+| Property                | Type                                                                             | Description                                                                                 | Default     |
+| ----------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ----------- |
+| `onPress`               | `() => void`                                                                     | Callback function to be called when the button is pressed.                                  | -           |
+| `variant`               | `'emphasis' \| 'solid' \| 'outline' \| 'ghost'`                                  | The variant of the button.                                                                  | 'solid'     |
+| `size`                  | `'xs' \| 'md' `                                                                  | The size of the button.                                                                     | 'md'        |
+| `colorScheme`           | `'highlight' \| 'affirmative \| 'destructive' \|`<br />` 'functional' \| 'gold'` | The colour scheme of the button.                                                            | 'highlight' |
+| `loading`               | `boolean`                                                                        | Changes the button to a loading state.                                                      | `false`     |
+| `disabled`              | `boolean`                                                                        | Disables the button.                                                                        | `false`     |
+| `pressed`               | `boolean`                                                                        | Changes the button to a pressed state.                                                      | `false`     |
+| `backgroundColor`       | `ColorValue`                                                                     | Custom background color override. Use sparingly for specific use cases only.                | -           |
+| `activeBackgroundColor` | `ColorValue`                                                                     | Custom active/pressed background color override. Use sparingly for specific use cases only. | -           |
+| `shadowColor`           | `ColorValue`                                                                     | Custom shadow color override. Use sparingly for specific use cases only.                    | -           |
 
 ## Variants
 
 <Canvas of={Stories.KitchenSink} />
+
+## Custom Color Overrides
+
+The `IconButton` component supports custom color overrides through the `backgroundColor`, `activeBackgroundColor`, and `shadowColor` props.
+
+**⚠️ Important:** These props should be used **sparingly** and only for specific use cases where brand-specific colors are required, such as service buttons (Electricity, Broadband, Mobile, Insurance, Cashback Card).
+
+For most use cases, you should use the standard `colorScheme` and `variant` props which maintain design system consistency.
+
+### Example: Service Icon Buttons
+
+<Canvas of={Stories.ServiceIconButtons} />
+
+```tsx
+import { IconButton } from '@utilitywarehouse/hearth-react-native';
+import {
+  ElectricityMediumIcon,
+  BroadbandMediumIcon,
+  MobileMediumIcon,
+  InsuranceMediumIcon,
+  CashbackCardMediumIcon,
+} from '@utilitywarehouse/hearth-react-native-icons';
+
+const MyComponent = () => {
+  return (
+    <>
+      <IconButton
+        icon={ElectricityMediumIcon}
+        backgroundColor="energyBlue200"
+        activeBackgroundColor="energyBlue300"
+        variant="emphasis"
+        shadowColor="energyBlue300"
+        onPress={() => console.log('Pressed')}
+      />
+      <IconButton
+        icon={BroadbandMediumIcon}
+        backgroundColor="broadbandGreen200"
+        activeBackgroundColor="broadbandGreen300"
+        variant="emphasis"
+        shadowColor="broadbandGreen300"
+        onPress={() => console.log('Pressed')}
+      />
+      <IconButton
+        icon={MobileMediumIcon}
+        backgroundColor="mobileRose200"
+        activeBackgroundColor="mobileRose300"
+        variant="emphasis"
+        shadowColor="mobileRose400"
+        onPress={() => console.log('Pressed')}
+      />
+      <IconButton
+        icon={InsuranceMediumIcon}
+        backgroundColor="insuranceOrange300"
+        activeBackgroundColor="insuranceOrange400"
+        variant="emphasis"
+        shadowColor="insuranceOrange400"
+        onPress={() => console.log('Pressed')}
+      />
+      <IconButton
+        icon={CashbackCardMediumIcon}
+        backgroundColor="cashbackLilac300"
+        activeBackgroundColor="cashbackLilac400"
+        variant="emphasis"
+        shadowColor="cashbackLilac500"
+        onPress={() => console.log('Pressed')}
+      />
+    </>
+  );
+};
+```
+
+### Override Props Behavior
+
+- **`backgroundColor`**: Sets the base background color of the button, overriding the color scheme's default background
+- **`activeBackgroundColor`**: Sets the background color when the button is pressed or in an active state
+- **`shadowColor`**: Sets the shadow/elevation color for the button
+
+These overrides work alongside the existing `variant` and `colorScheme` props, allowing you to maintain the structural styling while customising colors for specific branding requirements.

package/src/components/IconButton/IconButton.figma.tsx

@@ -1,16 +1,8 @@
 import figma from '@figma/code-connect';
-import IconButton from './IconButton';
-
-/**
- * -- This file was auto-generated by Code Connect --
- * `props` includes a mapping from your code props to Figma properties.
- * You should check this is correct, and update the `example` function
- * to return the code example you'd like to see in Figma
- */
+import { IconButton } from '../';
 
 figma.connect(IconButton, 'https://www.figma.com/design/6NKZXZhFSExXrcbBgc6zTR?node-id=90%3A1455', {
   props: {
-    // These props were automatically mapped based on your linked code:
     disabled: figma.enum('State', {
       Disabled: true,
     }),
@@ -18,38 +10,36 @@ figma.connect(IconButton, 'https://www.figma.com/design/6NKZXZhFSExXrcbBgc6zTR?n
       'SM-32': 'sm',
       'MD-48': 'md',
     }),
+    colorScheme: figma.enum('Color Scheme', {
+      Affirmative: 'affirmative',
+      Destructive: 'destructive',
+      Functional: 'functional',
+      Highlight: 'highlight',
+    }),
     loading: figma.enum('State', {
       Loading: true,
     }),
-    focusable: figma.enum('State', {
-      Focus: true,
-    }),
-    'aria-disabled': figma.enum('State', {
-      Disabled: true,
+    icon: figma.enum('Size', {
+      'SM-32': figma.instance('Icon-20'),
+      'MD-48': figma.instance('Icon-24'),
     }),
-    colorScheme: figma.enum('Color Scheme', {
-      Affirmative: 'affirmative',
-      Destructive: 'destructive',
+    variant: figma.enum('Variant', {
+      Emphasis: 'emphasis',
+      Solid: 'solid',
+      Outline: 'outline',
+      Ghost: 'ghost',
     }),
-    // No matching props could be found for these Figma properties:
-    // "icon24": figma.instance('Icon-24'),
-    // "icon20": figma.instance('Icon-20'),
-    // "variant": figma.enum('Variant', {
-    //   "Emphasis": "emphasis",
-    //   "Solid": "solid",
-    //   "Outline": "outline",
-    //   "Ghost": "ghost"
-    // }),
-    // "inverted": figma.boolean('Inverted?')
+    inverted: figma.boolean('Inverted?'),
   },
   example: props => (
     <IconButton
       disabled={props.disabled}
       size={props.size}
-      icon={null}
-      loading={props.loading}
-      focusable={props.focusable}
+      variant={props.variant}
+      inverted={props.inverted}
       colorScheme={props.colorScheme}
+      loading={props.loading}
+      icon={props.icon}
     />
   ),
 });

package/src/components/IconButton/IconButton.props.ts

@@ -1,6 +1,7 @@
 import type { ComponentType } from 'react';
 import type { PressableProps } from 'react-native';
 import { ViewProps } from 'react-native-svg/lib/typescript/fabric/utils';
+import { ColorValue } from '../../types';
 import { ButtonVariants } from '../Button/Button.props';
 
 export type IconButtonProps = {
@@ -22,5 +23,23 @@ export type IconButtonProps = {
    */
   loading?: boolean;
   children?: ViewProps['children'];
+  /**
+   * Custom background color override.
+   * ⚠️ Use sparingly and only for specific use cases (e.g., service buttons).
+   * @default undefined
+   */
+  backgroundColor?: ColorValue;
+  /**
+   * Custom active/pressed background color override.
+   * ⚠️ Use sparingly and only for specific use cases (e.g., service buttons).
+   * @default undefined
+   */
+  activeBackgroundColor?: ColorValue;
+  /**
+   * Custom shadow color override.
+   * ⚠️ Use sparingly and only for specific use cases (e.g., service buttons).
+   * @default undefined
+   */
+  shadowColor?: ColorValue;
 } & Omit<PressableProps, 'children'> &
   ButtonVariants;

package/src/components/IconButton/IconButton.stories.tsx

@@ -1,5 +1,12 @@
 import { Meta, StoryObj } from '@storybook/react-vite';
 import * as Icons from '@utilitywarehouse/hearth-react-native-icons';
+import {
+  BroadbandMediumIcon,
+  CashbackCardMediumIcon,
+  ElectricityMediumIcon,
+  InsuranceMediumIcon,
+  MobileMediumIcon,
+} from '@utilitywarehouse/hearth-react-native-icons';
 import { ComponentType } from 'react';
 import { IconButton, IconButtonProps } from '.';
 import { VariantTitle } from '../../../docs/components';
@@ -213,3 +220,52 @@ export const KitchenSink: Story = {
     );
   },
 };
+
+export const ServiceIconButtons: Story = {
+  render: () => {
+    return (
+      <ButtonGroup space="md">
+        <IconButton
+          icon={ElectricityMediumIcon}
+          backgroundColor="energyBlue200"
+          activeBackgroundColor="energyBlue300"
+          variant="emphasis"
+          shadowColor="energyBlue300"
+          onPress={() => console.log('Pressed')}
+        />
+        <IconButton
+          icon={BroadbandMediumIcon}
+          backgroundColor="broadbandGreen200"
+          activeBackgroundColor="broadbandGreen300"
+          variant="emphasis"
+          shadowColor="broadbandGreen300"
+          onPress={() => console.log('Pressed')}
+        />
+        <IconButton
+          icon={MobileMediumIcon}
+          backgroundColor="mobileRose200"
+          activeBackgroundColor="mobileRose300"
+          variant="emphasis"
+          shadowColor="mobileRose400"
+          onPress={() => console.log('Pressed')}
+        />
+        <IconButton
+          icon={InsuranceMediumIcon}
+          backgroundColor="insuranceOrange300"
+          activeBackgroundColor="insuranceOrange400"
+          variant="emphasis"
+          shadowColor="insuranceOrange400"
+          onPress={() => console.log('Pressed')}
+        />
+        <IconButton
+          icon={CashbackCardMediumIcon}
+          backgroundColor="cashbackLilac300"
+          activeBackgroundColor="cashbackLilac400"
+          variant="emphasis"
+          shadowColor="cashbackLilac500"
+          onPress={() => console.log('Pressed')}
+        />
+      </ButtonGroup>
+    );
+  },
+};

package/src/components/IconButton/IconButtonRoot.tsx

@@ -1,6 +1,7 @@
 import { useMemo } from 'react';
 import { Pressable, ViewStyle } from 'react-native';
 import { StyleSheet } from 'react-native-unistyles';
+import { getFlattenedColorValue } from '../../utils';
 import { IconButtonContext } from './IconButton.context';
 import type { IconButtonProps } from './IconButton.props';
 
@@ -11,6 +12,9 @@ const IconButtonRoot = ({
   size = 'md',
   inverted = false,
   states,
+  backgroundColor,
+  activeBackgroundColor,
+  shadowColor,
   ...props
 }: IconButtonProps & { states?: { active?: boolean; disabled?: boolean } }) => {
   const { active, disabled } = states || {};
@@ -21,7 +25,20 @@ const IconButtonRoot = ({
   );
   return (
     <IconButtonContext.Provider value={value}>
-      <Pressable {...props} style={[styles.container, props.style as ViewStyle]}>
+      <Pressable
+        {...props}
+        style={[
+          styles.container,
+          styles.overrides({
+            backgroundColor,
+            activeBackgroundColor,
+            shadowColor,
+            active,
+            variant,
+          }),
+          props.style as ViewStyle,
+        ]}
+      >
         {children}
       </Pressable>
     </IconButtonContext.Provider>
@@ -420,6 +437,42 @@ const styles = StyleSheet.create(theme => ({
       },
     ],
   },
+  overrides: ({ backgroundColor, activeBackgroundColor, shadowColor, active, variant }) => ({
+    ...(backgroundColor
+      ? {
+          backgroundColor: getFlattenedColorValue(backgroundColor, theme.color),
+          _web: {
+            _hover: {
+              backgroundColor: getFlattenedColorValue(
+                activeBackgroundColor ?? backgroundColor,
+                theme.color
+              ),
+            },
+            _active: {
+              backgroundColor: getFlattenedColorValue(
+                activeBackgroundColor ?? backgroundColor,
+                theme.color
+              ),
+            },
+          },
+        }
+      : {}),
+    ...(active && activeBackgroundColor
+      ? {
+          backgroundColor: getFlattenedColorValue(activeBackgroundColor, theme.color),
+        }
+      : {}),
+    ...(shadowColor && variant === 'emphasis'
+      ? {
+          boxShadow: `${theme.shadow.mobile.sm.x}px ${theme.shadow.mobile.sm.y}px ${theme.shadow.mobile.sm.spread}px ${getFlattenedColorValue(shadowColor, theme.color)}`,
+        }
+      : {}),
+    ...(active && shadowColor && variant === 'emphasis'
+      ? {
+          boxShadow: 'none',
+        }
+      : {}),
+  }),
 }));
 
 export default IconButtonRoot;

package/src/components/IconContainer/IconContainer.figma.tsx

@@ -1,19 +1,11 @@
 import figma from '@figma/code-connect';
-import IconContainer from './IconContainer';
-
-/**
- * -- This file was auto-generated by Code Connect --
- * `props` includes a mapping from your code props to Figma properties.
- * You should check this is correct, and update the `example` function
- * to return the code example you'd like to see in Figma
- */
+import { IconContainer } from '../';
 
 figma.connect(
   IconContainer,
   'https://www.figma.com/design/6NKZXZhFSExXrcbBgc6zTR?node-id=5462%3A9728',
   {
     props: {
-      // These props were automatically mapped based on your linked code:
       size: figma.enum('Size', {
         'SM-32': 'sm',
         'MD-48': 'md',
@@ -33,13 +25,15 @@ figma.connect(
         Cashback: 'cashback',
         Highlight: 'highlight',
       }),
-      // No matching props could be found for these Figma properties:
-      // "icon20": figma.instance('Icon-20'),
-      // "icon24": figma.instance('Icon-24')
+      icon: figma.enum('Size', {
+        'SM-32': figma.instance('Icon-20'),
+        'MD-48': figma.instance('Icon-24'),
+        'LG-64': figma.instance('Icon-24'),
+      }),
     },
     example: props => (
       <IconContainer
-        icon={null}
+        icon={props.icon}
         size={props.size}
         radiusNone={props.radiusNone}
         variant={props.variant}

package/src/components/IndicatorIconButton/IndicatorIconButton.figma.tsx

@@ -0,0 +1,16 @@
+import figma from '@figma/code-connect';
+import { IndicatorIconButton } from '..';
+
+figma.connect(
+  IndicatorIconButton,
+  'https://www.figma.com/design/6NKZXZhFSExXrcbBgc6zTR/Hearth-Components---Tokens?node-id=6778-10672&t=3uUSBVdxldgG5uz3-4',
+  {
+    props: {
+      indicator: figma.boolean('Indicator?'),
+      icon: figma.nestedProps('Icon Button/Unstyled', {
+        icon: figma.instance('Icon-24'),
+      }),
+    },
+    example: props => <IndicatorIconButton icon={props.icon.icon} indicator={props.indicator} />,
+  }
+);

package/src/components/Input/Input.docs.mdx

@@ -29,6 +29,8 @@ The input component is a text field that allows users to enter text, numbers, or
 - [Advanced Usage](#advanced-usage)
 - [Variants](#variants)
 - [Examples](#examples)
+  - [With Label and Helper Text](#with-label-and-helper-text)
+  - [With `prefix` and `suffix`](#with-prefix-and-suffix)
   - [With `FormField`](#with-formfield)
 - [Accessibility](#accessibility)
 
@@ -46,7 +48,7 @@ The input component is a text field that allows users to enter text, numbers, or
       <InputSlot>
         <InputIcon as={EmailMediumIcon} />
       </InputSlot>
-      <InputField placeholder="Placeholder" onChange={() => console.log('###')} />
+      <InputField placeholder="Placeholder" onChangeText={() => console.log('###')} />
     </Input>
   </Center>
 </UsageWrap>
@@ -95,8 +97,10 @@ all of the React Native [`View` props](https://reactnative.dev/docs/view).
 | required         | `boolean`                          | `true`      | Indicates that the input is required. **(Only to be used if the input has no children)**                                                                                |
 | leadingIcon      | `React.ComponentType`              | `-`         | The leading icon of the input. **(Only to be used if the input has no children)**                                                                                       |
 | trailingIcon     | `React.ComponentType`              | `-`         | The trailing icon of the input. **(Only to be used if the input has no children)**                                                                                      |
+| prefix           | `string \| React.ReactNode`        | `-`         | Content to display before the input field. **(Only to be used if the input has no children)**                                                                           |
+| suffix           | `string \| React.ReactNode`        | `-`         | Content to display after the input field. **(Only to be used if the input has no children)**                                                                            |
 | value            | `string`                           | `-`         | The value of the input. **(Only to be used if the input has no children)**                                                                                              |
-| onChange         | `function`                         | `-`         | Callback function that is triggered when the input value changes. **(Only to be used if the input has no children)** **(Only to be used if the input has no children)** |
+| onChangeText     | `function`                         | `-`         | Callback function that is triggered when the input value changes. **(Only to be used if the input has no children)** **(Only to be used if the input has no children)** |
 | onBlur           | `function`                         | `-`         | Callback function that is triggered when the input loses focus. **(Only to be used if the input has no children)**                                                      |
 | onFocus          | `function`                         | `-`         | Callback function that is triggered when the input gains focus. **(Only to be used if the input has no children)**                                                      |
 | placeholder      | `string`                           | `-`         | The placeholder text for the input. **(Only to be used if the input has no children)**                                                                                  |
@@ -113,7 +117,7 @@ The `InputField` inherits all of the React Native [`TextInput` props](https://re
 | ------------- | ---------------------- | -------- | ----------------------------------------------------------------- |
 | type          | `'text' \| 'password'` | `'text'` | The type of the input.                                            |
 | value         | `string`               | `-`      | The value of the input.                                           |
-| onChange      | `function`             | `-`      | Callback function that is triggered when the input value changes. |
+| onChangeText  | `function`             | `-`      | Callback function that is triggered when the input value changes. |
 | onBlur        | `function`             | `-`      | Callback function that is triggered when the input loses focus.   |
 | onFocus       | `function`             | `-`      | Callback function that is triggered when the input gains focus.   |
 | placeholder   | `string`               | `-`      | The placeholder text for the input.                               |
@@ -156,13 +160,12 @@ import {
   EyeOffMediumIcon,
 } from '@utilitywarehouse/hearth-react-native-icons';
 import { useState } from 'react';
-import { NativeSyntheticEvent, TextInputChangeEventData } from 'react-native';
 
 const AdvancedExample = () => {
   const [value, setValue] = useState<string>('');
   const [fieldType, setFieldType] = useState<'password' | 'text'>('password');
-  const handleChange = (e: NativeSyntheticEvent<TextInputChangeEventData>) => {
-    setValue(e.nativeEvent.text);
+  const handleChange = (text: string) => {
+    setValue(text);
   };
   const handleToggleFieldType = () => {
     setFieldType(fieldType === 'password' ? 'text' : 'password');
@@ -173,7 +176,7 @@ const AdvancedExample = () => {
         <InputIcon as={EmailMediumIcon} />
       </InputSlot>
       <InputField
-        onChange={handleChange}
+        onChangeText={handleChange}
         type={fieldType}
         value={value}
         placeholder="Secret email address"
@@ -207,7 +210,7 @@ The `Input` component can be used with a label and helper text by passing the `l
     <Input
       label="Label"
       helperText="Helper text"
-      onChange={() => console.log('###')}
+      onChangeText={() => console.log('###')}
       placeholder="Placeholder"
     />
   </Center>
@@ -218,14 +221,14 @@ import { Input } from '@utilitywarehouse/hearth-react-native';
 
 const MyComponent = () => {
   const [value, setValue] = useState('');
-  const handleChange = e => {
-    setValue(e.target.value);
+  const handleChange = text => {
+    setValue(text);
   };
   return (
     <Input
       label="Label"
       helperText="Helper text"
-      onChange={handleChange}
+      onChangeText={handleChange}
       value={value}
       placeholder="Placeholder"
     />
@@ -233,6 +236,43 @@ const MyComponent = () => {
 };
 ```
 
+## With `prefix` and `suffix`
+
+The `Input` component can be customised with `prefix` and `suffix` props to add content before or after the input field.
+
+<UsageWrap>
+  <Center>
+    <Input
+      label="Amount"
+      prefix="£"
+      suffix="GBP"
+      onChangeText={() => console.log('###')}
+      placeholder="0.00"
+    />
+  </Center>
+</UsageWrap>
+
+```tsx
+import { Input } from '@utilitywarehouse/hearth-react-native';
+
+const MyComponent = () => {
+  const [value, setValue] = useState('');
+  const handleChange = text => {
+    setValue(text);
+  };
+  return (
+    <Input
+      label="Amount"
+      prefix="£"
+      suffix="GBP"
+      onChangeText={handleChange}
+      value={value}
+      placeholder="0.00"
+    />
+  );
+};
+```
+
 ### With `FormField`
 
 The `Input` component can be used with the `FormField` component to create a custom input field.
@@ -241,7 +281,7 @@ For more information on the `FormField` componment view the [docs here](/docs/co
 <UsageWrap>
   <Center>
     <FormField label="Label" helperText="Helper text" helperPosition="bottom">
-      <Input onChange={() => console.log('###')} placeholder="Placeholder" />
+      <Input onChangeText={() => console.log('###')} placeholder="Placeholder" />
     </FormField>
   </Center>
 </UsageWrap>
@@ -251,12 +291,12 @@ import { FormField, Input } from '@utilitywarehouse/hearth-react-native';
 
 const MyComponent = () => {
   const [value, setValue] = useState('');
-  const handleChange = e => {
-    setValue(e.target.value);
+  const handleChange = text => {
+    setValue(text);
   };
   return (
     <FormField label="Label" helperText="Helper text" helperPosition="bottom">
-      <Input onChange={handleChange} value={value} placeholder="Placeholder" />
+      <Input onChangeText={handleChange} value={value} placeholder="Placeholder" />
     </FormField>
   );
 };