@praxiis/ui 0.0.1

package/src/primitives/actions/IconButton/useIconButtonLogic.ts

@@ -0,0 +1,172 @@
+/**
+ * IconButton Logic Hook
+ *
+ * Extracts all computational logic from the IconButton component.
+ * Returns memoized values for optimal render performance.
+ *
+ * Responsibilities:
+ * - Resolve responsive size prop to current breakpoint value
+ * - Compute icon size from container size (~45% ratio)
+ * - Determine icon/spinner colors based on variant and state
+ * - Calculate container styles (background, border, opacity)
+ * - Compute hitSlop for proper touch targets
+ * - Generate accessibility props
+ *
+ * The component (IconButton.tsx) is a "dumb view" that only renders
+ * the pre-computed values from this hook.
+ *
+ * @see IconButton.tsx - Component consuming this hook
+ * @see IconButton.helpers.ts - Pure calculation functions
+ * @see tokens/scales.ts - Mathematical ratios and constants
+ */
+
+import { useDesignSystem } from "../../../provider";
+import { useResponsiveProp } from "@shopify/restyle";
+import { useMemo } from "react";
+import { ViewStyle } from "react-native";
+import { useRestyleTheme } from "../../../core/restyle";
+import { getIconButtonA11y } from "./IconButton.a11y";
+import {
+  getIconButtonHitSlop,
+  getIconButtonIconColor,
+  getIconButtonIconSize,
+  getIconButtonSpinnerColor,
+  getIconButtonSpinnerSize,
+  getIconButtonThemeVariantKey,
+  resolveIconButtonStyle,
+} from "./IconButton.helpers";
+import {
+  IconButtonSize,
+  IconButtonVariant,
+  UseIconButtonLogicParams,
+  UseIconButtonLogicReturn,
+} from "./IconButton.types";
+
+/**
+ * Orchestrates IconButton rendering logic and state management.
+ * 
+ * Handles:
+ * - Responsive size and variant resolution
+ * - Icon size calculation (~45% of container ratio)
+ * - Icon and spinner color determination
+ * - Container styles (background, border, opacity)
+ * - Hit slop calculation for 44px minimum touch target
+ * - Ghost variant dynamic sizing (wraps icon tightly)
+ * - Accessibility props generation
+ * 
+ * @param params - Configuration object for icon button behavior
+ * @param params.variant - Visual variant ('contained' | 'outlined' | 'ghost')
+ * @param params.size - Size variant ('sm' | 'md' | 'lg')
+ * @param params.color - Theme color token for background/icon
+ * @param params.disabled - Whether button is disabled
+ * @param params.isLoading - Whether to show loading spinner
+ * @param params.accessibilityLabel - Custom a11y label (required for icon-only)
+ * @param params.accessibilityHint - Describes action result
+ * 
+ * @returns Computed values for rendering IconButton
+ * @returns {number} iconSize - Icon size in pixels (16-24px)
+ * @returns {string} iconColor - Icon color token
+ * @returns {ViewStyle} containerStyle - Dynamic container styles
+ * @returns {Insets} hitSlop - Touch target expansion
+ * @returns {object} a11yProps - Accessibility props
+ * @returns {boolean} showSpinner - Whether to display spinner
+ * @returns {string} spinnerSize - Spinner size variant
+ * @returns {string} spinnerColor - Spinner color token
+ * @returns {string} themeVariantKey - Restyle theme variant identifier
+ * 
+ * @performance This hook uses useMemo() for expensive calculations
+ * 
+ * @example
+ * const { iconSize, iconColor, containerStyle, hitSlop, a11yProps } = useIconButtonLogic({
+ *   variant: "contained",
+ *   size: "md",
+ *   color: "accentPrimary",
+ *   disabled: false,
+ *   isLoading: false,
+ *   accessibilityLabel: "Add to favorites",
+ * });
+ */
+export function useIconButtonLogic(
+  params: UseIconButtonLogicParams,
+): UseIconButtonLogicReturn {
+  const {
+    variant,
+    size,
+    color,
+    disabled,
+    isLoading,
+    accessibilityLabel,
+    accessibilityHint,
+  } = params;
+
+  const { labels: t } = useDesignSystem();
+  const theme = useRestyleTheme();
+  const resolvedSize = (useResponsiveProp(size) ?? "md") as IconButtonSize;
+  const resolvedVariant = (useResponsiveProp(variant) ?? "contained") as IconButtonVariant;
+
+  const themeVariantKey = getIconButtonThemeVariantKey(resolvedVariant);
+  const iconSize = getIconButtonIconSize(resolvedSize);
+  const iconColor = getIconButtonIconColor(resolvedVariant, color, disabled);
+  const hitSlop = getIconButtonHitSlop(resolvedSize, resolvedVariant);
+  const spinnerSize = getIconButtonSpinnerSize(resolvedSize);
+  const spinnerColor = getIconButtonSpinnerColor(resolvedVariant, color, disabled);
+
+  // Only calculate dynamic colors and opacity - structure comes from theme variant
+  const containerStyle = useMemo((): ViewStyle => {
+    const styleResult = resolveIconButtonStyle({
+      variant: resolvedVariant,
+      disabled,
+      isLoading,
+      color,
+      theme,
+    });
+
+    const baseStyle: ViewStyle = {
+      backgroundColor: styleResult.backgroundColor,
+      borderColor: styleResult.borderColor,
+      opacity: styleResult.opacity,
+      // borderRadius and borderWidth are handled by the theme variant
+    };
+
+    // For ghost variant, remove fixed container size - just wrap the icon
+    // Override any size from theme variant
+    if (resolvedVariant === "ghost") {
+      baseStyle.width = undefined;
+      baseStyle.height = undefined;
+      baseStyle.minWidth = undefined;
+      baseStyle.minHeight = undefined;
+      baseStyle.maxWidth = undefined;
+      baseStyle.maxHeight = undefined;
+    }
+
+    return baseStyle;
+  }, [resolvedVariant, disabled, isLoading, color, theme]);
+
+  const a11yProps = useMemo(
+    () =>
+      getIconButtonA11y({
+        accessibilityLabel,
+        accessibilityHint,
+        disabled,
+        isLoading,
+      }),
+    [accessibilityLabel, accessibilityHint, disabled, isLoading],
+  );
+
+  const showSpinner = isLoading;
+
+  const spinnerAccessibilityLabel = t.designSystem.iconButton.loadingLabel;
+
+  return {
+    iconSize,
+    iconColor,
+    containerStyle,
+    hitSlop,
+    a11yProps,
+    showSpinner,
+    spinnerSize,
+    spinnerColor,
+    themeVariantKey,
+    spinnerAccessibilityLabel,
+  };
+}

