@praxiis/ui 0.0.1

package/src/primitives/feedback/ProgressBar/useProgressBarLogic.ts

@@ -0,0 +1,120 @@
+/**
+ * ProgressBar Logic Hook
+ *
+ * Extracts all computational logic from the ProgressBar component.
+ * Returns memoized values for optimal render performance.
+ *
+ * Responsibilities:
+ * - Clamp and validate progress value
+ * - Calculate width percentage
+ * - Pass through the `color` prop as `indicatorColorToken`
+ * - Always use `"borderSubtle"` as the track color
+ * - Resolve size dimensions
+ * - Generate accessibility props
+ *
+ * @see ProgressBar.tsx - Component consuming this hook
+ * @see ProgressBar.helpers.ts - Pure calculation functions
+ * @see ProgressBar.a11y.ts - Accessibility prop generation
+ */
+
+import { useResponsiveProp } from "@shopify/restyle";
+import { useMemo } from "react";
+import { useDesignSystem } from "../../../provider";
+import { getProgressBarA11y } from "./ProgressBar.a11y";
+import {
+  clampProgress,
+  getProgressBarBorderRadius,
+  getWidthPercent,
+  progressToPercent,
+} from "./ProgressBar.helpers";
+import {
+  ProgressBarSize,
+  UseProgressBarLogicParams,
+  UseProgressBarLogicReturn,
+} from "./ProgressBar.types";
+
+/**
+ * Orchestrates ProgressBar rendering logic and state management.
+ * 
+ * Handles:
+ * - Responsive size resolution
+ * - Progress value clamping (0.0 to 1.0 range)
+ * - Width percentage calculation for indicator
+ * - Color token pass-through for indicator; track is always "borderSubtle"
+ * - Border radius calculation based on size
+ * - Accessibility props with progress value
+ * 
+ * @param params - Configuration object for progress bar behavior
+ * @param params.progress - Progress value (0.0 to 1.0, values outside clamped)
+ * @param params.color - Color token for the indicator (RestyleColor)
+ * @param params.size - Size variant ('sm' | 'md' | 'lg')
+ * @param params.accessibilityLabel - Custom a11y label
+ * 
+ * @returns Computed values for rendering ProgressBar
+ * 
+ * @performance This hook uses useMemo() for expensive calculations
+ * 
+ * @example
+ * const {
+ *   clampedProgress,
+ *   widthPercent,
+ *   indicatorColorToken,
+ *   trackColorToken,
+ *   borderRadius,
+ *   a11yProps,
+ * } = useProgressBarLogic({
+ *   progress: 0.75,
+ *   color: "feedbackSuccess",
+ *   size: "md",
+ * });
+ */
+export function useProgressBarLogic({
+  progress,
+  color,
+  size,
+  accessibilityLabel,
+}: UseProgressBarLogicParams): UseProgressBarLogicReturn {
+  const { labels: t } = useDesignSystem();
+  // Resolve responsive size
+  const resolvedSize = (useResponsiveProp(size) ?? "md") as ProgressBarSize;
+
+  // Memoized progress calculations
+  const progressValues = useMemo(() => {
+    const clamped = clampProgress(progress);
+    return {
+      clampedProgress: clamped,
+      progressPercent: progressToPercent(clamped),
+      widthPercent: getWidthPercent(clamped),
+    };
+  }, [progress]);
+
+  // Color tokens: indicator uses the color prop directly, track is always borderSubtle
+  const colorTokens = useMemo(
+    () => ({
+      indicatorColorToken: color,
+      trackColorToken: "borderSubtle" as const,
+    }),
+    [color]
+  );
+
+  // Border radius based on size
+  const borderRadius = getProgressBarBorderRadius(resolvedSize);
+
+  // Accessibility props
+  const a11yProps = useMemo(
+    () =>
+      getProgressBarA11y({
+        progress,
+        accessibilityLabel,
+        fallbackLabel: t.designSystem.progressBar.fallbackLabel,
+      }),
+    [progress, accessibilityLabel, t.designSystem.progressBar.fallbackLabel]
+  );
+
+  return {
+    ...progressValues,
+    ...colorTokens,
+    borderRadius,
+    a11yProps,
+  };
+}

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

