@praxiis/ui 0.0.1

package/src/primitives/inputs/Checkbox/Checkbox.helpers.ts

@@ -0,0 +1,132 @@
+/**
+ * Checkbox Component Helpers
+ *
+ * Pure functions for computing Checkbox styles, sizes, and colors.
+ * All calculations are derived from the centralized scales.ts token file.
+ */
+
+import { Insets } from "react-native";
+import { CHECKBOX_HIT_SLOP, CHECKBOX_ICON_SIZE } from "../../../tokens/scales";
+import { BaseThemeColor, RestyleColor } from "../../../types";
+import { IconSize } from "../../content/Icon";
+import {
+  CheckboxSize,
+  CheckboxStyleResult,
+  ResolveCheckboxStyleParams,
+} from "./Checkbox.types";
+
+// =============================================================================
+// ICON SIZE RESOLUTION
+// =============================================================================
+
+/**
+ * Get icon size based on checkbox size.
+ *
+ * Uses CHECKBOX_ICON_SIZE from scales.ts for mathematical consistency.
+ * Target ratio: ~75% (ICON_RATIOS.toggleControl)
+ *
+ * | Size | Container | Icon | Ratio |
+ * |------|-----------|------|-------|
+ * | sm   | 20px      | 16px | 80%   |
+ * | md   | 24px      | 20px | 83%   |
+ * | lg   | 32px      | 24px | 75%   |
+ *
+ * @param size - The checkbox size variant
+ * @returns The corresponding icon size
+ */
+export function getCheckboxIconSize(size: CheckboxSize): IconSize {
+  return CHECKBOX_ICON_SIZE[size];
+}
+
+// =============================================================================
+// TOUCH TARGET (hitSlop)
+// =============================================================================
+
+/**
+ * Get hitSlop based on checkbox size.
+ *
+ * Uses pre-calculated values from scales.ts to ensure
+ * all checkboxes meet the 44px minimum touch target.
+ *
+ * | Size | Container | hitSlop | Total |
+ * |------|-----------|---------|-------|
+ * | sm   | 20px      | 12px    | 44px  |
+ * | md   | 24px      | 10px    | 44px  |
+ * | lg   | 32px      | 6px     | 44px  |
+ *
+ * @param size - The checkbox size variant
+ * @returns Insets for touch target expansion
+ */
+export function getCheckboxHitSlop(size: CheckboxSize): Insets {
+  return CHECKBOX_HIT_SLOP[size];
+}
+
+// =============================================================================
+// COLOR RESOLUTION
+// =============================================================================
+
+/**
+ * Get check icon color based on disabled state.
+ *
+ * The check icon is always displayed on a filled background,
+ * so it uses inverse text color for contrast.
+ *
+ * | State    | Color        |
+ * |----------|--------------|
+ * | Normal   | textInverse  |
+ * | Disabled | textDisabled |
+ *
+ * @param disabled - Whether the checkbox is disabled
+ * @returns The computed icon color
+ */
+export function getCheckIconColor(disabled: boolean): RestyleColor {
+  return disabled ? "textDisabled" : "textInverse";
+}
+
+// =============================================================================
+// STYLE RESOLUTION
+// =============================================================================
+
+/**
+ * Resolve dynamic style properties for the Checkbox container.
+ *
+ * Static styles (borderRadius, borderWidth) come from theme variants.
+ * This function handles dynamic state-based values:
+ * - backgroundColor based on checked and disabled state
+ * - borderColor based on checked and disabled state
+ * - opacity based on disabled state
+ *
+ * @param params - Resolution parameters
+ * @returns Computed style object
+ */
+export function resolveCheckboxStyle(
+  params: ResolveCheckboxStyleParams
+): CheckboxStyleResult {
+  const { checked, disabled, color, theme } = params;
+
+  // Background color logic
+  let backgroundColor: string;
+  if (!checked) {
+    backgroundColor = "transparent";
+  } else if (disabled) {
+    backgroundColor = theme.colors.interactiveDisabled;
+  } else {
+    backgroundColor = theme.colors[color as BaseThemeColor];
+  }
+
+  // Border color logic
+  let borderColor: string;
+  if (disabled) {
+    borderColor = theme.colors.borderDefault;
+  } else if (!checked) {
+    borderColor = theme.colors.borderDefault;
+  } else {
+    borderColor = theme.colors[color as BaseThemeColor];
+  }
+
+  return {
+    backgroundColor,
+    borderColor,
+    opacity: 1,
+  };
+}

