@praxiis/ui 0.0.1

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

@@ -0,0 +1,235 @@
+/**
+ * IconButton Component Helpers
+ *
+ * Pure functions for computing IconButton styles, sizes, and colors.
+ * All calculations are derived from the centralized scales.ts token file.
+ */
+
+import { Insets } from "react-native";
+import {
+  GHOST_ICON_BUTTON_HIT_SLOP,
+  ICON_BUTTON_HIT_SLOP,
+  ICON_BUTTON_ICON_SIZE,
+  SPINNER_SIZE,
+} from "../../../tokens/scales";
+import { BaseThemeColor, RestyleColor } from "../../../types";
+import { IconSize } from "../../content/Icon";
+import {
+  IconButtonSize,
+  IconButtonStyleResult,
+  IconButtonVariant,
+  ResolveIconButtonStyleParams,
+} from "./IconButton.types";
+
+// =============================================================================
+// ICON SIZE RESOLUTION
+// =============================================================================
+
+/**
+ * Get icon size based on button size.
+ *
+ * Uses ICON_BUTTON_ICON_SIZE from scales.ts for mathematical consistency.
+ * Target ratio: ~45% (ICON_RATIOS.circularButton)
+ *
+ * | Size | Container | Icon | Ratio |
+ * |------|-----------|------|-------|
+ * | sm   | 36px      | 16px | 44%   |
+ * | md   | 44px      | 20px | 45%   |
+ * | lg   | 56px      | 24px | 43%   |
+ *
+ * @param size - The button size variant
+ * @returns The corresponding icon size
+ */
+export function getIconButtonIconSize(size: IconButtonSize): IconSize {
+  return ICON_BUTTON_ICON_SIZE[size];
+}
+
+// =============================================================================
+// TOUCH TARGET (hitSlop)
+// =============================================================================
+
+/**
+ * Get hitSlop based on button size and variant.
+ *
+ * Uses pre-calculated values from scales.ts to ensure
+ * all buttons meet the 44px minimum touch target.
+ *
+ * For contained/outlined variants:
+ * | Size | Container | hitSlop | Total |
+ * |------|-----------|---------|-------|
+ * | sm   | 36px      | 4px     | 44px  |
+ * | md   | 44px      | 0px     | 44px  |
+ * | lg   | 56px      | 0px     | 56px  |
+ *
+ * For ghost variant (icon size only):
+ * | Size | Icon   | hitSlop | Total |
+ * |------|--------|---------|-------|
+ * | sm   | 16px   | 14px    | 44px  |
+ * | md   | 20px   | 12px    | 44px  |
+ * | lg   | 24px   | 10px    | 44px  |
+ *
+ * @param size - The button size variant
+ * @param variant - The visual variant
+ * @returns Insets for touch target expansion
+ */
+export function getIconButtonHitSlop(
+  size: IconButtonSize,
+  variant: IconButtonVariant = "contained"
+): Insets {
+  // Ghost variant has no container, so use icon-based hitSlop
+  if (variant === "ghost") {
+    return GHOST_ICON_BUTTON_HIT_SLOP[size];
+  }
+  return ICON_BUTTON_HIT_SLOP[size];
+}
+
+// =============================================================================
+// SPINNER SIZE
+// =============================================================================
+
+/**
+ * Get spinner size based on button size.
+ *
+ * Uses SPINNER_SIZE from scales.ts for consistency across all components.
+ *
+ * | Button Size | Spinner Size |
+ * |-------------|--------------|
+ * | sm          | sm           |
+ * | md          | sm           |
+ * | lg          | lg           |
+ *
+ * @param size - The button size variant
+ * @returns The spinner size
+ */
+export function getIconButtonSpinnerSize(size: IconButtonSize): "sm" | "lg" {
+  return SPINNER_SIZE[size];
+}
+
+// =============================================================================
+// COLOR RESOLUTION
+// =============================================================================
+
+/**
+ * Get icon color based on variant and disabled state.
+ *
+ * | Variant   | Normal       | Disabled     |
+ * |-----------|--------------|--------------|
+ * | contained | textInverse  | textDisabled |
+ * | outlined  | color prop   | textDisabled |
+ * | ghost     | color prop   | textDisabled |
+ *
+ * @param variant - The visual variant
+ * @param color - The primary color prop
+ * @param disabled - Whether the button is disabled
+ * @returns The computed icon color
+ */
+export function getIconButtonIconColor(
+  variant: IconButtonVariant,
+  color: RestyleColor,
+  disabled: boolean
+): RestyleColor {
+  if (disabled) {
+    return "textDisabled";
+  }
+
+  // Contained variant uses inverse text color for contrast
+  if (variant === "contained") {
+    return "textInverse";
+  }
+
+  // Outlined and ghost variants use the specified color
+  return color;
+}
+
+/**
+ * Get spinner color based on variant and disabled state.
+ *
+ * Follows the same logic as icon color for visual consistency.
+ *
+ * @param variant - The visual variant
+ * @param color - The primary color prop
+ * @param disabled - Whether the button is disabled
+ * @returns The computed spinner color
+ */
+export function getIconButtonSpinnerColor(
+  variant: IconButtonVariant,
+  color: RestyleColor,
+  disabled: boolean
+): RestyleColor {
+  // Spinner uses same color logic as icon
+  return getIconButtonIconColor(variant, color, disabled);
+}
+
+// =============================================================================
+// THEME VARIANT KEY
+// =============================================================================
+
+/**
+ * Maps component variant to theme variant key.
+ *
+ * Currently 1:1 mapping, but this abstraction allows for
+ * future divergence between component API and theme structure.
+ *
+ * @param variant - The component variant
+ * @returns The theme variant key
+ */
+export function getIconButtonThemeVariantKey(
+  variant: IconButtonVariant
+): IconButtonVariant {
+  return variant;
+}
+
+// =============================================================================
+// STYLE RESOLUTION
+// =============================================================================
+
+/**
+ * Resolve dynamic style properties for the IconButton container.
+ *
+ * Static styles (borderRadius) come from theme variants.
+ * This function handles dynamic state-based values:
+ * - backgroundColor based on variant and disabled state
+ * - borderColor based on variant and disabled state
+ * - opacity based on disabled/loading state
+ *
+ * @param params - Resolution parameters
+ * @returns Computed style object
+ */
+export function resolveIconButtonStyle(
+  params: ResolveIconButtonStyleParams
+): IconButtonStyleResult {
+  const { variant, disabled, isLoading, color, theme } = params;
+
+  const isDisabledOrLoading = disabled || isLoading;
+
+  let backgroundColor: string;
+  let borderColor: string;
+  let borderWidth: number;
+
+  switch (variant) {
+    case "contained":
+      backgroundColor = isDisabledOrLoading
+        ? theme.colors.interactiveDisabled
+        : theme.colors[color as BaseThemeColor];
+      borderColor = "transparent";
+      borderWidth = 0;
+      break;
+
+    case "outlined":
+      backgroundColor = "transparent";
+      borderColor = isDisabledOrLoading
+        ? theme.colors.borderDefault
+        : theme.colors[color as BaseThemeColor];
+      borderWidth = 2;
+      break;
+
+    case "ghost":
+    default:
+      backgroundColor = "transparent";
+      borderColor = "transparent";
+      borderWidth = 0;
+      break;
+  }
+
+  return { backgroundColor, borderColor, borderWidth, opacity: 1 };
+}

