@praxiis/ui 0.0.1

package/src/primitives/feedback/Skeleton/useSkeletonLogic.ts

@@ -0,0 +1,125 @@
+/**
+ * Skeleton Logic Hook
+ *
+ * Extracts all computational logic from the Skeleton component.
+ * Returns memoized values for optimal render performance.
+ *
+ * Responsibilities:
+ * - Resolve responsive size prop
+ * - Calculate dimensions based on variant and size
+ * - Manage pulse animation
+ * - Provide accessibility props
+ *
+ * @see Skeleton.tsx - Component consuming this hook
+ * @see Skeleton.helpers.ts - Pure calculation functions
+ */
+
+import { useResponsiveProp } from "@shopify/restyle";
+import { useMemo } from "react";
+import { usePulseAnimation } from "../../../hooks/animations";
+import { getSkeletonA11y } from "./Skeleton.a11y";
+import {
+  getSkeletonBorderRadius,
+  getSkeletonDimensions,
+  SKELETON_ANIMATION,
+} from "./Skeleton.helpers";
+import { SkeletonSize, SkeletonVariant, UseSkeletonLogicParams, UseSkeletonLogicReturn } from "./Skeleton.types";
+
+/**
+ * Orchestrates Skeleton rendering logic and state management.
+ * 
+ * Handles:
+ * - Responsive size and variant resolution
+ * - Dimension calculation (width, height) with custom overrides
+ * - Border radius determination per variant
+ * - Pulse animation management (looping opacity)
+ * - Reduced motion support (disables animation)
+ * - Accessibility props generation
+ * 
+ * @param params - Configuration object for skeleton behavior
+ * @param params.variant - Shape variant ('text' | 'circular' | 'rectangular')
+ * @param params.size - Size variant ('sm' | 'md' | 'lg')
+ * @param params.width - Custom width override (responsive)
+ * @param params.height - Custom height override (responsive)
+ * @param params.animation - Animation type ('pulse' | 'wave' | 'none')
+ * @param params.color - Theme color token for skeleton
+ * @param params.duration - Animation duration in ms (default: 1500)
+ * 
+ * @returns Computed values for rendering Skeleton
+ * @returns {number} resolvedWidth - Computed width in pixels
+ * @returns {number} resolvedHeight - Computed height in pixels
+ * @returns {number} borderRadius - Border radius in pixels
+ * @returns {Animated.Value} animatedOpacity - Animated opacity (0.3-1.0)
+ * @returns {string} backgroundColor - Background color token
+ * @returns {object} a11yProps - Accessibility props
+ * 
+ * @performance
+ * - Uses native driver for smooth 60fps animations
+ * - Respects reduced motion preferences for accessibility
+ * - Animation loop runs independently per component
+ * 
+ * @example
+ * const {
+ *   resolvedWidth,
+ *   resolvedHeight,
+ *   borderRadius,
+ *   animatedOpacity,
+ *   backgroundColor,
+ * } = useSkeletonLogic({
+ *   variant: "text",
+ *   size: "md",
+ *   animation: "pulse",
+ *   color: "specialSkeleton",
+ *   duration: 1500,
+ * });
+ */
+export function useSkeletonLogic({
+  variant,
+  size,
+  width: customWidth,
+  height: customHeight,
+  animation,
+  color,
+  duration,
+}: UseSkeletonLogicParams): UseSkeletonLogicReturn {
+  // Resolve responsive size
+  const resolvedSize = (useResponsiveProp(size) ?? "md") as SkeletonSize;
+  const resolvedVariant = (useResponsiveProp(variant) ?? "text") as SkeletonVariant;
+  const resolvedCustomWidth = useResponsiveProp(customWidth);
+  const resolvedCustomHeight = useResponsiveProp(customHeight);
+  
+  // Calculate dimensions
+  const { width: resolvedWidth, height: resolvedHeight } = useMemo(
+    () =>
+      getSkeletonDimensions({
+        variant: resolvedVariant,
+        size: resolvedSize,
+        customWidth: resolvedCustomWidth,
+        customHeight: resolvedCustomHeight,
+      }),
+    [resolvedVariant, resolvedSize, resolvedCustomWidth, resolvedCustomHeight]
+  );
+
+  // Get border radius for variant
+  const borderRadius = getSkeletonBorderRadius(resolvedVariant);
+
+  // Pulse animation (respects reduced motion via usePulseAnimation)
+  const animatedOpacity = usePulseAnimation({
+    duration,
+    minOpacity: SKELETON_ANIMATION.MIN_OPACITY,
+    maxOpacity: SKELETON_ANIMATION.MAX_OPACITY,
+    enabled: animation === "pulse",
+  });
+
+  // Accessibility props
+  const a11yProps = getSkeletonA11y({});
+
+  return {
+    resolvedWidth,
+    resolvedHeight,
+    borderRadius,
+    animatedOpacity,
+    backgroundColor: color,
+    a11yProps,
+  };
+}

