@praxiis/ui 0.0.1

package/src/primitives/content/Chip/Chip.types.ts

@@ -0,0 +1,234 @@
+/**
+ * Chip Component Types
+ *
+ * Type definitions for the Chip component and its related hooks/helpers.
+ * All types are explicitly exported for external consumption.
+ */
+
+import { BoxProps, ResponsiveValue, VariantProps } from "@shopify/restyle";
+import { PressableProps, StyleProp, ViewStyle } from "react-native";
+import { RestyleTheme } from "../../../core/restyle";
+import { RestyleColor } from "../../../types";
+import { IconName, IconSize } from "../Icon";
+
+// =============================================================================
+// VARIANT TYPES (Explicitly exported for external use)
+// =============================================================================
+
+/**
+ * Visual variant for the Chip component.
+ *
+ * - `filled`: Solid background with the specified color
+ * - `outlined`: Transparent background with a colored border
+ */
+export type ChipVariant = Exclude<
+  keyof RestyleTheme["chipVariants"],
+  "defaults"
+>;
+
+/**
+ * Size preset for the Chip component.
+ *
+ * - `sm`: Small - compact lists, dense UIs
+ * - `md`: Medium - default size (32px height)
+ * - `lg`: Large - prominent tags, filter chips
+ */
+export type ChipSize = Exclude<keyof RestyleTheme["chipSizes"], "defaults">;
+
+/**
+ * Text variant type for chip labels.
+ */
+export type ChipTextVariant = Exclude<keyof RestyleTheme["textVariants"], "defaults">;
+
+// =============================================================================
+// RESTYLE PROP TYPES
+// =============================================================================
+
+type ChipVariantProps = VariantProps<RestyleTheme, "chipVariants">;
+type ChipSizeProps = VariantProps<RestyleTheme, "chipSizes", "size">;
+type ChipRestyleProps = ChipVariantProps & ChipSizeProps & BoxProps<RestyleTheme>;
+
+export type BaseChipProps = ChipRestyleProps & PressableProps;
+
+// =============================================================================
+// COMPONENT PROPS
+// =============================================================================
+
+/**
+ * Props for the Chip component.
+ *
+ * @example
+ * // Basic usage
+ * <Chip label="Tag" />
+ *
+ * @example
+ * // Selectable chip
+ * <Chip
+ *   label="Option A"
+ *   onPress={handleSelect}
+ *   selected={isSelected}
+ * />
+ *
+ * @example
+ * // Dismissible chip with icon
+ * <Chip
+ *   label="Filter"
+ *   iconName="filter-list"
+ *   onDelete={handleRemove}
+ *   color="primary"
+ * />
+ */
+export interface ChipProps extends Omit<BaseChipProps, "variant" | "style"> {
+  /** Chip label text */
+  label: string;
+  /** Visual variant of the chip (supports responsive values) */
+  variant?: ResponsiveValue<ChipVariant, RestyleTheme["breakpoints"]>;
+  /** Size of the chip (supports responsive values) */
+  size?: ResponsiveValue<ChipSize, RestyleTheme["breakpoints"]>;
+  /**
+   * Color for the chip. Accepts any theme color token.
+   * @default "accentPrimary"
+   */
+  color?: RestyleColor;
+  /** Whether the chip is selected */
+  selected?: boolean;
+  /** Whether the chip is disabled */
+  disabled?: boolean;
+  /** Press handler for selectable chips */
+  onPress?: () => void;
+  /** Delete handler for dismissible chips (shows close icon) */
+  onDelete?: () => void;
+  /** Optional leading icon name */
+  iconName?: IconName;
+  /** Test ID for testing */
+  testID?: string;
+  /** Accessibility label (required for screen readers) */
+  accessibilityLabel?: string;
+  /** Accessibility hint for additional context */
+  accessibilityHint?: string;
+  /** Custom style overrides */
+  style?: StyleProp<ViewStyle>;
+}
+
+// =============================================================================
+// HOOK TYPES
+// =============================================================================
+
+/**
+ * Parameters for the useChipLogic hook.
+ */
+export interface UseChipLogicParams {
+  label: string;
+  variant: ResponsiveValue<ChipVariant, RestyleTheme["breakpoints"]>;
+  size: ResponsiveValue<ChipSize, RestyleTheme["breakpoints"]>;
+  color: RestyleColor;
+  selected: boolean;
+  disabled: boolean;
+  onPress?: () => void;
+  onDelete?: () => void;
+  accessibilityLabel?: string;
+  accessibilityHint?: string;
+}
+
+/**
+ * Return value from the useChipLogic hook.
+ */
+export interface UseChipLogicReturn {
+  /** Theme variant key for the base component */
+  themeVariantKey: "filled" | "outlined";
+  /** Text variant based on chip size */
+  textVariant: ChipTextVariant;
+  /** Text color based on variant and state */
+  textColor: RestyleColor;
+  /** Icon size based on chip size */
+  iconSize: IconSize;
+  /** Icon color based on variant and state */
+  iconColor: RestyleColor;
+  /** Container style with token keys for Restyle */
+  containerStyle: ChipStyleResult;
+  /** Accessibility props */
+  a11yProps: ChipA11yProps;
+  /** Whether the chip is interactive */
+  isInteractive: boolean;
+  /** Whether to show delete icon */
+  showDeleteIcon: boolean;
+  /** Delete icon size */
+  deleteIconSize: IconSize;
+  /** Delete icon color */
+  deleteIconColor: RestyleColor;
+  /** Accessibility hint for the delete/remove button */
+  deleteHint: string;
+}
+
+// =============================================================================
+// ACCESSIBILITY TYPES
+// =============================================================================
+
+/**
+ * Parameters for the getChipA11y function.
+ */
+export interface ChipA11yParams {
+  label: string;
+  accessibilityLabel?: string;
+  accessibilityHint?: string;
+  disabled: boolean;
+  selected: boolean;
+  isSelectable: boolean;
+  isDismissible: boolean;
+  toggleHint: string;
+  removeHint: string;
+}
+
+/**
+ * Accessibility props returned by getChipA11y.
+ */
+export interface ChipA11yProps {
+  accessibilityRole: "button" | "checkbox";
+  accessibilityLabel: string;
+  accessibilityHint?: string;
+  accessibilityState: {
+    disabled: boolean;
+    selected?: boolean;
+    checked?: boolean;
+  };
+}
+
+// =============================================================================
+// HELPER TYPES
+// =============================================================================
+
+/**
+ * Parameters for resolveChipStyle function.
+ * Note: theme is no longer needed as we return token keys instead of resolved values.
+ */
+export interface ResolveChipStyleParams {
+  variant: ChipVariant;
+  color: RestyleColor;
+  selected: boolean;
+  disabled: boolean;
+}
+
+/**
+ * Result from resolveChipStyle function.
+ * Returns token keys instead of resolved hex values to let Restyle handle resolution.
+ */
+export interface ChipStyleResult {
+  backgroundColor: RestyleColor | "transparent";
+  borderColor: RestyleColor | "transparent";
+  borderWidth: number;
+  opacity: number;
+}
+
+/**
+ * Color token mapping for chip colors.
+ */
+export interface ChipColorTokens {
+  /** Background color for filled variant */
+  filled: RestyleColor;
+  /** Border/text color for outlined variant */
+  accent: RestyleColor;
+  /** Text color for filled variant */
+  filledText: RestyleColor;
+  /** Text color for outlined variant */
+  accentText: RestyleColor;
+}

