@praxiis/ui 0.0.1

package/src/primitives/inputs/SelectSheet/SelectSheetOption.tsx

@@ -0,0 +1,177 @@
+/**
+ * SelectSheetOption Component
+ *
+ * @description Individual option row for the SelectSheet - Atom
+ *
+ * Renders a single selectable option with radio/checkbox indicator,
+ * optional media content (icon or image), and label text.
+ * Follows the design system's atomic primacy and touch target rules.
+ *
+ * ## Layout
+ * | Position | Left Indicator          | Right Indicator (default) |
+ * |----------|-------------------------|---------------------------|
+ * | left     | Radio/Checkbox → Media → Label |                    |
+ * | right    | Media → Label → Radio/Checkbox |                    |
+ *
+ * ## Features
+ * - Supports icon (MaterialIcons) or image URL media
+ * - Configurable indicator position (left/right)
+ * - Consistent sizing with touch targets (52px row height)
+ * - Press feedback with background color change
+ * - Disabled state with reduced opacity
+ * - Full accessibility support
+ * - Memoized for performance
+ *
+ * @see SelectSheet.types.ts - Type definitions
+ * @see SelectSheet.a11y.ts - Accessibility prop generation
+ * @see tokens/scales.ts - SELECT_SHEET_LAYOUT
+ *
+ * @example
+ * // Basic usage (internal to SelectSheet)
+ * <SelectSheetOptionRow
+ *   option={{ value: "a", label: "Option A" }}
+ *   isSelected={true}
+ *   isMultiple={false}
+ *   onPress={handlePress}
+ *   showDivider={true}
+ * />
+ *
+ * @example
+ * // With icon and left indicator
+ * <SelectSheetOptionRow
+ *   option={{ value: "b", label: "Option B", icon: "star" }}
+ *   isSelected={false}
+ *   isMultiple={true}
+ *   onPress={handlePress}
+ *   indicatorPosition="left"
+ * />
+ */
+
+import React, { memo, useCallback } from "react";
+import { Image } from "react-native";
+import { SELECT_SHEET_LAYOUT } from "../../../tokens/scales";
+import { Icon } from "../../content/Icon";
+import { Box, Pressable } from "../../layout";
+import { Divider } from "../../layout/Divider";
+import { Text } from "../../typography";
+import { Checkbox } from "../Checkbox";
+import { RadioButton } from "../RadioButton";
+import type { SelectSheetOptionRowProps } from "./SelectSheet.types";
+
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+
+/** Standard image size for option media */
+const IMAGE_SIZE = 32;
+/** Standard icon/control size */
+const CONTROL_SIZE = "md" as const;
+
+// =============================================================================
+// COMPONENT IMPLEMENTATION
+// =============================================================================
+
+function SelectSheetOptionRowComponent<T>({
+  option,
+  isSelected,
+  isMultiple,
+  onPress,
+  showDivider,
+  indicatorPosition = "right",
+  a11yProps,
+  testID,
+}: SelectSheetOptionRowProps<T>) {
+
+  // Handler for pressable
+  const handlePress = useCallback(() => {
+    if (!option.disabled) {
+      onPress();
+    }
+  }, [option.disabled, onPress]);
+
+  // Selection indicator component
+  const SelectionIndicator = isMultiple ? (
+    <Checkbox
+      checked={isSelected}
+      onPress={onPress}
+      disabled={option.disabled}
+      size={CONTROL_SIZE}
+    />
+  ) : (
+    <RadioButton
+      checked={isSelected}
+      onPress={onPress}
+      disabled={option.disabled}
+      size={CONTROL_SIZE}
+    />
+  );
+
+  // Media content (icon or image)
+  const MediaContent = option.imageUrl ? (
+    <Image
+      source={{ uri: option.imageUrl }}
+      style={{
+        width: IMAGE_SIZE,
+        height: IMAGE_SIZE,
+        borderRadius: IMAGE_SIZE / 2,
+      }}
+      accessibilityIgnoresInvertColors
+    />
+  ) : option.icon ? (
+    <Icon
+      name={option.icon}
+      size={CONTROL_SIZE}
+      color={isSelected ? "accentPrimary" : "textSecondary"}
+    />
+  ) : null;
+
+  return (
+    <>
+      <Pressable
+        onPress={handlePress}
+        disabled={option.disabled}
+        testID={testID}
+        {...a11yProps}
+      >
+        {({ pressed }) => (
+          <Box
+            height={SELECT_SHEET_LAYOUT.optionRowHeight}
+            paddingHorizontal="lg"
+            paddingVertical="md"
+            flexDirection="row"
+            alignItems="center"
+            gap="md"
+            backgroundColor={
+              pressed && !option.disabled ? "backgroundTertiary" : "transparent"
+            }
+            opacity={option.disabled ? 0.5 : 1}
+          >
+            {/* Selection indicator on left */}
+            {indicatorPosition === "left" && SelectionIndicator}
+
+            {/* Media content (icon or image) */}
+            {MediaContent}
+
+            {/* Option label */}
+            <Box flex={1}>
+              <Text
+                variant="bodyMedium"
+                color={isSelected ? "accentPrimary" : "textPrimary"}
+              >
+                {option.label}
+              </Text>
+            </Box>
+
+            {/* Selection indicator on right (default) */}
+            {indicatorPosition === "right" && SelectionIndicator}
+          </Box>
+        )}
+      </Pressable>
+      {showDivider && <Divider />}
+    </>
+  );
+}
+
+export const SelectSheetOptionRow = memo(
+  SelectSheetOptionRowComponent,
+) as typeof SelectSheetOptionRowComponent;

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

