@utilitywarehouse/hearth-react-native 0.19.1 → 0.21.0

package/src/types/utilityProps.ts

@@ -0,0 +1,410 @@
+import type { Ref } from 'react';
+import type { TextProps as RNTextProps, Text, TextStyle, ViewStyle } from 'react-native';
+import type {
+  BackgroundColorValue,
+  BorderColorValue,
+  IconColorValue,
+  TextColorValue,
+} from './semanticColorValues';
+import type {
+  BorderRadiusValue,
+  BorderWidthValue,
+  ColorValue,
+  OpacityValue,
+  RawColorValue,
+  SpaceValue,
+} from './values';
+
+// ─── Margin Props ────────────────────────────────────────────────────────────
+
+export interface MarginProps {
+  /** Margin on all sides. Accepts theme space tokens or raw values. */
+  margin?: SpaceValue;
+  /** Horizontal margin (left and right). */
+  marginHorizontal?: SpaceValue;
+  /** Vertical margin (top and bottom). */
+  marginVertical?: SpaceValue;
+  /** Top margin. */
+  marginTop?: SpaceValue;
+  /** Bottom margin. */
+  marginBottom?: SpaceValue;
+  /** Left margin. */
+  marginLeft?: SpaceValue;
+  /** Right margin. */
+  marginRight?: SpaceValue;
+  /** End margin (logical). */
+  marginEnd?: SpaceValue;
+  /** Start margin (logical). */
+  marginStart?: SpaceValue;
+  /** Shorthand: margin on all sides. */
+  m?: SpaceValue;
+  /** Shorthand: horizontal margin. */
+  mx?: SpaceValue;
+  /** Shorthand: vertical margin. */
+  my?: SpaceValue;
+  /** Shorthand: top margin. */
+  mt?: SpaceValue;
+  /** Shorthand: bottom margin. */
+  mb?: SpaceValue;
+  /** Shorthand: left margin. */
+  ml?: SpaceValue;
+  /** Shorthand: right margin. */
+  mr?: SpaceValue;
+}
+
+// ─── Padding Props ───────────────────────────────────────────────────────────
+
+export interface PaddingProps {
+  /** Padding on all sides. Accepts theme space tokens or raw values. */
+  padding?: SpaceValue;
+  /** Horizontal padding (left and right). */
+  paddingHorizontal?: SpaceValue;
+  /** Vertical padding (top and bottom). */
+  paddingVertical?: SpaceValue;
+  /** Top padding. */
+  paddingTop?: SpaceValue;
+  /** Bottom padding. */
+  paddingBottom?: SpaceValue;
+  /** Left padding. */
+  paddingLeft?: SpaceValue;
+  /** Right padding. */
+  paddingRight?: SpaceValue;
+  /** End padding (logical). */
+  paddingEnd?: SpaceValue;
+  /** Start padding (logical). */
+  paddingStart?: SpaceValue;
+  /** Shorthand: padding on all sides. */
+  p?: SpaceValue;
+  /** Shorthand: horizontal padding. */
+  px?: SpaceValue;
+  /** Shorthand: vertical padding. */
+  py?: SpaceValue;
+  /** Shorthand: top padding. */
+  pt?: SpaceValue;
+  /** Shorthand: bottom padding. */
+  pb?: SpaceValue;
+  /** Shorthand: left padding. */
+  pl?: SpaceValue;
+  /** Shorthand: right padding. */
+  pr?: SpaceValue;
+}
+
+// ─── Spacing (Gap) Props ─────────────────────────────────────────────────────
+
+export interface GapProps {
+  /** Gap between child elements. */
+  gap?: SpaceValue;
+  /** Row gap between child elements. */
+  rowGap?: SpaceValue;
+  /** Column gap between child elements. */
+  columnGap?: SpaceValue;
+}
+
+// ─── Size Props ──────────────────────────────────────────────────────────────
+
+export interface SizeProps {
+  /** Element height. Accepts theme space tokens or raw values. */
+  height?: SpaceValue;
+  /** Element width. */
+  width?: SpaceValue;
+  /** Minimum height. */
+  minHeight?: SpaceValue;
+  /** Minimum width. */
+  minWidth?: SpaceValue;
+  /** Maximum height. */
+  maxHeight?: SpaceValue;
+  /** Maximum width. */
+  maxWidth?: SpaceValue;
+  /** Shorthand: height. */
+  h?: SpaceValue;
+  /** Shorthand: width. */
+  w?: SpaceValue;
+}
+
+// ─── Position Props ──────────────────────────────────────────────────────────
+
+export interface PositionProps {
+  /** Position type. */
+  position?: ViewStyle['position'];
+  /** Top offset. */
+  top?: SpaceValue;
+  /** Bottom offset. */
+  bottom?: SpaceValue;
+  /** Left offset. */
+  left?: SpaceValue;
+  /** Right offset. */
+  right?: SpaceValue;
+  /** Logical start offset. */
+  start?: SpaceValue;
+  /** Logical end offset. */
+  end?: SpaceValue;
+  /** Z-index for stacking order. */
+  zIndex?: number;
+}
+
+// ─── Background Color Props ──────────────────────────────────────────────────
+
+export interface BackgroundColorProps {
+  /** Background color. Accepts simplified semantic background tokens. */
+  backgroundColor?: BackgroundColorValue | RawColorValue;
+  /** Shorthand: background color. */
+  bg?: BackgroundColorValue | RawColorValue;
+  /** Shorthand: background color. */
+  bgColor?: BackgroundColorValue | RawColorValue;
+}
+
+// ─── Border Color Props ──────────────────────────────────────────────────────
+
+export interface BorderColorStyleProps {
+  /** Border color. Accepts simplified semantic border tokens. */
+  borderColor?: BorderColorValue | RawColorValue;
+  /** Bottom border color. */
+  borderBottomColor?: BorderColorValue | RawColorValue;
+  /** Left border color. */
+  borderLeftColor?: BorderColorValue | RawColorValue;
+  /** Right border color. */
+  borderRightColor?: BorderColorValue | RawColorValue;
+  /** Top border color. */
+  borderTopColor?: BorderColorValue | RawColorValue;
+  /** Block border color. */
+  borderBlockColor?: BorderColorValue | RawColorValue;
+  /** Block end border color. */
+  borderBlockEndColor?: BorderColorValue | RawColorValue;
+  /** Block start border color. */
+  borderBlockStartColor?: BorderColorValue | RawColorValue;
+  /** End border color. */
+  borderEndColor?: BorderColorValue | RawColorValue;
+  /** Start border color. */
+  borderStartColor?: BorderColorValue | RawColorValue;
+}
+
+// ─── Border Width Props ──────────────────────────────────────────────────────
+
+export interface BorderWidthProps {
+  /** Border width on all sides. */
+  borderWidth?: BorderWidthValue;
+  /** Bottom border width. */
+  borderBottomWidth?: BorderWidthValue;
+  /** End border width. */
+  borderEndWidth?: BorderWidthValue;
+  /** Left border width. */
+  borderLeftWidth?: BorderWidthValue;
+  /** Right border width. */
+  borderRightWidth?: BorderWidthValue;
+  /** Start border width. */
+  borderStartWidth?: BorderWidthValue;
+  /** Top border width. */
+  borderTopWidth?: BorderWidthValue;
+}
+
+// ─── Border Radius Props ────────────────────────────────────────────────────
+
+export interface BorderRadiusProps {
+  /** Border radius on all corners. */
+  borderRadius?: BorderRadiusValue;
+  /** Bottom-end border radius. */
+  borderBottomEndRadius?: BorderRadiusValue;
+  /** Bottom-left border radius. */
+  borderBottomLeftRadius?: BorderRadiusValue;
+  /** Bottom-right border radius. */
+  borderBottomRightRadius?: BorderRadiusValue;
+  /** Bottom-start border radius. */
+  borderBottomStartRadius?: BorderRadiusValue;
+  /** Top-end border radius. */
+  borderTopEndRadius?: BorderRadiusValue;
+  /** Top-left border radius. */
+  borderTopLeftRadius?: BorderRadiusValue;
+  /** Top-right border radius. */
+  borderTopRightRadius?: BorderRadiusValue;
+  /** Top-start border radius. */
+  borderTopStartRadius?: BorderRadiusValue;
+  /** End-end border radius. */
+  borderEndEndRadius?: BorderRadiusValue;
+  /** End-start border radius. */
+  borderEndStartRadius?: BorderRadiusValue;
+  /** Start-end border radius. */
+  borderStartEndRadius?: BorderRadiusValue;
+  /** Start-start border radius. */
+  borderStartStartRadius?: BorderRadiusValue;
+  /** Shorthand: border radius on all corners. */
+  rounded?: BorderRadiusValue;
+}
+
+// ─── Border Style Props ─────────────────────────────────────────────────────
+
+export interface BorderStyleProps {
+  /** Border style. */
+  borderStyle?: ViewStyle['borderStyle'];
+  /** Border curve. */
+  borderCurve?: ViewStyle['borderCurve'];
+}
+
+// ─── Border Props (combined) ─────────────────────────────────────────────────
+
+export interface BorderProps
+  extends BorderWidthProps, BorderRadiusProps, BorderColorStyleProps, BorderStyleProps {}
+
+// ─── Flex Layout Props ───────────────────────────────────────────────────────
+
+export interface FlexLayoutProps {
+  /** Align content. */
+  alignContent?: ViewStyle['alignContent'];
+  /** Align items. */
+  alignItems?: ViewStyle['alignItems'];
+  /** Align self. */
+  alignSelf?: ViewStyle['alignSelf'];
+  /** Flex value. */
+  flex?: number;
+  /** Flex basis. */
+  flexBasis?: ViewStyle['flexBasis'];
+  /** Flex direction. */
+  flexDirection?: ViewStyle['flexDirection'];
+  /** Flex grow. */
+  flexGrow?: number;
+  /** Flex shrink. */
+  flexShrink?: number;
+  /** Flex wrap. */
+  flexWrap?: ViewStyle['flexWrap'];
+  /** Justify content. */
+  justifyContent?: ViewStyle['justifyContent'];
+}
+
+// ─── Opacity Props ───────────────────────────────────────────────────────────
+
+export interface OpacityProps {
+  /** Opacity value. */
+  opacity?: OpacityValue;
+}
+
+// ─── Shadow Props ────────────────────────────────────────────────────────────
+
+export interface ShadowProps {
+  /** Shadow color. */
+  shadowColor?: ColorValue;
+  /** Shadow offset. */
+  shadowOffset?: ViewStyle['shadowOffset'];
+  /** Shadow opacity. */
+  shadowOpacity?: number;
+  /** Shadow radius. */
+  shadowRadius?: number;
+  /** Box shadow. */
+  boxShadow?: ViewStyle['boxShadow'];
+  /** Elevation (Android). */
+  elevation?: number;
+}
+
+// ─── Outline Props ───────────────────────────────────────────────────────────
+
+export interface OutlineProps {
+  /** Outline color. */
+  outlineColor?: ColorValue;
+  /** Outline offset. */
+  outlineOffset?: number;
+  /** Outline style. */
+  outlineStyle?: ViewStyle['outlineStyle'];
+  /** Outline width. */
+  outlineWidth?: number;
+}
+
+// ─── Display Props ───────────────────────────────────────────────────────────
+
+export interface DisplayProps {
+  /** Display type. */
+  display?: ViewStyle['display'];
+  /** Overflow behavior. */
+  overflow?: ViewStyle['overflow'];
+  /** Pointer events behavior. */
+  pointerEvents?: ViewStyle['pointerEvents'];
+  /** Backface visibility. */
+  backfaceVisibility?: ViewStyle['backfaceVisibility'];
+  /** Cursor type. */
+  cursor?: ViewStyle['cursor'];
+  /** Direction for bidirectional text. */
+  direction?: ViewStyle['direction'];
+  /** Aspect ratio. */
+  aspectRatio?: ViewStyle['aspectRatio'];
+}
+
+// ─── Transform Props ────────────────────────────────────────────────────────
+
+export interface TransformProps {
+  /** Transform array. */
+  transform?: ViewStyle['transform'];
+  /** Transform origin. */
+  transformOrigin?: ViewStyle['transformOrigin'];
+}
+
+// ─── Text Color Props ────────────────────────────────────────────────────────
+
+export interface TextColorProps {
+  /** Text color. Accepts simplified semantic text tokens. */
+  color?: TextColorValue;
+}
+
+// ─── Icon Color Props ────────────────────────────────────────────────────────
+
+export interface IconColorProps {
+  /** Icon color. Accepts simplified semantic icon tokens. */
+  iconColor?: IconColorValue;
+}
+
+// ─── Common Text Props ───────────────────────────────────────────────────────
+
+/**
+ * Common text styling props shared across text components (BodyText, Heading, DetailText).
+ * Includes margin utility props, simplified semantic text color, and standard text style props.
+ */
+export interface CommonTextProps extends RNTextProps, MarginProps {
+  /** Whether to truncate text with an ellipsis. */
+  truncated?: boolean;
+  /** Whether to show strikethrough text. */
+  strikeThrough?: boolean;
+  /** Whether to underline text. */
+  underline?: boolean;
+  /** Whether to italicise text. */
+  italic?: boolean;
+  /** Text color. Accepts simplified semantic text tokens. */
+  color?: TextColorValue | RawColorValue;
+  /** Text transform (uppercase, lowercase, capitalize). */
+  textTransform?: TextStyle['textTransform'];
+  /** Text alignment. */
+  textAlign?: TextStyle['textAlign'];
+  /** Vertical text alignment. */
+  textAlignVertical?: TextStyle['textAlignVertical'];
+  /** Text decoration line. */
+  textDecorationLine?: TextStyle['textDecorationLine'];
+  /** Text decoration style. */
+  textDecorationStyle?: TextStyle['textDecorationStyle'];
+  /** Text decoration color. Accepts any color value. */
+  textDecorationColor?: ColorValue;
+  /** User select behavior. */
+  userSelect?: TextStyle['userSelect'];
+  /** Whether to use inverted (light-on-dark) text color. */
+  inverted?: boolean;
+  /** Ref to the underlying Text element. */
+  ref?: Ref<Text>;
+}
+
+// ─── Composed Groups ─────────────────────────────────────────────────────────
+
+/** All spacing-related utility props (margin, padding, gap). */
+export interface SpacingProps extends MarginProps, PaddingProps, GapProps {}
+
+/** All layout-related utility props (flex, size, position). */
+export interface LayoutProps extends FlexLayoutProps, SizeProps, PositionProps {}
+
+/**
+ * All Box-level utility style props.
+ * This is the full set of style utilities available on Box.
+ */
+export interface AllUtilityProps
+  extends
+    SpacingProps,
+    LayoutProps,
+    BackgroundColorProps,
+    BorderProps,
+    OpacityProps,
+    ShadowProps,
+    OutlineProps,
+    DisplayProps,
+    TransformProps {}