package/src/primitives/content/Chip/index.ts

@@ -0,0 +1,47 @@
+/**
+ * Chip Component Module
+ *
+ * A compact element for tags, filters, and selections.
+ *
+ * Features:
+ * - Two variants: filled, outlined
+ * - Three sizes: sm, md, lg (supports responsive values)
+ * - Five color options: primary, secondary, success, warning, error
+ * - Optional leading icon
+ * - Selectable with visual feedback
+ * - Dismissible with close button
+ * - Full accessibility support
+ *
+ * @example
+ * import { Chip } from '@/src/design-system/primitives/content/Chip';
+ *
+ * // Basic tag
+ * <Chip label="JavaScript" />
+ *
+ * // Selectable chip
+ * <Chip
+ *   label="Option A"
+ *   onPress={() => setSelected(!selected)}
+ *   selected={selected}
+ *   variant="outlined"
+ * />
+ *
+ * // Dismissible chip
+ * <Chip
+ *   label="Filter"
+ *   onDelete={() => removeFilter()}
+ *   iconName="filter-list"
+ * />
+ */
+
+export { Chip } from "./Chip";
+
+export type {
+  ChipProps,
+  ChipVariant,
+  ChipSize,
+  ChipA11yParams,
+  ChipA11yProps,
+} from "./Chip.types";
+
+export { getChipA11y } from "./Chip.a11y";

