@praxiis/ui 0.0.1

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

@@ -0,0 +1,222 @@
+/**
+ * Avatar Component Types
+ *
+ * Type definitions for the Avatar component and its related hooks/helpers.
+ * All types are explicitly exported for external consumption.
+ *
+ * @see Avatar.tsx - Component implementation
+ */
+
+import { BoxProps, ResponsiveValue } from "@shopify/restyle";
+import { ImageSourcePropType, ViewProps } from "react-native";
+import { RestyleTheme } from "../../../core/restyle";
+import { RestyleColor } from "../../../types";
+
+// =============================================================================
+// VARIANT TYPES
+// =============================================================================
+
+/**
+ * Size preset for the Avatar component.
+ * Derived from theme avatarSizes variant.
+ *
+ * - `sm`: 32×32 - Compact lists, comments
+ * - `md`: 40×40 - Standard avatar (default)
+ * - `lg`: 56×56 - Profile headers, featured users
+ */
+export type AvatarSize = Exclude<keyof RestyleTheme["avatarSizes"], "defaults">;
+
+/**
+ * Status indicator for the Avatar component.
+ *
+ * - `online`: Green dot - user is active
+ * - `offline`: Gray dot - user is inactive
+ * - `busy`: Red dot - do not disturb
+ * - `away`: Yellow dot - user is away
+ * - `none`: No status indicator (default)
+ */
+export type AvatarStatus = "online" | "offline" | "busy" | "away" | "none";
+
+// =============================================================================
+// COMPONENT PROPS
+// =============================================================================
+
+/** Base props combining Restyle Box props with ViewProps */
+export type BaseAvatarProps = BoxProps<RestyleTheme> & ViewProps;
+
+/**
+ * Base props for the Avatar container.
+ * @internal
+ */
+export type BaseAvatarContainerProps = BoxProps<RestyleTheme> & ViewProps;
+
+/**
+ * Props for the Avatar component.
+ *
+ * @example
+ * // Image avatar
+ * <Avatar source={{ uri: "https://example.com/avatar.jpg" }} />
+ *
+ * @example
+ * // Initials fallback
+ * <Avatar name="John Doe" />
+ *
+ * @example
+ * // With status indicator
+ * <Avatar source={avatarUrl} status="online" />
+ *
+ * @example
+ * // Different sizes
+ * <Avatar name="JD" size="lg" />
+ */
+export interface AvatarProps extends Omit<BaseAvatarProps, "width" | "height" | "backgroundColor"> {
+  /**
+   * Image source for the avatar.
+   * Falls back to initials if not provided or fails to load.
+   */
+  source?: ImageSourcePropType;
+
+  /**
+   * User's name for generating initials fallback.
+   * First letter of first and last name are used (e.g., "John Doe" → "JD").
+   */
+  name?: string;
+
+  /**
+   * Size preset (supports responsive values).
+   * @default "md"
+   */
+  size?: ResponsiveValue<AvatarSize, RestyleTheme["breakpoints"]>;
+
+  /**
+   * Status indicator to display.
+   * @default "none"
+   */
+  status?: AvatarStatus;
+
+  /**
+   * Background color for initials fallback.
+   * @default "accentPrimary"
+   */
+  backgroundColor?: RestyleColor;
+
+  /**
+   * Text color for initials.
+   * @default "textInverse"
+   */
+  initialsColor?: RestyleColor;
+
+  /**
+   * Accessibility label for the avatar.
+   * Defaults to name if provided.
+   */
+  accessibilityLabel?: string;
+
+  /** Test ID for testing frameworks */
+  testID?: string;
+}
+
+// =============================================================================
+// HOOK TYPES
+// =============================================================================
+
+/**
+ * Parameters for the useAvatarLogic hook.
+ */
+export interface UseAvatarLogicParams {
+  source?: ImageSourcePropType;
+  name?: string;
+  size: ResponsiveValue<AvatarSize, RestyleTheme["breakpoints"]>;
+  status: AvatarStatus;
+  backgroundColor: RestyleColor;
+  initialsColor: RestyleColor;
+  accessibilityLabel?: string;
+}
+
+/**
+ * Return value from the useAvatarLogic hook.
+ */
+export interface UseAvatarLogicReturn {
+  /** Resolved size value */
+  resolvedSize: AvatarSize;
+  /** Computed avatar dimensions */
+  dimensions: AvatarDimensions;
+  /** Whether to show image or initials */
+  showImage: boolean;
+  /** Generated initials from name */
+  initials: string;
+  /** Status indicator color */
+  statusColor: RestyleColor | null;
+  /** Status indicator dimensions */
+  statusDimensions: StatusDimensions | null;
+  /** Accessibility props */
+  a11yProps: AvatarA11yProps;
+  /** Handler for image load error */
+  onImageError: () => void;
+}
+
+// =============================================================================
+// HELPER TYPES
+// =============================================================================
+
+/**
+ * Dimensions configuration for avatar sizes.
+ */
+export interface AvatarDimensions {
+  size: number;
+  fontSize: number;
+  borderRadius: number;
+}
+
+/**
+ * Dimensions for status indicator by avatar size.
+ */
+export interface StatusDimensions {
+  size: number;
+  borderWidth: number;
+  offset: number;
+}
+
+/**
+ * Size configuration map.
+ */
+export type AvatarSizeConfig = Record<AvatarSize, AvatarDimensions>;
+
+/**
+ * Status indicator configuration map.
+ */
+export type StatusSizeConfig = Record<AvatarSize, StatusDimensions>;
+
+/**
+ * Status color mapping.
+ */
+export type StatusColorMap = Record<Exclude<AvatarStatus, "none">, RestyleColor>;
+
+// =============================================================================
+// ACCESSIBILITY TYPES
+// =============================================================================
+
+/**
+ * Parameters for generating avatar accessibility props.
+ */
+export interface AvatarA11yParams {
+  /** User's name or custom label */
+  name?: string;
+  /** Custom accessibility label */
+  accessibilityLabel?: string;
+  /** Current status */
+  status: AvatarStatus;
+  /** Pre-translated fallback label */
+  fallbackLabel: string;
+  /** Pre-translated status labels */
+  statusLabels: Record<Exclude<AvatarStatus, "none">, string>;
+}
+
+/**
+ * Accessibility props returned by getAvatarA11y.
+ */
+export interface AvatarA11yProps {
+  accessible: boolean;
+  accessibilityRole: "image";
+  accessibilityLabel: string;
+}

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