@@ -0,0 +1,145 @@
+/**
+ * Skeleton Component Helpers
+ *
+ * Pure functions for calculating skeleton dimensions and styles.
+ * All values are derived from design tokens for consistency.
+ *
+ * ## Size Scale by Variant
+ *
+ * ### Text Variant (rounded rectangle)
+ * | Size | Width  | Height | Use Case |
+ * |------|--------|--------|----------|
+ * | sm   | 100%   | 16px   | Caption, labels |
+ * | md   | 100%   | 20px   | Body text (default) |
+ * | lg   | 100%   | 28px   | Headings |
+ *
+ * ### Circular Variant (avatar/icon)
+ * | Size | Width  | Height | Use Case |
+ * |------|--------|--------|----------|
+ * | sm   | 32px   | 32px   | Small avatar |
+ * | md   | 40px   | 40px   | Default avatar |
+ * | lg   | 56px   | 56px   | Large avatar |
+ *
+ * ### Rectangular Variant (image/card)
+ * | Size | Width  | Height | Use Case |
+ * |------|--------|--------|----------|
+ * | sm   | 100%   | 80px   | Thumbnail |
+ * | md   | 100%   | 120px  | Card image |
+ * | lg   | 100%   | 200px  | Hero image |
+ */
+
+import { RestyleTheme } from "../../../core/restyle";
+import {
+  ResolveSkeletonDimensionsParams,
+  SkeletonDimensionsResult,
+  SkeletonSize,
+  SkeletonSizeConfig,
+  SkeletonVariant,
+} from "./Skeleton.types";
+
+/**
+ * Predefined size configurations for each variant.
+ * Following 8px grid system for consistency.
+ */
+export const SKELETON_SIZE_CONFIG: SkeletonSizeConfig = {
+  text: {
+    sm: { width: "100%", height: 16 },
+    md: { width: "100%", height: 20 },
+    lg: { width: "100%", height: 28 },
+  },
+  circular: {
+    sm: { width: 32, height: 32 },
+    md: { width: 40, height: 40 },
+    lg: { width: 56, height: 56 },
+  },
+  rectangular: {
+    sm: { width: "100%", height: 80 },
+    md: { width: "100%", height: 120 },
+    lg: { width: "100%", height: 200 },
+  },
+} as const;
+
+/**
+ * Border radius mapping by variant.
+ * - text: small radius for text-like appearance
+ * - circular: full radius for perfect circle
+ * - rectangular: medium radius for card-like appearance
+ */
+export const SKELETON_BORDER_RADIUS: Record<SkeletonVariant, keyof RestyleTheme["borderRadii"]> = {
+  text: "xs",
+  circular: "full",
+  rectangular: "md",
+} as const;
+
+/**
+ * Animation timing constants.
+ */
+export const SKELETON_ANIMATION = {
+  /** Default pulse animation duration in ms */
+  DEFAULT_DURATION: 1500,
+  /** Minimum opacity during pulse */
+  MIN_OPACITY: 0.4,
+  /** Maximum opacity during pulse */
+  MAX_OPACITY: 1,
+} as const;
+
+/**
+ * Get dimensions for a skeleton based on variant and size.
+ *
+ * @param params - Variant, size, and optional custom dimensions
+ * @returns Resolved width and height values
+ *
+ * @example
+ * getSkeletonDimensions({ variant: "text", size: "md" })
+ * // { width: "100%", height: 20 }
+ *
+ * @example
+ * getSkeletonDimensions({ variant: "circular", size: "lg", customWidth: 64 })
+ * // { width: 64, height: 64 } // circular maintains aspect ratio
+ */
+export function getSkeletonDimensions(
+  params: ResolveSkeletonDimensionsParams
+): SkeletonDimensionsResult {
+  const { variant, size, customWidth, customHeight } = params;
+  const config = SKELETON_SIZE_CONFIG[variant][size];
+
+  let width = customWidth ?? config.width;
+  let height = customHeight ?? config.height;
+
+  // For circular variant, maintain 1:1 aspect ratio
+  if (variant === "circular") {
+    if (customWidth !== undefined && customHeight === undefined) {
+      height = typeof customWidth === "number" ? customWidth : config.height;
+    } else if (customHeight !== undefined && customWidth === undefined) {
+      width = customHeight;
+    }
+  }
+
+  return { width, height };
+}
+
+/**
+ * Get border radius token for variant.
+ *
+ * @param variant - Skeleton shape variant
+ * @returns Border radius token key
+ */
+export function getSkeletonBorderRadius(
+  variant: SkeletonVariant
+): keyof RestyleTheme["borderRadii"] {
+  return SKELETON_BORDER_RADIUS[variant];
+}
+
+/**
+ * Get default dimensions for a size preset.
+ *
+ * @param variant - Shape variant
+ * @param size - Size preset
+ * @returns Default dimensions
+ */
+export function getSkeletonSizePreset(
+  variant: SkeletonVariant,
+  size: SkeletonSize
+): SkeletonDimensionsResult {
+  return SKELETON_SIZE_CONFIG[variant][size];
+}