package/src/primitives/feedback/Spinner/Spinner.helpers.ts

@@ -0,0 +1,40 @@
+/**
+ * Spinner Component Helpers
+ *
+ * Pure functions for mapping Spinner props to ActivityIndicator values.
+ *
+ * ## Size Mapping
+ * | Spinner Size | ActivityIndicator | Visual Size |
+ * |--------------|-------------------|-------------|
+ * | sm           | "small"           | ~20px       |
+ * | lg           | "large"           | ~36px       |
+ *
+ * Note: Exact pixel sizes vary by platform (iOS vs Android).
+ */
+
+import { SpinnerSize } from "./Spinner.types";
+
+/**
+ * Maps design system size tokens to ActivityIndicator size prop.
+ * @internal
+ */
+const SPINNER_ACTIVITY_INDICATOR_SIZES: Record<SpinnerSize, "small" | "large"> = {
+  sm: "small",
+  lg: "large",
+} as const;
+
+/**
+ * Get ActivityIndicator size from Spinner size token.
+ *
+ * @param size - The spinner size variant (sm | lg)
+ * @returns The corresponding ActivityIndicator size
+ *
+ * @example
+ * getSpinnerActivityIndicatorSize("sm") // "small"
+ * getSpinnerActivityIndicatorSize("lg") // "large"
+ */
+export function getSpinnerActivityIndicatorSize(
+  size: SpinnerSize
+): "small" | "large" {
+  return SPINNER_ACTIVITY_INDICATOR_SIZES[size] || SPINNER_ACTIVITY_INDICATOR_SIZES.sm;
+}

package/src/primitives/feedback/Spinner/Spinner.tsx

@@ -0,0 +1,105 @@
+/**
+ * Spinner Component
+ *
+ * @description Loading indicator with theme integration - Atom
+ *
+ * Spinners provide visual feedback during asynchronous operations.
+ * Uses React Native's ActivityIndicator with theme-aware colors.
+ *
+ * ## Sizes
+ * | Size | Platform Mapping | Use Case |
+ * |------|------------------|----------|
+ * | sm   | "small"          | Inline loading, buttons |
+ * | lg   | "large"          | Full-screen loading, cards |
+ *
+ * ## Features
+ * - Two sizes: sm (small) and lg (large)
+ * - Responsive size support (phone/tablet breakpoints)
+ * - Theme-aware color tokens
+ * - Full accessibility support (progressbar role)
+ *
+ * @performance
+ * - Wrapped with React.memo() to prevent unnecessary re-renders
+ * - Uses useMemo() for color resolution from theme tokens
+ * - ActivityIndicator size mapped via constant-time lookup table
+ * - Native ActivityIndicator optimized by React Native for smooth animation
+ *
+ * @see Spinner.types.ts - Type definitions
+ * @see Spinner.helpers.ts - Size mapping functions
+ * @see Spinner.a11y.ts - Accessibility prop generation
+ *
+ * @example
+ * // Basic usage
+ * <Spinner />
+ *
+ * @example
+ * // Large with custom color
+ * <Spinner size="lg" color="feedbackSuccess" />
+ *
+ * @example
+ * // Responsive size
+ * <Spinner size={{ phone: "sm", tablet: "lg" }} />
+ *
+ * @example
+ * // With accessibility
+ * <Spinner accessibilityLabel="Loading your data" />
+ */
+
+import {
+  createRestyleComponent,
+  createVariant,
+  layout,
+  spacing,
+  spacingShorthand,
+} from "@shopify/restyle";
+import React, { memo } from "react";
+import { ActivityIndicator } from "react-native";
+import { RestyleTheme } from "../../../core/restyle";
+import { Box } from "../../layout";
+import { BaseSpinnerProps, SpinnerProps } from "./Spinner.types";
+import { useSpinnerLogic } from "./useSpinnerLogic";
+
+/**
+ * Base Spinner container with Restyle variant support.
+ * @internal
+ */
+const BaseSpinner = createRestyleComponent<BaseSpinnerProps, RestyleTheme>(
+  [
+    createVariant({ themeKey: "spinnerSizes", property: "size" }),
+    layout,
+    spacing,
+    spacingShorthand,
+  ],
+  Box,
+);
+
+function SpinnerComponent({
+  size = "sm",
+  color = "accentPrimary",
+  accessibilityLabel,
+  testID,
+  ...rest
+}: SpinnerProps) {
+  const { resolvedSize, activityIndicatorSize, spinnerColor, a11yProps } =
+    useSpinnerLogic({
+      size,
+      color,
+      accessibilityLabel,
+    });
+
+  return (
+    <BaseSpinner
+      size={resolvedSize}
+      alignItems="center"
+      justifyContent="center"
+      testID={testID}
+      {...a11yProps}
+      {...rest}
+    >
+      <ActivityIndicator size={activityIndicatorSize} color={spinnerColor} />
+    </BaseSpinner>
+  );
+}
+
+export const Spinner = memo(SpinnerComponent);
+Spinner.displayName = "Spinner";

