@praxiis/ui 0.0.1

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

@@ -0,0 +1,20 @@
+/**
+ * Icon Module
+ *
+ * Atom component for rendering Material Icons with theme integration.
+ *
+ * @example
+ * import { Icon } from "@/design-system/primitives/Icon";
+ *
+ * <Icon name="home" size="lg" color="accentPrimary" />
+ */
+
+export { Icon } from "./Icon";
+export { getIconA11y } from "./Icon.a11y";
+
+export type {
+  IconName,
+  IconProps,
+  IconSize,
+  IconA11yProps,
+} from "./Icon.types";

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

@@ -0,0 +1,73 @@
+/**
+ * Icon Logic Hook
+ *
+ * Extracts all computational logic from the Icon component.
+ * Returns memoized values for optimal render performance.
+ *
+ * Responsibilities:
+ * - Resolve responsive size prop to current breakpoint value
+ * - Convert size token to pixel value
+ * - Resolve color token to hex value
+ * - Generate accessibility props
+ *
+ * @see Icon.tsx - Component consuming this hook
+ * @see Icon.helpers.ts - Pure calculation functions
+ */
+
+import { useResponsiveProp } from "@shopify/restyle";
+import { useMemo } from "react";
+import { useRestyleTheme } from "../../../core/restyle";
+import { getIconA11y } from "./Icon.a11y";
+import { resolveIconColor, resolveIconSizeValue } from "./Icon.helpers";
+import { IconSize, UseIconLogicParams, UseIconLogicReturn } from "./Icon.types";
+
+/**
+ * Orchestrates Icon rendering logic and state management.
+ * 
+ * Handles:
+ * - Responsive size resolution
+ * - Size token to pixel value conversion
+ * - Color token to hex value resolution
+ * - Accessibility props generation
+ * 
+ * @param params - Configuration object for icon behavior
+ * @param params.color - Theme color token for icon
+ * @param params.size - Size variant ('xs' | 'sm' | 'md' | 'lg' | 'xl')
+ * @param params.accessibilityLabel - Screen reader label (required for standalone icons)
+ * @param params.accessibilityHint - Describes action result
+ * 
+ * @returns Computed values for rendering Icon
+ * @returns {number} iconSizeValue - Icon size in pixels (12-32px)
+ * @returns {string} iconColor - Resolved hex color value
+ * @returns {object} a11yProps - Accessibility props
+ * 
+ * @performance This hook uses useMemo() for size and color resolution
+ * 
+ * @example
+ * const { iconSizeValue, iconColor, a11yProps } = useIconLogic({
+ *   color: "textPrimary",
+ *   size: "md",
+ *   accessibilityLabel: "Home",
+ * });
+ */
+export function useIconLogic(params: UseIconLogicParams): UseIconLogicReturn {
+  const { color, size, accessibilityLabel, accessibilityHint } = params;
+
+  const theme = useRestyleTheme();
+  const resolvedSize = (useResponsiveProp(size) ?? "md") as IconSize;
+
+  const iconSizeValue = resolveIconSizeValue({ resolvedSize, theme });
+
+  const iconColor = resolveIconColor(color, theme);
+
+  const a11yProps = useMemo(
+    () => getIconA11y({ accessibilityLabel, accessibilityHint }),
+    [accessibilityLabel, accessibilityHint],
+  );
+
+  return {
+    iconSizeValue,
+    iconColor,
+    a11yProps,
+  };
+}

package/src/primitives/content/index.ts

@@ -0,0 +1,45 @@
+/**
+ * Content Components Module
+ *
+ * Components that present information to the user.
+ */
+
+export {
+  Avatar,
+  type AvatarProps,
+  type AvatarSize,
+  type AvatarStatus,
+  getInitials,
+  getAvatarA11y,
+} from "./Avatar";
+
+export {
+  Badge,
+  type BadgeProps,
+  type BadgeSize,
+  type BadgeVariant,
+  formatBadgeLabel,
+  getBadgeA11y,
+} from "./Badge";
+
+export {
+  Chip,
+  type ChipProps,
+  type ChipSize,
+  type ChipVariant,
+} from "./Chip";
+
+export {
+  Card,
+  type CardProps,
+  type CardVariant,
+} from "./Card";
+
+export {
+  Icon,
+  getIconA11y,
+  type IconName,
+  type IconProps,
+  type IconSize,
+  type IconA11yProps,
+} from "./Icon";

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