package/src/primitives/feedback/Skeleton/Skeleton.tsx

@@ -0,0 +1,155 @@
+/**
+ * Skeleton Component
+ *
+ * @description Animated placeholder for loading states - Atom
+ *
+ * Skeleton provides visual feedback during content loading, reducing
+ * perceived wait time and preventing layout shift. Uses performant
+ * native driver animations for smooth 60fps rendering.
+ *
+ * ## Variants
+ * | Variant     | Shape              | Use Case |
+ * |-------------|--------------------| ---------|
+ * | text        | Rounded rectangle  | Text placeholders |
+ * | circular    | Perfect circle     | Avatars, icons |
+ * | rectangular | Sharp corners      | Images, cards |
+ *
+ * ## Size Presets
+ * | Size | Text Height | Circular | Rectangular |
+ * |------|-------------|----------|-------------|
+ * | sm   | 16px        | 32×32    | 80px height |
+ * | md   | 20px        | 40×40    | 120px height |
+ * | lg   | 28px        | 56×56    | 200px height |
+ *
+ * ## Animation Types
+ * - `pulse`: Smooth opacity fade (default, best performance)
+ * - `wave`: Shimmer effect (premium feel)
+ * - `none`: Static placeholder
+ *
+ * ## Features
+ * - Three shape variants (text, circular, rectangular)
+ * - Three size presets with custom override support
+ * - Smooth pulse animation using native driver
+ * - Theme-aware skeleton color
+ * - Hidden from screen readers (decorative)
+ * - Responsive size support
+ *
+ * @performance
+ * - Wrapped with React.memo() to prevent unnecessary re-renders
+ * - Uses native driver for smooth 60fps pulse animations
+ * - Animated loop runs independently per skeleton instance
+ * - Respects reduced motion preferences for accessibility
+ * - Dimension calculations cached with useMemo()
+ *
+ * ## Best Practices
+ * - Match skeleton dimensions to actual content
+ * - Use consistent animation across loading states
+ * - Provide actual loading state via aria-live regions
+ * - Avoid excessive skeleton count (cognitive load)
+ *
+ * @see Skeleton.types.ts - Type definitions
+ * @see Skeleton.helpers.ts - Dimension calculations
+ * @see Skeleton.a11y.ts - Accessibility (hidden from AT)
+ *
+ * @example
+ * // Basic text skeleton
+ * <Skeleton />
+ *
+ * @example
+ * // Avatar skeleton
+ * <Skeleton variant="circular" size="lg" />
+ *
+ * @example
+ * // Custom dimensions
+ * <Skeleton variant="rectangular" width={300} height={200} />
+ *
+ * @example
+ * // Responsive size
+ * <Skeleton size={{ phone: "sm", tablet: "lg" }} />
+ *
+ * @example
+ * // Text block placeholder
+ * <Box gap="xs">
+ *   <Skeleton width="90%" />
+ *   <Skeleton width="75%" />
+ *   <Skeleton width="85%" />
+ * </Box>
+ *
+ * @example
+ * // Card skeleton
+ * <Card>
+ *   <Skeleton variant="rectangular" height={150} />
+ *   <Box padding="md" gap="sm">
+ *     <Skeleton variant="text" size="lg" width="60%" />
+ *     <Skeleton variant="text" size="sm" />
+ *     <Skeleton variant="text" size="sm" width="80%" />
+ *   </Box>
+ * </Card>
+ */
+
+import {
+  createRestyleComponent,
+  layout,
+  spacing,
+  spacingShorthand,
+} from "@shopify/restyle";
+import React, { memo } from "react";
+import { RestyleTheme } from "../../../core/restyle";
+import { BaseThemeColor } from "../../../types";
+import { AnimatedBox } from "../../layout";
+import { BaseSkeletonContainerProps, SkeletonProps } from "./Skeleton.types";
+import { useSkeletonLogic } from "./useSkeletonLogic";
+
+/**
+ * Base Skeleton container with Restyle support.
+ * @internal
+ */
+const BaseSkeletonContainer = createRestyleComponent<
+  BaseSkeletonContainerProps,
+  RestyleTheme
+>([layout, spacing, spacingShorthand], AnimatedBox);
+
+function SkeletonComponent({
+  variant = "text",
+  size = "md",
+  width,
+  height,
+  animation = "pulse",
+  color = "specialSkeleton",
+  duration = 1500,
+  testID,
+  ...rest
+}: SkeletonProps) {
+  const {
+    resolvedWidth,
+    resolvedHeight,
+    borderRadius,
+    animatedOpacity,
+    backgroundColor,
+    a11yProps,
+  } = useSkeletonLogic({
+    variant,
+    size,
+    width,
+    height,
+    animation,
+    color,
+    duration,
+  });
+
+  return (
+    <BaseSkeletonContainer
+      testID={testID}
+      backgroundColor={backgroundColor as BaseThemeColor}
+      borderRadius={borderRadius}
+      width={resolvedWidth as any}
+      height={resolvedHeight}
+      style={{ opacity: animatedOpacity }}
+      {...a11yProps}
+      {...rest}
+    />
+  );
+}
+
+export const Skeleton = memo(SkeletonComponent);
+Skeleton.displayName = "Skeleton";

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