package/src/types/values.ts

@@ -57,16 +57,13 @@ export type FlattenColorKeys<T> =
       }[keyof T]
     : never;
 
+export type RawColorValue = 'transparent' | HSLA | HSL | RGB | RGBA | HEX;
+
 export type ColorValue =
   | 'currentColor'
-  | 'transparent'
+  | RawColorValue
   | FlattenColorKeys<Omit<typeof color, 'light' | 'dark'> & { white: '#ffffff'; black: '#000000' }>
   | FlattenColorKeys<(typeof color)['light']>
-  | HSLA
-  | HSL
-  | RGB
-  | RGBA
-  | HEX
   | undefined;
 
 export type BorderRadiusValue =
@@ -74,7 +71,7 @@ export type BorderRadiusValue =
   | AnimatableNumericValue
   | undefined;
 
-export type BordeWidthValue =
+export type BorderWidthValue =
   | `${keyof (typeof lightTheme)['borderWidth'] & (string | number)}`
   | number
   | undefined;

package/src/utils/coloursAsArray.ts

@@ -1,4 +1,5 @@
 import { color } from '../tokens';
+import semanticColors from '../tokens/semantic-light';
 
 const { light, ...restOfColors } = color;
 
@@ -57,3 +58,8 @@ export default function coloursAsArray(): Array<string> {
 
   return [...primitiveColors, ...primitiveColorValues, ...semanticColorValues];
 }