package/src/primitives/inputs/Checkbox/Checkbox.tsx

@@ -0,0 +1,150 @@
+/**
+ * Checkbox Component
+ *
+ * @description Toggle control for binary choices - Atom
+ *
+ * Checkbox provides a compact toggle for boolean form values.
+ * Uses a checkmark icon to indicate the checked state.
+ *
+ * ## Ratios & Constraints
+ * - Icon = Container × ~75% (ICON_RATIOS.toggleControl)
+ * - All sizes meet 44px minimum touch target via hitSlop
+ *
+ * ## Size Scale
+ * | Size | Container | Icon | hitSlop | Touch Target |
+ * |------|-----------|------|---------|--------------|
+ * | sm   | 20px      | 16px | 12px    | 44px         |
+ * | md   | 24px      | 20px | 10px    | 44px         |
+ * | lg   | 32px      | 24px | 6px     | 44px         |
+ *
+ * ## Visual States
+ * - Unchecked: Border only, transparent background
+ * - Checked: Filled background with checkmark icon
+ * - Disabled: Reduced opacity (0.5)
+ *
+ * ## Features
+ * - Responsive size prop (phone/tablet breakpoints)
+ * - Customizable color when checked
+ * - Full accessibility support (checkbox role)
+ * 
+ * @performance
+ * - Wrapped with React.memo() to prevent unnecessary re-renders
+ * - Uses useMemo() for expensive calculations (style resolution, icon sizing)
+ * - Check icon calculated using ~75% container ratio for instant rendering
+ * - Hit slop pre-calculated in lookup tables for 44px touch targets
+ *
+ * @see Checkbox.types.ts - Type definitions
+ * @see Checkbox.helpers.ts - Pure calculation functions
+ * @see Checkbox.a11y.ts - Accessibility prop generation
+ * @see tokens/scales.ts - Mathematical ratios
+ *
+ * @example
+ * // Basic usage
+ * <Checkbox
+ *   checked={isChecked}
+ *   onPress={toggleChecked}
+ *   accessibilityLabel="Accept terms"
+ * />
+ *
+ * @example
+ * // Responsive with label
+ * <Checkbox
+ *   checked={isChecked}
+ *   onPress={toggleChecked}
+ *   size={{ phone: "md", tablet: "lg" }}
+ *   color="feedbackSuccess"
+ *   label="Enable notifications"
+ * />
+ */
+
+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 { Icon } from "../../content/Icon";
+import {
+  BaseCheckboxInteractiveContainerProps,
+  CheckboxProps,
+} from "./Checkbox.types";
+import { useCheckboxLogic } from "./useCheckboxLogic";
+
+/**
+ * Base container with Restyle variant support.
+ * @internal
+ */
+const BaseCheckboxInteractiveContainer = createRestyleComponent<
+  BaseCheckboxInteractiveContainerProps,
+  RestyleTheme
+>(
+  [
+    createVariant({ themeKey: "checkboxSizes", property: "size" }),
+    backgroundColor,
+    border,
+    layout,
+    spacing,
+    spacingShorthand,
+  ],
+  Pressable,
+);
+
+const CheckboxComponent = forwardRef<View, CheckboxProps>(function Checkbox(
+  {
+    checked,
+    onPress,
+    size = "md",
+    disabled = false,
+    color = "accentPrimary",
+    label,
+    accessibilityLabel,
+    accessibilityHint,
+    testID,
+    ...rest
+  },
+  ref,
+) {
+  const { iconSize, checkIconColor, containerStyle, hitSlop, a11yProps } =
+    useCheckboxLogic({
+      checked,
+      disabled,
+      size,
+      color,
+      label,
+      accessibilityLabel,
+      accessibilityHint,
+    });
+
+  const handlePress = useCallback(() => {
+    if (!disabled) {
+      onPress();
+    }
+  }, [disabled, onPress]);
+
+  return (
+    <BaseCheckboxInteractiveContainer
+      ref={ref}
+      size={size}
+      onPress={handlePress}
+      disabled={disabled}
+      hitSlop={hitSlop}
+      testID={testID}
+      alignItems="center"
+      justifyContent="center"
+      style={containerStyle}
+      {...a11yProps}
+      {...rest}
+    >
+      {checked && <Icon name="check" size={iconSize} color={checkIconColor} accessibilityLabel="check" />}
+    </BaseCheckboxInteractiveContainer>
+  );
+});
+
+export const Checkbox = memo(CheckboxComponent);
+Checkbox.displayName = "Checkbox";