package/src/primitives/feedback/Spinner/Spinner.types.ts

@@ -0,0 +1,114 @@
+/**
+ * Spinner Component Types
+ *
+ * Type definitions for the Spinner component and its related hooks/helpers.
+ *
+ * @see Spinner.tsx - Component implementation
+ */
+
+import { BoxProps, ResponsiveValue, VariantProps } from "@shopify/restyle";
+import { ViewProps } from "react-native";
+import { RestyleTheme } from "../../../core/restyle";
+import { RestyleColor } from "../../../types";
+
+/**
+ * Size variants for the Spinner.
+ * Derived from theme spinnerSizes.
+ * Maps to React Native ActivityIndicator sizes.
+ *
+ * - `sm`: "small" ActivityIndicator - for inline/button loading
+ * - `lg`: "large" ActivityIndicator - for full-screen/card loading
+ */
+export type SpinnerSize = Exclude<
+  keyof RestyleTheme["spinnerSizes"],
+  "defaults"
+>;
+
+/** Restyle props for Spinner size variant */
+type SpinnerSizeProps = VariantProps<RestyleTheme, "spinnerSizes", "size">;
+
+/** Combined restyle props for base spinner */
+export type BaseSpinnerProps = SpinnerSizeProps &
+  BoxProps<RestyleTheme> &
+  ViewProps;
+
+/**
+ * Props for the Spinner component.
+ *
+ * @example
+ * <Spinner size="lg" color="accentPrimary" accessibilityLabel="Loading" />
+ *
+ * @example
+ * // Responsive size
+ * <Spinner size={{ phone: "sm", tablet: "lg" }} />
+ */
+export interface SpinnerProps extends Omit<BaseSpinnerProps, "size"> {
+  /**
+   * Size of the spinner (supports responsive values).
+   * @default "sm"
+   */
+  size?: ResponsiveValue<SpinnerSize, RestyleTheme["breakpoints"]>;
+
+  /**
+   * Spinner color from theme palette.
+   * @default "accentPrimary"
+   */
+  color?: RestyleColor;
+
+  /**
+   * Accessibility label for screen readers.
+   * @default "Loading"
+   */
+  accessibilityLabel?: string;
+
+  /** Test ID for testing frameworks */
+  testID?: string;
+}
+
+/**
+ * Parameters for the useSpinnerLogic hook.
+ */
+export interface UseSpinnerLogicParams {
+  size: ResponsiveValue<SpinnerSize, RestyleTheme["breakpoints"]>;
+  color: RestyleColor;
+  accessibilityLabel?: string;
+}
+
+/**
+ * Return value from the useSpinnerLogic hook.
+ */
+export interface UseSpinnerLogicReturn {
+  /** Resolved size for restyle variant */
+  resolvedSize: SpinnerSize;
+  /** Mapped ActivityIndicator size ("small" | "large") */
+  activityIndicatorSize: "small" | "large";
+  /** Resolved hex color string */
+  spinnerColor: string;
+  /** Accessibility props */
+  a11yProps: SpinnerA11yProps;
+}
+
+/**
+ * Parameters for generating spinner accessibility props.
+ */
+export interface SpinnerA11yParams {
+  /**
+   * Text description of what is loading.
+   */
+  accessibilityLabel?: string;
+
+  /**
+   * Pre-translated fallback label from i18n.
+   * Used when accessibilityLabel is not provided.
+   */
+  fallbackLabel: string;
+}
+
+/**
+ * Accessibility props returned by getSpinnerA11y.
+ */
+export interface SpinnerA11yProps {
+  accessibilityLabel: string;
+  accessibilityRole: "progressbar";
+  accessibilityState: { busy: boolean };
+}

package/src/primitives/feedback/Spinner/index.ts