@@ -0,0 +1,122 @@
+/**
+ * ProgressBar Component Helpers
+ *
+ * Pure functions for computing progress values and styles.
+ *
+ * ## Size Mapping
+ * | Size | Height | Border Radius |
+ * |------|--------|---------------|
+ * | sm   | 4px    | 2px (xs)      |
+ * | md   | 8px    | 4px (sm)      |
+ * | lg   | 12px   | 6px (md)      |
+ *
+ * ## Color Model
+ * The indicator color is supplied directly via a `color` prop (RestyleColor).
+ * The track background is always `"borderSubtle"`.
+ */
+
+import { ProgressBarSize } from "./ProgressBar.types";
+
+// =============================================================================
+// PROGRESS VALUE UTILITIES
+// =============================================================================
+
+/**
+ * Clamp progress value between 0 and 1.
+ *
+ * Ensures the progress value is always within valid bounds,
+ * even if invalid values are passed.
+ *
+ * @param progress - Raw progress value
+ * @returns Clamped value between 0 and 1
+ *
+ * @example
+ * clampProgress(0.5)  // 0.5
+ * clampProgress(-0.2) // 0
+ * clampProgress(1.5)  // 1
+ */
+export function clampProgress(progress: number): number {
+  return Math.min(Math.max(progress, 0), 1);
+}
+
+/**
+ * Convert progress (0-1) to percentage (0-100).
+ *
+ * @param progress - Progress value between 0 and 1
+ * @returns Percentage as integer (0-100)
+ *
+ * @example
+ * progressToPercent(0.5)   // 50
+ * progressToPercent(0.333) // 33
+ */
+export function progressToPercent(progress: number): number {
+  return Math.round(clampProgress(progress) * 100);
+}
+
+/**
+ * Get width percentage string for indicator.
+ *
+ * @param progress - Progress value between 0 and 1
+ * @returns Width percentage string (e.g., "50%")
+ *
+ * @example
+ * getWidthPercent(0.5) // "50%"
+ */
+export function getWidthPercent(progress: number): string {
+  return `${progressToPercent(progress)}%`;
+}
+
+// =============================================================================
+// SIZE RESOLUTION
+// =============================================================================
+
+/**
+ * Progress bar height mapping.
+ *
+ * | Size | Height |
+ * |------|--------|
+ * | sm   | 4px    |
+ * | md   | 8px    |
+ * | lg   | 12px   |
+ */
+export const PROGRESS_BAR_HEIGHTS: Record<ProgressBarSize, number> = {
+  sm: 4,
+  md: 8,
+  lg: 12,
+} as const;
+
+/**
+ * Progress bar border radius mapping.
+ * Uses half of height for pill shape.
+ *
+ * | Size | Radius |
+ * |------|--------|
+ * | sm   | 2px    |
+ * | md   | 4px    |
+ * | lg   | 6px    |
+ */
+export const PROGRESS_BAR_BORDER_RADIUS: Record<ProgressBarSize, number> = {
+  sm: 2,
+  md: 4,
+  lg: 6,
+} as const;
+
+/**
+ * Get height for a size variant.
+ *
+ * @param size - Progress bar size
+ * @returns Height in pixels
+ */
+export function getProgressBarHeight(size: ProgressBarSize): number {
+  return PROGRESS_BAR_HEIGHTS[size];
+}
+
+/**
+ * Get border radius for a size variant.
+ *
+ * @param size - Progress bar size
+ * @returns Border radius in pixels
+ */
+export function getProgressBarBorderRadius(size: ProgressBarSize): number {
+  return PROGRESS_BAR_BORDER_RADIUS[size];
+}

package/src/primitives/feedback/ProgressBar/ProgressBar.tsx