@@ -0,0 +1,48 @@
+/**
+ * SelectSheet Component
+ *
+ * Barrel export for the SelectSheet component and related types.
+ *
+ * @example
+ * ```tsx
+ * import { SelectSheet, type SelectSheetOption, type SelectSheetPosition } from '@/design-system/primitives/inputs/SelectSheet';
+ *
+ * <SelectSheet
+ *   visible={true}
+ *   options={options}
+ *   value={selected}
+ *   onChange={setSelected}
+ *   onClose={handleClose}
+ *   position="center"
+ * />
+ * ```
+ */
+
+export { SelectSheet } from "./SelectSheet";
+export { SelectSheetOptionRow } from "./SelectSheetOption";
+export { useSelectSheetLogic } from "./useSelectSheetLogic";
+
+export type {
+  SelectSheetProps,
+  SelectSheetOption,
+  SelectSheetMode,
+  SelectSheetPosition,
+  SelectSheetLayout,
+  SelectSheetOptionRowProps,
+  SelectSheetIndicatorPosition,
+} from "./SelectSheet.types";
+
+export {
+  normalizeValue,
+  denormalizeValue,
+  toggleSelection,
+  isValueSelected,
+  getDisplayLabel,
+  calculateListHeight,
+  filterOptions,
+} from "./SelectSheet.helpers";
+
+export {
+  getSheetA11yProps,
+  getOptionA11yProps,
+} from "./SelectSheet.a11y";

package/src/primitives/inputs/SelectSheet/useSelectSheetLogic.ts

