@praxiis/ui 0.0.1

package/src/components/EmptyState/useEmptyStateLogic.ts

@@ -0,0 +1,131 @@
+/**
+ * EmptyState Logic Hook
+ *
+ * Extracts all computational logic from the EmptyState component.
+ * Returns memoized values for optimal render performance.
+ *
+ * Responsibilities:
+ * - Resolve responsive variant prop
+ * - Calculate styling configuration based on variant
+ * - Determine visibility of optional elements
+ * - Provide accessibility props
+ *
+ * @see EmptyState.tsx - Component consuming this hook
+ * @see EmptyState.helpers.ts - Pure calculation functions
+ */
+
+import { useResponsiveProp } from "@shopify/restyle";
+import { useMemo } from "react";
+import { getEmptyStateA11y } from "./EmptyState.a11y";
+import { getEmptyStateConfig } from "./EmptyState.helpers";
+import { EmptyStateVariant, UseEmptyStateLogicParams, UseEmptyStateLogicReturn } from "./EmptyState.types";
+
+/**
+ * Orchestrates EmptyState rendering logic and state management.
+ * 
+ * Handles:
+ * - Responsive variant resolution
+ * - Configuration lookup (icon size, text variants, spacing)
+ * - Icon resolution (custom or type-based defaults)
+ * - Color determination based on type (error vs default)
+ * - Element visibility flags (icon, actions)
+ * - Accessibility props generation
+ * 
+ * @param params - Configuration object for empty state behavior
+ * @param params.type - Semantic type ('default' | 'error')
+ * @param params.variant - Size variant ('default' | 'compact')
+ * @param params.iconName - Optional custom icon
+ * @param params.title - Title text
+ * @param params.description - Description text
+ * @param params.actionLabel - Primary action button label
+ * @param params.secondaryActionLabel - Secondary action button label
+ * @param params.accessibilityLabel - Custom a11y label
+ * 
+ * @returns Computed values for rendering EmptyState
+ * @returns {number} iconSize - Icon size in pixels
+ * @returns {string} iconColor - Icon color token
+ * @returns {string} titleColor - Title color token
+ * @returns {string} titleVariant - Title text variant
+ * @returns {string} descriptionVariant - Description text variant
+ * @returns {number} containerPadding - Container padding in pixels
+ * @returns {number} contentGap - Gap between elements in pixels
+ * @returns {object} a11yProps - Accessibility props
+ * @returns {boolean} showIcon - Whether to show icon
+ * @returns {boolean} showAction - Whether to show primary action
+ * @returns {boolean} showSecondaryAction - Whether to show secondary action
+ * @returns {string} resolvedIconName - Resolved icon name
+ * 
+ * @performance This hook uses useMemo() for configuration lookups
+ * 
+ * @example
+ * const {
+ *   iconSize,
+ *   iconColor,
+ *   titleVariant,
+ *   showIcon,
+ *   showAction,
+ *   resolvedIconName,
+ * } = useEmptyStateLogic({
+ *   variant: "default",
+ *   iconName: "inbox",
+ *   title: "No messages",
+ *   description: "Your inbox is empty",
+ *   actionLabel: "Compose",
+ *   secondaryActionLabel: "Learn more",
+ * });
+ */
+export function useEmptyStateLogic({
+  type,
+  variant,
+  iconName,
+  title,
+  description,
+  actionLabel,
+  secondaryActionLabel,
+  accessibilityLabel,
+}: UseEmptyStateLogicParams): UseEmptyStateLogicReturn {
+  // Resolve responsive variant
+  const resolvedVariant = (useResponsiveProp(variant) ?? "default") as EmptyStateVariant;
+
+  // Get variant configuration
+  const config = getEmptyStateConfig(resolvedVariant);
+
+  // Determine icon based on type if not provided
+  const resolvedIconName = iconName || (type === "error" ? "error" : "inbox");
+
+  // Determine colors based on type
+  const iconColor = type === "error" ? "feedbackError" : "textSecondary";
+
+  const titleColor = type === "error" ? "feedbackError" : "textPrimary";
+
+  // Determine element visibility
+  const showIcon = resolvedIconName !== undefined;
+  const showAction = actionLabel !== undefined;
+  const showSecondaryAction = secondaryActionLabel !== undefined;
+
+  // Accessibility props
+  const a11yProps = useMemo(
+    () =>
+      getEmptyStateA11y({
+        title,
+        description,
+        accessibilityLabel,
+      }),
+    [title, description, accessibilityLabel]
+  );
+
+  return {
+    iconSize: config.iconSize,
+    iconColor,
+    titleColor,
+    titleVariant: config.titleVariant,
+    descriptionVariant: config.descriptionVariant,
+    containerPadding: config.containerPadding,
+    contentGap: config.contentGap,
+    a11yProps,
+    showIcon,
+    showAction,
+    showSecondaryAction,
+    resolvedIconName,
+  };
+}