@@ -0,0 +1,154 @@
+/**
+ * ProgressBar Component
+ *
+ * @description Determinate progress indicator with theme integration - Atom
+ *
+ * ProgressBars display the completion status of a task or process.
+ * Uses a track (background) and indicator (filled portion) pattern
+ * with support for a custom `color` prop and multiple sizes.
+ *
+ * ## Ratios & Constraints
+ * - Height scales proportionally with size variant
+ * - Border radius is half of height for pill shape
+ * - Indicator smoothly fills based on progress value
+ *
+ * ## Size Scale
+ * | Size | Height | Border Radius | Use Case |
+ * |------|--------|---------------|----------|
+ * | sm   | 4px    | 2px           | Inline, compact indicators |
+ * | md   | 8px    | 4px           | Standard progress bars |
+ * | lg   | 12px   | 6px           | Prominent indicators |
+ *
+ * ## Color Model
+ * The `color` prop accepts any `RestyleColor` token (base or app-extended).
+ * The track background is always `"borderSubtle"`.
+ *
+ * ## Features
+ * - Responsive size prop
+ * - Flexible color via RestyleColor token
+ * - Optional label support
+ * - Full accessibility support (progressbar role with value)
+ * - Memoized for performance
+ * - Restyle spacing prop support
+ *
+ * @see ProgressBar.types.ts - Type definitions
+ * @see ProgressBar.helpers.ts - Pure calculation functions
+ * @see ProgressBar.a11y.ts - Accessibility prop generation
+ *
+ * @example
+ * // Basic usage
+ * <ProgressBar progress={0.5} />
+ *
+ * @example
+ * // With color and label
+ * <ProgressBar
+ *   progress={0.75}
+ *   color="feedbackSuccess"
+ *   label="Upload complete"
+ *   accessibilityLabel="File upload 75% complete"
+ * />
+ *
+ * @example
+ * // Responsive size with spacing
+ * <ProgressBar
+ *   progress={0.3}
+ *   size={{ phone: "sm", tablet: "md" }}
+ *   marginBottom="lg"
+ * />
+ */
+
+import {
+  createRestyleComponent,
+  createVariant,
+  layout,
+  spacing,
+  spacingShorthand,
+} from "@shopify/restyle";
+import React, { memo } from "react";
+import { DimensionValue } from "react-native";
+import { RestyleTheme } from "../../../core/restyle";
+import { BaseThemeColor } from "../../../types";
+import { Box } from "../../layout";
+import { Text } from "../../typography";
+import {
+  BaseProgressBarContainerProps,
+  ProgressBarProps,
+} from "./ProgressBar.types";
+import { useProgressBarLogic } from "./useProgressBarLogic";
+
+/**
+ * Base container with Restyle variant support for sizing.
+ * @internal
+ */
+const BaseProgressBarContainer = createRestyleComponent<
+  BaseProgressBarContainerProps,
+  RestyleTheme
+>(
+  [
+    createVariant({ themeKey: "progressBarSizes", property: "size" }),
+    layout,
+    spacing,
+    spacingShorthand,
+  ],
+  Box,
+);
+
+// =============================================================================
+// PROGRESS BAR COMPONENT
+// =============================================================================
+
+function ProgressBarComponent({
+  progress,
+  color = "accentPrimary",
+  size = "md",
+  label,
+  accessibilityLabel,
+  testID,
+  style,
+  ...rest
+}: ProgressBarProps) {
+  const {
+    widthPercent,
+    indicatorColorToken,
+    trackColorToken,
+    borderRadius,
+    a11yProps,
+  } = useProgressBarLogic({
+    progress,
+    color,
+    size,
+    accessibilityLabel,
+  });
+
+  return (
+    <BaseProgressBarContainer
+      size={size}
+      testID={testID}
+      style={style}
+      {...rest}
+    >
+      {label && (
+        <Text variant="labelSmall" color="textSecondary" marginBottom="xs">
+          {label}
+        </Text>
+      )}
+      <Box
+        width="100%"
+        overflow="hidden"
+        backgroundColor={trackColorToken}
+        style={{ borderRadius }}
+        {...a11yProps}
+      >
+        <Box
+          height="100%"
+          width={widthPercent as DimensionValue}
+          backgroundColor={indicatorColorToken as BaseThemeColor}
+          style={{ borderRadius }}
+        />
+      </Box>
+    </BaseProgressBarContainer>
+  );
+}
+
+export const ProgressBar = memo(ProgressBarComponent);
+ProgressBar.displayName = "ProgressBar";

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