@@ -0,0 +1,46 @@
+/**
+ * Avatar Component
+ *
+ * @description Profile images with fallback initials and status indicators
+ *
+ * @example
+ * import { Avatar } from "@/design-system";
+ *
+ * // Image avatar
+ * <Avatar source={{ uri: "https://..." }} name="John Doe" />
+ *
+ * // Initials fallback
+ * <Avatar name="John Doe" />
+ *
+ * // With status
+ * <Avatar name="Jane" status="online" />
+ */
+
+export { Avatar } from "./Avatar";
+export type {
+  AvatarA11yParams,
+  AvatarA11yProps,
+  AvatarDimensions,
+  AvatarProps,
+  AvatarSize,
+  AvatarSizeConfig,
+  AvatarStatus,
+  BaseAvatarContainerProps,
+  BaseAvatarProps,
+  StatusColorMap,
+  StatusDimensions,
+  StatusSizeConfig,
+  UseAvatarLogicParams,
+  UseAvatarLogicReturn,
+} from "./Avatar.types";
+export {
+  AVATAR_SIZE_CONFIG,
+  getAvatarDimensions,
+  getInitials,
+  getStatusColor,
+  getStatusDimensions,
+  STATUS_COLORS,
+  STATUS_SIZE_CONFIG,
+} from "./Avatar.helpers";
+export { getAvatarA11y } from "./Avatar.a11y";
+export { useAvatarLogic } from "./useAvatarLogic";

package/src/primitives/content/Avatar/useAvatarLogic.ts