+
+export const backgroundColorKeys = Object.keys(semanticColors.background);
+export const borderColorKeys = Object.keys(semanticColors.border);
+export const textColorKeys = Object.keys(semanticColors.text);
+export const iconColorKeys = Object.keys(semanticColors.icon);

package/src/utils/index.ts

@@ -1,4 +1,11 @@
-export { default as coloursAsArray, extractLightColorValues } from './coloursAsArray';
+export {
+  backgroundColorKeys,
+  borderColorKeys,
+  default as coloursAsArray,
+  extractLightColorValues,
+  iconColorKeys,
+  textColorKeys,
+} from './coloursAsArray';
 export { default as formatThousands } from './formatThousands';
 export { default as getFlattenedColorValue } from './getFlattenedColorValue';
 export { getInitials } from './getInitials';

package/src/utils/styleUtils.ts

@@ -34,9 +34,15 @@ export const propStyleMapping: { [key: string]: keyof ViewStyle } = {
 };
 
 /**
- * Mapping of style props to their theme category
+ * Mapping of style props to their theme category.
+ *
+ * - `backgroundColor` maps to `theme.helpers.semanticColor.background` (simplified semantic background tokens)
+ *   with fallback to `theme.color` for full color values
+ * - `borderColor` (and variants) maps to `theme.helpers.semanticColor.border` (simplified semantic border tokens)
+ *   with fallback to `theme.color` for full color values
+ * - Other color props (shadowColor, outlineColor) still map to the full `theme.color` object
  */