package/src/primitives/actions/IconButton/IconButton.tsx

@@ -0,0 +1,177 @@
+/**
+ * IconButton Component
+ *
+ * @description Circular icon-only button for actions - Atom
+ *
+ * IconButton provides icon-only interactive controls for common actions
+ * like favorites, settings, close, etc. It's optimized for touch with
+ * proper hit targets and accessibility.
+ *
+ * ## Ratios & Constraints
+ * - Icon = Container × ~45% (ICON_RATIOS.circularButton)
+ * - All sizes meet 44px minimum touch target via hitSlop
+ *
+ * ## Size Scale
+ * | Size | Container | Icon | hitSlop | Touch Target |
+ * |------|-----------|------|---------|--------------|
+ * | sm   | 36px      | 16px | 4px     | 44px         |
+ * | md   | 44px      | 20px | 0px     | 44px         |
+ * | lg   | 56px      | 24px | 0px     | 56px         |
+ *
+ * ## Variants
+ * - `contained`: Solid background (default)
+ * - `outlined`: Border only, transparent background
+ * - `ghost`: Icon only, no container (minimal footprint)
+ *
+ * ## Features
+ * - Responsive size prop (phone/tablet breakpoints)
+ * - Loading state with spinner
+ * - Full accessibility support
+ *
+ * @performance
+ * - Wrapped with React.memo() to prevent unnecessary re-renders
+ * - Uses useMemo() for expensive calculations (style resolution, icon sizing)
+ * - Icon calculations cached using ~45% container ratio for 60fps performance
+ * - Ghost variant dynamic sizing optimized with conditional style computation
+ *
+ * @see IconButton.types.ts - Type definitions
+ * @see IconButton.helpers.ts - Pure calculation functions
+ * @see IconButton.a11y.ts - Accessibility prop generation
+ * @see tokens/scales.ts - Mathematical ratios
+ *
+ * @example
+ * // Basic usage
+ * <IconButton
+ *   iconName="favorite"
+ *   onPress={handleLike}
+ *   accessibilityLabel="Add to favorites"
+ * />
+ *
+ * @example
+ * // Responsive with loading state
+ * <IconButton
+ *   iconName="save"
+ *   onPress={handleSave}
+ *   variant="outlined"
+ *   size={{ phone: "md", tablet: "lg" }}
+ *   isLoading={isSaving}
+ *   accessibilityLabel="Save changes"
+ * />
+ */
+
+import {
+  backgroundColor,
+  border,
+  createRestyleComponent,
+  createVariant,
+  layout,
+  spacing,
+  spacingShorthand,
+} from "@shopify/restyle";
+import React, { memo, useCallback } from "react";
+import { Pressable } from "react-native";
+import { RestyleTheme } from "../../../core/restyle";
+import { Icon } from "../../content/Icon";
+import { Spinner } from "../../feedback/Spinner";
+import {
+  BaseIconButtonContainerProps,
+  IconButtonProps,
+} from "./IconButton.types";
+import { useIconButtonLogic } from "./useIconButtonLogic";
+
+/**
+ * Base container with Restyle variant support.
+ * @internal
+ */
+const BaseIconButtonContainer = createRestyleComponent<
+  BaseIconButtonContainerProps,
+  RestyleTheme
+>(
+  [
+    createVariant({ themeKey: "iconButtonVariants" }),
+    createVariant({ themeKey: "iconButtonSizes", property: "size" }),
+    backgroundColor,
+    border,
+    layout,
+    spacing,
+    spacingShorthand,
+  ],
+  Pressable,
+);
+
+function IconButtonComponent({
+  iconName,
+  onPress,
+  variant = "contained",
+  size = "md",
+  color = "accentPrimary",
+  disabled = false,
+  isLoading = false,
+  testID,
+  accessibilityLabel,
+  accessibilityHint,
+  ...rest
+}: IconButtonProps) {
+  const {
+    iconSize,
+    iconColor,
+    containerStyle,
+    hitSlop,
+    a11yProps,
+    showSpinner,
+    spinnerSize,
+    spinnerColor,
+    themeVariantKey,
+    spinnerAccessibilityLabel,
+  } = useIconButtonLogic({
+    iconName,
+    variant,
+    size,
+    color,
+    disabled,
+    isLoading,
+    accessibilityLabel,
+    accessibilityHint,
+  });
+
+  const handlePress = useCallback(() => {
+    if (!disabled && !isLoading) {
+      onPress();
+    }
+  }, [disabled, isLoading, onPress]);
+
+  return (
+    <BaseIconButtonContainer
+      variant={themeVariantKey}
+      // Only apply size variant for contained/outlined - ghost should wrap icon
+      size={variant === "ghost" ? undefined : size}
+      onPress={handlePress}
+      disabled={disabled || isLoading}
+      hitSlop={hitSlop}
+      testID={testID}
+      alignItems="center"
+      justifyContent="center"
+      style={containerStyle}
+      {...a11yProps}
+      {...rest}
+    >
+      {showSpinner ? (
+        <Spinner
+          size={spinnerSize}
+          color={spinnerColor}
+          accessibilityLabel={spinnerAccessibilityLabel}
+        />
+      ) : (
+        <Icon
+          name={iconName}
+          size={iconSize}
+          color={iconColor}
+          accessibilityLabel={iconName}
+        />
+      )}
+    </BaseIconButtonContainer>
+  );
+}
+
+export const IconButton = memo(IconButtonComponent);
+IconButton.displayName = "IconButton";

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

