@praxiis/ui 0.0.1

package/src/primitives/inputs/RadioButton/RadioButton.tsx

@@ -0,0 +1,159 @@
+/**
+ * RadioButton Component
+ *
+ * @description Single-selection control for option groups - Atom
+ *
+ * RadioButton provides a circular indicator for single-selection within groups.
+ * Uses a filled inner dot to indicate the checked state.
+ *
+ * ## Ratios & Constraints
+ * - Inner dot = Container × ~40% (RADIO_BUTTON_INNER_SIZE)
+ * - All sizes meet 44px minimum touch target via hitSlop
+ *
+ * ## Size Scale
+ * | Size | Container | Inner Dot | hitSlop | Touch Target |
+ * |------|-----------|-----------|---------|--------------|
+ * | sm   | 20px      | 8px       | 12px    | 44px         |
+ * | md   | 24px      | 10px      | 10px    | 44px         |
+ * | lg   | 32px      | 14px      | 6px     | 44px         |
+ *
+ * ## Visual States
+ * - Unchecked: Border only, transparent background
+ * - Checked: Filled background with white inner dot
+ * - Disabled: Reduced opacity (0.5)
+ *
+ * ## Features
+ * - Responsive size prop (phone/tablet breakpoints)
+ * - Customizable color when checked
+ * - Full accessibility support (radio role)
+ *
+ * @performance
+ * - Wrapped with React.memo() to prevent unnecessary re-renders
+ * - Uses useMemo() for expensive calculations (style resolution, inner dot sizing)
+ * - Inner dot calculated using ~40% container ratio for instant rendering
+ * - Hit slop pre-calculated in lookup tables for 44px touch targets
+ *
+ * @see RadioButton.types.ts - Type definitions
+ * @see RadioButton.helpers.ts - Pure calculation functions
+ * @see RadioButton.a11y.ts - Accessibility prop generation
+ * @see useRadioButtonLogic.ts - Logic hook
+ * @see tokens/scales.ts - Mathematical ratios
+ *
+ * @example
+ * // Basic usage
+ * <RadioButton
+ *   checked={isSelected}
+ *   onPress={handleSelect}
+ *   accessibilityLabel="Option A"
+ * />
+ *
+ * @example
+ * // Responsive with color
+ * <RadioButton
+ *   checked={isSelected}
+ *   onPress={handleSelect}
+ *   size={{ phone: "md", tablet: "lg" }}
+ *   color="feedbackSuccess"
+ * />
+ */
+
+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 { Box } from "../../layout";
+import {
+  BaseRadioButtonInteractiveContainerProps,
+  RadioButtonProps,
+} from "./RadioButton.types";
+import { useRadioButtonLogic } from "./useRadioButtonLogic";
+
+/**
+ * Base container with Restyle variant support.
+ * @internal
+ */
+const BaseRadioButtonInteractiveContainer = createRestyleComponent<
+  BaseRadioButtonInteractiveContainerProps,
+  RestyleTheme
+>(
+  [
+    createVariant({ themeKey: "radioButtonSizes", property: "size" }),
+    backgroundColor,
+    border,
+    layout,
+    spacing,
+    spacingShorthand,
+  ],
+  Pressable,
+);
+
+const RadioButtonComponent = forwardRef<View, RadioButtonProps>(
+  function RadioButton(
+    {
+      checked,
+      onPress,
+      size = "md",
+      disabled = false,
+      color = "accentPrimary",
+      label,
+      accessibilityLabel,
+      accessibilityHint,
+      testID,
+      ...rest
+    },
+    ref,
+  ) {
+    const { innerDotSize, containerStyle, hitSlop, a11yProps } =
+      useRadioButtonLogic({
+        checked,
+        disabled,
+        size,
+        color,
+        label,
+        accessibilityLabel,
+        accessibilityHint,
+      });
+
+    const handlePress = useCallback(() => {
+      if (!disabled) {
+        onPress();
+      }
+    }, [disabled, onPress]);
+
+    return (
+      <BaseRadioButtonInteractiveContainer
+        ref={ref}
+        size={size}
+        onPress={handlePress}
+        disabled={disabled}
+        hitSlop={hitSlop}
+        testID={testID}
+        alignItems="center"
+        justifyContent="center"
+        style={containerStyle}
+        {...a11yProps}
+        {...rest}
+      >
+        {checked && (
+          <Box
+            width={innerDotSize}
+            height={innerDotSize}
+            borderRadius="full"
+            backgroundColor="textInverse"
+          />
+        )}
+      </BaseRadioButtonInteractiveContainer>
+    );
+  },
+);
+
+export const RadioButton = memo(RadioButtonComponent);
+RadioButton.displayName = "RadioButton";

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