@@ -0,0 +1,149 @@
+/**
+ * Avatar Logic Hook
+ *
+ * Extracts all computational logic from the Avatar component.
+ * Returns memoized values for optimal render performance.
+ *
+ * Responsibilities:
+ * - Resolve responsive size prop
+ * - Calculate dimensions based on size
+ * - Generate initials from name
+ * - Handle image load errors
+ * - Provide accessibility props
+ *
+ * @see Avatar.tsx - Component consuming this hook
+ * @see Avatar.helpers.ts - Pure calculation functions
+ */
+
+import { useDesignSystem } from "../../../provider";
+import { useResponsiveProp } from "@shopify/restyle";
+import { useCallback, useMemo, useState } from "react";
+import { getAvatarA11y } from "./Avatar.a11y";
+import {
+  getAvatarDimensions,
+  getInitials,
+  getStatusColor,
+  getStatusDimensions,
+} from "./Avatar.helpers";
+import { AvatarSize, UseAvatarLogicParams, UseAvatarLogicReturn } from "./Avatar.types";
+
+/**
+ * Orchestrates Avatar rendering logic and state management.
+ * 
+ * Handles:
+ * - Responsive size resolution
+ * - Dimension calculation (width, height, border radius)
+ * - Image vs initials display logic
+ * - Initials generation from name
+ * - Image error handling (fallback to initials)
+ * - Status indicator color and dimensions
+ * - Accessibility props generation
+ * 
+ * @param params - Configuration object for avatar behavior
+ * @param params.source - Image source (local or remote)
+ * @param params.name - User name (for initials fallback)
+ * @param params.size - Size variant ('xs' | 'sm' | 'md' | 'lg' | 'xl')
+ * @param params.status - Status indicator ('none' | 'online' | 'offline' | 'busy' | 'away')
+ * @param params.backgroundColor - Theme color token for initials background
+ * @param params.initialsColor - Theme color token for initials text
+ * @param params.accessibilityLabel - Custom a11y label
+ * 
+ * @returns Computed values for rendering Avatar
+ * @returns {string} resolvedSize - Resolved size variant
+ * @returns {object} dimensions - Width, height, border radius
+ * @returns {boolean} showImage - Whether to display image or initials
+ * @returns {string} initials - Generated initials (1-2 chars)
+ * @returns {string} statusColor - Status indicator color token
+ * @returns {object} statusDimensions - Status indicator dimensions
+ * @returns {object} a11yProps - Accessibility props
+ * @returns {function} onImageError - Image error handler
+ * 
+ * @performance This hook uses useMemo() for expensive calculations
+ * 
+ * @example
+ * const {
+ *   dimensions,
+ *   showImage,
+ *   initials,
+ *   statusColor,
+ *   statusDimensions,
+ *   a11yProps,
+ *   onImageError,
+ * } = useAvatarLogic({
+ *   source: { uri: "https://..." },
+ *   name: "John Doe",
+ *   size: "md",
+ *   status: "online",
+ *   backgroundColor: "accentPrimary",
+ *   initialsColor: "textInverse",
+ * });
+ */
+export function useAvatarLogic({
+  source,
+  name,
+  size,
+  status,
+  backgroundColor,
+  initialsColor,
+  accessibilityLabel,
+}: UseAvatarLogicParams): UseAvatarLogicReturn {
+  const { labels: t } = useDesignSystem();
+
+  // Track image load errors
+  const [imageError, setImageError] = useState(false);
+
+  // Resolve responsive size
+  const resolvedSize = (useResponsiveProp(size) ?? "md") as AvatarSize;
+
+  // Calculate dimensions
+  const dimensions = getAvatarDimensions(resolvedSize);
+
+  // Determine if we should show image or initials
+  const showImage = !!source && !imageError;
+
+  // Generate initials
+  const initials = getInitials(name);
+
+  // Get status color
+  const statusColor = getStatusColor(status);
+
+  // Get status dimensions
+  const statusDimensions = status !== "none" ? getStatusDimensions(resolvedSize) : null;
+
+  // Handle image load error
+  const onImageError = useCallback(() => {
+    setImageError(true);
+  }, []);
+
+  // Build translated status labels
+  const statusLabels = useMemo(() => ({
+    online: t.designSystem.avatar.statusOnline,
+    offline: t.designSystem.avatar.statusOffline,
+    busy: t.designSystem.avatar.statusBusy,
+    away: t.designSystem.avatar.statusAway,
+  }), [t]);
+
+  // Accessibility props
+  const a11yProps = useMemo(
+    () =>
+      getAvatarA11y({
+        name,
+        accessibilityLabel,
+        status,
+        fallbackLabel: t.designSystem.avatar.fallbackLabel,
+        statusLabels,
+      }),
+    [name, accessibilityLabel, status, t, statusLabels]
+  );
+
+  return {
+    resolvedSize,
+    dimensions,
+    showImage,
+    initials,
+    statusColor,
+    statusDimensions,
+    a11yProps,
+    onImageError,
+  };
+}

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