package/src/primitives/actions/index.ts

@@ -0,0 +1,20 @@
+/**
+ * Actions Components Module
+ *
+ * Components that trigger user-initiated actions.
+ */
+
+export {
+  Button,
+  type ButtonProps,
+  type ButtonRef,
+  type ButtonSize,
+  type ButtonVariant,
+} from "./Button";
+
+export {
+  IconButton,
+  type IconButtonProps,
+  type IconButtonSize,
+  type IconButtonVariant,
+} from "./IconButton";

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

@@ -0,0 +1,177 @@
+/**
+ * Avatar Component Helpers
+ *
+ * Pure functions for calculating avatar dimensions, initials, and status colors.
+ * All values follow 8px grid system for consistency.
+ *
+ * ## Size Scale
+ * | Size | Dimensions | Font Size | Use Case |
+ * |------|------------|-----------|----------|
+ * | sm   | 32×32      | 12px      | Compact lists, comments |
+ * | md   | 40×40      | 14px      | Standard (default) |
+ * | lg   | 56×56      | 20px      | Profile headers |
+ *
+ * ## Status Indicator Scale
+ * | Size | Indicator | Border |
+ * |------|-----------|--------|
+ * | sm   | 8px       | 2px    |
+ * | md   | 10px      | 2px    |
+ * | lg   | 14px      | 2px    |
+ */
+
+import { RestyleColor } from "../../../types";
+import {
+  AvatarDimensions,
+  AvatarSize,
+  AvatarSizeConfig,
+  AvatarStatus,
+  StatusColorMap,
+  StatusDimensions,
+  StatusSizeConfig,
+} from "./Avatar.types";
+
+// =============================================================================
+// TYPOGRAPHY MAPPING
+// =============================================================================
+
+/**
+ * Map avatar size to typography variant for initials text.
+ *
+ * | Size | Typography   |
+ * |------|------------- |
+ * | sm   | labelSmall   |
+ * | md   | labelMedium  |
+ * | lg   | labelLarge   |
+ */
+export const AVATAR_INITIALS_TYPOGRAPHY: Record<
+  AvatarSize,
+  "labelSmall" | "labelMedium" | "labelLarge"
+> = {
+  sm: "labelSmall",
+  md: "labelMedium",
+  lg: "labelLarge",
+};
+
+/**
+ * Size configuration for avatar dimensions.
+ * Following 8px grid system.
+ */
+export const AVATAR_SIZE_CONFIG: AvatarSizeConfig = {
+  sm: { size: 32, fontSize: 12, borderRadius: 16 },
+  md: { size: 40, fontSize: 14, borderRadius: 20 },
+  lg: { size: 56, fontSize: 20, borderRadius: 28 },
+} as const;
+
+/**
+ * Status indicator size configuration by avatar size.
+ */
+export const STATUS_SIZE_CONFIG: StatusSizeConfig = {
+  sm: { size: 8, borderWidth: 2, offset: 0 },
+  md: { size: 10, borderWidth: 2, offset: 0 },
+  lg: { size: 14, borderWidth: 2, offset: 0 },
+} as const;
+
+/**
+ * Status indicator color mapping.
+ */
+export const STATUS_COLORS: StatusColorMap = {
+  online: "feedbackSuccess",
+  offline: "textTertiary",
+  busy: "feedbackError",
+  away: "feedbackWarning",
+} as const;
+
+/**
+ * Get dimensions for an avatar based on size.
+ *
+ * @param size - Avatar size preset
+ * @returns Avatar dimensions (size, fontSize, borderRadius)
+ *
+ * @example
+ * getAvatarDimensions("md")
+ * // { size: 40, fontSize: 14, borderRadius: 20 }
+ */
+export function getAvatarDimensions(size: AvatarSize): AvatarDimensions {
+  return AVATAR_SIZE_CONFIG[size];
+}
+
+/**
+ * Get status indicator dimensions based on avatar size.
+ *
+ * @param size - Avatar size preset
+ * @returns Status indicator dimensions
+ *
+ * @example
+ * getStatusDimensions("lg")
+ * // { size: 14, borderWidth: 2, offset: 0 }
+ */
+export function getStatusDimensions(size: AvatarSize): StatusDimensions {
+  return STATUS_SIZE_CONFIG[size];
+}
+
+/**
+ * Get status indicator color.
+ *
+ * @param status - Avatar status
+ * @returns Color token or null if no status
+ *
+ * @example
+ * getStatusColor("online")
+ * // "feedbackSuccess"
+ */
+export function getStatusColor(status: AvatarStatus): RestyleColor | null {
+  if (status === "none") return null;
+  return STATUS_COLORS[status];
+}
+
+/**
+ * Generate initials from a name.
+ * 
+ * Algorithm handles different naming conventions:
+ * - 1 word: first letter (e.g., "Luis" → "L")
+ * - 2-3 words: first + last (e.g., "John Doe" → "JD")
+ * - 4+ words: first + second-to-last (Hispanic pattern)
+ *   e.g., "Luis Enrique Medina Galvan" → "LM"
+ *   (First name + paternal surname)
+ *
+ * @param name - Full name string
+ * @returns Initials (1-2 characters, uppercase)
+ *
+ * @example
+ * getInitials("John Doe")
+ * // "JD"
+ *
+ * @example
+ * getInitials("Alice")
+ * // "A"
+ *
+ * @example
+ * getInitials("María José García López")
+ * // "MG" (first name + paternal surname)
+ *
+ * @example
+ * getInitials("Luis Enrique Medina Galvan")
+ * // "LM" (first name + paternal surname)
+ */
+export function getInitials(name?: string): string {
+  if (!name || name.trim().length === 0) return "?";
+
+  const parts = name.trim().split(/\s+/).filter(Boolean);
+
+  if (parts.length === 0) return "?";
+  if (parts.length === 1) return parts[0].charAt(0).toUpperCase();
+
+  const first = parts[0].charAt(0);
+
+  // For 4+ word names (common in Hispanic cultures),
+  // use first name + paternal surname (second-to-last)
+  // e.g., "Luis Enrique Medina Galvan" → L + M
+  if (parts.length >= 4) {
+    const paternal = parts[parts.length - 2].charAt(0);
+    return (first + paternal).toUpperCase();
+  }
+
+  // For 2-3 word names, use first + last
+  const last = parts[parts.length - 1].charAt(0);
+  return (first + last).toUpperCase();
+}