-export const themeStyleMapping: { [key in keyof ViewStyle]?: string } = {
+export const themeStyleMapping: { [key: string]: string } = {
   // Space related
   top: 'space',
   bottom: 'space',
@@ -71,18 +77,20 @@ export const themeStyleMapping: { [key in keyof ViewStyle]?: string } = {
   maxHeight: 'space',
   start: 'space',
   end: 'space',
-  // Colors
-  backgroundColor: 'color',
-  borderColor: 'color',
-  borderBottomColor: 'color',
-  borderLeftColor: 'color',
-  borderRightColor: 'color',
-  borderTopColor: 'color',
-  borderBlockColor: 'color',
-  borderBlockEndColor: 'color',
-  borderBlockStartColor: 'color',
-  borderEndColor: 'color',
-  borderStartColor: 'color',
+  // Semantic background color (simplified keys: 'brand', 'primary', 'secondary')
+  backgroundColor: 'helpers.semanticColor.background',
+  // Semantic border colors (simplified keys: 'strong', 'subtle')
+  borderColor: 'helpers.semanticColor.border',
+  borderBottomColor: 'helpers.semanticColor.border',
+  borderLeftColor: 'helpers.semanticColor.border',
+  borderRightColor: 'helpers.semanticColor.border',
+  borderTopColor: 'helpers.semanticColor.border',
+  borderBlockColor: 'helpers.semanticColor.border',
+  borderBlockEndColor: 'helpers.semanticColor.border',
+  borderBlockStartColor: 'helpers.semanticColor.border',
+  borderEndColor: 'helpers.semanticColor.border',
+  borderStartColor: 'helpers.semanticColor.border',
+  // Other colors (still use the full color object for flexibility)
   outlineColor: 'color',
   shadowColor: 'color',
   // Border radii
@@ -109,6 +117,29 @@ export const themeStyleMapping: { [key in keyof ViewStyle]?: string } = {
   borderWidth: 'borderWidth',
 };
 
+/**
+ * Mapping of theme categories to their fallback categories.
+ * When a value isn't found in the primary theme category, the fallback is tried.
+ * This ensures backward compatibility with full color values.
+ */
+export const themeStyleFallbackMapping: { [key: string]: string } = {
+  'helpers.semanticColor.background': 'color',
+  'helpers.semanticColor.border': 'color',
+  'helpers.semanticColor.text': 'color',
+  'helpers.semanticColor.icon': 'color',
+};
+
+/**
+ * Mapping of custom semantic prop names to their style prop + theme category.
+ * These are props that don't correspond 1:1 with ViewStyle keys.
+ */
+export const semanticPropMapping: { [key: string]: { styleProp: string; themeKey: string } } = {
+  /** Maps iconColor prop -> resolves against theme.helpers.semanticColor.icon (semantic icon tokens) */
+  iconColor: { styleProp: 'color', themeKey: 'helpers.semanticColor.icon' },
+  /** Maps color prop -> resolves against theme.helpers.semanticColor.text (semantic text tokens) */
+  color: { styleProp: 'color', themeKey: 'helpers.semanticColor.text' },
+};
+
 /**
  * Set of all possible ViewStyle property names
  */

package/src/utils/themeValueHelpers.ts

@@ -58,3 +58,41 @@ export const resolveThemeValue = (value: any, themeMapping: any): any => {
   // If none of the approaches work, return the original value
   return value;
 };
+
+/**
+ * Resolve a dot-notation key against the theme object.
+ * e.g., 'semanticColor.text' -> theme.semanticColor.text
+ * Simple keys like 'space' are resolved via direct bracket access.
+ */
+export const resolveThemeKey = (theme: Record<string, any>, key: string): any => {
+  if (key.includes('.')) {
+    return key.split('.').reduce((obj, k) => obj?.[k], theme);
+  }
+  return theme[key];
+};
+
+/**
+ * Resolve a theme value with a fallback theme mapping.
+ * First tries the primary mapping (e.g., theme.semanticColor.background for simplified tokens).
+ * If not found, falls back to the secondary mapping (e.g., theme.color for full color values).
+ * This ensures backward compatibility while supporting simplified token names.
+ */
+export const resolveThemeValueWithFallback = (
+  value: any,
+  primaryMapping: any,
+  fallbackMapping?: any
+): any => {
+  const resolved = resolveThemeValue(value, primaryMapping);
+
+  // If the value was resolved (changed from input), return it
+  if (resolved !== value) {
+    return resolved;
+  }
+
+  // If we have a fallback mapping and the primary didn't resolve, try the fallback
+  if (fallbackMapping) {
+    return resolveThemeValue(value, fallbackMapping);
+  }
+
+  return resolved;
+};

package/src/components/Radio/RadioTileRoot.figma.tsx

@@ -1,31 +0,0 @@
-import React from "react"
-import RadioTileRoot from "./RadioTileRoot"
-import figma from "@figma/code-connect"
-
-/**
- * -- This file was auto-generated by Code Connect --
- * None of your props could be automatically mapped to Figma properties.
- * You should update the `props` object to include a mapping from your
- * code props to Figma properties, and update the `example` function to
- * return the code example you'd like to see in Figma
- */
-
-figma.connect(
-  RadioTileRoot,
-  "https://www.figma.com/design/6NKZXZhFSExXrcbBgc6zTR?node-id=3138%3A13222",
-  {
-    props: {
-      // No matching props could be found for these Figma properties:
-      // "helperText": figma.boolean('Helper text?'),
-      // "helperText": figma.string('Helper text'),
-      // "label": figma.string('Label'),
-      // "image": figma.boolean('Image?'),
-      // "state": figma.enum('State', {
-      //   "Default": "default",
-      //   "Focus": "focus"
-      // }),
-      // "checked": figma.boolean('Checked?')
-    },
-    example: (props) => <RadioTileRoot />,
-  },
-)