@@ -0,0 +1,309 @@
+/**
+ * Orchestrates SelectSheet rendering logic and state management.
+ * 
+ * Handles:
+ * - Selection state management (single/multiple modes)
+ * - Temporary selections during multi-select (confirm/cancel)
+ * - Search/filtering of options
+ * - List height calculation based on screen size
+ * - Option press handling with mode-specific behavior
+ * - Confirm/cancel handlers for multi-select
+ * - Selection state checking
+ * 
+ * @param params - Configuration object for select sheet behavior
+ * @param params.value - Current selected value(s)
+ * @param params.mode - Selection mode ('single' | 'multiple')
+ * @param params.visible - Whether sheet is visible
+ * @param params.options - Available options array
+ * @param params.onChange - Callback when value changes
+ * @param params.onClose - Callback when sheet should close
+ * @param params.listHeight - Custom list height override
+ * @param params.closeOnSelect - Whether to close immediately on single selection
+ * 
+ * @returns Computed values for rendering SelectSheet
+ * @returns {T[]} tempSelections - Temporary selections (multi-select mode)
+ * @returns {SelectSheetOption<T>[]} filteredOptions - Filtered options by search
+ * @returns {string} searchQuery - Current search query
+ * @returns {function} handleOptionPress - Option press handler
+ * @returns {function} handleConfirm - Confirm selection (multi-select)
+ * @returns {function} handleCancel - Cancel selection (multi-select)
+ * @returns {function} handleSearchChange - Search query change handler
+ * @returns {function} isSelected - Check if option is selected
+ * @returns {SelectSheetLayout} layout - Layout configuration
+ * @returns {boolean} isMultiple - Whether in multiple mode
+ * @returns {boolean} hasSelection - Whether any options selected
+ * 
+ * @performance
+ * - Uses useMemo() for filtered options and layout calculations
+ * - useCallback() for handler memoization
+ * - Syncs temp selections only when sheet becomes visible
+ * 
+ * @example
+ * const {
+ *   filteredOptions,
+ *   handleOptionPress,
+ *   handleConfirm,
+ *   isSelected,
+ *   layout
+ * } = useSelectSheetLogic({
+ *   value: ["option1", "option3"],
+ *   mode: "multiple",
+ *   visible: true,
+ *   options: myOptions,
+ *   onChange: setValue,
+ *   onClose: () => setVisible(false),
+ * });
+ */
+
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { AccessibilityProps, useWindowDimensions } from "react-native";
+
+import { useDesignSystem } from "../../../provider";
+import {
+  calculateListHeight,
+  denormalizeValue,
+  filterOptions,
+  normalizeValue,
+  toggleSelection,
+} from "./SelectSheet.helpers";
+import { getSheetA11yProps, getOptionA11yProps } from "./SelectSheet.a11y";
+import type {
+  SelectSheetLayout,
+  SelectSheetMode,
+  SelectSheetOption,
+  SelectSheetPosition,
+} from "./SelectSheet.types";
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+interface UseSelectSheetLogicParams<T> {
+  /** Current value(s) */
+  value: T | T[] | null;
+  /** Selection mode */
+  mode: SelectSheetMode;
+  /** Whether sheet is visible */
+  visible: boolean;
+  /** Available options */
+  options: SelectSheetOption<T>[];
+  /** Callback when value changes */
+  onChange: (value: T | T[] | null) => void;
+  /** Callback when sheet should close */
+  onClose: () => void;
+  /** Custom list height override */
+  listHeight?: number;
+  /** Whether to close immediately on single selection */
+  closeOnSelect?: boolean;
+  /** Sheet title for a11y */
+  title?: string;
+  /** Sheet position for a11y */
+  position?: SelectSheetPosition;
+  /** Custom accessibility label */
+  accessibilityLabel?: string;
+}
+
+interface UseSelectSheetLogicReturn<T> {
+  // Selection state
+  tempSelections: T[];
+  filteredOptions: SelectSheetOption<T>[];
+  searchQuery: string;
+
+  // Handlers
+  handleOptionPress: (optionValue: T) => void;
+  handleConfirm: () => void;
+  handleCancel: () => void;
+  handleSearchChange: (query: string) => void;
+  isSelected: (optionValue: T) => boolean;
+
+  // Layout
+  layout: SelectSheetLayout;
+
+  // Computed flags
+  isMultiple: boolean;
+  hasSelection: boolean;
+
+  // Accessibility
+  sheetA11yProps: ReturnType<typeof getSheetA11yProps>;
+
+  // Option a11y factory
+  getOptionA11y: (params: {
+    label: string;
+    isSelected: boolean;
+    isDisabled: boolean;
+    isMultiple: boolean;
+    index: number;
+    total: number;
+  }) => AccessibilityProps;
+}
+
+// =============================================================================
+// HOOK IMPLEMENTATION
+// =============================================================================
+
+export function useSelectSheetLogic<T>({
+  value,
+  mode,
+  visible,
+  options,
+  onChange,
+  onClose,
+  listHeight: customListHeight,
+  closeOnSelect,
+  title,
+  position = "center",
+  accessibilityLabel,
+}: UseSelectSheetLogicParams<T>): UseSelectSheetLogicReturn<T> {
+  const isMultiple = mode === "multiple";
+  const { height: screenHeight } = useWindowDimensions();
+  const { labels: t } = useDesignSystem();
+
+  // -------------------------------------------------------------------------
+  // Selection State
+  // -------------------------------------------------------------------------
+
+  const [tempSelections, setTempSelections] = useState<T[]>(() =>
+    normalizeValue(value, isMultiple)
+  );
+  const [searchQuery, setSearchQuery] = useState("");
+
+  // Sync temp selections when value or visibility changes
+  useEffect(() => {
+    if (visible) {
+      setTempSelections(normalizeValue(value, isMultiple));
+      setSearchQuery(""); // Reset search on open
+    }
+  }, [value, visible, isMultiple]);
+
+  // -------------------------------------------------------------------------
+  // Filtered Options
+  // -------------------------------------------------------------------------
+
+  const filteredOptions = useMemo(
+    () => filterOptions(options, searchQuery),
+    [options, searchQuery]
+  );
+
+  // -------------------------------------------------------------------------
+  // Layout Calculations
+  // -------------------------------------------------------------------------
+
+  const layout = useMemo(
+    () => ({
+      listHeight: calculateListHeight(
+        options.length,
+        screenHeight,
+        customListHeight
+      ),
+    }),
+    [options.length, screenHeight, customListHeight]
+  );
+
+  // -------------------------------------------------------------------------
+  // Selection Logic
+  // -------------------------------------------------------------------------
+
+  const isSelected = useCallback(
+    (optionValue: T): boolean => tempSelections.includes(optionValue),
+    [tempSelections]
+  );
+
+  const hasSelection = tempSelections.length > 0;
+
+  const handleOptionPress = useCallback(
+    (optionValue: T) => {
+      if (isMultiple) {
+        // Multiple mode - toggle in temp selections
+        setTempSelections((prev) =>
+          toggleSelection(prev, optionValue, isMultiple)
+        );
+      } else {
+        // Single mode - select and optionally close immediately
+        onChange(optionValue);
+        if (closeOnSelect !== false) {
+          onClose();
+        }
+      }
+    },
+    [isMultiple, onChange, onClose, closeOnSelect]
+  );
+
+  const handleConfirm = useCallback(() => {
+    onChange(denormalizeValue(tempSelections, isMultiple));
+    onClose();
+  }, [tempSelections, isMultiple, onChange, onClose]);
+
+  const handleCancel = useCallback(() => {
+    setTempSelections(normalizeValue(value, isMultiple));
+    onClose();
+  }, [value, isMultiple, onClose]);
+
+  const handleSearchChange = useCallback((query: string) => {
+    setSearchQuery(query);
+  }, []);
+
+  // Accessibility
+  const positionLabels = useMemo(() => ({
+    bottom: t.designSystem.selectSheet.positionBottom,
+    top: t.designSystem.selectSheet.positionTop,
+    center: t.designSystem.selectSheet.positionCenter,
+  }), [t]);
+
+  const sheetA11yProps = useMemo(
+    () => getSheetA11yProps({
+      title,
+      position,
+      accessibilityLabel,
+      positionLabels,
+      fallbackTitle: t.designSystem.selectSheet.fallbackTitle,
+    }),
+    [title, position, accessibilityLabel, positionLabels, t],
+  );
+
+  const optionI18n = useMemo(() => ({
+    selectedLabel: t.designSystem.selectSheet.selected,
+    disabledLabel: t.designSystem.selectSheet.disabled,
+    ofLabel: t.designSystem.selectSheet.of,
+  }), [t]);
+
+  const getOptionA11y = useCallback(
+    (params: {
+      label: string;
+      isSelected: boolean;
+      isDisabled: boolean;
+      isMultiple: boolean;
+      index: number;
+      total: number;
+    }) => getOptionA11yProps({ ...params, ...optionI18n }),
+    [optionI18n],
+  );
+
+  // -------------------------------------------------------------------------
+  // Return Values
+  // -------------------------------------------------------------------------
+
+  return {
+    // Selection state
+    tempSelections,
+    filteredOptions,
+    searchQuery,
+
+    // Handlers
+    handleOptionPress,
+    handleConfirm,
+    handleCancel,
+    handleSearchChange,
+    isSelected,
+
+    // Layout
+    layout,
+
+    // Computed flags
+    isMultiple,
+    hasSelection,
+
+    // Accessibility
+    sheetA11yProps,
+    getOptionA11y,
+  };
+}

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