@@ -0,0 +1,106 @@
+/**
+ * RadioButton Component Types
+ *
+ * Type definitions for the RadioButton 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";
+
+// =============================================================================
+// VARIANT TYPES (Explicitly exported for external use)
+// =============================================================================
+
+/**
+ * Size variants derived from theme.
+ * Maps to radioButtonSizes in restyleTheme.ts
+ *
+ * | Size | Container | Touch Target |
+ * |------|-----------|--------------|
+ * | sm   | 20px      | 44px (hitSlop) |
+ * | md   | 24px      | 44px (hitSlop) |
+ * | lg   | 32px      | 44px (hitSlop) |
+ */
+export type RadioButtonSize = Exclude<
+  keyof RestyleTheme["radioButtonSizes"],
+  "defaults"
+>;
+
+/** Ref type for the RadioButton component — the underlying React Native View instance. */
+export type RadioButtonRef = View;
+
+// =============================================================================
+// RESTYLE PROP TYPES
+// =============================================================================
+
+type RadioButtonSizeVariantProps = VariantProps<
+  RestyleTheme,
+  "radioButtonSizes",
+  "size"
+>;
+type RadioButtonRestyleProps = RadioButtonSizeVariantProps & BoxProps<RestyleTheme>;
+
+export type BaseRadioButtonInteractiveContainerProps = RadioButtonRestyleProps & PressableProps;
+
+export interface RadioButtonProps extends Omit<RadioButtonRestyleProps, "size"> {
+  checked: boolean;
+  onPress: () => void;
+  /** Size of the radio button (supports responsive values) */
+  size?: ResponsiveValue<RadioButtonSize, RestyleTheme["breakpoints"]>;
+  disabled?: boolean;
+  color?: RestyleColor;
+  label?: string;
+  accessibilityLabel?: string;
+  accessibilityHint?: string;
+  testID?: string;
+}
+
+export interface UseRadioButtonLogicParams {
+  checked: boolean;
+  disabled: boolean;
+  size: ResponsiveValue<RadioButtonSize, RestyleTheme["breakpoints"]>;
+  color: RestyleColor;
+  label?: string;
+  accessibilityLabel?: string;
+  accessibilityHint?: string;
+}
+
+export interface UseRadioButtonLogicReturn {
+  innerDotSize: number;
+  containerStyle: ViewStyle;
+  hitSlop: Insets;
+  a11yProps: RadioButtonA11yProps;
+}
+
+export interface RadioButtonA11yParams {
+  label?: string;
+  accessibilityLabel?: string;
+  accessibilityHint?: string;
+  checked: boolean;
+  disabled: boolean;
+  /** i18n fallback label when no label or accessibilityLabel provided */
+  fallbackLabel: string;
+}
+
+export interface RadioButtonA11yProps {
+  accessibilityLabel: string;
+  accessibilityHint?: string;
+  accessibilityRole: "radio";
+  accessibilityState: { checked: boolean; disabled: boolean };
+}
+
+export interface ResolveRadioButtonStyleParams {
+  checked: boolean;
+  disabled: boolean;
+  color: RestyleColor;
+  theme: RestyleTheme;
+}
+
+export interface RadioButtonStyleResult {
+  backgroundColor: string;
+  borderColor: string;
+  opacity: number;
+}

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

@@ -0,0 +1,25 @@
+/**
+ * RadioButton Component
+ *
+ * Barrel export for the RadioButton component and related types.
+ */
+
+export { RadioButton } from "./RadioButton";
+
+export type {
+  RadioButtonProps,
+  RadioButtonRef,
+  RadioButtonSize,
+  RadioButtonA11yProps,
+  UseRadioButtonLogicParams,
+  UseRadioButtonLogicReturn,
+} from "./RadioButton.types";
+
+export { getRadioButtonA11y } from "./RadioButton.a11y";
+export { useRadioButtonLogic } from "./useRadioButtonLogic";
+export {
+  getRadioButtonInnerSize,
+  getRadioButtonHitSlop,
+  resolveRadioButtonStyle,
+  isValidRadioButtonSize,
+} from "./RadioButton.helpers";

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