@@ -0,0 +1,223 @@
+/**
+ * Skeleton Component Types
+ *
+ * Type definitions for the Skeleton component and its related hooks/helpers.
+ * All types are explicitly exported for external consumption.
+ *
+ * @see Skeleton.tsx - Component implementation
+ */
+
+import { BoxProps, ResponsiveValue } from "@shopify/restyle";
+import { Animated, ViewProps } from "react-native";
+import { RestyleTheme } from "../../../core/restyle";
+import { RestyleColor } from "../../../types";
+
+// =============================================================================
+// VARIANT TYPES
+// =============================================================================
+
+/**
+ * Shape variant for the Skeleton component.
+ * Derived from the restyle theme's `skeletonVariants` keys.
+ *
+ * - `text`: Rounded rectangle for text placeholders (default)
+ * - `circular`: Perfect circle for avatars/icons
+ * - `rectangular`: Sharp corners for images/cards
+ */
+export type SkeletonVariant = Exclude<keyof RestyleTheme["skeletonVariants"], "defaults">;
+
+/**
+ * Size preset for the Skeleton component.
+ * Derived from the restyle theme's `skeletonSizes` keys.
+ * Maps to predefined dimensions for common use cases.
+ *
+ * - `sm`: Small - compact UI elements (16px height for text)
+ * - `md`: Medium - standard content (20px height for text)
+ * - `lg`: Large - headings/prominent elements (28px height for text)
+ */
+export type SkeletonSize = Exclude<keyof RestyleTheme["skeletonSizes"], "defaults">;
+
+/**
+ * Animation style for the Skeleton component.
+ *
+ * - `pulse`: Opacity fades in/out (default, performant)
+ * - `wave`: Shimmer effect moving left to right (premium feel)
+ * - `none`: No animation (static placeholder)
+ */
+export type SkeletonAnimation = "pulse" | "wave" | "none";
+
+// =============================================================================
+// COMPONENT PROPS
+// =============================================================================
+
+/** Base props combining Restyle Box props with ViewProps */
+export type BaseSkeletonProps = BoxProps<RestyleTheme> & ViewProps;
+
+/**
+ * Base props for the Skeleton container.
+ * @internal
+ */
+export type BaseSkeletonContainerProps = BoxProps<RestyleTheme> & ViewProps;
+
+/**
+ * Props for the Skeleton component.
+ *
+ * @example
+ * // Text skeleton (default)
+ * <Skeleton width={200} />
+ *
+ * @example
+ * // Avatar skeleton
+ * <Skeleton variant="circular" size="lg" />
+ *
+ * @example
+ * // Image placeholder
+ * <Skeleton variant="rectangular" width={300} height={200} />
+ *
+ * @example
+ * // Multiple text lines
+ * <Skeleton.Group>
+ *   <Skeleton width="80%" />
+ *   <Skeleton width="60%" />
+ *   <Skeleton width="90%" />
+ * </Skeleton.Group>
+ */
+export interface SkeletonProps extends Omit<BaseSkeletonProps, "width" | "height"> {
+  /**
+   * Shape variant of the skeleton (supports responsive values).
+   * @default "text"
+   */
+  variant?: ResponsiveValue<SkeletonVariant, RestyleTheme["breakpoints"]>;
+
+  /**
+   * Size preset (supports responsive values).
+   * Provides predefined dimensions based on variant.
+   * @default "md"
+   */
+  size?: ResponsiveValue<SkeletonSize, RestyleTheme["breakpoints"]>;
+
+  /**
+   * Custom width. Overrides size preset width.
+   * Accepts number (pixels), string (percentage), or responsive value.
+   */
+  width?: ResponsiveValue<number | string, RestyleTheme["breakpoints"]>;
+
+  /**
+   * Custom height. Overrides size preset height.
+   * Accepts number (pixels) or responsive value.
+   */
+  height?: ResponsiveValue<number, RestyleTheme["breakpoints"]>;
+
+  /**
+   * Animation style.
+   * @default "pulse"
+   */
+  animation?: SkeletonAnimation;
+
+  /**
+   * Background color token from theme.
+   * @default "specialSkeleton"
+   */
+  color?: RestyleColor;
+
+  /**
+   * Animation duration in milliseconds.
+   * @default 1500
+   */
+  duration?: number;
+
+  /** Test ID for testing frameworks */
+  testID?: string;
+}
+
+// =============================================================================
+// HOOK TYPES
+// =============================================================================
+
+/**
+ * Parameters for the useSkeletonLogic hook.
+ */
+export interface UseSkeletonLogicParams {
+  variant: ResponsiveValue<SkeletonVariant, RestyleTheme["breakpoints"]>;
+  size: ResponsiveValue<SkeletonSize, RestyleTheme["breakpoints"]>;
+  width?: ResponsiveValue<number | string, RestyleTheme["breakpoints"]>;
+  height?: ResponsiveValue<number, RestyleTheme["breakpoints"]>;
+  animation: SkeletonAnimation;
+  color: RestyleColor;
+  duration: number;
+}
+
+/**
+ * Return value from the useSkeletonLogic hook.
+ */
+export interface UseSkeletonLogicReturn {
+  /** Resolved width value */
+  resolvedWidth: number | string;
+  /** Resolved height value */
+  resolvedHeight: number;
+  /** Border radius based on variant */
+  borderRadius: keyof RestyleTheme["borderRadii"];
+  /** Animated opacity value for pulse animation */
+  animatedOpacity: Animated.Value;
+  /** Background color token */
+  backgroundColor: RestyleColor;
+  /** Accessibility props */
+  a11yProps: SkeletonA11yProps;
+}
+
+// =============================================================================
+// HELPER TYPES
+// =============================================================================
+
+/**
+ * Dimensions configuration for skeleton sizes.
+ */
+export interface SkeletonDimensions {
+  width: number | string;
+  height: number;
+}
+
+/**
+ * Size configuration map by variant.
+ */
+export type SkeletonSizeConfig = Record<SkeletonVariant, Record<SkeletonSize, SkeletonDimensions>>;
+
+/**
+ * Parameters for resolving skeleton dimensions.
+ */
+export interface ResolveSkeletonDimensionsParams {
+  variant: SkeletonVariant;
+  size: SkeletonSize;
+  customWidth?: number | string;
+  customHeight?: number;
+}
+
+/**
+ * Result from resolving skeleton dimensions.
+ */
+export interface SkeletonDimensionsResult {
+  width: number | string;
+  height: number;
+}
+
+// =============================================================================
+// ACCESSIBILITY TYPES
+// =============================================================================
+
+/**
+ * Parameters for generating skeleton accessibility props.
+ */
+export interface SkeletonA11yParams {
+  /** Optional label for screen readers */
+  accessibilityLabel?: string;
+}
+
+/**
+ * Accessibility props returned by getSkeletonA11y.
+ */
+export interface SkeletonA11yProps {
+  accessible: boolean;
+  accessibilityRole: "none";
+  accessibilityElementsHidden: boolean;
+  importantForAccessibility: "no-hide-descendants";
+}

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

