@praxiis/ui 0.0.1

package/src/primitives/actions/Button/Button.tsx

@@ -0,0 +1,198 @@
+/**
+ * Button Component
+ *
+ * @description Text button for primary actions - Atom
+ *
+ * Button provides labeled interactive controls for triggering actions.
+ * Supports optional icons, loading states, and multiple visual variants.
+ *
+ * ## Ratios & Constraints
+ * - Icon matches text visual weight (ICON_RATIOS.textAdjacent = 1.0)
+ * - All sizes meet 44px minimum touch target
+ *
+ * ## Size Scale
+ * | Size | Height | Icon | Text Variant | Padding |
+ * |------|--------|------|--------------|---------|
+ * | sm   | 36px   | 16px | labelSmall   | sm (8px)|
+ * | md   | 44px   | 20px | labelMedium  | md (12px)|
+ * | lg   | 52px   | 24px | labelLarge   | lg (16px)|
+ *
+ * ## Variants
+ * - `solid`: Solid background (default)
+ * - `outline`: Border only, transparent background
+ * - `ghost`: Text only, no background or border
+ *
+ * ## Features
+ * - Responsive size prop (phone/tablet breakpoints)
+ * - Optional leading icon
+ * - Loading state with spinner
+ * - Full accessibility support
+ *
+ * @performance
+ * - Wrapped with React.memo() to prevent unnecessary re-renders
+ * - Uses useMemo() for expensive calculations (style resolution, color computation)
+ * - Icon and spinner calculations cached for 60fps performance
+ * - Restyle theme variant resolution optimized with memoization
+ *
+ * @see Button.types.ts - Type definitions
+ * @see Button.helpers.ts - Pure calculation functions
+ * @see Button.a11y.ts - Accessibility prop generation
+ * @see tokens/scales.ts - Mathematical ratios
+ *
+ * @example
+ * // Basic usage
+ * <Button title="Save" onPress={handleSave} />
+ *
+ * @example
+ * // With icon and loading state
+ * <Button
+ *   title="Save"
+ *   iconName="save"
+ *   onPress={handleSave}
+ *   isLoading={isSaving}
+ *   variant="solid"
+ *   accessibilityLabel="Save changes"
+ * />
+ *
+ * @example
+ * // Responsive with custom color
+ * <Button
+ *   title="Delete"
+ *   onPress={handleDelete}
+ *   variant="outline"
+ *   size={{ phone: "md", tablet: "lg" }}
+ *   color="feedbackError"
+ * />
+ */
+
+import {
+  backgroundColor,
+  border,
+  createRestyleComponent,
+  createVariant,
+  layout,
+  spacing,
+  spacingShorthand,
+} from "@shopify/restyle";
+import React, { forwardRef, memo, useCallback } from "react";
+import { Pressable, View } from "react-native";
+import { RestyleTheme } from "../../../core/restyle";
+import { BaseThemeColor } from "../../../types";
+import { Icon } from "../../content/Icon";
+import { Spinner } from "../../feedback/Spinner";
+import { Text } from "../../typography";
+import { BaseButtonProps, ButtonProps } from "./Button.types";
+import { useButtonLogic } from "./useButtonLogic";
+
+/**
+ * Base container with Restyle variant support.
+ * @internal
+ */
+const BaseButtonContainer = createRestyleComponent<
+  BaseButtonProps,
+  RestyleTheme
+>(
+  [
+    createVariant({ themeKey: "buttonVariants" }),
+    createVariant({ themeKey: "buttonSizes", property: "size" }),
+    backgroundColor,
+    border,
+    layout,
+    spacing,
+    spacingShorthand,
+  ],
+  Pressable,
+);
+
+const ButtonComponent = forwardRef<View, ButtonProps>(
+  function ButtonComponent({
+  title,
+  onPress,
+  variant = "solid",
+  size = "md",
+  color = "accentPrimary",
+  disabled = false,
+  isLoading = false,
+  iconName,
+  testID,
+  accessibilityHint,
+  accessibilityLabel,
+  style,
+  ...rest
+}: ButtonProps, ref) {
+  const {
+    themeVariantKey,
+    textVariant,
+    textColor,
+    iconSize,
+    iconColor,
+    containerStyle,
+    hitSlop,
+    a11yProps,
+    showSpinner,
+    spinnerSize,
+    spinnerColor,
+    spinnerAccessibilityLabel,
+  } = useButtonLogic({
+    title,
+    variant,
+    size,
+    color,
+    disabled,
+    isLoading,
+    iconName,
+    accessibilityLabel,
+    accessibilityHint,
+  });
+
+  const handlePress = useCallback(() => {
+    if (!disabled && !isLoading) {
+      onPress();
+    }
+  }, [disabled, isLoading, onPress]);
+
+  return (
+    <BaseButtonContainer
+      ref={ref}
+      variant={themeVariantKey}
+      size={size}
+      onPress={handlePress}
+      disabled={disabled || isLoading}
+      hitSlop={hitSlop}
+      testID={testID}
+      flexDirection="row"
+      alignItems="center"
+      justifyContent="center"
+      gap="xs"
+      borderRadius="md"
+      style={[containerStyle, style]}
+      {...a11yProps}
+      {...rest}
+    >
+      {showSpinner ? (
+        <Spinner
+          size={spinnerSize}
+          color={spinnerColor}
+          accessibilityLabel={spinnerAccessibilityLabel}
+        />
+      ) : (
+        <>
+          {iconName && iconSize && (
+            <Icon
+              name={iconName}
+              size={iconSize}
+              color={iconColor}
+              accessibilityLabel={iconName}
+            />
+          )}
+          <Text variant={textVariant} color={textColor as BaseThemeColor}>
+            {title}
+          </Text>
+        </>
+      )}
+    </BaseButtonContainer>
+  );
+});
+
+export const Button = memo(ButtonComponent);
+Button.displayName = "Button";

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