package/src/primitives/content/Avatar/Avatar.tsx

@@ -0,0 +1,199 @@
+/**
+ * Avatar Component
+ *
+ * @description Profile images with fallback initials and status indicators - Atom
+ *
+ * Avatar displays user profile images with automatic fallback to initials
+ * when no image is available or fails to load. Supports status indicators
+ * for presence information.
+ *
+ * ## Size Scale (from theme avatarSizes)
+ * | Size | Dimensions | Use Case |
+ * |------|------------|----------|
+ * | sm   | 32×32      | Compact lists, comments |
+ * | md   | 40×40      | Standard (default) |
+ * | lg   | 56×56      | Profile headers |
+ *
+ * ## Status Indicators
+ * - `online`: Green - user is active
+ * - `offline`: Gray - user is inactive
+ * - `busy`: Red - do not disturb
+ * - `away`: Yellow - user is away
+ * - `none`: No indicator (default)
+ *
+ * ## Features
+ * - Three size presets with responsive support (from restyle theme)
+ * - Automatic initials generation from name
+ * - Graceful image load error handling
+ * - Status indicator with proper positioning
+ * - Theme-aware colors
+ * - Accessible with proper labels
+ * - Memoized for performance
+ *
+ * ## Best Practices
+ * - Always provide `name` for fallback and accessibility
+ * - Use consistent sizes within a context
+ * - Consider loading states for async images
+ *
+ * @see Avatar.types.ts - Type definitions
+ * @see Avatar.helpers.ts - Dimension and initials calculations
+ * @see Avatar.a11y.ts - Accessibility props
+ *
+ * @example
+ * // Basic with image
+ * <Avatar source={{ uri: "https://example.com/avatar.jpg" }} name="John Doe" />
+ *
+ * @example
+ * // Initials fallback
+ * <Avatar name="John Doe" />
+ *
+ * @example
+ * // With status
+ * <Avatar source={avatarUrl} name="Jane" status="online" />
+ *
+ * @example
+ * // Large profile avatar
+ * <Avatar name="John Doe" size="lg" />
+ *
+ * @example
+ * // Responsive size
+ * <Avatar name="User" size={{ phone: "sm", tablet: "lg" }} />
+ *
+ * @example
+ * // Custom colors
+ * <Avatar
+ *   name="Brand User"
+ *   backgroundColor="accentSecondary"
+ *   initialsColor="white"
+ * />
+ */
+
+import {
+  createRestyleComponent,
+  createVariant,
+  layout,
+  spacing,
+  spacingShorthand,
+  VariantProps,
+} from "@shopify/restyle";
+import React, { memo } from "react";
+import { Image, StyleSheet } from "react-native";
+import { RestyleTheme } from "../../../core/restyle";
+import { BaseThemeColor } from "../../../types";
+import { Box } from "../../layout";
+import { Text } from "../../typography";
+import { AVATAR_INITIALS_TYPOGRAPHY } from "./Avatar.helpers";
+import { AvatarProps, BaseAvatarContainerProps } from "./Avatar.types";
+import { useAvatarLogic } from "./useAvatarLogic";
+
+/**
+ * Size variant for Avatar.
+ * @internal
+ */
+const sizeVariant = createVariant<RestyleTheme, "avatarSizes", "size">({
+  themeKey: "avatarSizes",
+  property: "size",
+});
+
+/**
+ * Base Avatar container with Restyle support.
+ * @internal
+ */
+const BaseAvatarContainer = createRestyleComponent<
+  BaseAvatarContainerProps & VariantProps<RestyleTheme, "avatarSizes", "size">,
+  RestyleTheme
+>([layout, spacing, spacingShorthand, sizeVariant], Box);
+
+function AvatarComponent({
+  source,
+  name,
+  size = "md",
+  status = "none",
+  backgroundColor = "accentPrimary",
+  initialsColor = "textInverse",
+  accessibilityLabel,
+  testID,
+  ...rest
+}: AvatarProps) {
+  const {
+    resolvedSize,
+    dimensions,
+    showImage,
+    initials,
+    statusColor,
+    statusDimensions,
+    a11yProps,
+    onImageError,
+  } = useAvatarLogic({
+    source,
+    name,
+    size,
+    status,
+    backgroundColor,
+    initialsColor,
+    accessibilityLabel,
+  });
+
+  return (
+    <BaseAvatarContainer
+      testID={testID}
+      size={resolvedSize}
+      {...a11yProps}
+      {...rest}
+    >
+      {/* Inner container for image/initials with overflow hidden */}
+      <Box
+        width={dimensions.size}
+        height={dimensions.size}
+        borderRadius="full"
+        backgroundColor={showImage ? undefined : (backgroundColor as BaseThemeColor)}
+        overflow="hidden"
+        alignItems="center"
+        justifyContent="center"
+      >
+        {showImage ? (
+          <Image
+            source={source!}
+            style={[
+              styles.image,
+              { width: dimensions.size, height: dimensions.size },
+            ]}
+            onError={onImageError}
+          />
+        ) : (
+          <Text
+            variant={AVATAR_INITIALS_TYPOGRAPHY[resolvedSize]}
+            color={initialsColor as BaseThemeColor}
+            fontWeight="600"
+          >
+            {initials}
+          </Text>
+        )}
+      </Box>
+
+      {/* Status indicator - outside overflow hidden container */}
+      {statusColor && statusDimensions && (
+        <Box
+          position="absolute"
+          bottom={statusDimensions.offset}
+          right={statusDimensions.offset}
+          width={statusDimensions.size}
+          height={statusDimensions.size}
+          borderRadius="full"
+          backgroundColor={statusColor as BaseThemeColor}
+          borderWidth={statusDimensions.borderWidth}
+          borderColor="backgroundPrimary"
+        />
+      )}
+    </BaseAvatarContainer>
+  );
+}
+
+const styles = StyleSheet.create({
+  image: {
+    resizeMode: "cover",
+  },
+});
+
+export const Avatar = memo(AvatarComponent);
+Avatar.displayName = "Avatar";