package/src/components/Header/Header.helpers.ts

@@ -0,0 +1,93 @@
+/**
+ * Header Component Helpers
+ *
+ * Pure functions for computing Header dimensions, sizes, and mappings.
+ *
+ * ## Size Configuration
+ * | Header Size | Height | Text Variant  | IconButton |
+ * |-------------|--------|---------------|------------|
+ * | sm          | 44px   | headingSmall  | sm (36px)  |
+ * | md          | 56px   | headingMedium | md (44px)  |
+ * | lg          | 64px   | headingLarge  | lg (56px)  |
+ *
+ * ## Safe Area Calculation
+ * Total height = base height + safe area top inset (when enabled)
+ */
+
+import { ResponsiveValue } from "@shopify/restyle";
+import { ViewStyle } from "react-native";
+import { RestyleTheme } from "../../core/restyle";
+import { IconButtonSize } from "../../primitives/actions/IconButton";
+import {
+  HeaderDimensionsResult,
+  HeaderSize,
+  HeaderTextVariant,
+  ResolveHeaderDimensionsParams,
+} from "./Header.types";
+
+/**
+ * Maps header size to text variant.
+ */
+export const SIZE_TO_TEXT_VARIANT: Record<HeaderSize, HeaderTextVariant> = {
+  sm: "headingSmall",
+  md: "headingMedium",
+  lg: "headingLarge",
+} as const;
+
+/**
+ * Maps Header size to IconButton size for proper visual alignment.
+ *
+ * | Header | IconButton | Ratio |
+ * |--------|------------|-------|
+ * | sm 44px| sm 36px    | 82%   |
+ * | md 56px| md 44px    | 79%   |
+ * | lg 64px| lg 56px    | 87%   |
+ *
+ * @param headerSize - Header size (supports responsive values)
+ * @returns Corresponding IconButton size
+ */
+export function getHeaderIconButtonSize(
+  headerSize: ResponsiveValue<HeaderSize, RestyleTheme["breakpoints"]>,
+): ResponsiveValue<IconButtonSize, RestyleTheme["breakpoints"]> {
+  // If responsive, map each breakpoint
+  if (typeof headerSize === "object") {
+    return {
+      phone:
+        headerSize.phone === "sm"
+          ? "sm"
+          : headerSize.phone === "lg"
+            ? "lg"
+            : "md",
+      tablet:
+        headerSize.tablet === "sm"
+          ? "sm"
+          : headerSize.tablet === "lg"
+            ? "lg"
+            : "md",
+    };
+  }
+  // If single value, map directly
+  return headerSize === "sm" ? "sm" : headerSize === "lg" ? "lg" : "md";
+}
+
+export const BACK_BUTTON_HIT_SLOP = {
+  top: 8,
+  bottom: 8,
+  left: 8,
+  right: 8,
+} as const;
+
+export function resolveHeaderDimensions(
+  params: ResolveHeaderDimensionsParams,
+): HeaderDimensionsResult {
+  const { resolvedSize, safeAreaTop, topInset, theme } = params;
+  const { height } = theme.headerSizes[resolvedSize];
+  const topPadding = safeAreaTop ? topInset : 0;
+  const totalHeight = height + topPadding;
+
+  return { topPadding, totalHeight };
+}
+
+export function resolveContainerStyle(topPadding: number): ViewStyle {
+  return { paddingTop: topPadding };
+}