@@ -0,0 +1,109 @@
+/**
+ * Switch Component Helpers
+ *
+ * Pure functions for computing Switch styles, dimensions, and colors.
+ * All calculations are derived from the centralized scales.ts token file.
+ */
+
+import { Insets } from "react-native";
+import {
+  calculateSwitchThumbSize,
+  SWITCH_DIMENSIONS,
+  SWITCH_HIT_SLOP,
+  SWITCH_THUMB_INSET,
+} from "../../../tokens/scales";
+import {
+  ResolveSwitchStyleParams,
+  SwitchDimensions,
+  SwitchSize,
+  SwitchStyleResult,
+} from "./Switch.types";
+
+// =============================================================================
+// DIMENSION RESOLUTION
+// =============================================================================
+
+/**
+ * Get switch dimensions based on size.
+ *
+ * Uses SWITCH_DIMENSIONS from scales.ts for consistent sizing.
+ * Thumb size is calculated using SWITCH_THUMB_INSET for consistent padding.
+ *
+ * | Size | Track W | Track H | Thumb | Inset |
+ * |------|---------|---------|-------|-------|
+ * | sm   | 40px    | 24px    | 20px  | 2px   |
+ * | md   | 48px    | 28px    | 24px  | 2px   |
+ * | lg   | 56px    | 32px    | 28px  | 2px   |
+ *
+ * Thumb size formula: trackHeight - (SWITCH_THUMB_INSET * 2)
+ *
+ * @param size - The switch size variant
+ * @returns Track width, track height, and thumb size
+ */
+export function getSwitchDimensions(size: SwitchSize): SwitchDimensions {
+  const dimensions = SWITCH_DIMENSIONS[size] ?? SWITCH_DIMENSIONS.md;
+  const thumbSize = calculateSwitchThumbSize(dimensions.trackHeight);
+
+  return {
+    trackWidth: dimensions.trackWidth,
+    trackHeight: dimensions.trackHeight,
+    thumbSize,
+  };
+}
+
+/**
+ * Get the thumb inset value.
+ * This is the padding between the track edge and the thumb.
+ *
+ * Exposed for components that need to calculate thumb position.
+ *
+ * @returns The thumb inset in pixels
+ */
+export function getSwitchThumbInset(): number {
+  return SWITCH_THUMB_INSET;
+}
+
+// =============================================================================
+// TOUCH TARGET (hitSlop)
+// =============================================================================
+
+/**
+ * Get hitSlop based on switch size.
+ *
+ * Uses pre-calculated values from scales.ts to ensure
+ * all switches meet the 44px minimum touch target.
+ *
+ * | Size | Track H | hitSlop | Total |
+ * |------|---------|---------|-------|
+ * | sm   | 24px    | 10px    | 44px  |
+ * | md   | 28px    | 8px     | 44px  |
+ * | lg   | 32px    | 6px     | 44px  |
+ *
+ * @param size - The switch size variant
+ * @returns Insets for touch target expansion
+ */
+export function getSwitchHitSlop(size: SwitchSize): Insets {
+  return SWITCH_HIT_SLOP[size];
+}
+
+// =============================================================================
+// STYLE RESOLUTION
+// =============================================================================
+
+/**
+ * Resolve dynamic style properties for the Switch container.
+ *
+ * This function handles disabled state opacity.
+ * Track and thumb colors are handled by animated interpolations
+ * in the useSwitchLogic hook.
+ *
+ * @param params - Resolution parameters
+ * @returns Computed style object
+ */
+export function resolveSwitchStyle(
+  params: ResolveSwitchStyleParams
+): SwitchStyleResult {
+  return {
+    opacity: 1,
+  };
+}