@@ -0,0 +1,117 @@
+/**
+ * RadioButton Logic Hook
+ *
+ * Extracts all computational logic from the RadioButton component.
+ * Returns memoized values for optimal render performance.
+ *
+ * Responsibilities:
+ * - Resolve responsive size prop to current breakpoint value
+ * - Compute inner dot size from container size (~40% ratio)
+ * - Calculate container styles (background, border, opacity)
+ * - Compute hitSlop for proper touch targets
+ * - Generate accessibility props
+ *
+ * The component (RadioButton.tsx) is a "dumb view" that only renders
+ * the pre-computed values from this hook.
+ *
+ * @see RadioButton.tsx - Component consuming this hook
+ * @see RadioButton.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 { getRadioButtonA11y } from "./RadioButton.a11y";
+import {
+  getRadioButtonHitSlop,
+  getRadioButtonInnerSize,
+  resolveRadioButtonStyle,
+} from "./RadioButton.helpers";
+import { RadioButtonSize, UseRadioButtonLogicParams, UseRadioButtonLogicReturn } from "./RadioButton.types";
+
+/**
+ * Orchestrates RadioButton rendering logic and state management.
+ * 
+ * Handles:
+ * - Responsive size resolution
+ * - Inner dot size calculation (~40% of container ratio)
+ * - Container styles (background, border, opacity)
+ * - Hit slop calculation for 44px minimum touch target
+ * - Accessibility props generation with checked state
+ * 
+ * @param params - Configuration object for radio button behavior
+ * @param params.checked - Whether radio button is selected
+ * @param params.disabled - Whether radio button 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 RadioButton
+ * @returns {number} innerDotSize - Inner dot size in pixels
+ * @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 { innerDotSize, containerStyle, hitSlop, a11yProps } = useRadioButtonLogic({
+ *   checked: true,
+ *   disabled: false,
+ *   size: "md",
+ *   color: "accentPrimary",
+ *   label: "Option A - Standard shipping",
+ * });
+ */
+export function useRadioButtonLogic(
+  params: UseRadioButtonLogicParams
+): UseRadioButtonLogicReturn {
+  const {
+    checked,
+    disabled,
+    size,
+    color,
+    label,
+    accessibilityLabel,
+    accessibilityHint,
+  } = params;
+
+  const { labels: t } = useDesignSystem();
+  const theme = useRestyleTheme();
+  const resolvedSize = (useResponsiveProp(size) ?? "md") as RadioButtonSize;
+
+  const innerDotSize = getRadioButtonInnerSize(resolvedSize);
+  const hitSlop = getRadioButtonHitSlop(resolvedSize);
+
+  const containerStyle = useMemo((): ViewStyle => {
+    const styleResult = resolveRadioButtonStyle({
+      checked,
+      disabled,
+      color,
+      theme,
+    });
+
+    return {
+      backgroundColor: styleResult.backgroundColor,
+      borderColor: styleResult.borderColor,
+      opacity: styleResult.opacity,
+    };
+  }, [checked, disabled, color, theme]);
+
+  const a11yProps = useMemo(
+    () => getRadioButtonA11y({ label, accessibilityLabel, accessibilityHint, checked, disabled, fallbackLabel: t.designSystem.radioButton.fallbackLabel }),
+    [label, accessibilityLabel, accessibilityHint, checked, disabled, t.designSystem.radioButton.fallbackLabel]
+  );
+
+  return {
+    innerDotSize,
+    containerStyle,
+    hitSlop,
+    a11yProps,
+  };
+}

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