@@ -0,0 +1,178 @@
+/**
+ * ProgressBar Component Types
+ *
+ * Type definitions for the ProgressBar component and its related hooks/helpers.
+ *
+ * @see ProgressBar.tsx - Component implementation
+ */
+
+import { BoxProps, ResponsiveValue, VariantProps } from "@shopify/restyle";
+import { ViewProps, ViewStyle } from "react-native";
+import { RestyleTheme } from "../../../core/restyle";
+import { RestyleColor } from "../../../types";
+
+// =============================================================================
+// SIZE TYPES
+// =============================================================================
+
+/**
+ * Size variant for the ProgressBar.
+ * Derived from the restyle theme's `progressBarSizes` keys.
+ *
+ * - `sm`: 4px height - compact inline progress
+ * - `md`: 8px height - standard progress bars (default)
+ * - `lg`: 12px height - prominent progress indicators
+ */
+export type ProgressBarSize = Exclude<keyof RestyleTheme["progressBarSizes"], "defaults">;
+
+// =============================================================================
+// RESTYLE PROP TYPES
+// =============================================================================
+
+type ProgressBarSizeProps = VariantProps<
+  RestyleTheme,
+  "progressBarSizes",
+  "size"
+>;
+type ProgressBarRestyleProps = ProgressBarSizeProps & BoxProps<RestyleTheme>;
+
+export type BaseProgressBarProps = ProgressBarRestyleProps & ViewProps;
+
+// =============================================================================
+// COMPONENT PROPS
+// =============================================================================
+
+/**
+ * Props for the ProgressBar component.
+ *
+ * @example
+ * <ProgressBar progress={0.5} />
+ *
+ * @example
+ * <ProgressBar
+ *   progress={0.75}
+ *   color="feedbackSuccess"
+ *   size="lg"
+ *   label="Upload progress"
+ *   accessibilityLabel="File upload 75% complete"
+ * />
+ */
+export interface ProgressBarProps extends Omit<
+  BaseProgressBarProps,
+  "variant" | "style" | "size"
+> {
+  /**
+   * Progress value between 0 and 1.
+   * - 0 = empty
+   * - 0.5 = 50% complete
+   * - 1 = fully complete
+   */
+  progress: number;
+
+  /**
+   * Color token for the progress indicator fill.
+   * Accepts any RestyleColor — base theme tokens or app-extended tokens.
+   * The track background is always `"borderSubtle"`.
+   * @default "accentPrimary"
+   */
+  color?: RestyleColor;
+
+  /**
+   * Size of the progress bar (supports responsive values).
+   * @default "md"
+   */
+  size?: ResponsiveValue<ProgressBarSize, RestyleTheme["breakpoints"]>;
+
+  /**
+   * Optional visible label displayed above the progress bar.
+   * When provided, creates a labeled progress indicator.
+   */
+  label?: string;
+
+  /**
+   * Custom style overrides for the container.
+   */
+  style?: ViewStyle;
+
+  /** Test ID for testing frameworks */
+  testID?: string;
+
+  /**
+   * Accessibility label for screen readers.
+   * Should describe what the progress represents.
+   * @example "File upload progress"
+   */
+  accessibilityLabel?: string;
+}
+
+// =============================================================================
+// HOOK TYPES
+// =============================================================================
+
+/**
+ * Parameters for the useProgressBarLogic hook.
+ */
+export interface UseProgressBarLogicParams {
+  progress: number;
+  color: RestyleColor;
+  size: ResponsiveValue<ProgressBarSize, RestyleTheme["breakpoints"]>;
+  accessibilityLabel?: string;
+}
+
+/**
+ * Return value from the useProgressBarLogic hook.
+ */
+export interface UseProgressBarLogicReturn {
+  /** Clamped progress value (0-1) */
+  clampedProgress: number;
+  /** Progress as percentage (0-100) */
+  progressPercent: number;
+  /** Width percentage string for indicator */
+  widthPercent: string;
+  /** Indicator color token (e.g., "accentPrimary") — may be an extended color */
+  indicatorColorToken: RestyleColor;
+  /** Track background color token — always "borderSubtle" */
+  trackColorToken: keyof RestyleTheme["colors"];
+  /** Resolved border radius value */
+  borderRadius: number;
+  /** Accessibility props */
+  a11yProps: ProgressBarA11yProps;
+}
+
+// =============================================================================
+// ACCESSIBILITY TYPES
+// =============================================================================
+
+/**
+ * Parameters for getProgressBarA11y function.
+ */
+export interface ProgressBarA11yParams {
+  progress: number;
+  accessibilityLabel?: string;
+
+  /**
+   * Pre-translated fallback label from i18n.
+   * Used when accessibilityLabel is not provided.
+   */
+  fallbackLabel: string;
+}
+/**
+ * Accessibility props returned by getProgressBarA11y.
+ * Implements WCAG 4.1.2 Name, Role, Value for determinate progress bars.
+ */
+export interface ProgressBarA11yProps {
+  accessibilityRole: "progressbar";
+  accessibilityLabel: string;
+  accessibilityValue: {
+    min: number;
+    max: number;
+    now: number;
+  };
+}
+
+// =============================================================================
+// BASE COMPONENT (Restyle-enabled container)
+// =============================================================================
+export type BaseProgressBarContainerProps = ProgressBarSizeProps &
+  BoxProps<RestyleTheme> &
+  ViewProps;

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

@@ -0,0 +1,17 @@
+/**
+ * ProgressBar Module
+ *
+ * Atom component for displaying determinate progress with theme integration.
+ *
+ * @example
+ * import { ProgressBar } from "@/design-system/primitives/feedback/ProgressBar";
+ *
+ * <ProgressBar progress={0.75} color="feedbackSuccess" accessibilityLabel="Upload progress" />
+ */
+
+export { ProgressBar } from "./ProgressBar";
+export type {
+  ProgressBarProps,
+  ProgressBarSize,
+} from "./ProgressBar.types";
+export * from "./ProgressBar.a11y";