@@ -0,0 +1,18 @@
+/**
+ * Spinner Module
+ *
+ * Atom component for displaying loading indicators with theme integration.
+ *
+ * @example
+ * import { Spinner } from "@/design-system/primitives/feedback/Spinner";
+ *
+ * <Spinner size="lg" color="accentPrimary" accessibilityLabel="Loading" />
+ */
+
+export { Spinner } from "./Spinner";
+export type {
+  SpinnerProps,
+  SpinnerSize,
+  BaseSpinnerProps,
+} from "./Spinner.types";
+export * from "./Spinner.a11y";

package/src/primitives/feedback/Spinner/useSpinnerLogic.ts

@@ -0,0 +1,84 @@
+/**
+ * Spinner Logic Hook
+ *
+ * Extracts all computational logic from the Spinner component.
+ * Returns memoized values for optimal render performance.
+ *
+ * Responsibilities:
+ * - Resolve responsive size prop
+ * - Map size token to ActivityIndicator size
+ * - Resolve color token to hex value
+ *
+ * @see Spinner.tsx - Component consuming this hook
+ * @see Spinner.helpers.ts - Pure calculation functions
+ */
+
+import { useResponsiveProp } from "@shopify/restyle";
+import { useMemo } from "react";
+import { useDesignSystem } from "../../../provider";
+import { useRestyleTheme } from "../../../core/restyle";
+import { BaseThemeColor } from "../../../types";
+import { getSpinnerA11y } from "./Spinner.a11y";
+import { getSpinnerActivityIndicatorSize } from "./Spinner.helpers";
+import { SpinnerSize, UseSpinnerLogicParams, UseSpinnerLogicReturn } from "./Spinner.types";
+
+/**
+ * Orchestrates Spinner rendering logic and state management.
+ * 
+ * Handles:
+ * - Responsive size resolution
+ * - Size mapping to ActivityIndicator size ('small' | 'large')
+ * - Color token resolution to hex value
+ * - Accessibility props generation
+ * 
+ * @param params - Configuration object for spinner behavior
+ * @param params.size - Size variant ('sm' | 'md' | 'lg')
+ * @param params.color - Theme color token for spinner
+ * @param params.accessibilityLabel - Custom a11y label
+ * 
+ * @returns Computed values for rendering Spinner
+ * @returns {string} resolvedSize - Resolved size variant
+ * @returns {string} activityIndicatorSize - RN ActivityIndicator size
+ * @returns {string} spinnerColor - Resolved hex color
+ * @returns {object} a11yProps - Accessibility props
+ * 
+ * @performance This hook uses useMemo() for color resolution
+ * 
+ * @example
+ * const { resolvedSize, activityIndicatorSize, spinnerColor } = useSpinnerLogic({
+ *   size: "lg",
+ *   color: "accentPrimary",
+ * });
+ * 
+ * @example
+ * // With responsive size
+ * const { activityIndicatorSize, spinnerColor } = useSpinnerLogic({
+ *   size: { phone: "sm", tablet: "lg" },
+ *   color: "accentPrimary",
+ * });
+ */
+export function useSpinnerLogic({
+  size,
+  color,
+  accessibilityLabel,
+}: UseSpinnerLogicParams): UseSpinnerLogicReturn {
+  const { labels: t } = useDesignSystem();
+  const theme = useRestyleTheme();
+  const resolvedSize = (useResponsiveProp(size) ?? "sm") as SpinnerSize;
+
+  const activityIndicatorSize = getSpinnerActivityIndicatorSize(resolvedSize);
+
+  const spinnerColor = theme.colors[color as BaseThemeColor];
+
+  const a11yProps = useMemo(
+    () => getSpinnerA11y({ accessibilityLabel, fallbackLabel: t.designSystem.spinner.fallbackLabel }),
+    [accessibilityLabel, t.designSystem.spinner.fallbackLabel],
+  );
+
+  return {
+    resolvedSize,
+    activityIndicatorSize,
+    spinnerColor,
+    a11yProps,
+  };
+}

package/src/primitives/feedback/Toast/Toast.helpers.ts