package/src/components/Header/Header.tsx

@@ -0,0 +1,185 @@
+/**
+ * Header Component
+ *
+ * @description Navigation header with title and actions - Organism
+ *
+ * Header is a complex component combining multiple atoms and molecules
+ * into a complete navigation bar with back button, title, and actions.
+ *
+ * ## Size Scale
+ * | Size | Height | Text Variant | IconButton |
+ * |------|--------|--------------|------------|
+ * | sm   | 44px   | headingSmall | sm (36px)  |
+ * | md   | 56px   | headingMedium| md (44px)  |
+ * | lg   | 64px   | headingLarge | lg (56px)  |
+ *
+ * ## Safe Area Handling
+ * When `safeAreaTop={true}` (default), the header adds top padding
+ * for the device safe area (notch/status bar). Total height = size + insets.top.
+ *
+ * ## Back Button Behavior
+ * - Shows when `showBackButton={true}` AND `onBackPress` is provided
+ * - Calls `onBackPress` when pressed
+ * - Accessibility labels from i18n translations
+ *
+ * ## Features
+ * - Responsive size prop (phone/tablet breakpoints)
+ * - Optional back button with smart visibility
+ * - Custom left/right items for actions
+ * - Safe area aware (status bar + notch)
+ * - Full accessibility support (header role)
+ *
+ * @performance
+ * - Wrapped with React.memo() to prevent unnecessary re-renders
+ * - Uses useMemo() for dimension calculations with safe area insets
+ * - Back button visibility computed once per canGoBack() change
+ * - Container styles cached to avoid style object recreation
+ * - Integrates with expo-router for efficient navigation state
+ *
+ * @see Header.types.ts - Type definitions
+ * @see Header.helpers.ts - Size and dimension functions
+ * @see Header.a11y.ts - Accessibility prop generation
+ *
+ * @example
+ * // Basic usage
+ * <Header title="Settings" />
+ *
+ * @example
+ * // With actions
+ * <Header
+ *   title="Profile"
+ *   size={{ phone: "md", tablet: "lg" }}
+ *   rightItems={
+ *     <HeaderRightItems>
+ *       <IconButton iconName="edit" onPress={handleEdit} accessibilityLabel="Edit" />
+ *     </HeaderRightItems>
+ *   }
+ * />
+ *
+ * @example
+ * // Custom back handler
+ * <Header
+ *   title="Checkout"
+ *   onBackPress={handleConfirmCancel}
+ *   accessibilityLabel="Checkout header"
+ * />
+ */
+
+import { RestyleTheme } from "../../core/restyle";
+import { Box, IconButton, Text } from "../../primitives";
+import {
+  backgroundColor,
+  border,
+  createRestyleComponent,
+  createVariant,
+  layout,
+  opacity,
+  spacing,
+  spacingShorthand,
+} from "@shopify/restyle";
+import React, { memo } from "react";
+import { getHeaderIconButtonSize } from "./Header.helpers";
+import {
+  BaseHeaderContainerProps,
+  HeaderProps,
+  HeaderRightItemsProps,
+} from "./Header.types";
+import { useHeaderLogic } from "./useHeaderLogic";
+
+/**
+ * Base container with Restyle variant support.
+ * @internal
+ */
+const BaseHeaderContainer = createRestyleComponent<
+  BaseHeaderContainerProps,
+  RestyleTheme
+>(
+  [
+    createVariant({ themeKey: "headerVariants" }),
+    createVariant({ themeKey: "headerSizes", property: "size" }),
+    backgroundColor,
+    border,
+    layout,
+    opacity,
+    spacing,
+    spacingShorthand,
+  ],
+  Box,
+);
+
+function HeaderComponent({
+  title,
+  accessibilityLabel,
+  accessibilityHint,
+  size = "md",
+  variant,
+  showBackButton = true,
+  rightItems,
+  leftItems,
+  safeAreaTop = true,
+  onBackPress,
+  testID,
+  ...rest
+}: HeaderProps) {
+  const {
+    showBack,
+    textVariant,
+    dimensions,
+    containerStyle,
+    backButtonA11yProps,
+    a11yContainerProps,
+    handleBack,
+  } = useHeaderLogic({
+    accessibilityLabel,
+    accessibilityHint,
+    size,
+    showBackButton,
+    safeAreaTop,
+    onBackPress,
+  });
+
+  return (
+    <BaseHeaderContainer
+      height={dimensions.totalHeight}
+      variant={variant}
+      style={containerStyle}
+      testID={testID}
+      {...a11yContainerProps}
+      {...rest}
+    >
+      {showBack && (
+        <IconButton
+          iconName="arrow-back"
+          onPress={handleBack}
+          variant="ghost"
+          size={getHeaderIconButtonSize(size)}
+          accessibilityLabel={
+            backButtonA11yProps.accessibilityLabel ?? "Go back"
+          }
+          accessibilityHint={backButtonA11yProps.accessibilityHint}
+        />
+      )}
+      {leftItems}
+      {title && (
+        <Text flex={1} numberOfLines={1} variant={textVariant}>
+          {title}
+        </Text>
+      )}
+      {rightItems}
+    </BaseHeaderContainer>
+  );
+}
+
+function HeaderRightItemsComponent({ children }: HeaderRightItemsProps) {
+  return (
+    <Box flexDirection="row" alignItems="center" gap="xs">
+      {children}
+    </Box>
+  );
+}
+
+export const Header = memo(HeaderComponent);
+Header.displayName = "Header";
+
+export const HeaderRightItems = memo(HeaderRightItemsComponent);
+HeaderRightItems.displayName = "HeaderRightItems";