@@ -0,0 +1,44 @@
+/**
+ * Skeleton Component
+ *
+ * @description Animated placeholder for loading states
+ *
+ * @example
+ * import { Skeleton } from "@/design-system";
+ *
+ * // Text skeleton
+ * <Skeleton />
+ *
+ * // Avatar skeleton
+ * <Skeleton variant="circular" size="lg" />
+ *
+ * // Image placeholder
+ * <Skeleton variant="rectangular" width={300} height={200} />
+ */
+
+export { Skeleton } from "./Skeleton";
+export type {
+  BaseSkeletonProps,
+  ResolveSkeletonDimensionsParams,
+  SkeletonA11yParams,
+  SkeletonA11yProps,
+  SkeletonAnimation,
+  SkeletonDimensions,
+  SkeletonDimensionsResult,
+  SkeletonProps,
+  SkeletonSize,
+  SkeletonSizeConfig,
+  SkeletonVariant,
+  UseSkeletonLogicParams,
+  UseSkeletonLogicReturn,
+} from "./Skeleton.types";
+export {
+  getSkeletonBorderRadius,
+  getSkeletonDimensions,
+  getSkeletonSizePreset,
+  SKELETON_ANIMATION,
+  SKELETON_BORDER_RADIUS,
+  SKELETON_SIZE_CONFIG,
+} from "./Skeleton.helpers";
+export { getSkeletonA11y } from "./Skeleton.a11y";
+export { useSkeletonLogic } from "./useSkeletonLogic";