package/src/primitives/inputs/Checkbox/Checkbox.types.ts

@@ -0,0 +1,106 @@
+/**
+ * Checkbox Component Types
+ *
+ * Type definitions for the Checkbox component and its related hooks/helpers.
+ * All types are explicitly exported for external consumption.
+ */
+
+import { BoxProps, ResponsiveValue, VariantProps } from "@shopify/restyle";
+import { Insets, PressableProps, View, ViewStyle } from "react-native";
+import { RestyleTheme } from "../../../core/restyle";
+import { RestyleColor } from "../../../types";
+import { IconSize } from "../../content/Icon";
+
+// =============================================================================
+// VARIANT TYPES (Explicitly exported for external use)
+// =============================================================================
+
+/**
+ * Size variants derived from theme.
+ * Maps to checkboxSizes in restyleTheme.ts
+ *
+ * | Size | Container | Touch Target |
+ * |------|-----------|--------------|
+ * | sm   | 20px      | 44px (hitSlop) |
+ * | md   | 24px      | 44px (hitSlop) |
+ * | lg   | 32px      | 44px (hitSlop) |
+ */
+export type CheckboxSize = Exclude<
+  keyof RestyleTheme["checkboxSizes"],
+  "defaults"
+>;
+
+/** Ref type for the Checkbox component — the underlying React Native View instance. */
+export type CheckboxRef = View;
+
+// =============================================================================
+// RESTYLE PROP TYPES
+// =============================================================================
+
+type CheckboxSizeVariantProps = VariantProps<
+  RestyleTheme,
+  "checkboxSizes",
+  "size"
+>;
+type CheckboxRestyleProps = CheckboxSizeVariantProps & BoxProps<RestyleTheme>;
+
+export type BaseCheckboxInteractiveContainerProps = CheckboxRestyleProps & PressableProps;
+
+export interface CheckboxProps extends Omit<CheckboxRestyleProps, "size"> {
+  checked: boolean;
+  onPress: () => void;
+  /** Size of the checkbox (supports responsive values) */
+  size?: ResponsiveValue<CheckboxSize, RestyleTheme["breakpoints"]>;
+  disabled?: boolean;
+  color?: RestyleColor;
+  label?: string;
+  accessibilityLabel?: string;
+  accessibilityHint?: string;
+  testID?: string;
+}
+
+export interface UseCheckboxLogicParams {
+  checked: boolean;
+  disabled: boolean;
+  size: ResponsiveValue<CheckboxSize, RestyleTheme["breakpoints"]>;
+  color: RestyleColor;
+  label?: string;
+  accessibilityLabel?: string;
+  accessibilityHint?: string;
+}
+
+export interface UseCheckboxLogicReturn {
+  iconSize: IconSize;
+  checkIconColor: RestyleColor;
+  containerStyle: ViewStyle;
+  hitSlop: Insets;
+  a11yProps: CheckboxA11yProps;
+}
+
+export interface CheckboxA11yParams {
+  label?: string;
+  accessibilityLabel?: string;
+  accessibilityHint?: string;
+  checked: boolean;
+  disabled: boolean;
+}
+
+export interface CheckboxA11yProps {
+  accessibilityLabel: string;
+  accessibilityHint?: string;
+  accessibilityRole: "checkbox";
+  accessibilityState: { checked: boolean; disabled: boolean };
+}
+
+export interface ResolveCheckboxStyleParams {
+  checked: boolean;
+  disabled: boolean;
+  color: RestyleColor;
+  theme: RestyleTheme;
+}
+
+export interface CheckboxStyleResult {
+  backgroundColor: string;
+  borderColor: string;
+  opacity: number;
+}

package/src/primitives/inputs/Checkbox/index.ts

@@ -0,0 +1,30 @@
+/**
+ * Checkbox Module
+ *
+ * Atom component for binary toggle controls in forms.
+ *
+ * ## Mathematical Ratios
+ * - Icon = Container × ~75% (ICON_RATIOS.toggleControl)
+ * - All sizes meet 44px minimum touch target via hitSlop
+ *
+ * @example
+ * import { Checkbox } from "@/design-system/primitives/inputs/Checkbox";
+ *
+ * <Checkbox
+ *   checked={isChecked}
+ *   onPress={toggleChecked}
+ *   accessibilityLabel="Accept terms"
+ * />
+ */
+
+export { Checkbox } from "./Checkbox";
+
+export type {
+  CheckboxProps,
+  CheckboxRef,
+  CheckboxSize,
+  CheckboxA11yParams,
+  CheckboxA11yProps,
+} from "./Checkbox.types";
+
+export { getCheckboxA11y } from "./Checkbox.a11y";