package/src/components/Header/Header.types.ts

@@ -0,0 +1,153 @@
+/**
+ * Header Component Types
+ *
+ * Type definitions for the Header component and its related hooks/helpers.
+ *
+ * @see Header.tsx - Component implementation
+ */
+
+import { BoxProps, ResponsiveValue, VariantProps } from "@shopify/restyle";
+import { ReactNode } from "react";
+import { AccessibilityRole, ViewProps, ViewStyle } from "react-native";
+import { RestyleTheme } from "../../core/restyle";
+
+type HeaderVariantProps = VariantProps<
+  RestyleTheme,
+  "headerVariants",
+  "variant"
+>;
+type HeaderSizeProps = VariantProps<RestyleTheme, "headerSizes", "size">;
+type HeaderRestyleProps = HeaderVariantProps &
+  HeaderSizeProps &
+  BoxProps<RestyleTheme>;
+
+/**
+ * Size variants for the Header.
+ *
+ * | Size | Height | Text Variant  | Use Case |
+ * |------|--------|---------------|----------|
+ * | sm   | 44px   | headingSmall  | Compact screens |
+ * | md   | 56px   | headingMedium | Default mobile |
+ * | lg   | 64px   | headingLarge  | Tablets, emphasis |
+ */
+export type HeaderSize = Exclude<
+  keyof RestyleTheme["headerSizes"],
+  "defaults"
+>;
+
+/** Visual variants derived from theme headerVariants */
+export type HeaderVariant = Exclude<
+  keyof RestyleTheme["headerVariants"],
+  "defaults"
+>;
+
+/** @internal Base container props for Restyle integration */
+export type BaseHeaderContainerProps = HeaderRestyleProps & ViewProps;
+
+/**
+ * Props for the Header component.
+ *
+ * @example
+ * <Header
+ *   title="Settings"
+ *   size="md"
+ *   showBackButton
+ *   rightItems={<IconButton iconName="more-vert" onPress={handleMore} accessibilityLabel="More" />}
+ * />
+ */
+export interface HeaderProps extends Omit<HeaderRestyleProps, "size"> {
+  /** Title text displayed in header */
+  title?: string;
+
+  /**
+   * Size of the header (supports responsive values).
+   * @default "md"
+   */
+  size?: ResponsiveValue<HeaderSize, RestyleTheme["breakpoints"]>;
+
+  /** Accessibility label for the header container */
+  accessibilityLabel?: string;
+
+  /** Accessibility hint for additional context */
+  accessibilityHint?: string;
+
+  /**
+   * Whether to show back button (only shows when `onBackPress` is also provided).
+   * @default true
+   */
+  showBackButton?: boolean;
+
+  /** Content rendered on the right side of the header */
+  rightItems?: ReactNode;
+
+  /** Content rendered on the left side (after back button) */
+  leftItems?: ReactNode;
+
+  /**
+   * Whether to add safe area top padding.
+   * @default true
+   */
+  safeAreaTop?: boolean;
+
+  /** Back button press handler — back button only renders when this is provided */
+  onBackPress?: () => void;
+
+  /** Test ID for testing frameworks */
+  testID?: string;
+}
+
+export interface HeaderRightItemsProps {
+  children: ReactNode;
+}
+
+export type HeaderTextVariant =
+  | "headingSmall"
+  | "headingMedium"
+  | "headingLarge";
+
+export interface UseHeaderLogicParams {
+  accessibilityLabel: string | undefined;
+  accessibilityHint: string | undefined;
+  size: ResponsiveValue<HeaderSize, RestyleTheme["breakpoints"]>;
+  showBackButton: boolean;
+  safeAreaTop: boolean;
+  onBackPress: (() => void) | undefined;
+}
+
+export interface UseHeaderLogicReturn {
+  handleBack: () => void;
+  showBack: boolean;
+  dimensions: HeaderDimensionsResult;
+  containerStyle: ViewStyle;
+  a11yContainerProps: HeaderA11yProps;
+  textVariant: HeaderTextVariant;
+  backButtonA11yProps: HeaderA11yProps;
+}
+
+export interface ResolveHeaderDimensionsParams {
+  resolvedSize: HeaderSize;
+  safeAreaTop: boolean;
+  topInset: number;
+  theme: RestyleTheme;
+}
+
+export interface HeaderDimensionsResult {
+  topPadding: number;
+  totalHeight: number;
+}
+
+export interface HeaderA11yParams {
+  accessibilityLabel?: string;
+  accessibilityHint?: string;
+}
+
+export interface HeaderBackButtonA11yParams {
+  accessibilityLabel?: string;
+  accessibilityHint?: string;
+}
+
+export interface HeaderA11yProps {
+  accessibilityRole: AccessibilityRole;
+  accessibilityLabel?: string;
+  accessibilityHint?: string;
+}