package/src/primitives/content/Chip/useChipLogic.ts

@@ -0,0 +1,167 @@
+/**
+ * Chip Logic Hook
+ *
+ * Extracts all computational logic from the Chip component.
+ * Returns memoized values for optimal render performance.
+ *
+ * Responsibilities:
+ * - Resolve responsive size prop
+ * - Calculate colors based on variant, color, and state
+ * - Compute icon sizes
+ * - Generate container styles (token keys for Restyle)
+ * - Provide accessibility props
+ *
+ * @see Chip.tsx - Component consuming this hook
+ * @see Chip.helpers.ts - Pure calculation functions
+ */
+
+import { useDesignSystem } from "../../../provider";
+import { useResponsiveProp } from "@shopify/restyle";
+import { useMemo } from "react";
+import { getChipA11y } from "./Chip.a11y";
+import {
+  getChipIconColor,
+  getChipIconSize,
+  getChipTextColor,
+  getChipTextVariant,
+  getThemeVariantKey,
+  resolveChipStyle,
+} from "./Chip.helpers";
+import { ChipSize, ChipStyleResult, ChipVariant, UseChipLogicParams, UseChipLogicReturn } from "./Chip.types";
+
+/**
+ * Orchestrates Chip rendering logic and state management.
+ * 
+ * Handles:
+ * - Responsive size and variant resolution
+ * - Theme variant key mapping for Restyle
+ * - Text variant and color calculation
+ * - Icon size and color determination
+ * - Container style computation (background, border, opacity)
+ * - Interactive state detection (press/delete handlers)
+ * - Delete icon visibility and styling
+ * - Accessibility props with selection/dismissible states
+ * 
+ * @param params - Configuration object for chip behavior
+ * @param params.label - Chip label text
+ * @param params.variant - Visual variant ('filled' | 'outlined')
+ * @param params.size - Size variant ('sm' | 'md' | 'lg')
+ * @param params.color - Theme color token
+ * @param params.selected - Whether chip is selected
+ * @param params.disabled - Whether chip is disabled
+ * @param params.onPress - Optional press handler (makes chip selectable)
+ * @param params.onDelete - Optional delete handler (shows X icon)
+ * @param params.accessibilityLabel - Custom a11y label
+ * @param params.accessibilityHint - Describes action result
+ * 
+ * @returns Computed values for rendering Chip
+ * @returns {string} themeVariantKey - Restyle theme variant identifier
+ * @returns {string} textVariant - Text component variant
+ * @returns {string} textColor - Text color token
+ * @returns {number} iconSize - Icon size in pixels
+ * @returns {string} iconColor - Icon color token
+ * @returns {ChipStyleResult} containerStyle - Container style tokens
+ * @returns {object} a11yProps - Accessibility props
+ * @returns {boolean} isInteractive - Whether chip responds to press
+ * @returns {boolean} showDeleteIcon - Whether to show delete icon
+ * @returns {number} deleteIconSize - Delete icon size in pixels
+ * @returns {string} deleteIconColor - Delete icon color token
+ * 
+ * @performance This hook uses useMemo() for expensive calculations
+ * 
+ * @example
+ * const {
+ *   themeVariantKey,
+ *   textColor,
+ *   iconSize,
+ *   containerStyle,
+ *   showDeleteIcon,
+ *   a11yProps
+ * } = useChipLogic({
+ *   label: "React",
+ *   variant: "filled",
+ *   size: "md",
+ *   color: "primary",
+ *   selected: true,
+ *   onDelete: () => removeTag("react"),
+ * });
+ */
+export function useChipLogic(params: UseChipLogicParams): UseChipLogicReturn {
+  const {
+    label,
+    variant,
+    size,
+    color,
+    selected,
+    disabled,
+    onPress,
+    onDelete,
+    accessibilityLabel,
+    accessibilityHint,
+  } = params;
+
+  const { labels: t } = useDesignSystem();
+
+  const resolvedSize = (useResponsiveProp(size) ?? "md") as ChipSize;
+  const resolvedVariant = (useResponsiveProp(variant) ?? "filled") as ChipVariant;
+
+  // Theme variant key for the base component
+  const themeVariantKey = getThemeVariantKey(resolvedVariant);
+
+  // Text styling
+  const textVariant = getChipTextVariant(resolvedSize);
+  const textColor = getChipTextColor(resolvedVariant, color, selected, disabled);
+
+  // Icon styling
+  const iconSize = getChipIconSize(resolvedSize);
+  const iconColor = getChipIconColor(resolvedVariant, color, selected, disabled);
+
+  // Interaction states
+  const isInteractive = !!onPress || !!onDelete;
+  const showDeleteIcon = !!onDelete;
+
+  // Delete icon uses same size and color as leading icon
+  const deleteIconSize = iconSize;
+  const deleteIconColor = iconColor;
+  const deleteHint = t.designSystem.chip.removeHint;
+
+  // Container style - returns token keys for Restyle to handle
+  const containerStyle: ChipStyleResult = resolveChipStyle({
+    variant: resolvedVariant,
+    color,
+    selected,
+    disabled,
+  });
+
+  // Accessibility props
+  const a11yProps = useMemo(
+    () =>
+      getChipA11y({
+        label,
+        accessibilityLabel,
+        accessibilityHint,
+        disabled,
+        selected,
+        isSelectable: !!onPress && !onDelete,
+        isDismissible: !!onDelete,
+        toggleHint: t.designSystem.chip.toggleHint,
+        removeHint: t.designSystem.chip.removeHint,
+      }),
+    [label, accessibilityLabel, accessibilityHint, disabled, selected, onPress, onDelete, t]
+  );
+
+  return {
+    themeVariantKey,
+    textVariant,
+    textColor,
+    iconSize,
+    iconColor,
+    containerStyle,
+    a11yProps,
+    isInteractive,
+    showDeleteIcon,
+    deleteIconSize,
+    deleteIconColor,
+    deleteHint,
+  };
+}

