@utilitywarehouse/hearth-react-native 0.14.0 → 0.15.0

package/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> @utilitywarehouse/hearth-react-native@0.14.0 build /home/runner/work/hearth/hearth/packages/react-native
+> @utilitywarehouse/hearth-react-native@0.15.0 build /home/runner/work/hearth/hearth/packages/react-native
 > tsc
 

package/.turbo/turbo-lint.log

@@ -1,5 +1,5 @@
 
-> @utilitywarehouse/hearth-react-native@0.14.0 lint /home/runner/work/hearth/hearth/packages/react-native
+> @utilitywarehouse/hearth-react-native@0.15.0 lint /home/runner/work/hearth/hearth/packages/react-native
 > TIMING=1 eslint --max-warnings 0
 
 Rule | Time (ms) | Relative

package/CHANGELOG.md

@@ -1,5 +1,58 @@
 # @utilitywarehouse/hearth-react-native
 
+## 0.15.0
+
+### Minor Changes
+
+- [#766](https://github.com/utilitywarehouse/hearth/pull/766) [`183155a`](https://github.com/utilitywarehouse/hearth/commit/183155a1aaf7713f0ab8a39ab1e5684ef6190d0c) Thanks [@jordmccord](https://github.com/jordmccord)! - 🌟 [FEATURE] Custom `ListItem` styles for `UL` and `OL` components
+
+  Added new props to `UL`, `OL`, and `ListItem` components to support custom list markers, including icons, images, and colors. This brings the functionality closer to CSS-like list styling. We also fixed a layout issue where list item text could overflow the container.
+
+  **Components affected**:
+
+  - `UL` (UnorderedList)
+  - `OL` (OrderedList)
+  - `ListItem`
+
+  **Developer changes**:
+
+  You can now customise list bullets/markers using the new `listStyle*` props. These can be set on the list container to apply to all items, or overridden on individual list items.
+
+  ```tsx
+  import { UL, LI } from '@utilitywarehouse/hearth-react-native';
+  import { TickIcon } from '@utilitywarehouse/hearth-react-native-icons';
+
+  <UL listStyleColour="feedbackPositiveSurfaceDefault" listStyleIcon={TickIcon}>
+    <LI>Success item 1</LI>
+    <LI listStyleColour="feedbackDangerSurfaceDefault">Error item override</LI>
+  </UL>;
+  ```
+
+  Supported props:
+
+  - `listStyleImage`: React Element (e.g. `<Image />`)
+  - `listStyleIcon`: Icon component
+  - `listStyleWidth` / `listStyleHeight`: Dimensions for the marker (default: 20)
+  - `listStyleColour`: Color token or value for the marker
+
+### Patch Changes
+
+- [#762](https://github.com/utilitywarehouse/hearth/pull/762) [`2d2bbd2`](https://github.com/utilitywarehouse/hearth/commit/2d2bbd2ba109b9acb2e0b220766eb02c0ad5710e) Thanks [@jordmccord](https://github.com/jordmccord)! - 🐛 [FIX]: Fixes Android error when passing boolean or number as a `Checkbox` value
+
+- [#764](https://github.com/utilitywarehouse/hearth/pull/764) [`46f115d`](https://github.com/utilitywarehouse/hearth/commit/46f115dd4bd9da824496e8ec19e29276523931a1) Thanks [@jordmccord](https://github.com/jordmccord)! - 🐛 [FIX]: Fixes `HelperText` wrapping issue
+
+- [#762](https://github.com/utilitywarehouse/hearth/pull/762) [`2d2bbd2`](https://github.com/utilitywarehouse/hearth/commit/2d2bbd2ba109b9acb2e0b220766eb02c0ad5710e) Thanks [@jordmccord](https://github.com/jordmccord)! - 🐛 [FIX]: Fixes `PillGroup` `onChange` prop types
+
+- [#764](https://github.com/utilitywarehouse/hearth/pull/764) [`46f115d`](https://github.com/utilitywarehouse/hearth/commit/46f115dd4bd9da824496e8ec19e29276523931a1) Thanks [@jordmccord](https://github.com/jordmccord)! - 🐛 [FIX]: `DescriptionListItem` description disappearing when direction is `column`
+
+- [#762](https://github.com/utilitywarehouse/hearth/pull/762) [`2d2bbd2`](https://github.com/utilitywarehouse/hearth/commit/2d2bbd2ba109b9acb2e0b220766eb02c0ad5710e) Thanks [@jordmccord](https://github.com/jordmccord)! - 🐛 [FIX]: Input styles are now passed to the correct View
+
+## 0.14.1
+
+### Patch Changes
+
+- [#749](https://github.com/utilitywarehouse/hearth/pull/749) [`ded4b2e`](https://github.com/utilitywarehouse/hearth/commit/ded4b2e3dcad9c1cc4860a13120e44a43e5f0dde) Thanks [@jordmccord](https://github.com/jordmccord)! - Fixes `CardAction` padding
+
 ## 0.14.0
 
 ### Minor Changes

package/build/components/Card/CardAction/CardActionRoot.js

@@ -120,9 +120,9 @@ const styles = StyleSheet.create(theme => ({
     withIconContainer: {
         alignItems: 'center',
         flexDirection: 'row',
-        paddingVertical: theme.components.list.item.functional.padding,
-        paddingHorizontal: theme.components.list.item.functional.padding,
-        gap: theme.components.list.item.gap,
+        paddingVertical: theme.components.cardAction.content.paddingVertical,
+        paddingHorizontal: theme.components.cardAction.content.paddingHorizontal,
+        gap: theme.components.cardAction.content.gap,
         flex: 1,
         variants: {
             hasIconContainer: {

package/build/components/Checkbox/Checkbox.d.ts

@@ -10,7 +10,7 @@ declare const CheckboxIcon: import("react").ForwardRefExoticComponent<import("re
 }>;
 declare const CheckboxLabel: import("react").ForwardRefExoticComponent<import("react").RefAttributes<import("../Label/Label.props").default> & Omit<import("../Label/Label.props").default, "ref">>;
 declare const Checkbox: {
-    ({ children, label, disabled, checked, helperIcon, helperText, invalidText, validText, validationStatus: validation, showValidationIcon, type, image, ...props }: CheckboxProps): import("react/jsx-runtime").JSX.Element;
+    ({ children, label, disabled, checked, helperIcon, helperText, invalidText, validText, validationStatus: validation, showValidationIcon, type, image, value, ...props }: CheckboxProps): import("react/jsx-runtime").JSX.Element;
     displayName: string;
 };
 declare const CheckboxTile: {

package/build/components/Checkbox/Checkbox.js

@@ -25,15 +25,13 @@ CheckboxGroup.displayName = 'CheckboxGroup';
 CheckboxIndicator.displayName = 'CheckboxIndicator';
 CheckboxIcon.displayName = 'CheckboxIcon';
 CheckboxLabel.displayName = 'CheckboxLabel';
-const Checkbox = ({ children, label, disabled, checked, helperIcon, helperText, invalidText, validText, validationStatus: validation, showValidationIcon, type = 'default', image, ...props }) => {
+const Checkbox = ({ children, label, disabled, checked, helperIcon, helperText, invalidText, validText, validationStatus: validation, showValidationIcon, type = 'default', image, value, ...props }) => {
     const { validationStatus: fieldValidationStatus } = useFormFieldContext();
     const { validationStatus: groupValidationStatus, type: groupType } = useCheckboxGroupContext();
     const validationStatus = fieldValidationStatus ?? groupValidationStatus ?? validation ?? 'initial';
     const checkboxType = groupType ?? type;
     const checkboxChildren = children ? (children) : (_jsxs(_Fragment, { children: [_jsx(CheckboxIndicator, { children: _jsx(CheckboxIcon, {}) }), image ? image : null, _jsxs(CheckboxTextContent, { children: [!!label && _jsx(CheckboxLabel, { children: label }), !!helperText && _jsx(Helper, { disabled: disabled, icon: helperIcon, text: helperText }), validationStatus === 'invalid' && !!invalidText && (_jsx(Helper, { showIcon: showValidationIcon, disabled: disabled, validationStatus: "invalid", text: invalidText })), validationStatus === 'valid' && !!validText && (_jsx(Helper, { disabled: disabled, showIcon: showValidationIcon, validationStatus: "valid", text: validText }))] })] }));
-    return (
-    // @ts-expect-error - type
-    _jsx(CheckboxComponent, { ...props, isDisabled: disabled, isChecked: checked, children: checkboxType === 'tile' ? (_jsx(CheckboxTileRoot, { children: checkboxChildren })) : (checkboxChildren) }));
+    return (_jsx(CheckboxComponent, { ...props, value: (value ?? '').toString(), isDisabled: disabled, isChecked: checked, children: checkboxType === 'tile' ? (_jsx(CheckboxTileRoot, { children: checkboxChildren })) : (checkboxChildren) }));
 };
 const CheckboxTile = ({ type = 'tile', ...props }) => {
     return _jsx(Checkbox, { ...props, type: type });

package/build/components/DescriptionList/DescriptionListItem.js

@@ -44,7 +44,14 @@ const styles = StyleSheet.create(theme => ({
         color: theme.color.text.secondary,
     },
     descriptionWrapper: {
-        flex: 1,
+        variants: {
+            direction: {
+                row: {
+                    flex: 1,
+                },
+                column: {},
+            },
+        },
     },
 }));
 export default DescriptionListItem;

package/build/components/HTMLElements/ListItem.d.ts

@@ -1,5 +1,13 @@
 import { ViewProps } from 'react-native';
-export interface ListItemProps extends ViewProps {
+import { ColorValue } from '../../types';
+export interface ListStyleProps {
+    listStyleImage?: React.ReactElement;
+    listStyleIcon?: React.ComponentType<any>;
+    listStyleWidth?: number;
+    listStyleHeight?: number;
+    listStyleColour?: ColorValue;
+}
+export interface ListItemProps extends ViewProps, ListStyleProps {
     children: ViewProps['children'];
 }
 declare const ListItem: {

package/build/components/HTMLElements/ListItem.js

@@ -7,8 +7,7 @@ const ListItem = ({ children, style, ...rest }) => {
 ListItem.displayName = 'ListItem';
 const styles = StyleSheet.create({
     item: {
-        flexDirection: 'row',
-        alignItems: 'flex-start',
+        flexShrink: 1,
     },
 });
 export default ListItem;

package/build/components/HTMLElements/OrderedList.d.ts

@@ -1,12 +1,13 @@
 import { ViewProps, ViewStyle } from 'react-native';
 import { SpaceValue } from '../../types';
-export interface OrderedListProps extends ViewProps {
+import { ListStyleProps } from './ListItem';
+export interface OrderedListProps extends ViewProps, ListStyleProps {
     children: ViewProps['children'];
     gap?: SpaceValue;
     bulletStyle?: ViewStyle;
 }
 declare const OrderedList: {
-    ({ children, gap, style, ...rest }: OrderedListProps): import("react/jsx-runtime").JSX.Element;
+    ({ children, gap, style, listStyleImage, listStyleIcon, listStyleWidth, listStyleHeight, listStyleColour, ...rest }: OrderedListProps): import("react/jsx-runtime").JSX.Element;
     displayName: string;
 };
 export default OrderedList;

package/build/components/HTMLElements/OrderedList.js

@@ -1,15 +1,40 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import React from 'react';
 import { StyleSheet, View } from 'react-native';
-import { useStyleProps } from '../../hooks';
+import { useStyleProps, useTheme } from '../../hooks';
+import { getFlattenedColorValue } from '../../utils';
 import { BodyText } from '../BodyText';
-const OrderedList = ({ children, gap = '100', style, ...rest }) => {
+const OrderedList = ({ children, gap = '100', style, listStyleImage, listStyleIcon, listStyleWidth, listStyleHeight, listStyleColour, ...rest }) => {
     const { computedStyles } = useStyleProps({ gap });
+    const theme = useTheme();
     let itemNumber = 0;
     return (_jsx(View, { style: [computedStyles, style], ...rest, children: React.Children.map(children, child => {
             if (React.isValidElement(child)) {
                 itemNumber++;
-                return (_jsxs(View, { style: styles.listItemContainer, children: [_jsx(BodyText, { style: styles.number, children: `${itemNumber}.` }), React.cloneElement(child, {})] }));
+                const childProps = child.props;
+                const image = childProps.listStyleImage ?? listStyleImage;
+                const Icon = childProps.listStyleIcon ?? listStyleIcon;
+                const width = childProps.listStyleWidth ?? listStyleWidth ?? 20;
+                const height = childProps.listStyleHeight ?? listStyleHeight ?? 20;
+                const colourRaw = childProps.listStyleColour ?? listStyleColour;
+                const colour = colourRaw ? getFlattenedColorValue(colourRaw, theme.color) : undefined;
+                let bullet;
+                if (image) {
+                    const imageEl = image;
+                    bullet = React.cloneElement(imageEl, {
+                        style: [{ width, height }, imageEl.props.style],
+                    });
+                }
+                else if (Icon) {
+                    bullet = (_jsx(Icon, { width: width, height: height, color: colour ?? theme.color.text.primary }));
+                }
+                else {
+                    bullet = (_jsx(BodyText, { style: [styles.number, colour && { color: colour }], children: `${itemNumber}.` }));
+                }
+                const isCustom = !!(image || Icon);
+                return (_jsxs(View, { style: styles.listItemContainer, children: [isCustom ? _jsx(View, { style: { marginRight: 8 }, children: bullet }) : bullet, React.cloneElement(child, {
+                            style: [childProps.style, { flex: 1 }],
+                        })] }));
             }
             return child;
         }) }));
@@ -22,7 +47,7 @@ const styles = StyleSheet.create({
     },
     number: {
         marginRight: 8,
-        lineHeight: undefined, // Allow number to align with first line of text
+        lineHeight: undefined,
     },
 });
 export default OrderedList;

package/build/components/HTMLElements/UnorderedList.d.ts

@@ -1,12 +1,13 @@
 import { ViewProps, ViewStyle } from 'react-native';
 import { SpaceValue } from '../../types';
-export interface UnorderedListProps extends ViewProps {
+import { ListStyleProps } from './ListItem';
+export interface UnorderedListProps extends ViewProps, ListStyleProps {
     children: ViewProps['children'];
     gap?: SpaceValue;
     bulletStyle?: ViewStyle;
 }
 declare const UnorderedList: {
-    ({ children, gap, style, ...rest }: UnorderedListProps): import("react/jsx-runtime").JSX.Element;
+    ({ children, gap, style, listStyleImage, listStyleIcon, listStyleWidth, listStyleHeight, listStyleColour, ...rest }: UnorderedListProps): import("react/jsx-runtime").JSX.Element;
     displayName: string;
 };
 export default UnorderedList;

package/build/components/HTMLElements/UnorderedList.js

@@ -1,13 +1,38 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import React from 'react';
 import { StyleSheet, View } from 'react-native';
-import { useStyleProps } from '../../hooks';
+import { useStyleProps, useTheme } from '../../hooks';
+import { getFlattenedColorValue } from '../../utils';
 import { BodyText } from '../BodyText';
-const UnorderedList = ({ children, gap = '100', style, ...rest }) => {
+const UnorderedList = ({ children, gap = '100', style, listStyleImage, listStyleIcon, listStyleWidth, listStyleHeight, listStyleColour, ...rest }) => {
     const { computedStyles } = useStyleProps({ gap });
+    const theme = useTheme();
     return (_jsx(View, { style: [computedStyles, style], ...rest, children: React.Children.map(children, child => {
             if (React.isValidElement(child)) {
-                return (_jsxs(View, { style: styles.listItemContainer, children: [_jsx(BodyText, { style: styles.bullet, children: "\u2022" }), React.cloneElement(child, {})] }));
+                const childProps = child.props;
+                const image = childProps.listStyleImage ?? listStyleImage;
+                const Icon = childProps.listStyleIcon ?? listStyleIcon;
+                const width = childProps.listStyleWidth ?? listStyleWidth ?? 20;
+                const height = childProps.listStyleHeight ?? listStyleHeight ?? 20;
+                const colourRaw = childProps.listStyleColour ?? listStyleColour;
+                const colour = colourRaw ? getFlattenedColorValue(colourRaw, theme.color) : undefined;
+                let bullet;
+                if (image) {
+                    const imageEl = image;
+                    bullet = React.cloneElement(imageEl, {
+                        style: [{ width, height }, imageEl.props.style],
+                    });
+                }
+                else if (Icon) {
+                    bullet = (_jsx(Icon, { width: width, height: height, color: colour ?? theme.color.text.primary }));
+                }
+                else {
+                    bullet = _jsx(BodyText, { style: [styles.bullet, colour && { color: colour }], children: "\u2022" });
+                }
+                const isCustom = !!(image || Icon);
+                return (_jsxs(View, { style: styles.listItemContainer, children: [isCustom ? _jsx(View, { style: { marginRight: 8 }, children: bullet }) : bullet, React.cloneElement(child, {
+                            style: [childProps.style, { flex: 1 }],
+                        })] }));
             }
             return child;
         }) }));
@@ -20,7 +45,7 @@ const styles = StyleSheet.create({
     },
     bullet: {
         marginRight: 8,
-        lineHeight: undefined, // Allow bullet to align with first line of text
+        lineHeight: undefined,
     },
 });
 export default UnorderedList;

package/build/components/Helper/Helper.js

@@ -23,7 +23,7 @@ const styles = StyleSheet.create(theme => ({
     container: {
         flexDirection: 'row',
         gap: theme.components.formField.helper.gap,
-        alignItems: 'center',
+        alignItems: 'flex-start',
         variants: {
             disabled: {
                 true: {

package/build/components/Helper/HelperText.js

@@ -11,6 +11,7 @@ HelperText.displayName = 'HelperText';
 const styles = StyleSheet.create(theme => ({
     text: {
         color: theme.color.text.secondary,
+        flexShrink: 1,
         variants: {
             validationStatus: {
                 valid: {

package/build/components/Input/Input.js

@@ -19,7 +19,7 @@ export const InputComponent = createInput({
 export const InputSlot = InputComponent.Slot;
 export const InputField = InputComponent.Input;
 export const InputIcon = InputComponent.Icon;
-const Input = forwardRef(({ validationStatus = 'initial', children, disabled, focused, readonly, leadingIcon, trailingIcon, type, showPasswordToggle = true, onClear, format, loading, clearable = false, required, inBottomSheet = false, ...props }, ref) => {
+const Input = forwardRef(({ validationStatus = 'initial', children, disabled, focused, readonly, leadingIcon, trailingIcon, type, showPasswordToggle = true, onClear, format, loading, clearable = false, required, inBottomSheet = false, style, ...props }, ref) => {
     const formFieldContext = useFormFieldContext();
     const { disabled: formFieldDisabled } = formFieldContext;
     const validationStatusFromContext = formFieldContext?.validationStatus ?? validationStatus;
@@ -46,7 +46,7 @@ const Input = forwardRef(({ validationStatus = 'initial', children, disabled, fo
         }
         return undefined;
     })();
-    return (_jsx(InputComponent, { ...(children ? props : {}), validationStatus: validationStatusFromContext, isInvalid: validationStatusFromContext === 'invalid', isReadOnly: readonly, isDisabled: formFieldDisabled ?? disabled, isFocused: focused, type: type, isRequired: isRequired, children: children ? (_jsx(_Fragment, { children: children })) : (_jsxs(_Fragment, { children: [!!leadingIconComponent && (_jsx(InputSlot, { children: _jsx(InputIcon, { as: leadingIconComponent }) })), _jsx(InputField
+    return (_jsx(InputComponent, { ...(children ? props : {}), validationStatus: validationStatusFromContext, isInvalid: validationStatusFromContext === 'invalid', isReadOnly: readonly, isDisabled: formFieldDisabled ?? disabled, isFocused: focused, type: type, isRequired: isRequired, style: style, children: children ? (_jsx(_Fragment, { children: children })) : (_jsxs(_Fragment, { children: [!!leadingIconComponent && (_jsx(InputSlot, { children: _jsx(InputIcon, { as: leadingIconComponent }) })), _jsx(InputField
                 // @ts-expect-error - ref forwarding issue
                 , { 
                     // @ts-expect-error - ref forwarding issue

package/build/components/PillGroup/PillGroup.props.d.ts

@@ -1,15 +1,27 @@
 import React from 'react';
 import { ScrollViewProps, ViewStyle } from 'react-native';
-export interface PillGroupProps extends Omit<ScrollViewProps, 'horizontal' | 'contentContainerStyle' | 'showsHorizontalScrollIndicator'> {
-    /** Controlled selected value(s) */
-    value: string | string[];
-    /** Multi-select mode. Default = false */
-    multiple?: boolean;
+export interface PillGroupBaseProps extends Omit<ScrollViewProps, 'horizontal' | 'contentContainerStyle' | 'showsHorizontalScrollIndicator'> {
     /** Allow pills to wrap lines. Default = true */
     wrap?: boolean;
-    /** Handle selection changes */
-    onChange?: (value: string | string[]) => void;
     /** Children must be <Pill> elements */
     children: React.ReactNode;
     style?: ViewStyle | ViewStyle[];
 }
+interface SinglePillGroupProps extends PillGroupBaseProps {
+    /** Multi-select mode. Default = false */
+    multiple?: false;
+    /** Controlled selected value */
+    value: string;
+    /** Handle selection changes */
+    onChange?: (value: string) => void;
+}
+interface MultiPillGroupProps extends PillGroupBaseProps {
+    /** Multi-select mode. Default = false */
+    multiple: true;
+    /** Controlled selected value(s) */
+    value: string[];
+    /** Handle selection changes */
+    onChange?: (value: string[]) => void;
+}
+export type PillGroupProps = SinglePillGroupProps | MultiPillGroupProps;
+export {};

package/docs/introduction.mdx

@@ -212,6 +212,16 @@ StyleSheet.configure({
   breakpoints,
 });
 
+// For some reason react-native-reanimated's default mock doesn't mock useReducedMotion, so we need to override it here
+// as we use that method in our components.
+jest.mock('react-native-reanimated', () => {
+  return {
+    ...jest.requireActual('react-native-reanimated/mock'),
+    useReducedMotion: () => {}, // Add this line
+  };
+});
+require('react-native-reanimated').setUpTests();
+
 // rest of your setup...
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@utilitywarehouse/hearth-react-native",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Utility Warehouse React Native UI library",
   "main": "build/index.js",
   "types": "build/index.d.ts",
@@ -58,7 +58,7 @@
     "@utilitywarehouse/hearth-fonts": "^0.0.4",
     "@utilitywarehouse/hearth-react-icons": "^0.7.4",
     "@utilitywarehouse/hearth-react-native-icons": "^0.7.4",
-    "@utilitywarehouse/hearth-svg-assets": "^0.2.0",
+    "@utilitywarehouse/hearth-svg-assets": "^0.3.0",
     "@utilitywarehouse/hearth-tokens": "^0.2.2"
   },
   "peerDependencies": {

package/src/components/Card/CardAction/CardActionRoot.tsx

@@ -222,9 +222,9 @@ const styles = StyleSheet.create(theme => ({
   withIconContainer: {
     alignItems: 'center',
     flexDirection: 'row',
-    paddingVertical: theme.components.list.item.functional.padding,
-    paddingHorizontal: theme.components.list.item.functional.padding,
-    gap: theme.components.list.item.gap,
+    paddingVertical: theme.components.cardAction.content.paddingVertical,
+    paddingHorizontal: theme.components.cardAction.content.paddingHorizontal,
+    gap: theme.components.cardAction.content.gap,
     flex: 1,
     variants: {
       hasIconContainer: {

package/src/components/Checkbox/Checkbox.tsx

@@ -42,6 +42,7 @@ const Checkbox = ({
   showValidationIcon,
   type = 'default',
   image,
+  value,
   ...props
 }: CheckboxProps) => {
   const { validationStatus: fieldValidationStatus } = useFormFieldContext();
@@ -80,8 +81,12 @@ const Checkbox = ({
     </>
   );
   return (
-    // @ts-expect-error - type
-    <CheckboxComponent {...props} isDisabled={disabled} isChecked={checked}>
+    <CheckboxComponent
+      {...props}
+      value={(value ?? '').toString()}
+      isDisabled={disabled}
+      isChecked={checked}
+    >
       {checkboxType === 'tile' ? (
         <CheckboxTileRoot>{checkboxChildren}</CheckboxTileRoot>
       ) : (

package/src/components/DescriptionList/DescriptionListItem.tsx

@@ -86,7 +86,14 @@ const styles = StyleSheet.create(theme => ({
     color: theme.color.text.secondary,
   },
   descriptionWrapper: {
-    flex: 1,
+    variants: {
+      direction: {
+        row: {
+          flex: 1,
+        },
+        column: {},
+      },
+    },
   },
 }));
 

package/src/components/HTMLElements/ListItem.tsx

@@ -1,7 +1,16 @@
 import { StyleSheet, View, ViewProps } from 'react-native';
+import { ColorValue } from '../../types';
 import { BodyText } from '../BodyText';
 
-export interface ListItemProps extends ViewProps {
+export interface ListStyleProps {
+  listStyleImage?: React.ReactElement;
+  listStyleIcon?: React.ComponentType<any>;
+  listStyleWidth?: number;
+  listStyleHeight?: number;
+  listStyleColour?: ColorValue;
+}
+
+export interface ListItemProps extends ViewProps, ListStyleProps {
   children: ViewProps['children'];
 }
 
@@ -17,8 +26,7 @@ ListItem.displayName = 'ListItem';
 
 const styles = StyleSheet.create({
   item: {
-    flexDirection: 'row',
-    alignItems: 'flex-start',
+    flexShrink: 1,
   },
 });
 

package/src/components/HTMLElements/Lists.docs.mdx

@@ -1,6 +1,7 @@
-import { Meta, Canvas, Story, Controls } from '@storybook/addon-docs/blocks';
-import { UL, OL, LI, Center, BodyText } from '../..';
-import { ViewFigmaButton, BackToTopButton, UsageWrap } from '../../../docs/components';
+import { Canvas, Controls, Meta, Story } from '@storybook/addon-docs/blocks';
+import { BodyText, Center, LI, OL, UL } from '../..';
+import { BackToTopButton, UsageWrap, ViewFigmaButton } from '../../../docs/components';
+import * as UnorderedListStory from './UnorderedList.stories';
 
 <Meta title="Utility Components / UL & OL (Lists)" />
 
@@ -11,6 +12,9 @@ import { ViewFigmaButton, BackToTopButton, UsageWrap } from '../../../docs/compo
 The `UL` (Unordered List) and `OL` (Ordered List) components are used to display lists of items. `UL` displays a bulleted list, and `OL` displays a numbered list. The `LI` (List Item) component is used to define each item within these lists.
 
 - [Usage](#usage)
+  - [Unordered List (UL)](#unordered-list-ul)
+  - [Ordered List (OL)](#ordered-list-ol)
+  - [Customising List Styles](#customising-list-styles)
 - [Components](#components)
 
 ## Usage
@@ -73,32 +77,76 @@ const MyComponent = () => {
 };
 ```
 
+### Customising List Styles
+
+You can customise the appearance of list markers using props like `listStyleIcon`, `listStyleImage`, `listStyleColour`, and dimensions. These props can be applied to the `UL`/`OL` container to affect all items, or on individual `LI` components to override them.
+
+<Canvas of={UnorderedListStory.WithCustomIcon} />
+
+```tsx
+import { UL, LI } from '@utilitywarehouse/native-ui';
+import { TickMediumIcon } from '@utilitywarehouse/hearth-react-native-icons';
+import { Image } from 'react-native';
+
+const MyComponent = () => {
+  return (
+    <UL listStyleColour="feedbackDangerSurfaceDefault">
+      <LI>Primary colored bullet</LI>
+      <LI listStyleColour="feedbackPositiveSurfaceDefault">Danger colored bullet override</LI>
+      <LI listStyleIcon={TickMediumIcon}>Icon bullet</LI>
+      <LI
+        listStyleImage={<Image source={{ uri: '...' }} />}
+        listStyleWidth={20}
+        listStyleHeight={20}
+      >
+        Image bullet
+      </LI>
+    </UL>
+  );
+};
+```
+
 ## Components
 
 ### `UL`
 
 The `UL` component is a container for unordered list items. It inherits all the properties of React Native's [`View` component](https://reactnative.dev/docs/view).
 
-| Property      | Type              | Default | Description                                         |
-| ------------- | ----------------- | ------- | --------------------------------------------------- |
-| `gap`         | `SpaceValue`      | `'100'` | The gap between the list items.                     |
-| `bulletStyle` | `ViewStyle`       | -       | Custom style for the bullet points.                 |
-| `children`    | `React.ReactNode` | -       | The `LI` components to be rendered within the list. |
+| Property          | Type                  | Default | Description                                              |
+| ----------------- | --------------------- | ------- | -------------------------------------------------------- |
+| `gap`             | `SpaceValue`          | `'100'` | The gap between the list items.                          |
+| `bulletStyle`     | `ViewStyle`           | -       | Custom style for the bullet points.                      |
+| `children`        | `React.ReactNode`     | -       | The `LI` components to be rendered within the list.      |
+| `listStyleImage`  | `React.ReactElement`  | -       | Custom element (e.g. Image) to use as the bullet/marker. |
+| `listStyleIcon`   | `React.ComponentType` | -       | Custom icon component to use as the bullet/marker.       |
+| `listStyleWidth`  | `number`              | `20`    | Width of the custom bullet/marker.                       |
+| `listStyleHeight` | `number`              | `20`    | Height of the custom bullet/marker.                      |
+| `listStyleColour` | `ColorValue`          | -       | Color of the bullet/marker.                              |
 
 ### `OL`
 
 The `OL` component is a container for ordered list items. It inherits all the properties of React Native's [`View` component](https://reactnative.dev/docs/view).
 
-| Property      | Type              | Default | Description                                         |
-| ------------- | ----------------- | ------- | --------------------------------------------------- |
-| `gap`         | `SpaceValue`      | `'100'` | The gap between the list items.                     |
-| `bulletStyle` | `ViewStyle`       | -       | Custom style for the numbers.                       |
-| `children`    | `React.ReactNode` | -       | The `LI` components to be rendered within the list. |
+| Property          | Type                  | Default | Description                                              |
+| ----------------- | --------------------- | ------- | -------------------------------------------------------- |
+| `gap`             | `SpaceValue`          | `'100'` | The gap between the list items.                          |
+| `bulletStyle`     | `ViewStyle`           | -       | Custom style for the numbers.                            |
+| `children`        | `React.ReactNode`     | -       | The `LI` components to be rendered within the list.      |
+| `listStyleImage`  | `React.ReactElement`  | -       | Custom element (e.g. Image) to use as the bullet/marker. |
+| `listStyleIcon`   | `React.ComponentType` | -       | Custom icon component to use as the bullet/marker.       |
+| `listStyleWidth`  | `number`              | `20`    | Width of the custom bullet/marker.                       |
+| `listStyleHeight` | `number`              | `20`    | Height of the custom bullet/marker.                      |
+| `listStyleColour` | `ColorValue`          | -       | Color of the number/marker.                              |
 
 ### `LI`
 
 The `LI` component represents an item in a list. It wraps its children in a `BodyText` component if the children are a string. It inherits all the properties of React Native's [`View` component](https://reactnative.dev/docs/view).
 
-| Property   | Type              | Default | Description                                       |
-| ---------- | ----------------- | ------- | ------------------------------------------------- |
-| `children` | `React.ReactNode` | -       | The content to be displayed inside the list item. |
+| Property          | Type                  | Default | Description                                              |
+| ----------------- | --------------------- | ------- | -------------------------------------------------------- |
+| `children`        | `React.ReactNode`     | -       | The content to be displayed inside the list item.        |
+| `listStyleImage`  | `React.ReactElement`  | -       | Custom element (e.g. Image) to use as the bullet/marker. |
+| `listStyleIcon`   | `React.ComponentType` | -       | Custom icon component to use as the bullet/marker.       |
+| `listStyleWidth`  | `number`              | `20`    | Width of the custom bullet/marker.                       |
+| `listStyleHeight` | `number`              | `20`    | Height of the custom bullet/marker.                      |
+| `listStyleColour` | `ColorValue`          | -       | Color of the bullet/marker/number.                       |

package/src/components/HTMLElements/OrderedList.stories.tsx

@@ -1,9 +1,10 @@
 import { Meta, StoryObj } from '@storybook/react-vite';
-import OrderedList from './OrderedList';
-import ListItem from './ListItem';
 import { primitive } from '@utilitywarehouse/hearth-tokens/js';
+import { View } from 'react-native';
 import { InputType } from 'storybook/internal/types';
 import { SpaceValue } from '../../types';
+import ListItem from './ListItem';
+import OrderedList from './OrderedList';
 
 const gap: InputType = {
   options: Object.keys(primitive.space),
@@ -53,3 +54,33 @@ export const WithCustomGap: Story = {
     </OrderedList>
   ),
 };
+
+export const WithColoredNumbers: Story = {
+  render: ({ ...args }) => (
+    <OrderedList {...args} listStyleColour="piggyPink300">
+      <ListItem>Item 1</ListItem>
+      <ListItem>Item 2</ListItem>
+    </OrderedList>
+  ),
+};
+
+export const WithIconOverride: Story = {
+  render: ({ ...args }) => {
+    const CustomIcon = (props: any) => (
+      <View
+        style={{
+          width: props.width,
+          height: props.height,
+          backgroundColor: props.color || 'blue',
+          borderRadius: 4,
+        }}
+      />
+    );
+    return (
+      <OrderedList {...args} listStyleIcon={CustomIcon}>
+        <ListItem>Item 1 (overridden)</ListItem>
+        <ListItem>Item 2 (overridden)</ListItem>
+      </OrderedList>
+    );
+  },
+};

package/src/components/HTMLElements/OrderedList.tsx

@@ -1,27 +1,75 @@
 import React from 'react';
 import { StyleSheet, View, ViewProps, ViewStyle } from 'react-native';
-import { useStyleProps } from '../../hooks';
+import { useStyleProps, useTheme } from '../../hooks';
 import { SpaceValue } from '../../types';
+import { getFlattenedColorValue } from '../../utils';
 import { BodyText } from '../BodyText';
+import { ListItemProps, ListStyleProps } from './ListItem';
 
-export interface OrderedListProps extends ViewProps {
+export interface OrderedListProps extends ViewProps, ListStyleProps {
   children: ViewProps['children'];
   gap?: SpaceValue;
   bulletStyle?: ViewStyle;
 }
 
-const OrderedList = ({ children, gap = '100', style, ...rest }: OrderedListProps) => {
+const OrderedList = ({
+  children,
+  gap = '100',
+  style,
+  listStyleImage,
+  listStyleIcon,
+  listStyleWidth,
+  listStyleHeight,
+  listStyleColour,
+  ...rest
+}: OrderedListProps) => {
   const { computedStyles } = useStyleProps({ gap });
+  const theme = useTheme();
   let itemNumber = 0;
+
   return (
     <View style={[computedStyles, style]} {...rest}>
       {React.Children.map(children, child => {
         if (React.isValidElement(child)) {
           itemNumber++;
+          const childProps = child.props as ListItemProps;
+
+          const image = childProps.listStyleImage ?? listStyleImage;
+          const Icon = childProps.listStyleIcon ?? listStyleIcon;
+          const width = childProps.listStyleWidth ?? listStyleWidth ?? 20;
+          const height = childProps.listStyleHeight ?? listStyleHeight ?? 20;
+          const colourRaw = childProps.listStyleColour ?? listStyleColour;
+
+          const colour = colourRaw ? getFlattenedColorValue(colourRaw, theme.color) : undefined;
+
+          let bullet;
+          if (image) {
+            const imageEl = image as React.ReactElement<any>;
+            bullet = React.cloneElement(imageEl, {
+              style: [{ width, height }, imageEl.props.style],
+            });
+          } else if (Icon) {
+            bullet = (
+              <Icon width={width} height={height} color={colour ?? theme.color.text.primary} />
+            );
+          } else {
+            bullet = (
+              <BodyText
+                style={[styles.number, colour && { color: colour }]}
+              >{`${itemNumber}.`}</BodyText>
+            );
+          }
+
+          const isCustom = !!(image || Icon);
+
           return (
             <View style={styles.listItemContainer}>
-              <BodyText style={styles.number}>{`${itemNumber}.`}</BodyText>
-              {React.cloneElement(child as React.ReactElement<any>, {}) as ViewProps['children']}
+              {isCustom ? <View style={{ marginRight: 8 }}>{bullet}</View> : bullet}
+              {
+                React.cloneElement(child as React.ReactElement<ListItemProps>, {
+                  style: [childProps.style, { flex: 1 }],
+                }) as ViewProps['children']
+              }
             </View>
           );
         }
@@ -40,7 +88,7 @@ const styles = StyleSheet.create({
   },
   number: {
     marginRight: 8,
-    lineHeight: undefined, // Allow number to align with first line of text
+    lineHeight: undefined,
   },
 });
 

package/src/components/HTMLElements/UnorderedList.stories.tsx

@@ -1,10 +1,11 @@
-import { Meta, StoryObj } from '@storybook/react-vite';
-import UnorderedList from './UnorderedList';
-import ListItem from './ListItem';
+import { Meta, StoryObj } from '@storybook/react-native';
+import { TickMediumIcon } from '@utilitywarehouse/hearth-react-native-icons';
 import { primitive } from '@utilitywarehouse/hearth-tokens/js';
-import { InputType } from 'storybook/internal/types';
+import { Image, View } from 'react-native';
+import ListItem from './ListItem';
+import UnorderedList from './UnorderedList';
 
-const gap: InputType = {
+const gap = {
   options: Object.keys(primitive.space),
   control: 'select',
   description: 'Gap between list items.',
@@ -50,3 +51,60 @@ export const WithCustomGap: Story = {
     </UnorderedList>
   ),
 };
+
+export const WithCustomIcon: Story = {
+  render: ({ ...args }) => {
+    return (
+      <UnorderedList
+        {...args}
+        listStyleIcon={TickMediumIcon}
+        listStyleColour="feedbackDangerSurfaceDefault"
+      >
+        <ListItem>List item 1 with icon</ListItem>
+        <ListItem>List item 2 with icon</ListItem>
+        <ListItem>
+          List item 3 with icon is a long example to test alignment, lorem ipsum dolor sit amet
+        </ListItem>
+      </UnorderedList>
+    );
+  },
+};
+
+export const WithCustomImage: Story = {
+  render: ({ ...args }) => (
+    <UnorderedList
+      {...args}
+      listStyleImage={
+        <Image
+          source={{ uri: 'https://placehold.co/20x20.png' }}
+          style={{ width: 20, height: 20 }}
+        />
+      }
+    >
+      <ListItem>List item 1 with image</ListItem>
+      <ListItem>List item 2 with image</ListItem>
+    </UnorderedList>
+  ),
+};
+
+export const WithIndividualItemOverride: Story = {
+  render: ({ ...args }) => {
+    const CheckIcon = (props: any) => (
+      <View
+        style={{
+          width: props.width,
+          height: props.height,
+          backgroundColor: 'green',
+          borderRadius: 10,
+        }}
+      />
+    );
+    return (
+      <UnorderedList {...args}>
+        <ListItem>Default bullet item</ListItem>
+        <ListItem listStyleIcon={CheckIcon}>Success item</ListItem>
+        <ListItem listStyleColour="blue600">Colored bullet item</ListItem>
+      </UnorderedList>
+    );
+  },
+};

package/src/components/HTMLElements/UnorderedList.tsx

@@ -1,25 +1,69 @@
 import React from 'react';
 import { StyleSheet, View, ViewProps, ViewStyle } from 'react-native';
-import { useStyleProps } from '../../hooks';
+import { useStyleProps, useTheme } from '../../hooks';
 import { SpaceValue } from '../../types';
+import { getFlattenedColorValue } from '../../utils';
 import { BodyText } from '../BodyText';
+import { ListItemProps, ListStyleProps } from './ListItem';
 
-export interface UnorderedListProps extends ViewProps {
+export interface UnorderedListProps extends ViewProps, ListStyleProps {
   children: ViewProps['children'];
   gap?: SpaceValue;
   bulletStyle?: ViewStyle;
 }
 
-const UnorderedList = ({ children, gap = '100', style, ...rest }: UnorderedListProps) => {
+const UnorderedList = ({
+  children,
+  gap = '100',
+  style,
+  listStyleImage,
+  listStyleIcon,
+  listStyleWidth,
+  listStyleHeight,
+  listStyleColour,
+  ...rest
+}: UnorderedListProps) => {
   const { computedStyles } = useStyleProps({ gap });
+  const theme = useTheme();
+
   return (
     <View style={[computedStyles, style]} {...rest}>
       {React.Children.map(children, child => {
         if (React.isValidElement(child)) {
+          const childProps = child.props as ListItemProps;
+
+          const image = childProps.listStyleImage ?? listStyleImage;
+          const Icon = childProps.listStyleIcon ?? listStyleIcon;
+          const width = childProps.listStyleWidth ?? listStyleWidth ?? 20;
+          const height = childProps.listStyleHeight ?? listStyleHeight ?? 20;
+          const colourRaw = childProps.listStyleColour ?? listStyleColour;
+
+          const colour = colourRaw ? getFlattenedColorValue(colourRaw, theme.color) : undefined;
+
+          let bullet;
+          if (image) {
+            const imageEl = image as React.ReactElement<any>;
+            bullet = React.cloneElement(imageEl, {
+              style: [{ width, height }, imageEl.props.style],
+            });
+          } else if (Icon) {
+            bullet = (
+              <Icon width={width} height={height} color={colour ?? theme.color.text.primary} />
+            );
+          } else {
+            bullet = <BodyText style={[styles.bullet, colour && { color: colour }]}>•</BodyText>;
+          }
+
+          const isCustom = !!(image || Icon);
+
           return (
             <View style={styles.listItemContainer}>
-              <BodyText style={styles.bullet}>•</BodyText>
-              {React.cloneElement(child as React.ReactElement<any>, {}) as ViewProps['children']}
+              {isCustom ? <View style={{ marginRight: 8 }}>{bullet}</View> : bullet}
+              {
+                React.cloneElement(child as React.ReactElement<ListItemProps>, {
+                  style: [childProps.style, { flex: 1 }],
+                }) as ViewProps['children']
+              }
             </View>
           );
         }
@@ -38,7 +82,7 @@ const styles = StyleSheet.create({
   },
   bullet: {
     marginRight: 8,
-    lineHeight: undefined, // Allow bullet to align with first line of text
+    lineHeight: undefined,
   },
 });
 

package/src/components/Helper/Helper.tsx

@@ -52,7 +52,7 @@ const styles = StyleSheet.create(theme => ({
   container: {
     flexDirection: 'row',
     gap: theme.components.formField.helper.gap,
-    alignItems: 'center',
+    alignItems: 'flex-start',
     variants: {
       disabled: {
         true: {

package/src/components/Helper/HelperText.tsx

@@ -23,6 +23,7 @@ HelperText.displayName = 'HelperText';
 const styles = StyleSheet.create(theme => ({
   text: {
     color: theme.color.text.secondary,
+    flexShrink: 1,
     variants: {
       validationStatus: {
         valid: {

package/src/components/Input/Input.tsx

@@ -48,6 +48,7 @@ const Input = forwardRef<TextInput, InputProps>(
       clearable = false,
       required,
       inBottomSheet = false,
+      style,
       ...props
     },
     ref
@@ -96,6 +97,7 @@ const Input = forwardRef<TextInput, InputProps>(
         isFocused={focused}
         type={type as undefined}
         isRequired={isRequired}
+        style={style}
       >
         {children ? (
           <>{children}</>

package/src/components/PillGroup/PillGroup.props.ts

@@ -1,22 +1,36 @@
 import React from 'react';
 import { ScrollViewProps, ViewStyle } from 'react-native';
 
-export interface PillGroupProps
-  extends Omit<ScrollViewProps, 'horizontal' | 'contentContainerStyle' | 'showsHorizontalScrollIndicator'> {
-  /** Controlled selected value(s) */
-  value: string | string[];
-
-  /** Multi-select mode. Default = false */
-  multiple?: boolean;
-
+export interface PillGroupBaseProps
+  extends Omit<
+    ScrollViewProps,
+    'horizontal' | 'contentContainerStyle' | 'showsHorizontalScrollIndicator'
+  > {
   /** Allow pills to wrap lines. Default = true */
   wrap?: boolean;
 
-  /** Handle selection changes */
-  onChange?: (value: string | string[]) => void;
-
   /** Children must be <Pill> elements */
   children: React.ReactNode;
 
   style?: ViewStyle | ViewStyle[];
 }
+
+interface SinglePillGroupProps extends PillGroupBaseProps {
+  /** Multi-select mode. Default = false */
+  multiple?: false;
+  /** Controlled selected value */
+  value: string;
+  /** Handle selection changes */
+  onChange?: (value: string) => void;
+}
+
+interface MultiPillGroupProps extends PillGroupBaseProps {
+  /** Multi-select mode. Default = false */
+  multiple: true;
+  /** Controlled selected value(s) */
+  value: string[];
+  /** Handle selection changes */
+  onChange?: (value: string[]) => void;
+}
+
+export type PillGroupProps = SinglePillGroupProps | MultiPillGroupProps;

package/src/components/PillGroup/PillGroup.stories.tsx

@@ -1,12 +1,11 @@
-import React, { useState } from 'react';
 import { Meta, StoryObj } from '@storybook/react-vite';
 import { HeartMediumIcon } from '@utilitywarehouse/hearth-react-native-icons';
+import { useState } from 'react';
 import { PillGroup } from '.';
-import { Pill } from './Pill';
 import { VariantTitle } from '../../../docs/components';
 import { BodyText } from '../BodyText';
 import { Flex } from '../Flex';
-import { Heading } from '../Heading';
+import { Pill } from './Pill';
 
 const meta = {
   title: 'Stories / PillGroup',
@@ -104,7 +103,7 @@ export const WrapBehavior: Story = {
     return (
       <Flex space="xl" direction="column" align="center">
         <VariantTitle title="Wrap: False">
-          <PillGroup wrap={false} value={value1} onChange={v => setValue1(v as string)}>
+          <PillGroup wrap={false} value={value1} onChange={setValue1}>
             <Pill value="1" label="New" />
             <Pill value="2" label="Some label" />
             <Pill value="3" label="Short" />
@@ -113,7 +112,7 @@ export const WrapBehavior: Story = {
           </PillGroup>
         </VariantTitle>
         <VariantTitle title="Wrap: True">
-          <PillGroup wrap={true} value={value2} onChange={v => setValue2(v as string)}>
+          <PillGroup wrap={true} value={value2} onChange={setValue2}>
             <Pill value="6" label="New" />
             <Pill value="7" label="Some label" />
             <Pill value="8" label="Short" />
@@ -141,7 +140,7 @@ export const Multiple: Story = {
 
     return (
       <Flex space="lg" direction="column" align="center" style={{ maxWidth: 400 }}>
-        <PillGroup wrap={true} multiple value={selectedCategories} onChange={v => setSelectedCategories(v as string[])}>
+        <PillGroup wrap={true} multiple value={selectedCategories} onChange={setSelectedCategories}>
           <Pill value="unread" label="Unread" />
           <Pill value="new" label="New" icon={HeartMediumIcon} />
           <Pill value="favourites" label="My favourites" icon={HeartMediumIcon} />

package/src/components/PillGroup/PillGroup.tsx

@@ -1,4 +1,4 @@
-import React, { useMemo } from 'react';
+import { useMemo } from 'react';
 import { ScrollView } from 'react-native';
 import { StyleSheet } from 'react-native-unistyles';
 import { Box } from '../Box';
@@ -24,9 +24,9 @@ export const PillGroup = ({
           const newValue = normalizedValue.includes(pillValue)
             ? normalizedValue.filter(v => v !== pillValue)
             : [...normalizedValue, pillValue];
-          onChange?.(newValue);
+          (onChange as (value: string[]) => void)?.(newValue);
         } else {
-          onChange?.(pillValue);
+          (onChange as (value: string) => void)?.(pillValue);
         }
       },
     }),