package/src/components/Header/index.ts

@@ -0,0 +1,44 @@
+/**
+ * Header Module
+ *
+ * Organism component for navigation headers with title and actions.
+ *
+ * Combines IconButton, Text, and Box atoms into a complete
+ * navigation bar with safe area awareness.
+ *
+ * ## Components
+ * - **Header**: Main navigation header
+ * - **HeaderRightItems**: Container for right-side action buttons
+ *
+ * ## Size Scale
+ * | Size | Height | Use Case |
+ * |------|--------|----------|
+ * | sm   | 44px   | Compact screens |
+ * | md   | 56px   | Default mobile |
+ * | lg   | 64px   | Tablets |
+ *
+ * @example
+ * import { Header, HeaderRightItems } from "@/design-system/primitives/navigation/Header";
+ *
+ * <Header
+ *   title="Profile"
+ *   rightItems={
+ *     <HeaderRightItems>
+ *       <IconButton iconName="edit" onPress={handleEdit} accessibilityLabel="Edit" />
+ *     </HeaderRightItems>
+ *   }
+ * />
+ */
+
+export { Header, HeaderRightItems } from "./Header";
+
+export type {
+  HeaderProps,
+  HeaderSize,
+  HeaderVariant,
+  HeaderRightItemsProps,
+  HeaderA11yParams,
+  HeaderA11yProps,
+} from "./Header.types";
+
+export { getHeaderA11y, getHeaderBackButtonA11y } from "./Header.a11y";