package/src/primitives/content/Icon/Icon.helpers.ts

@@ -0,0 +1,54 @@
+/**
+ * Icon Component Helpers
+ *
+ * Pure functions for resolving icon sizes and colors from the theme.
+ *
+ * ## Size Scale Reference
+ * | Size | Pixels | Use Case |
+ * |------|--------|----------|
+ * | xs   | 12px   | Badges, status dots |
+ * | sm   | 16px   | Compact buttons, dense lists |
+ * | md   | 20px   | Default, standard buttons |
+ * | lg   | 24px   | Primary actions, headers |
+ * | xl   | 32px   | Tablet headers, emphasized |
+ * | 2xl  | 40px   | Empty states, onboarding |
+ * | 3xl  | 48px   | Hero sections |
+ *
+ * @see tokens/index.ts - iconSize token definitions
+ */
+
+import { RestyleTheme } from "../../../core/restyle";
+import { BaseThemeColor, RestyleColor } from "../../../types";
+import { ResolveIconSizeParams } from "./Icon.types";
+
+/**
+ * Resolve icon size to pixel value from theme.
+ *
+ * @param params - Contains resolvedSize and theme
+ * @returns The icon size in pixels
+ *
+ * @example
+ * resolveIconSizeValue({ resolvedSize: "lg", theme }) // 24
+ */
+export function resolveIconSizeValue(params: ResolveIconSizeParams): number {
+  const { resolvedSize, theme } = params;
+  const sizeConfig = theme.iconSizes[resolvedSize];
+  return sizeConfig.width || sizeConfig.height;
+}
+
+/**
+ * Resolve icon color token to hex value from theme.
+ *
+ * @param color - Theme color token (e.g., "textPrimary", "accentPrimary")
+ * @param theme - Current Restyle theme
+ * @returns The resolved hex color string
+ *
+ * @example
+ * resolveIconColor("accentPrimary", theme) // "#A68B6A"
+ */
+export function resolveIconColor(
+  color: RestyleColor,
+  theme: RestyleTheme,
+): string {
+  return theme.colors[color as BaseThemeColor];
+}