@@ -0,0 +1,175 @@
+/**
+ * Badge Component Helpers
+ *
+ * Pure functions for calculating badge dimensions and color styles.
+ * All values follow 4px/8px grid system for consistency.
+ *
+ * ## Size Scale
+ * | Size | Height | Min Width | Dot Size | Use Case |
+ * |------|--------|-----------|----------|----------|
+ * | sm   | 16px   | 16px      | 6px      | Inline indicators |
+ * | md   | 20px   | 20px      | 8px      | Standard (default) |
+ * | lg   | 24px   | 24px      | 10px     | Prominent badges |
+ *
+ * ## Color Variants
+ * - `filled`: Solid background, inverse text
+ * - `outlined`: Border only, transparent background
+ */
+
+import {
+  BadgeColorStyles,
+  BadgeDimensions,
+  BadgeSize,
+  BadgeSizeConfig,
+  BadgeVariant,
+} from "./Badge.types";
+import { RestyleColor } from "../../../types";
+
+// =============================================================================
+// TYPOGRAPHY & DOT SIZE MAPPINGS
+// =============================================================================
+
+/**
+ * Map badge size to typography variant for label text.
+ *
+ * | Size | Typography     |
+ * |------|----------------|
+ * | sm   | captionSmall   |
+ * | md   | caption        |
+ * | lg   | labelSmall     |
+ */
+export const BADGE_TYPOGRAPHY: Record<
+  BadgeSize,
+  "captionSmall" | "caption" | "labelSmall"
+> = {
+  sm: "captionSmall",
+  md: "caption",
+  lg: "labelSmall",
+};
+
+/**
+ * Map badge size to dot indicator dimensions.
+ *
+ * | Size | Dot Size |
+ * |------|----------|
+ * | sm   | 6px      |
+ * | md   | 8px      |
+ * | lg   | 10px     |
+ */
+export const BADGE_DOT_SIZE: Record<BadgeSize, number> = {
+  sm: 6,
+  md: 8,
+  lg: 10,
+};
+
+/**
+ * Size configuration for badge dimensions.
+ * Following 4px/8px grid system.
+ */
+export const BADGE_SIZE_CONFIG: BadgeSizeConfig = {
+  sm: {
+    height: 16,
+    minWidth: 16,
+    paddingHorizontal: 4,
+    borderRadius: 8,
+    dotSize: 6,
+    fontSize: 10,
+  },
+  md: {
+    height: 20,
+    minWidth: 20,
+    paddingHorizontal: 6,
+    borderRadius: 10,
+    dotSize: 8,
+    fontSize: 12,
+  },
+  lg: {
+    height: 24,
+    minWidth: 24,
+    paddingHorizontal: 8,
+    borderRadius: 12,
+    dotSize: 10,
+    fontSize: 14,
+  },
+} as const;
+
+/**
+ * Get color styles for a badge based on variant and color token.
+ * Works with any RestyleColor — no preset lookup needed.
+ *
+ * @param variant - Badge variant
+ * @param color - Any theme color token
+ * @returns Color styles for the badge
+ *
+ * @example
+ * getBadgeColorStyles("filled", "feedbackSuccess")
+ * // { backgroundColor: "feedbackSuccess", textColor: "textInverse", ... }
+ */
+export function getBadgeColorStyles(
+  variant: BadgeVariant,
+  color: RestyleColor,
+): BadgeColorStyles {
+  if (variant === "outlined") {
+    return {
+      backgroundColor: "transparent",
+      textColor: color,
+      borderColor: color,
+      borderWidth: 1,
+    };
+  }
+
+  // filled (default)
+  return {
+    backgroundColor: color,
+    textColor: "textInverse",
+    borderColor: "transparent",
+    borderWidth: 0,
+  };
+}
+
+/**
+ * Get dimensions for a badge based on size.
+ *
+ * @param size - Badge size preset
+ * @returns Badge dimensions
+ *
+ * @example
+ * getBadgeDimensions("md")
+ * // { height: 20, minWidth: 20, paddingHorizontal: 6, ... }
+ */
+export function getBadgeDimensions(size: BadgeSize): BadgeDimensions {
+  return BADGE_SIZE_CONFIG[size];
+}
+
+/**
+ * Format the display text for a badge.
+ * Handles max value truncation for numeric labels.
+ *
+ * @param label - The label value
+ * @param max - Maximum numeric value before truncation
+ * @returns Formatted display string
+ *
+ * @example
+ * formatBadgeLabel(5, 99)
+ * // "5"
+ *
+ * @example
+ * formatBadgeLabel(100, 99)
+ * // "99+"
+ *
+ * @example
+ * formatBadgeLabel("New", 99)
+ * // "New"
+ */
+export function formatBadgeLabel(
+  label: string | number | undefined,
+  max: number
+): string {
+  if (label === undefined || label === null) return "";
+
+  if (typeof label === "number") {
+    return label > max ? `${max}+` : String(label);
+  }
+
+  return String(label);
+}