@utilitywarehouse/hearth-react-native 0.4.2 → 0.6.0

package/src/components/DescriptionList/DescriptionList.docs.mdx

@@ -32,7 +32,11 @@ Display pairs of related metadata (heading + description). Supports column (stac
   >
     <DescriptionListItem heading="Account Number" description="123456789" />
     <DescriptionListItem heading="Sort Code" description="12-34-56" />
-    <DescriptionListItem heading="Status" description="Active" />
+    <DescriptionListItem
+      heading="Status"
+      description="Inactive"
+      invalidText="Status cannot be inactive"
+    />
   </DescriptionList>
 </UsageWrap>
 
@@ -42,7 +46,11 @@ import { DescriptionList, DescriptionListItem } from '@utilitywarehouse/hearth-r
 <DescriptionList direction="column" heading="Account details" helperText="Static account metadata">
   <DescriptionListItem heading="Account Number" description="123456789" />
   <DescriptionListItem heading="Sort Code" description="12-34-56" />
-  <DescriptionListItem heading="Status" description="Active" />
+  <DescriptionListItem
+    heading="Status"
+    description="Inactive"
+    invalidText="Status cannot be inactive"
+  />
 </DescriptionList>;
 ```
 
@@ -50,34 +58,23 @@ import { DescriptionList, DescriptionListItem } from '@utilitywarehouse/hearth-r
 
 ### DescriptionList
 
-| Prop               | Type                                         | Description                                      | Default     |
-| ------------------ | -------------------------------------------- | ------------------------------------------------ | ----------- |
-| `direction`        | `'row' \| 'column'`                          | Layout orientation                               | `column`    |
-| `itemHeadingWidth` | `number`                                     | Override heading column width in row layout      | token value |
-| `heading`          | `string`                                     | Optional overall heading (renders SectionHeader) | -           |
-| `helperText`       | `string`                                     | Supporting text under heading                    | -           |
-| `linkText`         | `string`                                     | Section header link text                         | -           |
-| `linkHref`         | `string`                                     | Header link URL (web)                            | -           |
-| `linkIcon`         | `ComponentType`                              | Header link icon                                 | -           |
-| `linkIconPosition` | `'left' \| 'right'`                          | Header link icon position                        | `right`     |
-| `linkOnPress`      | `() => void`                                 | Header link press handler                        | -           |
-| `linkTarget`       | `'_blank' \| '_self' \| '_parent' \| '_top'` | Header link target                               | `_self`     |
-| `linkShowIcon`     | `boolean`                                    | Whether header link icon is shown                | `false`     |
+| Prop                    | Type                | Description                                      | Default     |
+| ----------------------- | ------------------- | ------------------------------------------------ | ----------- |
+| `direction`             | `'row' \| 'column'` | Layout orientation                               | `column`    |
+| `itemHeadingWidth`      | `number`            | Override heading column width in row layout      | token value |
+| `heading`               | `string`            | Optional overall heading (renders SectionHeader) | -           |
+| `helperText`            | `string`            | Supporting text under heading                    | -           |
+| `headerTrailingContent` | `ReactNode`         | Custom trailing content for heading (e.g. Link)  | -           |
 
 ### DescriptionListItem
 
-| Prop               | Type                                         | Description                                  | Default    |
-| ------------------ | -------------------------------------------- | -------------------------------------------- | ---------- |
-| `heading`          | `ReactNode`                                  | Heading (label) content                      | (required) |
-| `description`      | `ReactNode`                                  | Description (value) content                  | (required) |
-| `headingWidth`     | `number`                                     | Per-item heading width override (row layout) | inherits   |
-| `linkText`         | `string`                                     | Inline action link text                      | -          |
-| `linkHref`         | `string`                                     | Inline action link URL (web)                 | -          |
-| `linkIcon`         | `ComponentType`                              | Inline action link icon                      | -          |
-| `linkIconPosition` | `'left' \| 'right'`                          | Inline link icon position                    | `right`    |
-| `linkOnPress`      | `() => void`                                 | Inline link press handler                    | -          |
-| `linkTarget`       | `'_blank' \| '_self' \| '_parent' \| '_top'` | Inline link target                           | `_self`    |
-| `linkShowIcon`     | `boolean`                                    | Show inline link icon                        | `false`    |
+| Prop              | Type        | Description                                      | Default    |
+| ----------------- | ----------- | ------------------------------------------------ | ---------- |
+| `heading`         | `ReactNode` | Heading (label) content                          | (required) |
+| `description`     | `ReactNode` | Description (value) content                      | (required) |
+| `headingWidth`    | `number`    | Per-item heading width override (row layout)     | inherits   |
+| `trailingContent` | `ReactNode` | Optional trailing content (e.g. Link, Button)    | -          |
+| `invalidText`     | `string`    | Text to show under description for invalid value | -          |
 
 > Uses `theme.components.descriptionList` tokens for spacing & column width.
 

package/src/components/DescriptionList/DescriptionList.props.ts

@@ -1,4 +1,3 @@
-import { ComponentType } from 'react';
 import type { ViewProps } from 'react-native';
 
 export interface DescriptionListProps extends ViewProps {
@@ -8,13 +7,7 @@ export interface DescriptionListProps extends ViewProps {
   itemHeadingWidth?: number;
   heading?: string;
   helperText?: string;
-  linkText?: string;
-  linkHref?: string;
-  linkIcon?: ComponentType;
-  linkIconPosition?: 'left' | 'right';
-  linkOnPress?: () => void;
-  linkTarget?: '_blank' | '_self' | '_parent' | '_top';
-  linkShowIcon?: boolean;
+  headerTrailingContent?: React.ReactNode;
 }
 
 export default DescriptionListProps;

package/src/components/DescriptionList/DescriptionList.stories.tsx

@@ -2,6 +2,7 @@ import { Meta, StoryObj } from '@storybook/react-vite';
 import { DescriptionList, DescriptionListItem } from '.';
 import { VariantTitle } from '../../../docs/components';
 import { Flex } from '../Flex';
+import { Link } from '../Link';
 
 const meta: Meta<typeof DescriptionList> = {
   title: 'Stories / DescriptionList',
@@ -26,19 +27,6 @@ const meta: Meta<typeof DescriptionList> = {
       control: 'text',
       description: 'Supporting text shown under heading (Playground only).',
     },
-    linkText: { control: 'text', description: 'Header link text (Playground only).' },
-    linkHref: { control: 'text', description: 'Header link href (web).' },
-    linkIconPosition: {
-      control: 'select',
-      options: ['left', 'right'],
-      description: 'Header link icon position.',
-    },
-    linkShowIcon: { control: 'boolean', description: 'Show header link icon.' },
-    linkTarget: {
-      control: 'select',
-      options: ['_blank', '_self', '_parent', '_top'],
-      description: 'Header link target (web).',
-    },
   },
   args: {
     direction: 'column',
@@ -53,7 +41,7 @@ type Story = StoryObj<typeof meta>;
 const sampleData = [
   { heading: 'Account Number', description: '123456789' },
   { heading: 'Sort Code', description: '12-34-56' },
-  { heading: 'Status', description: 'Active' },
+  { heading: 'Status', description: 'Inactive', invalidText: 'Status cannot be inactive' },
 ];
 
 export const Playground: Story = {
@@ -64,6 +52,7 @@ export const Playground: Story = {
           key={item.heading}
           heading={item.heading}
           description={item.description}
+          invalidText={item.invalidText}
         />
       ))}
     </DescriptionList>
@@ -79,6 +68,7 @@ export const Row: Story = {
           key={item.heading}
           heading={item.heading}
           description={item.description}
+          invalidText={item.invalidText}
         />
       ))}
     </DescriptionList>
@@ -94,6 +84,7 @@ export const Column: Story = {
           key={item.heading}
           heading={item.heading}
           description={item.description}
+          invalidText={item.invalidText}
         />
       ))}
     </DescriptionList>
@@ -111,6 +102,7 @@ export const KitchenSink: Story = {
               key={item.heading}
               heading={item.heading}
               description={item.description}
+              invalidText={item.invalidText}
             />
           ))}
         </DescriptionList>
@@ -122,6 +114,7 @@ export const KitchenSink: Story = {
               key={item.heading}
               heading={item.heading}
               description={item.description}
+              invalidText={item.invalidText}
             />
           ))}
         </DescriptionList>
@@ -138,15 +131,16 @@ export const WithLinks: Story = {
       <DescriptionListItem
         heading="Account Number"
         description="123456789"
-        linkText="Manage"
-        linkHref="https://example.com/account"
-        linkShowIcon
+        trailingContent={<Link href="https://example.com/account">Manage account</Link>}
       />
       <DescriptionListItem
         heading="Status"
         description="Active"
-        linkText="Change"
-        linkHref="https://example.com/status"
+        trailingContent={
+          <Link href="https://example.com/status" showIcon={false}>
+            Change
+          </Link>
+        }
       />
       <DescriptionListItem heading="Region" description="United Kingdom" />
     </DescriptionList>

package/src/components/DescriptionList/DescriptionList.tsx

@@ -10,13 +10,7 @@ const DescriptionList = ({
   itemHeadingWidth,
   heading,
   helperText,
-  linkText,
-  linkHref,
-  linkIcon,
-  linkIconPosition,
-  linkOnPress,
-  linkTarget,
-  linkShowIcon,
+  headerTrailingContent,
   children,
   style,
   ...props
@@ -31,13 +25,7 @@ const DescriptionList = ({
           <SectionHeader
             heading={heading}
             helperText={helperText}
-            linkText={linkText}
-            linkHref={linkHref}
-            linkIcon={linkIcon}
-            linkIconPosition={linkIconPosition}
-            linkOnPress={linkOnPress}
-            linkTarget={linkTarget}
-            linkShowIcon={linkShowIcon}
+            trailingContent={headerTrailingContent}
           />
         ) : null}
         {children}

package/src/components/DescriptionList/DescriptionListItem.props.ts

@@ -1,4 +1,4 @@
-import type { ComponentType, ReactNode } from 'react';
+import type { ReactNode } from 'react';
 import type { ViewProps } from 'react-native';
 
 export interface DescriptionListItemProps extends ViewProps {
@@ -7,13 +7,8 @@ export interface DescriptionListItemProps extends ViewProps {
   /** Description / value part */
   description: ReactNode;
   headingWidth?: number;
-  linkText?: string;
-  linkHref?: string;
-  linkIcon?: ComponentType;
-  linkIconPosition?: 'left' | 'right';
-  linkOnPress?: () => void;
-  linkTarget?: '_blank' | '_self' | '_parent' | '_top';
-  linkShowIcon?: boolean;
+  trailingContent?: ReactNode;
+  invalidText?: string;
 }
 
 export default DescriptionListItemProps;

package/src/components/DescriptionList/DescriptionListItem.tsx

@@ -1,8 +1,9 @@
+import { ErrorCircleSmallIcon } from '@utilitywarehouse/hearth-react-native-icons';
 import { View } from 'react-native';
 import { StyleSheet } from 'react-native-unistyles';
 import { useTheme } from '../../hooks';
 import { BodyText } from '../BodyText';
-import { Link } from '../Link';
+import Helper from '../Helper/Helper';
 import { useDescriptionListContext } from './DescriptionList.context';
 import type DescriptionListItemProps from './DescriptionListItem.props';
 
@@ -10,13 +11,8 @@ const DescriptionListItem = ({
   heading,
   description,
   headingWidth,
-  linkText,
-  linkHref,
-  linkIcon,
-  linkIconPosition,
-  linkOnPress,
-  linkTarget,
-  linkShowIcon,
+  trailingContent,
+  invalidText,
   style,
   ...props
 }: DescriptionListItemProps) => {
@@ -46,21 +42,17 @@ const DescriptionListItem = ({
         </View>
         <View style={styles.descriptionWrapper}>
           {descIsText ? <BodyText>{description}</BodyText> : description}
+          {!!invalidText && (
+            <Helper
+              validationStatus="invalid"
+              showIcon
+              icon={ErrorCircleSmallIcon}
+              text={invalidText || ''}
+            />
+          )}
         </View>
       </View>
-      {linkText ? (
-        <Link
-          href={linkHref}
-          onPress={linkOnPress}
-          target={linkTarget}
-          showIcon={linkShowIcon}
-          icon={linkIcon}
-          iconPosition={linkIconPosition}
-          accessibilityRole="link"
-        >
-          {linkText}
-        </Link>
-      ) : null}
+      {trailingContent ? trailingContent : null}
     </View>
   );
 };

package/src/components/IndicatorIconButton/IndicatorIconButton.docs.mdx

@@ -0,0 +1,85 @@
+import { Canvas, Controls, Meta, Story } from '@storybook/addon-docs/blocks';
+import { BellMediumIcon } from '@utilitywarehouse/hearth-react-native-icons';
+import { Box, Button, ButtonIcon, ButtonText, Center, IconButton } from '../../';
+import { BackToTopButton, UsageWrap, ViewFigmaButton } from '../../../docs/components';
+import { IndicatorIconButton } from './';
+import * as Stories from './IndicatorIconButton.stories';
+
+<Meta title="Components / Indicator Icon Button" />
+
+<BackToTopButton />
+
+<ViewFigmaButton url="https://www.figma.com/design/6NKZXZhFSExXrcbBgc6zTR/Hearth-Components?node-id=1-162" />
+
+# Indicator Icon Button
+
+The `IndicatorIconButton` component is used to trigger an action or event, such as opening a dialog or navigating to other screen. It extends the regular `UnstyledIconButton` with an optional red dot indicator in the top-right corner, useful for showing notifications or unread status.
+
+- [Playground](#playground)
+- [Usage](#usage)
+- [Props](#props)
+- [Examples](#examples)
+
+## Playground
+
+<Canvas of={Stories.Playground} />
+
+<Controls of={Stories.Playground} />
+
+## Usage
+
+<UsageWrap>
+  <Center>
+    <IndicatorIconButton
+      icon={BellMediumIcon}
+      onPress={() => console.log('Button pressed')}
+      indicator={true}
+    />
+  </Center>
+</UsageWrap>
+
+```tsx
+import { IndicatorIconButton } from '@utilitywarehouse/hearth-react-native';
+import { BellMediumIcon } from '@utilitywarehouse/hearth-react-native-icons';
+
+const MyComponent = () => {
+  const handlePress = () => {
+    console.log('Button pressed');
+  };
+  return <IndicatorIconButton icon={BellMediumIcon} onPress={handlePress} indicator={true} />;
+};
+```
+
+## Props
+
+| Property    | Type         | Description                                                | Default |
+| ----------- | ------------ | ---------------------------------------------------------- | ------- |
+| `onPress`   | `() => void` | Callback function to be called when the button is pressed. | -       |
+| `pressed`   | `boolean`    | Changes the button to a pressed state.                     | `false` |
+| `indicator` | `boolean`    | Shows a red dot indicator in the top-right corner.         | `false` |
+
+## Examples
+
+### Variants
+
+<Canvas of={Stories.Variants} />
+
+### Colour icons
+
+You can pass color as the iconStyle props:
+
+```javascript
+const { color } = useTheme();
+
+return (
+  <IndicatorIconButton {...props} iconStyle={{ color: color.energyBlue[500] }} />
+)
+```
+
+It does not work on Storybook on web, only mobile.
+
+<Canvas of={Stories.Colourful} />
+
+### Adding accessability label
+
+<Canvas of={Stories.WithAccessibilityLabel} />

package/src/components/IndicatorIconButton/IndicatorIconButton.props.ts

@@ -0,0 +1,12 @@
+import { UnstyledIconButtonProps } from '../UnstyledIconButton';
+
+export type IndicatorIconButtonProps = Omit<
+  UnstyledIconButtonProps,
+  'size' | 'disabled' | 'loading'
+> & {
+  /**
+   * If `true`, displays a red dot indicator in the top-right corner.
+   * @default false
+   */
+  indicator?: boolean;
+};

package/src/components/IndicatorIconButton/IndicatorIconButton.stories.tsx

@@ -0,0 +1,142 @@
+import { Meta, StoryObj } from '@storybook/react-vite';
+import * as Icons from '@utilitywarehouse/hearth-react-native-icons';
+import { ComponentType } from 'react';
+import { VariantTitle } from '../../../docs/components';
+import { Box } from '../Box';
+import { Flex } from '../Flex';
+import { useTheme } from '../../hooks';
+import IndicatorIconButton from './IndicatorIconButton';
+
+const meta = {
+  title: 'Stories / IndicatorIconButton',
+  component: IndicatorIconButton,
+  parameters: {
+    layout: 'centered',
+  },
+  argTypes: {
+    inverted: {
+      type: 'boolean',
+      control: 'boolean',
+      description: 'To set the button to be inverted. (To only be used on `purple` backgrounds)',
+    },
+    icon: {
+      options: ['none', ...Object.keys(Icons).filter(icon => icon.includes('Medium'))],
+      control: 'select',
+      description: 'The icon component for the button.',
+    },
+    pressed: {
+      type: 'boolean',
+      control: 'boolean',
+      description: 'To set the button to be pressed.',
+    },
+    indicator: {
+      type: 'boolean',
+      control: 'boolean',
+      description: 'To show or hide the red dot indicator.',
+    },
+  },
+  args: {
+    icon: 'BellMediumIcon' as unknown as ComponentType,
+    inverted: false,
+    pressed: false,
+    indicator: true,
+  },
+} satisfies Meta<typeof IndicatorIconButton>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Playground: Story = {
+  render: args => {
+    const icon = typeof args.icon === 'string' ? Icons[args.icon as keyof typeof Icons] : args.icon;
+    return <IndicatorIconButton {...args} icon={icon} />;
+  },
+};
+
+export const Variants: Story = {
+  render: args => {
+    const icon = typeof args.icon === 'string' ? Icons[args.icon as keyof typeof Icons] : args.icon;
+    return (
+      <Flex direction="column" space="xl">
+        <Flex direction="row" space="lg">
+          <Box>
+            <VariantTitle title="Without Indicator" invert={args.inverted}>
+              <IndicatorIconButton {...args} icon={icon} indicator={false} />
+            </VariantTitle>
+          </Box>
+          <Box>
+            <VariantTitle title="With Indicator" invert={args.inverted}>
+              <IndicatorIconButton {...args} icon={icon} indicator={true} />
+            </VariantTitle>
+          </Box>
+        </Flex>
+        <Flex direction="row" space="lg">
+          <Box style={{ backgroundColor: 'purple', padding: 10, borderRadius: 8 }}>
+            <VariantTitle title="Inverted" invert={!args.inverted}>
+              <IndicatorIconButton {...args} icon={icon} inverted={true} />
+            </VariantTitle>
+          </Box>
+        </Flex>
+      </Flex>
+    );
+  },
+};
+
+export const Colourful: Story = {
+  render: args => {
+    const icon = typeof args.icon === 'string' ? Icons[args.icon as keyof typeof Icons] : args.icon;
+    const theme = useTheme();
+
+    return (
+      <Flex direction="column" space="xl">
+        <Flex direction="row" space="lg">
+          <Box>
+            <IndicatorIconButton {...args} icon={icon} iconStyle={{ color: theme.color.energyBlue[500] }} />
+          </Box>
+          <Box>
+            <IndicatorIconButton {...args} icon={icon} iconStyle={{ color: theme.color.cashbackLilac[500] }} />
+          </Box>
+        </Flex>
+      </Flex>
+    );
+  },
+};
+
+export const WithAccessibilityLabel: Story = {
+  render: args => {
+    return (
+      <Flex direction="column" space="xl">
+        <Box>
+          <VariantTitle title="Notification label" invert={args.inverted}>
+            <IndicatorIconButton
+              {...args}
+              icon={Icons.BellMediumIcon}
+              indicator={true}
+              accessibilityLabel="New notifications available"
+            />
+          </VariantTitle>
+        </Box>
+        <Box>
+          <VariantTitle title="No new actions, cashback section" invert={args.inverted}>
+            <IndicatorIconButton
+              {...args}
+              icon={Icons.CashbackCardMediumIcon}
+              indicator={false}
+              accessibilityLabel="Cashback section"
+            />
+          </VariantTitle>
+        </Box>
+        <Box>
+          <VariantTitle title="New action, cashback section" invert={args.inverted}>
+            <IndicatorIconButton
+              {...args}
+              icon={Icons.CashbackCardMediumIcon}
+              indicator={true}
+              accessibilityLabel="Cashback section, new transactions"
+            />
+          </VariantTitle>
+        </Box>
+      </Flex>
+    );
+  },
+};

package/src/components/IndicatorIconButton/IndicatorIconButton.tsx

@@ -0,0 +1,36 @@
+import React from 'react';
+import { View } from 'react-native';
+import { StyleSheet } from 'react-native-unistyles';
+import { UnstyledIconButton } from '../UnstyledIconButton';
+import { IndicatorIconButtonProps } from './IndicatorIconButton.props';
+
+const IndicatorIconButton = ({ indicator = false, ...props }: IndicatorIconButtonProps) => {
+  return (
+    <View style={styles.container}>
+      <UnstyledIconButton size="md" {...props} />
+      {indicator && <View style={styles.indicator} />}
+    </View>
+  );
+};
+
+IndicatorIconButton.displayName = 'IndicatorIconButton';
+
+const styles = StyleSheet.create(theme => ({
+  container: {
+    position: 'relative',
+    width: theme.components.iconButton.unstyled.md.width,
+    height: theme.components.iconButton.unstyled.md.height,
+  },
+  indicator: {
+    position: 'absolute',
+    top: 2,
+    right: 1,
+    width: theme.components.indicatorIconButton.indicator.width,
+    height: theme.components.indicatorIconButton.indicator.height,
+    borderRadius: theme.components.indicatorIconButton.indicator.radius,
+    backgroundColor: theme.color.interactive.destructive.surface.strong.default,
+    zIndex: 1,
+  },
+}));
+
+export default IndicatorIconButton;

package/src/components/IndicatorIconButton/index.tsx

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

package/src/components/Link/LinkText.tsx

@@ -1,15 +1,15 @@
 import { TextProps } from 'react-native';
-import { useLinkContext } from './Link.context';
 import { StyleSheet } from 'react-native-unistyles';
-import { DetailText } from '../DetailText';
+import { BodyText } from '../BodyText';
+import { useLinkContext } from './Link.context';
 
 const LinkText = ({ children, ...props }: TextProps) => {
   const { inverted, disabled, active } = useLinkContext();
   styles.useVariants({ active, inverted, disabled });
   return (
-    <DetailText size="md" {...props} style={[styles.text, props.style]}>
+    <BodyText size="md" weight="semibold" {...props} style={[styles.text, props.style]}>
       {children}
-    </DetailText>
+    </BodyText>
   );
 };
 

package/src/components/List/List.context.ts

@@ -4,7 +4,6 @@ import type ListProps from './List.props';
 export const ListContext = createContext<{
   loading?: ListProps['loading'];
   disabled?: ListProps['disabled'];
-  divider?: ListProps['divider'];
   container?: ListProps['container'];
 }>({});