package/src/primitives/content/Icon/Icon.tsx

@@ -0,0 +1,110 @@
+/**
+ * Icon Component
+ *
+ * @description Renders Material Icons with theme integration - Atom
+ *
+ * Icons are the most fundamental visual element in the design system.
+ * This component wraps @expo/vector-icons/MaterialIcons with Restyle
+ * theming for consistent sizing and coloring across the app.
+ *
+ * ## Size Scale
+ * | Size | Pixels | Use Case |
+ * |------|--------|----------|
+ * | xs   | 12px   | Badges, status dots |
+ * | sm   | 16px   | Compact buttons, dense lists |
+ * | md   | 20px   | Default, standard buttons |
+ * | lg   | 24px   | Primary actions, headers |
+ * | xl   | 32px   | Tablet headers, emphasized |
+ * | 2xl  | 40px   | Empty states, onboarding |
+ * | 3xl  | 48px   | Hero sections |
+ *
+ * ## Features
+ * - Responsive size prop (phone/tablet breakpoints)
+ * - Theme-aware color tokens
+ * - Full accessibility support
+ * - Memoized for performance
+ *
+ * @see Icon.types.ts - Type definitions
+ * @see Icon.helpers.ts - Size/color resolution functions
+ * @see Icon.a11y.ts - Accessibility prop generation
+ *
+ * @example
+ * // Basic usage
+ * <Icon name="home" />
+ *
+ * @example
+ * // With size and color
+ * <Icon name="settings" size="lg" color="accentPrimary" />
+ *
+ * @example
+ * // Responsive with accessibility
+ * <Icon
+ *   name="check"
+ *   size={{ phone: "md", tablet: "lg" }}
+ *   accessibilityLabel="Checkmark"
+ * />
+ */
+
+import MaterialIcons from "@expo/vector-icons/MaterialIcons";
+import {
+  createRestyleComponent,
+  createVariant,
+  layout,
+  spacing,
+  spacingShorthand,
+} from "@shopify/restyle";
+import React, { memo } from "react";
+import { RestyleTheme } from "../../../core/restyle";
+import { Box } from "../../layout";
+import { BaseIconContainerProps, IconProps } from "./Icon.types";
+import { useIconLogic } from "./useIconLogic";
+
+/**
+ * Base container with Restyle variant support for icon sizing.
+ * @internal
+ */
+const BaseIconContainer = createRestyleComponent<
+  BaseIconContainerProps,
+  RestyleTheme
+>(
+  [
+    createVariant({ themeKey: "iconSizes", property: "size" }),
+    layout,
+    spacing,
+    spacingShorthand,
+  ],
+  Box,
+);
+
+function IconComponent({
+  name,
+  color = "textPrimary",
+  size = "md",
+  iconStyle,
+  testID,
+  accessibilityLabel,
+  accessibilityHint,
+  ...rest
+}: IconProps) {
+  const { iconSizeValue, iconColor, a11yProps } = useIconLogic({
+    color,
+    size,
+    accessibilityLabel,
+    accessibilityHint,
+  });
+
+  return (
+    <BaseIconContainer {...a11yProps} {...rest}>
+      <MaterialIcons
+        name={name}
+        size={iconSizeValue}
+        color={iconColor}
+        style={iconStyle}
+        testID={testID}
+      />
+    </BaseIconContainer>
+  );
+}
+
+export const Icon = memo(IconComponent);
+Icon.displayName = "Icon";