package/src/primitives/inputs/Checkbox/useCheckboxLogic.ts

@@ -0,0 +1,121 @@
+/**
+ * Checkbox Logic Hook
+ *
+ * Extracts all computational logic from the Checkbox component.
+ * Returns memoized values for optimal render performance.
+ *
+ * Responsibilities:
+ * - Resolve responsive size prop to current breakpoint value
+ * - Compute icon size from container size (~75% ratio)
+ * - Determine icon color based on disabled state
+ * - Calculate container styles (background, border, opacity)
+ * - Compute hitSlop for proper touch targets
+ * - Generate accessibility props
+ *
+ * The component (Checkbox.tsx) is a "dumb view" that only renders
+ * the pre-computed values from this hook.
+ *
+ * @see Checkbox.tsx - Component consuming this hook
+ * @see Checkbox.helpers.ts - Pure calculation functions
+ * @see tokens/scales.ts - Mathematical ratios and constants
+ */
+
+import { useResponsiveProp } from "@shopify/restyle";
+import { useMemo } from "react";
+import { ViewStyle } from "react-native";
+import { useRestyleTheme } from "../../../core/restyle";
+import { getCheckboxA11y } from "./Checkbox.a11y";
+import {
+  getCheckboxHitSlop,
+  getCheckboxIconSize,
+  getCheckIconColor,
+  resolveCheckboxStyle,
+} from "./Checkbox.helpers";
+import { CheckboxSize, UseCheckboxLogicParams, UseCheckboxLogicReturn } from "./Checkbox.types";
+
+/**
+ * Orchestrates Checkbox rendering logic and state management.
+ * 
+ * Handles:
+ * - Responsive size resolution
+ * - Check icon size calculation (~75% of container ratio)
+ * - Check icon color determination
+ * - Container styles (background, border, opacity)
+ * - Hit slop calculation for 44px minimum touch target
+ * - Accessibility props generation with checked state
+ * 
+ * @param params - Configuration object for checkbox behavior
+ * @param params.checked - Whether checkbox is checked
+ * @param params.disabled - Whether checkbox is disabled
+ * @param params.size - Size variant ('sm' | 'md' | 'lg')
+ * @param params.color - Theme color token for checked state
+ * @param params.label - Associated label text
+ * @param params.accessibilityLabel - Custom a11y label
+ * @param params.accessibilityHint - Describes action result
+ * 
+ * @returns Computed values for rendering Checkbox
+ * @returns {number} iconSize - Check icon size in pixels
+ * @returns {string} checkIconColor - Check icon color token
+ * @returns {ViewStyle} containerStyle - Dynamic container styles
+ * @returns {Insets} hitSlop - Touch target expansion
+ * @returns {object} a11yProps - Accessibility props with checked state
+ * 
+ * @performance This hook uses useMemo() for expensive calculations
+ * 
+ * @example
+ * const { iconSize, checkIconColor, containerStyle, hitSlop, a11yProps } = useCheckboxLogic({
+ *   checked: true,
+ *   disabled: false,
+ *   size: "md",
+ *   color: "accentPrimary",
+ *   label: "Accept terms and conditions",
+ * });
+ */
+export function useCheckboxLogic(
+  params: UseCheckboxLogicParams,
+): UseCheckboxLogicReturn {
+  const {
+    checked,
+    disabled,
+    size,
+    color,
+    label,
+    accessibilityLabel,
+    accessibilityHint,
+  } = params;
+
+  const theme = useRestyleTheme();
+  const resolvedSize = (useResponsiveProp(size) ?? "md") as CheckboxSize;
+
+  const iconSize = getCheckboxIconSize(resolvedSize);
+  const checkIconColor = getCheckIconColor(disabled);
+  const hitSlop = getCheckboxHitSlop(resolvedSize);
+
+  const containerStyle = useMemo((): ViewStyle => {
+    const styleResult = resolveCheckboxStyle({
+      checked,
+      disabled,
+      color,
+      theme,
+    });
+
+    return {
+      backgroundColor: styleResult.backgroundColor,
+      borderColor: styleResult.borderColor,
+      opacity: styleResult.opacity,
+    };
+  }, [checked, disabled, color, theme]);
+
+  const a11yProps = useMemo(
+    () => getCheckboxA11y({ label, accessibilityLabel, accessibilityHint, checked, disabled }),
+    [label, accessibilityLabel, accessibilityHint, checked, disabled],
+  );
+
+  return {
+    iconSize,
+    checkIconColor,
+    containerStyle,
+    hitSlop,
+    a11yProps,
+  };
+}