@@ -0,0 +1,207 @@
+/**
+ * Button Component Types
+ *
+ * Type definitions for the Button component and its related hooks/helpers.
+ * All types are explicitly exported for external consumption.
+ */
+
+import { BoxProps, ResponsiveValue, VariantProps } from "@shopify/restyle";
+import { Insets, PressableProps, StyleProp, View, 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 variant for the Button component.
+ * Derived from the restyle theme's `buttonVariants` keys.
+ *
+ * - `solid`: Filled background with the specified color
+ * - `outline`: Transparent background with a colored border
+ * - `ghost`: Completely transparent, text only
+ */
+export type ButtonVariant = Exclude<
+  keyof RestyleTheme["buttonVariants"],
+  "defaults" | "disabled"
+>;
+
+/** Ref type for the Button component — the underlying React Native View instance. */
+export type ButtonRef = View;
+
+// =============================================================================
+// RESTYLE PROP TYPES
+// =============================================================================
+
+type ButtonVariantProps = VariantProps<RestyleTheme, "buttonVariants">;
+type ButtonSizeProps = VariantProps<RestyleTheme, "buttonSizes", "size">;
+type ButtonRestyleProps = ButtonVariantProps &
+  ButtonSizeProps &
+  BoxProps<RestyleTheme>;
+
+/**
+ * Size variant for the Button component.
+ *
+ * - `sm`: Small button - Dense UIs, secondary actions
+ * - `md`: Medium button - Default size (meets 44px touch target)
+ * - `lg`: Large button - Tablets, high-emphasis actions
+ */
+export type ButtonSize = Exclude<keyof RestyleTheme["buttonSizes"], "defaults">;
+
+export type ButtonTextVariant = Exclude<
+  keyof RestyleTheme["textVariants"],
+  "defaults"
+>;
+
+// =============================================================================
+// RESPONSIVE VARIANT TYPES (Shared across ButtonProps and UseButtonLogicParams)
+// =============================================================================
+
+export type ButtonResponsiveVariant = ResponsiveValue<
+  ButtonVariant,
+  RestyleTheme["breakpoints"]
+>;
+
+export type ButtonResponsiveSize = ResponsiveValue<
+  ButtonSize,
+  RestyleTheme["breakpoints"]
+>;
+
+export type BaseButtonProps = ButtonRestyleProps & PressableProps;
+
+/**
+ * Props for the Button component.
+ *
+ * @example
+ * // Basic usage
+ * <Button title="Save" onPress={handleSave} />
+ *
+ * @example
+ * // With icon and loading state
+ * <Button
+ *   title="Save"
+ *   iconName="save"
+ *   onPress={handleSave}
+ *   isLoading={isSaving}
+ *   variant="solid"
+ *   accessibilityLabel="Save changes"
+ * />
+ */
+export interface ButtonProps extends Omit<
+  BaseButtonProps,
+  "variant" | "style"
+> {
+  /** Button title/label text */
+  title: string;
+  /** Press handler callback */
+  onPress: () => void;
+  /** Visual variant of the button (supports responsive values) */
+  variant?: ButtonResponsiveVariant;
+  /** Size of the button (supports responsive values) */
+  size?: ButtonResponsiveSize;
+  /** Primary color - controls background (solid) or border/text (outline/ghost) */
+  color?: RestyleColor;
+  /** Whether the button is disabled */
+  disabled?: boolean;
+  /** Whether the button is in a loading state */
+  isLoading?: boolean;
+  /** Optional icon name from MaterialIcons to display before the title */
+  iconName?: IconName;
+  /** Test ID for testing */
+  testID?: string;
+  /** Accessibility label (required for screen readers) */
+  accessibilityLabel?: string;
+  /** Accessibility hint for additional context */
+  accessibilityHint?: string;
+  /** Custom style overrides */
+  style?: StyleProp<ViewStyle>;
+}
+
+/**
+ * Parameters for the useButtonLogic hook.
+ */
+export interface UseButtonLogicParams {
+  title: string;
+  variant: ButtonResponsiveVariant;
+  size: ButtonResponsiveSize;
+  color: RestyleColor;
+  disabled: boolean;
+  isLoading: boolean;
+  iconName?: IconName;
+  accessibilityLabel?: string;
+  accessibilityHint?: string;
+}
+
+/**
+ * Return value from the useButtonLogic hook.
+ */
+export interface UseButtonLogicReturn {
+  /** Theme variant key for the base component */
+  themeVariantKey: ButtonVariant;
+  /** Text variant based on button size */
+  textVariant: ButtonTextVariant;
+  /** Text color based on variant and disabled state */
+  textColor: RestyleColor;
+  /** Icon size (only if iconName provided) */
+  iconSize: IconSize | undefined;
+  /** Icon color based on variant and disabled state */
+  iconColor: RestyleColor;
+  /** Container style with dynamic colors and opacity */
+  containerStyle: ViewStyle;
+  /** hitSlop insets to ensure 44px minimum touch target */
+  hitSlop: Insets;
+  /** Accessibility props */
+  a11yProps: ButtonA11yProps;
+  /** Whether to show spinner instead of content */
+  showSpinner: boolean;
+  /** Spinner size based on button size */
+  spinnerSize: "sm" | "lg";
+  /** Spinner color based on variant */
+  spinnerColor: RestyleColor;
+  /** Translated loading label for spinner accessibility */
+  spinnerAccessibilityLabel: string;
+}
+
+/**
+ * Parameters for the getButtonA11y function.
+ */
+export interface ButtonA11yParams {
+  title: string;
+  accessibilityLabel?: string;
+  accessibilityHint?: string;
+  disabled: boolean;
+  isLoading: boolean;
+}
+
+/**
+ * Accessibility props returned by getButtonA11y.
+ */
+export interface ButtonA11yProps {
+  accessibilityRole: "button";
+  accessibilityLabel: string;
+  accessibilityHint?: string;
+  accessibilityState: { disabled: boolean; busy: boolean };
+}
+
+/**
+ * Parameters for resolveButtonStyle function.
+ */
+export interface ResolveButtonStyleParams {
+  variant: ButtonVariant;
+  disabled: boolean;
+  isLoading: boolean;
+  color: RestyleColor;
+  theme: RestyleTheme;
+}
+
+/**
+ * Result from resolveButtonStyle function.
+ */
+export interface ButtonStyleResult {
+  backgroundColor: string;
+  borderColor: string;
+  borderWidth: number;
+  opacity: number;
+}

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

@@ -0,0 +1,41 @@
+/**
+ * Button Component Module
+ *
+ * A flexible button component for triggering actions.
+ *
+ * Features:
+ * - Three variants: solid, outline, ghost
+ * - Three sizes: sm, md, lg (supports responsive values)
+ * - Optional icon before text
+ * - Loading state with spinner
+ * - Full accessibility support
+ *
+ * @example
+ * import { Button } from '@/src/design-system/primitives/actions/Button';
+ *
+ * // Basic usage
+ * <Button title="Save" onPress={handleSave} />
+ *
+ * // With icon and loading state
+ * <Button
+ *   title="Save"
+ *   iconName="save"
+ *   onPress={handleSave}
+ *   isLoading={isSaving}
+ *   variant="solid"
+ *   accessibilityLabel="Save changes"
+ * />
+ */
+
+export { Button } from "./Button";
+
+export type {
+  ButtonProps,
+  ButtonRef,
+  ButtonVariant,
+  ButtonSize,
+  ButtonA11yParams,
+  ButtonA11yProps,
+} from "./Button.types";
+
+export { getButtonA11y } from "./Button.a11y";

package/src/primitives/actions/Button/useButtonLogic.ts

@@ -0,0 +1,160 @@
+import { useResponsiveProp } from "@shopify/restyle";
+import { useMemo } from "react";
+import { ViewStyle } from "react-native";
+import { useRestyleTheme } from "../../../core/restyle";
+import { useDesignSystem } from "../../../provider";
+import { getButtonA11y } from "./Button.a11y";
+import {
+  getButtonHitSlop,
+  getButtonIconColor,
+  getButtonIconSize,
+  getButtonSpinnerColor,
+  getButtonSpinnerSize,
+  getTextColor,
+  getTextVariant,
+  resolveButtonStyle,
+} from "./Button.helpers";
+import {
+  ButtonSize,
+  ButtonVariant,
+  UseButtonLogicParams,
+  UseButtonLogicReturn,
+} from "./Button.types";
+
+/**
+ * Orchestrates Button rendering logic and state management.
+ *
+ * Handles:
+ * - Responsive size and variant resolution
+ * - Theme variant key mapping for Restyle
+ * - Text, icon, and spinner styling calculations
+ * - Container styles (background, border, opacity)
+ * - Hit slop calculation for 44px minimum touch target
+ * - Accessibility props generation
+ *
+ * @param params - Configuration object for button behavior
+ * @param params.title - Button label text
+ * @param params.variant - Visual variant ('solid' | 'outline' | 'ghost')
+ * @param params.size - Size variant ('sm' | 'md' | 'lg')
+ * @param params.color - Theme color token for background/text
+ * @param params.disabled - Whether button is disabled
+ * @param params.isLoading - Whether to show loading spinner
+ * @param params.iconName - Optional icon to display
+ * @param params.accessibilityLabel - Custom a11y label
+ * @param params.accessibilityHint - Describes action result
+ *
+ * @returns Computed values for rendering Button
+ * @returns {string} themeVariantKey - Restyle theme variant identifier
+ * @returns {string} textVariant - Text component variant
+ * @returns {string} textColor - Text color token
+ * @returns {number} iconSize - Icon size in pixels
+ * @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
+ *
+ * @performance This hook uses useMemo() for expensive calculations
+ *
+ * @example
+ * const { themeVariantKey, textColor, iconSize, a11yProps } = useButtonLogic({
+ *   title: "Save Changes",
+ *   variant: "solid",
+ *   size: "md",
+ *   color: "accentPrimary",
+ *   iconName: "save",
+ *   accessibilityLabel: "Save your changes"
+ * });
+ */
+export function useButtonLogic(
+  params: UseButtonLogicParams,
+): UseButtonLogicReturn {
+  const {
+    title,
+    variant,
+    size,
+    color,
+    disabled,
+    isLoading,
+    iconName,
+    accessibilityLabel,
+    accessibilityHint,
+  } = params;
+
+  const { labels: t } = useDesignSystem();
+  const theme = useRestyleTheme();
+  const resolvedSize = (useResponsiveProp(size) ?? "md") as ButtonSize;
+  const resolvedVariant = (useResponsiveProp(variant) ?? "solid") as ButtonVariant;
+
+  // Theme variant key — ButtonVariant is derived from restyle, so it maps directly
+  const themeVariantKey = resolvedVariant;
+
+  // Text styling
+  const textVariant = getTextVariant(resolvedSize);
+  const textColor = getTextColor(resolvedVariant, color, disabled);
+
+  // Icon styling (only computed if iconName provided)
+  const iconSize = iconName ? getButtonIconSize(resolvedSize) : undefined;
+  const iconColor = getButtonIconColor(resolvedVariant, color, disabled);
+
+  // Touch target - ensure 44px minimum
+  const hitSlop = getButtonHitSlop(resolvedSize);
+
+  // Spinner styling
+  const spinnerSize = getButtonSpinnerSize(resolvedSize);
+  const spinnerColor = getButtonSpinnerColor(resolvedVariant, color, disabled);
+
+  // Whether to show spinner instead of content
+  const showSpinner = isLoading;
+
+  // Translated spinner label
+  const spinnerAccessibilityLabel = t.designSystem.button.loadingLabel;
+
+  // Container style - only dynamic colors and opacity
+  const containerStyle = useMemo((): ViewStyle => {
+    const styleResult = resolveButtonStyle({
+      variant: resolvedVariant,
+      disabled,
+      isLoading,
+      color,
+      theme,
+    });
+
+    return {
+      backgroundColor: styleResult.backgroundColor,
+      borderColor: styleResult.borderColor,
+      borderWidth: styleResult.borderWidth,
+      opacity: styleResult.opacity,
+    };
+  }, [resolvedVariant, disabled, isLoading, color, theme]);
+
+  // Accessibility props
+  const a11yProps = useMemo(
+    () =>
+      getButtonA11y({
+        title,
+        accessibilityLabel,
+        accessibilityHint,
+        disabled,
+        isLoading,
+      }),
+    [title, accessibilityLabel, accessibilityHint, disabled, isLoading],
+  );
+
+  return {
+    themeVariantKey,
+    textVariant,
+    textColor,
+    iconSize,
+    iconColor,
+    containerStyle,
+    hitSlop,
+    a11yProps,
+    showSpinner,
+    spinnerSize,
+    spinnerColor,
+    spinnerAccessibilityLabel,
+  };
+}