@@ -0,0 +1,273 @@
+/**
+ * IconButton Component Types
+ *
+ * Type definitions for the IconButton component and its related hooks/helpers.
+ * All types are explicitly exported for external consumption.
+ */
+
+import { BoxProps, ResponsiveValue, VariantProps } from "@shopify/restyle";
+import { Insets, PressableProps, ViewStyle } from "react-native";
+import { RestyleTheme } from "../../../core/restyle";
+import { RestyleColor } from "../../../types";
+import { IconName, IconSize } from "../../content/Icon";
+
+// =============================================================================
+// VARIANT TYPES (Explicitly exported for external use)
+// =============================================================================
+
+/**
+ * Visual style variants for IconButton.
+ *
+ * - `contained`: Solid background with inverse icon color
+ * - `outlined`: Transparent background with colored border
+ * - `ghost`: No background or border, icon only (minimal footprint)
+ */
+export type IconButtonVariant = Exclude<
+  keyof RestyleTheme["iconButtonVariants"],
+  "defaults"
+>;
+
+/**
+ * Size variants derived from theme.
+ * Maps to iconButtonSizes in restyleTheme.ts
+ *
+ * | Size | Container | Touch Target |
+ * |------|-----------|--------------|
+ * | sm   | 36px      | 44px (hitSlop) |
+ * | md   | 44px      | 44px (native) |
+ * | lg   | 56px      | 56px (native) |
+ */
+export type IconButtonSize = Exclude<
+  keyof RestyleTheme["iconButtonSizes"],
+  "defaults"
+>;
+
+// =============================================================================
+// RESTYLE PROP TYPES
+// =============================================================================
+
+type IconButtonVariantProps = VariantProps<RestyleTheme, "iconButtonVariants">;
+type IconButtonSizeVariantProps = VariantProps<
+  RestyleTheme,
+  "iconButtonSizes",
+  "size"
+>;
+type IconButtonRestyleProps = IconButtonVariantProps &
+  IconButtonSizeVariantProps &
+  BoxProps<RestyleTheme>;
+
+/**
+ * Base props for the IconButton container component.
+ * Combines Restyle props with Pressable props.
+ */
+export type BaseIconButtonContainerProps = IconButtonRestyleProps &
+  PressableProps;
+
+// =============================================================================
+// COMPONENT PROPS
+// =============================================================================
+
+/**
+ * Props for the IconButton component.
+ *
+ * @example
+ * // Basic usage
+ * <IconButton
+ *   iconName="favorite"
+ *   onPress={handleLike}
+ *   accessibilityLabel="Add to favorites"
+ * />
+ *
+ * @example
+ * // Responsive size with loading state
+ * <IconButton
+ *   iconName="save"
+ *   onPress={handleSave}
+ *   variant="outlined"
+ *   size={{ phone: "md", tablet: "lg" }}
+ *   color="accentPrimary"
+ *   isLoading={isSaving}
+ *   accessibilityLabel="Save changes"
+ *   accessibilityHint="Double tap to save your changes"
+ * />
+ */
+export interface IconButtonProps
+  extends Omit<IconButtonRestyleProps, "size" | "variant"> {
+  /** Icon name from MaterialIcons */
+  iconName: IconName;
+
+  /** Press handler callback */
+  onPress: () => void;
+
+  /** Visual variant of the button (supports responsive values) */
+  variant?: ResponsiveValue<IconButtonVariant, RestyleTheme["breakpoints"]>;
+
+  /** Size of the button (supports responsive values) */
+  size?: ResponsiveValue<IconButtonSize, RestyleTheme["breakpoints"]>;
+
+  /** Primary color - controls background (contained) or border/icon (outlined/ghost) */
+  color?: RestyleColor;
+
+  /** Whether the button is disabled */
+  disabled?: boolean;
+
+  /** Whether the button is in a loading state */
+  isLoading?: boolean;
+
+  /** Test ID for testing */
+  testID?: string;
+
+  /** Accessibility label (required for screen readers) */
+  accessibilityLabel: string;
+
+  /** Accessibility hint for additional context */
+  accessibilityHint?: string;
+}
+
+// =============================================================================
+// LOGIC HOOK TYPES
+// =============================================================================
+
+/**
+ * Parameters for the useIconButtonLogic hook.
+ */
+export interface UseIconButtonLogicParams {
+  /** Icon name from MaterialIcons */
+  iconName: IconName;
+
+  /** Visual variant of the button */
+  variant: ResponsiveValue<IconButtonVariant, RestyleTheme["breakpoints"]>;
+
+  /** Size of the button (supports responsive values) */
+  size: ResponsiveValue<IconButtonSize, RestyleTheme["breakpoints"]>;
+
+  /** Primary color for the button */
+  color: RestyleColor;
+
+  /** Whether the button is disabled */
+  disabled: boolean;
+
+  /** Whether the button is in a loading state */
+  isLoading: boolean;
+
+  /** Accessibility label for screen readers */
+  accessibilityLabel: string;
+
+  /** Accessibility hint for additional context */
+  accessibilityHint?: string;
+}
+
+/**
+ * Return value from the useIconButtonLogic hook.
+ * Contains all computed values needed to render the IconButton.
+ */
+export interface UseIconButtonLogicReturn {
+  /** Resolved icon size from scale mapping */
+  iconSize: IconSize;
+
+  /** Computed icon color based on variant and state */
+  iconColor: RestyleColor;
+
+  /** Dynamic container styles (backgroundColor, borderColor, opacity) */
+  containerStyle: ViewStyle;
+
+  /** Touch target expansion based on visual size */
+  hitSlop: Insets;
+
+  /** Accessibility properties object */
+  a11yProps: IconButtonA11yProps;
+
+  /** Whether to show spinner instead of icon */
+  showSpinner: boolean;
+
+  /** Spinner size derived from button size */
+  spinnerSize: "sm" | "lg";
+
+  /** Spinner color matching icon color logic */
+  spinnerColor: RestyleColor;
+
+  /** Theme variant key for BaseIconButtonContainer */
+  themeVariantKey: IconButtonVariant;
+
+  /** Translated loading label for spinner accessibility */
+  spinnerAccessibilityLabel: string;
+}
+
+// =============================================================================
+// ACCESSIBILITY TYPES
+// =============================================================================
+
+/**
+ * Parameters for the getIconButtonA11y function.
+ */
+export interface IconButtonA11yParams {
+  /** Accessibility label for screen readers */
+  accessibilityLabel: string;
+
+  /** Optional accessibility hint */
+  accessibilityHint?: string;
+
+  /** Whether the button is disabled */
+  disabled: boolean;
+
+  /** Whether the button is loading */
+  isLoading: boolean;
+}
+
+/**
+ * Accessibility props returned by getIconButtonA11y.
+ */
+export interface IconButtonA11yProps {
+  /** Label read by screen readers */
+  accessibilityLabel: string;
+
+  /** Hint read by screen readers (optional) */
+  accessibilityHint?: string;
+
+  /** Role for screen readers */
+  accessibilityRole: "button";
+
+  /** State for screen readers */
+  accessibilityState: { disabled: boolean; busy: boolean };
+}
+
+// =============================================================================
+// STYLE RESOLUTION TYPES
+// =============================================================================
+
+/**
+ * Parameters for the resolveIconButtonStyle function.
+ */
+export interface ResolveIconButtonStyleParams {
+  /** Visual variant of the button */
+  variant: IconButtonVariant;
+
+  /** Whether the button is disabled */
+  disabled: boolean;
+
+  /** Whether the button is loading */
+  isLoading: boolean;
+
+  /** Primary color for the button */
+  color: RestyleColor;
+
+  /** The Restyle theme object */
+  theme: RestyleTheme;
+}
+
+/**
+ * Result from resolveIconButtonStyle function.
+ */
+export interface IconButtonStyleResult {
+  /** Background color value */
+  backgroundColor: string;
+
+  /** Border color value */
+  borderColor: string;
+
+  /** Border width in pixels */
+  borderWidth: number;
+
+  /** Opacity value (0-1) */
+  opacity: number;
+}

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

@@ -0,0 +1,30 @@
+/**
+ * IconButton Module
+ *
+ * Atom component for circular icon-only buttons.
+ *
+ * ## Mathematical Ratios
+ * - Icon = Container × ~45% (ICON_RATIOS.circularButton)
+ * - All sizes meet 44px minimum touch target
+ *
+ * @example
+ * import { IconButton } from "@/design-system/primitives/actions/IconButton";
+ *
+ * <IconButton
+ *   iconName="favorite"
+ *   onPress={handleLike}
+ *   accessibilityLabel="Add to favorites"
+ * />
+ */
+
+export { IconButton } from "./IconButton";
+
+export type {
+  IconButtonProps,
+  IconButtonVariant,
+  IconButtonSize,
+  IconButtonA11yParams,
+  IconButtonA11yProps,
+} from "./IconButton.types";
+
+export { getIconButtonA11y } from "./IconButton.a11y";