package/src/primitives/inputs/RadioButton/RadioButton.helpers.ts

@@ -0,0 +1,123 @@
+/**
+ * RadioButton Component Helpers
+ *
+ * Pure functions for computing RadioButton styles, sizes, and colors.
+ * All calculations are derived from the centralized scales.ts token file.
+ */
+
+import { Insets } from "react-native";
+import { RADIO_BUTTON_HIT_SLOP, RADIO_BUTTON_INNER_SIZE } from "../../../tokens/scales";
+import { BaseThemeColor } from "../../../types";
+import {
+  RadioButtonSize,
+  RadioButtonStyleResult,
+  ResolveRadioButtonStyleParams,
+} from "./RadioButton.types";
+
+// =============================================================================
+// INNER DOT SIZE RESOLUTION
+// =============================================================================
+
+/**
+ * Get inner dot size based on radio button size.
+ *
+ * Uses RADIO_BUTTON_INNER_SIZE from scales.ts for mathematical consistency.
+ * Target ratio: ~40% of container
+ *
+ * | Size | Container | Inner Dot | Ratio |
+ * |------|-----------|-----------|-------|
+ * | sm   | 20px      | 8px       | 40%   |
+ * | md   | 24px      | 10px      | 42%   |
+ * | lg   | 32px      | 14px      | 44%   |
+ *
+ * @param size - The radio button size variant
+ * @returns The inner dot diameter in pixels
+ */
+export function getRadioButtonInnerSize(size: RadioButtonSize): number {
+  return RADIO_BUTTON_INNER_SIZE[size];
+}
+
+// =============================================================================
+// TOUCH TARGET (hitSlop)
+// =============================================================================
+
+/**
+ * Get hitSlop based on radio button size.
+ *
+ * Uses pre-calculated values from scales.ts to ensure
+ * all radio buttons meet the 44px minimum touch target.
+ *
+ * | Size | Container | hitSlop | Total |
+ * |------|-----------|---------|-------|
+ * | sm   | 20px      | 12px    | 44px  |
+ * | md   | 24px      | 10px    | 44px  |
+ * | lg   | 32px      | 6px     | 44px  |
+ *
+ * @param size - The radio button size variant
+ * @returns Insets for touch target expansion
+ */
+export function getRadioButtonHitSlop(size: RadioButtonSize): Insets {
+  return RADIO_BUTTON_HIT_SLOP[size];
+}
+
+// =============================================================================
+// STYLE RESOLUTION
+// =============================================================================
+
+/**
+ * Resolve dynamic style properties for the RadioButton container.
+ *
+ * Static styles (borderRadius, borderWidth) come from theme variants.
+ * This function handles dynamic state-based values:
+ * - backgroundColor based on checked and disabled state
+ * - borderColor based on checked and disabled state
+ * - opacity based on disabled state
+ *
+ * @param params - Resolution parameters
+ * @returns Computed style object
+ */
+export function resolveRadioButtonStyle(
+  params: ResolveRadioButtonStyleParams
+): RadioButtonStyleResult {
+  const { checked, disabled, color, theme } = params;
+
+  // Background color logic
+  let backgroundColor: string;
+  if (!checked) {
+    backgroundColor = "transparent";
+  } else if (disabled) {
+    backgroundColor = theme.colors.interactiveDisabled;
+  } else {
+    backgroundColor = theme.colors[color as BaseThemeColor];
+  }
+
+  // Border color logic
+  let borderColor: string;
+  if (disabled) {
+    borderColor = theme.colors.borderDefault;
+  } else if (!checked) {
+    borderColor = theme.colors.borderDefault;
+  } else {
+    borderColor = theme.colors[color as BaseThemeColor];
+  }
+
+  return {
+    backgroundColor,
+    borderColor,
+    opacity: 1,
+  };
+}
+
+// =============================================================================
+// VALIDATION
+// =============================================================================
+
+/**
+ * Validate if a value is a valid RadioButton size.
+ *
+ * @param value - Value to validate
+ * @returns True if valid size
+ */
+export function isValidRadioButtonSize(value: unknown): value is RadioButtonSize {
+  return value === "sm" || value === "md" || value === "lg";
+}