@@ -0,0 +1,174 @@
+import type { RestyleTheme } from "../../../core/restyle";
+import type {
+  SegmentedControlSize,
+  SegmentedControlVariant,
+} from "./SegmentedControl.types";
+
+// =============================================================================
+// TYPOGRAPHY MAPPING
+// =============================================================================
+
+/**
+ * Map segment size to text typography variant.
+ *
+ * | Size | Typography   |
+ * |------|------------- |
+ * | sm   | labelSmall   |
+ * | md   | labelMedium  |
+ * | lg   | labelLarge   |
+ */
+export const SEGMENT_TEXT_VARIANT: Record<
+  SegmentedControlSize,
+  "labelSmall" | "labelMedium" | "labelLarge"
+> = {
+  sm: "labelSmall",
+  md: "labelMedium",
+  lg: "labelLarge",
+};
+
+/**
+ * Size configuration mapping
+ */
+const SIZE_CONFIG: Record<
+  SegmentedControlSize,
+  {
+    paddingVertical: keyof RestyleTheme["spacing"];
+    paddingHorizontal: keyof RestyleTheme["spacing"];
+    containerPadding: keyof RestyleTheme["spacing"];
+    borderRadius: keyof RestyleTheme["borderRadii"];
+  }
+> = {
+  sm: {
+    paddingVertical: "xs",
+    paddingHorizontal: "sm",
+    containerPadding: "2xs",
+    borderRadius: "md",
+  },
+  md: {
+    paddingVertical: "sm",
+    paddingHorizontal: "md",
+    containerPadding: "2xs",
+    borderRadius: "lg",
+  },
+  lg: {
+    paddingVertical: "md",
+    paddingHorizontal: "lg",
+    containerPadding: "xs",
+    borderRadius: "lg",
+  },
+};
+
+/**
+ * Variant configuration mapping
+ */
+const VARIANT_CONFIG: Record<
+  SegmentedControlVariant,
+  {
+    containerBackground: keyof RestyleTheme["colors"];
+    selectedBackground: keyof RestyleTheme["colors"];
+    unselectedBackground: keyof RestyleTheme["colors"];
+    selectedTextColor: keyof RestyleTheme["colors"];
+    unselectedTextColor: keyof RestyleTheme["colors"];
+    disabledTextColor: keyof RestyleTheme["colors"];
+  }
+> = {
+  default: {
+    containerBackground: "backgroundTertiary",
+    selectedBackground: "backgroundPrimary",
+    unselectedBackground: "transparent",
+    selectedTextColor: "accentPrimary",
+    unselectedTextColor: "textSecondary",
+    disabledTextColor: "textDisabled",
+  },
+  outline: {
+    containerBackground: "transparent",
+    selectedBackground: "accentPrimary",
+    unselectedBackground: "transparent",
+    selectedTextColor: "textInverse",
+    unselectedTextColor: "textPrimary",
+    disabledTextColor: "textDisabled",
+  },
+};
+
+/**
+ * Get container styles based on size and variant
+ */
+export function getContainerStyles(
+  size: SegmentedControlSize,
+  variant: SegmentedControlVariant
+): {
+  backgroundColor: keyof RestyleTheme["colors"];
+  borderRadius: keyof RestyleTheme["borderRadii"];
+  padding: keyof RestyleTheme["spacing"];
+} {
+  const sizeConfig = SIZE_CONFIG[size] || SIZE_CONFIG.md;
+  const variantConfig = VARIANT_CONFIG[variant] || VARIANT_CONFIG.default;
+
+  return {
+    backgroundColor: variantConfig.containerBackground,
+    borderRadius: sizeConfig.borderRadius,
+    padding: sizeConfig.containerPadding,
+  };
+}
+
+/**
+ * Get segment styles based on selection state
+ */
+export function getSegmentStyles(
+  size: SegmentedControlSize,
+  variant: SegmentedControlVariant,
+  isSelected: boolean,
+  _isDisabled: boolean
+): {
+  backgroundColor: keyof RestyleTheme["colors"];
+  borderRadius: keyof RestyleTheme["borderRadii"];
+  paddingVertical: keyof RestyleTheme["spacing"];
+  paddingHorizontal: keyof RestyleTheme["spacing"];
+} {
+  const sizeConfig = SIZE_CONFIG[size] || SIZE_CONFIG.md;
+  const variantConfig = VARIANT_CONFIG[variant] || VARIANT_CONFIG.default;
+
+  return {
+    backgroundColor: isSelected
+      ? variantConfig.selectedBackground
+      : variantConfig.unselectedBackground,
+    borderRadius: sizeConfig.borderRadius,
+    paddingVertical: sizeConfig.paddingVertical,
+    paddingHorizontal: sizeConfig.paddingHorizontal,
+  };
+}
+
+/**
+ * Get text color based on selection state
+ */
+export function getTextColor(
+  variant: SegmentedControlVariant,
+  isSelected: boolean,
+  isDisabled: boolean
+): keyof RestyleTheme["colors"] {
+  const variantConfig = VARIANT_CONFIG[variant] || VARIANT_CONFIG.default;
+
+  if (isDisabled) {
+    return variantConfig.disabledTextColor;
+  }
+
+  return isSelected
+    ? variantConfig.selectedTextColor
+    : variantConfig.unselectedTextColor;
+}
+
+/**
+ * Validate options array
+ */
+export function validateOptions(
+  options: { value: string; label: string }[]
+): boolean {
+  if (!Array.isArray(options) || options.length < 2) {
+    return false;
+  }
+
+  const values = options.map((o) => o.value);
+  const uniqueValues = new Set(values);
+
+  return uniqueValues.size === values.length;
+}