@@ -0,0 +1,163 @@
+/**
+ * Toast Component Helpers
+ *
+ * Pure functions for mapping Toast props to style values.
+ *
+ * ## Variant Color Mapping
+ * | Variant | Background Token      | Border Token         | Icon Token          |
+ * |---------|----------------------|----------------------|---------------------|
+ * | success | feedbackSuccessLight | feedbackSuccess      | feedbackSuccessDark |
+ * | error   | feedbackErrorLight   | feedbackError        | feedbackErrorDark   |
+ * | warning | feedbackWarningLight | feedbackWarning      | feedbackWarningDark |
+ * | info    | feedbackInfoLight    | feedbackInfo         | feedbackInfoDark    |
+ *
+ * @see Toast.types.ts - Type definitions
+ */
+
+import { MaterialIconName, RestyleColor } from "../../../types";
+import { ToastVariant } from "./Toast.types";
+
+// =============================================================================
+// VARIANT COLOR MAPPINGS
+// =============================================================================
+
+/**
+ * Background color tokens for each variant.
+ * @internal
+ */
+const TOAST_BACKGROUND_COLORS: Record<ToastVariant, RestyleColor> = {
+  success: "feedbackSuccessLight",
+  error: "feedbackErrorLight",
+  warning: "feedbackWarningLight",
+  info: "feedbackInfoLight",
+} as const;
+
+/**
+ * Border color tokens for each variant.
+ * @internal
+ */
+const TOAST_BORDER_COLORS: Record<ToastVariant, RestyleColor> = {
+  success: "feedbackSuccess",
+  error: "feedbackError",
+  warning: "feedbackWarning",
+  info: "feedbackInfo",
+} as const;
+
+/**
+ * Icon color tokens for each variant.
+ * @internal
+ */
+const TOAST_ICON_COLORS: Record<ToastVariant, RestyleColor> = {
+  success: "feedbackSuccessDark",
+  error: "feedbackErrorDark",
+  warning: "feedbackWarningDark",
+  info: "feedbackInfoDark",
+} as const;
+
+/**
+ * Text color tokens for each variant.
+ * @internal
+ */
+const TOAST_TEXT_COLORS: Record<ToastVariant, RestyleColor> = {
+  success: "feedbackSuccessDark",
+  error: "feedbackErrorDark",
+  warning: "feedbackWarningDark",
+  info: "feedbackInfoDark",
+} as const;
+
+/**
+ * Default icon for each variant.
+ * @internal
+ */
+const TOAST_DEFAULT_ICONS: Record<ToastVariant, MaterialIconName> = {
+  success: "check-circle",
+  error: "error",
+  warning: "warning",
+  info: "info",
+} as const;
+
+// =============================================================================
+// PUBLIC HELPERS
+// =============================================================================
+
+/**
+ * Get background color token for toast variant.
+ *
+ * @param variant - Toast variant
+ * @returns Background color token
+ *
+ * @example
+ * getToastBackgroundColor("success") // "feedbackSuccessLight"
+ */
+export function getToastBackgroundColor(variant: ToastVariant): RestyleColor {
+  return TOAST_BACKGROUND_COLORS[variant] ?? TOAST_BACKGROUND_COLORS.info;
+}
+
+/**
+ * Get border color token for toast variant.
+ *
+ * @param variant - Toast variant
+ * @returns Border color token
+ *
+ * @example
+ * getToastBorderColor("error") // "feedbackError"
+ */
+export function getToastBorderColor(variant: ToastVariant): RestyleColor {
+  return TOAST_BORDER_COLORS[variant] ?? TOAST_BORDER_COLORS.info;
+}
+
+/**
+ * Get icon color token for toast variant.
+ *
+ * @param variant - Toast variant
+ * @returns Icon color token
+ *
+ * @example
+ * getToastIconColor("warning") // "feedbackWarningDark"
+ */
+export function getToastIconColor(variant: ToastVariant): RestyleColor {
+  return TOAST_ICON_COLORS[variant] ?? TOAST_ICON_COLORS.info;
+}
+
+/**
+ * Get text color token for toast variant.
+ *
+ * @param variant - Toast variant
+ * @returns Text color token
+ *
+ * @example
+ * getToastTextColor("info") // "feedbackInfoDark"
+ */
+export function getToastTextColor(variant: ToastVariant): RestyleColor {
+  return TOAST_TEXT_COLORS[variant] ?? TOAST_TEXT_COLORS.info;
+}
+
+/**
+ * Get default icon for toast variant, or use custom icon if provided.
+ *
+ * @param variant - Toast variant
+ * @param customIcon - Optional custom icon override
+ * @returns Icon name to display
+ *
+ * @example
+ * getToastIcon("success") // "check-circle"
+ * getToastIcon("success", "thumb-up") // "thumb-up"
+ */
+export function getToastIcon(
+  variant: ToastVariant,
+  customIcon?: MaterialIconName
+): MaterialIconName {
+  return customIcon ?? TOAST_DEFAULT_ICONS[variant] ?? TOAST_DEFAULT_ICONS.info;
+}
+
+/**
+ * Generate a unique ID for a toast.
+ *
+ * @returns Unique toast ID
+ *
+ * @example
+ * generateToastId() // "toast-1234567890-abc"
+ */
+export function generateToastId(): string {
+  return `toast-${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;
+}