package/src/primitives/content/Icon/Icon.types.ts

@@ -0,0 +1,95 @@
+/**
+ * Icon Component Types
+ *
+ * Type definitions for the Icon component and its related hooks/helpers.
+ *
+ * @see Icon.tsx - Component implementation
+ */
+
+import MaterialIcons from "@expo/vector-icons/MaterialIcons";
+import { BoxProps, ResponsiveValue, VariantProps } from "@shopify/restyle";
+import { AccessibilityRole, ViewProps } from "react-native";
+import { RestyleTheme } from "../../../core/restyle";
+import { RestyleColor } from "../../../types";
+
+type IconSizeVariantProps = VariantProps<RestyleTheme, "iconSizes", "size">;
+type IconRestyleProps = IconSizeVariantProps & BoxProps<RestyleTheme>;
+
+/** All available Material Icon names from @expo/vector-icons */
+export type IconName = keyof typeof MaterialIcons.glyphMap;
+
+/** Size variants: xs | sm | md | lg | xl | 2xl | 3xl */
+export type IconSize = Exclude<keyof RestyleTheme["iconSizes"], "defaults">;
+
+
+/** @internal Base container props for Restyle integration */
+export type BaseIconContainerProps = IconRestyleProps & ViewProps;
+
+/**
+ * Props for the Icon component.
+ *
+ * @example
+ * <Icon name="home" size="lg" color="accentPrimary" />
+ */
+export interface IconProps extends Omit<IconRestyleProps, "size"> {
+  /** Material Icon name (e.g., "home", "settings", "check") */
+  name: IconName;
+
+  /**
+   * Size of the icon (supports responsive values).
+   * @default "md"
+   */
+  size?: ResponsiveValue<IconSize, RestyleTheme["breakpoints"]>;
+
+  /**
+   * Icon color from theme palette.
+   * @default "textPrimary"
+   */
+  color?: RestyleColor;
+
+  /** Custom styles applied directly to the MaterialIcons component */
+  iconStyle?: React.ComponentProps<typeof MaterialIcons>["style"];
+
+  /** Test ID for testing frameworks */
+  testID?: string;
+
+  /**
+   * Accessibility label for screen readers.
+   * @warning Logs console warning in dev if missing
+   */
+  accessibilityLabel?: string;
+
+  /** Additional context for screen readers */
+  accessibilityHint?: string;
+}
+
+export interface UseIconLogicParams {
+  color: RestyleColor;
+  size: ResponsiveValue<IconSize, RestyleTheme["breakpoints"]>;
+  accessibilityLabel?: string;
+  accessibilityHint?: string;
+}
+
+export interface UseIconLogicReturn {
+  iconSizeValue: number;
+  iconColor: string;
+  a11yProps: IconA11yProps;
+}
+
+export interface IconA11yParams {
+  /** Text alternative for screen readers */
+  accessibilityLabel?: string;
+  /** Additional context about the icon's purpose */
+  accessibilityHint?: string;
+}
+
+export interface IconA11yProps {
+  accessibilityRole: AccessibilityRole;
+  accessibilityLabel?: string;
+  accessibilityHint?: string;
+}
+
+export interface ResolveIconSizeParams {
+  resolvedSize: IconSize;
+  theme: RestyleTheme;
+}