@praxiis/ui 0.0.1

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

@@ -0,0 +1,147 @@
+/**
+ * SelectSheet Helper Functions
+ *
+ * Pure utility functions for SelectSheet component.
+ * All values derived from tokens/scales.ts for consistency.
+ *
+ * @see tokens/scales.ts - SELECT_SHEET_LAYOUT
+ */
+
+import { SELECT_SHEET_LAYOUT } from "../../../tokens/scales";
+import type {
+  SelectSheetOption,
+} from "./SelectSheet.types";
+
+// =============================================================================
+// SELECTION LOGIC HELPERS
+// =============================================================================
+
+/**
+ * Normalize value to array format for internal use.
+ */
+export function normalizeValue<T>(
+  value: T | T[] | null,
+  isMultiple: boolean
+): T[] {
+  if (value === null || value === undefined) {
+    return [];
+  }
+  if (isMultiple) {
+    return Array.isArray(value) ? value : [value];
+  }
+  return Array.isArray(value) ? value : [value];
+}
+
+/**
+ * Denormalize array back to expected format based on mode.
+ */
+export function denormalizeValue<T>(
+  values: T[],
+  isMultiple: boolean
+): T | T[] | null {
+  if (isMultiple) {
+    return values;
+  }
+  return values.length > 0 ? values[0] : null;
+}
+
+/**
+ * Toggle selection in array.
+ */
+export function toggleSelection<T>(
+  currentSelections: T[],
+  value: T,
+  isMultiple: boolean
+): T[] {
+  if (isMultiple) {
+    const index = currentSelections.indexOf(value);
+    if (index >= 0) {
+      return currentSelections.filter((v) => v !== value);
+    }
+    return [...currentSelections, value];
+  }
+  // Single mode - replace selection
+  return [value];
+}
+
+/**
+ * Check if value is selected.
+ */
+export function isValueSelected<T>(selections: T[], value: T): boolean {
+  return selections.includes(value);
+}
+
+// =============================================================================
+// DISPLAY HELPERS
+// =============================================================================
+
+/**
+ * Get display label for selected value(s).
+ */
+export function getDisplayLabel<T>(
+  options: SelectSheetOption<T>[],
+  value: T | T[] | null,
+  placeholder: string = "Select..."
+): string {
+  if (value === null || value === undefined) {
+    return placeholder;
+  }
+
+  const values = Array.isArray(value) ? value : [value];
+  if (values.length === 0) {
+    return placeholder;
+  }
+
+  const labels = values
+    .map((v) => options.find((o) => o.value === v)?.label)
+    .filter(Boolean);
+
+  if (labels.length === 0) {
+    return placeholder;
+  }
+
+  if (labels.length === 1) {
+    return labels[0] as string;
+  }
+
+  return `${labels[0]} +${labels.length - 1} more`;
+}
+
+// =============================================================================
+// LAYOUT CALCULATION HELPERS
+// =============================================================================
+
+/**
+ * Calculate list height based on custom prop or default.
+ * If customListHeight is provided, uses that.
+ * Otherwise uses the default fixed height from tokens.
+ */
+export function calculateListHeight(
+  optionCount: number,
+  screenHeight: number,
+  customListHeight?: number
+): number {
+  if (customListHeight) {
+    return customListHeight;
+  }
+
+  // Use fixed default height, but don't exceed viewport height
+  return Math.min(SELECT_SHEET_LAYOUT.defaultListHeight, screenHeight);
+}
+
+/**
+ * Filter options by search query.
+ */
+export function filterOptions<T>(
+  options: SelectSheetOption<T>[],
+  query: string
+): SelectSheetOption<T>[] {
+  if (!query.trim()) {
+    return options;
+  }
+
+  const normalizedQuery = query.toLowerCase().trim();
+  return options.filter((option) =>
+    option.label.toLowerCase().includes(normalizedQuery)
+  );
+}

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

@@ -0,0 +1,247 @@
+/**
+ * SelectSheet Component
+ *
+ * @description Selection dialog for picking from a list of options - Molecule
+ *
+ * SelectSheet presents a scrollable list of options in a modal dialog.
+ * Supports single and multiple selection modes with radio/checkbox indicators.
+ * Built on top of the Modal component for consistent overlay behavior.
+ *
+ * ## Selection Modes
+ * | Mode     | Indicator  | Behavior                          |
+ * |----------|------------|-----------------------------------|
+ * | single   | RadioButton| Selects one, closes on select     |
+ * | multiple | Checkbox   | Selects many, "Done" to confirm   |
+ *
+ * ## Width Behavior
+ * | Viewport | Width                                    |
+ * |----------|------------------------------------------|
+ * | Phone    | Full width minus lg (16px) horizontal    |
+ * | Tablet   | Capped at 480px max-width                |
+ *
+ * ## Positions
+ * - `center`: Standard dialog centered on screen (default)
+ * - `top`: Anchored to top with slide-down animation
+ * - `bottom`: Anchored to bottom with slide-up animation
+ *
+ * ## Features
+ * - Single and multiple selection modes
+ * - Radio/checkbox indicators (left or right position)
+ * - Optional icons and images per option
+ * - Virtualized list (FlatList) for performance
+ * - Configurable list height
+ * - Built on Modal for consistent overlay UX
+ * - Full accessibility support
+ * - Memoized for performance
+ *
+ * @see SelectSheet.types.ts - Type definitions
+ * @see SelectSheet.helpers.ts - Pure calculation functions
+ * @see SelectSheet.a11y.ts - Accessibility prop generation
+ * @see SelectSheetOption.tsx - Individual option row
+ * @see tokens/scales.ts - SELECT_SHEET_LAYOUT
+ *
+ * @example
+ * // Single select
+ * <SelectSheet
+ *   visible={isOpen}
+ *   onClose={() => setOpen(false)}
+ *   options={[
+ *     { value: "usd", label: "US Dollar" },
+ *     { value: "eur", label: "Euro" },
+ *   ]}
+ *   value="usd"
+ *   onChange={setCurrency}
+ * />
+ *
+ * @example
+ * // Multiple select with icons
+ * <SelectSheet
+ *   visible={isOpen}
+ *   onClose={() => setOpen(false)}
+ *   mode="multiple"
+ *   title="Select Categories"
+ *   options={categories.map(c => ({ value: c.id, label: c.name, icon: c.icon }))}
+ *   value={selectedIds}
+ *   onChange={setSelectedIds}
+ *   position="bottom"
+ * />
+ */
+
+import React, { memo, useCallback } from "react";
+import { useDesignSystem } from "../../../provider";
+import { SELECT_SHEET_LAYOUT } from "../../../tokens/scales";
+import { Button } from "../../actions/Button";
+import { Box, FlatList } from "../../layout";
+import type { ModalPosition } from "../../overlays/Modal";
+import { Modal } from "../../overlays/Modal";
+import type { SelectSheetOption, SelectSheetProps } from "./SelectSheet.types";
+import { SelectSheetOptionRow } from "./SelectSheetOption";
+import { useSelectSheetLogic } from "./useSelectSheetLogic";
+
+// =============================================================================
+// DEFAULT VALUES
+// =============================================================================
+
+const DEFAULT_TITLE = "Select";
+
+// =============================================================================
+// COMPONENT IMPLEMENTATION
+// =============================================================================
+
+function SelectSheetComponent<T = string>({
+  visible,
+  onClose,
+  options,
+  value,
+  onChange,
+  mode = "single",
+  position = "center",
+  title = DEFAULT_TITLE,
+  doneText,
+  listHeight: customListHeight,
+  showDividers = true,
+  closeOnSelect,
+  indicatorPosition = "right",
+  testID,
+  accessibilityLabel,
+}: SelectSheetProps<T>) {
+  const { labels: t } = useDesignSystem();
+  const effectiveDoneText = doneText ?? t.designSystem.selectSheet.doneLabel;
+
+  const {
+    filteredOptions,
+    handleOptionPress,
+    handleConfirm,
+    handleCancel,
+    isSelected,
+    isMultiple,
+    layout,
+    sheetA11yProps,
+    getOptionA11y,
+  } = useSelectSheetLogic({
+    value,
+    mode,
+    visible,
+    options,
+    onChange,
+    onClose,
+    listHeight: customListHeight,
+    title,
+    position,
+    accessibilityLabel,
+  });
+
+  // Map SelectSheet position to Modal position
+  const modalPosition: ModalPosition = position;
+
+  // Render option item
+  const renderOption = useCallback(
+    ({ item, index }: { item: SelectSheetOption<T>; index: number }) => (
+      <SelectSheetOptionRow
+        option={item}
+        isSelected={isSelected(item.value)}
+        isMultiple={isMultiple}
+        onPress={() => handleOptionPress(item.value)}
+        showDivider={showDividers && index < filteredOptions.length - 1}
+        indicatorPosition={indicatorPosition}
+        a11yProps={getOptionA11y({
+          label: item.label,
+          isSelected: isSelected(item.value),
+          isDisabled: item.disabled || false,
+          isMultiple,
+          index,
+          total: filteredOptions.length,
+        })}
+        testID={testID ? `${testID}-option-${index}` : undefined}
+      />
+    ),
+    [
+      isSelected,
+      isMultiple,
+      handleOptionPress,
+      showDividers,
+      filteredOptions.length,
+      indicatorPosition,
+      getOptionA11y,
+      testID,
+    ],
+  );
+
+  const keyExtractor = useCallback(
+    (item: SelectSheetOption<T>, index: number) =>
+      `option-${index}-${String(item.value)}`,
+    [],
+  );
+
+  const getItemLayout = useCallback(
+    (
+      _data: ArrayLike<SelectSheetOption<T>> | null | undefined,
+      index: number,
+    ) => ({
+      length: SELECT_SHEET_LAYOUT.optionRowHeight,
+      offset: SELECT_SHEET_LAYOUT.optionRowHeight * index,
+      index,
+    }),
+    [],
+  );
+
+  return (
+    <Modal
+      visible={visible}
+      onClose={handleCancel}
+      title={title}
+      position={modalPosition}
+      closeOnBackdropPress
+      showCloseButton={true}
+      accessibilityLabel={accessibilityLabel}
+    >
+      <Box testID={testID} {...sheetA11yProps}>
+        {/* Options List */}
+        <Box style={{ maxHeight: layout.listHeight }}>
+          <FlatList
+            data={filteredOptions}
+            renderItem={renderOption}
+            keyExtractor={keyExtractor}
+            getItemLayout={getItemLayout}
+            showsVerticalScrollIndicator={false}
+            bounces={false}
+            initialNumToRender={10}
+            maxToRenderPerBatch={10}
+            windowSize={5}
+          />
+        </Box>
+
+        {/* Footer - Done button for multiple mode */}
+        {isMultiple && (
+          <Box
+            paddingHorizontal="lg"
+            paddingVertical="md"
+            borderTopWidth={1}
+            borderTopColor="borderSubtle"
+            flexDirection="row"
+            justifyContent="flex-end"
+          >
+            <Button
+              title={effectiveDoneText}
+              variant="ghost"
+              size="md"
+              onPress={handleConfirm}
+              testID={testID ? `${testID}-done` : undefined}
+            />
+          </Box>
+        )}
+      </Box>
+    </Modal>
+  );
+}
+
+// =============================================================================
+// EXPORTS
+// =============================================================================
+
+export const SelectSheet = memo(SelectSheetComponent) as <T = string>(
+  props: SelectSheetProps<T>,
+) => React.ReactElement;
+
+// @ts-expect-error - displayName on generic component
+SelectSheet.displayName = "SelectSheet";

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

@@ -0,0 +1,196 @@
+/**
+ * SelectSheet Component Types
+ *
+ * Type definitions for the SelectSheet selection dialog component.
+ * Follows Modal pattern with consistent width behavior:
+ * - Phone: Full width minus lg (16px) horizontal padding
+ * - Tablet (≥768px): Capped at 480px max-width (phone-like experience)
+ *
+ * @see tokens/scales.ts - SELECT_SHEET_LAYOUT
+ * @see core/restyle/restyleTheme.ts - selectSheetVariants
+ */
+
+import { IconName } from "../../content/Icon";
+
+// =============================================================================
+// POSITION TYPES
+// =============================================================================
+
+/**
+ * SelectSheet position controlling vertical placement.
+ *
+ * - `center`: Centered vertically (default, standard dialog)
+ * - `top`: Anchored to top of screen
+ * - `bottom`: Bottom sheet anchored to screen bottom
+ */
+export type SelectSheetPosition = "center" | "top" | "bottom";
+
+// =============================================================================
+// OPTION TYPES
+// =============================================================================
+
+/**
+ * Individual option for the SelectSheet
+ */
+export interface SelectSheetOption<T = string> {
+  /** Unique value for the option */
+  value: T;
+  /** Display label */
+  label: string;
+  /** Optional icon name from MaterialIcons */
+  icon?: IconName;
+  /** Optional image URL to display */
+  imageUrl?: string;
+  /** Whether this option is disabled */
+  disabled?: boolean;
+}
+
+/**
+ * Position of the selection indicator (checkbox/radio button)
+ */
+export type SelectSheetIndicatorPosition = "left" | "right";
+
+// =============================================================================
+// MODE TYPES
+// =============================================================================
+
+/**
+ * Selection mode - single or multiple
+ */
+export type SelectSheetMode = "single" | "multiple";
+
+// =============================================================================
+// COMPONENT PROPS
+// =============================================================================
+
+/**
+ * SelectSheet component props.
+ *
+ * @template T - Type of option values (defaults to string)
+ */
+export interface SelectSheetProps<T = string> {
+  // -------------------------------------------------------------------------
+  // Required Props
+  // -------------------------------------------------------------------------
+
+  /** Whether the sheet is visible */
+  visible: boolean;
+  /** Callback when sheet should close */
+  onClose: () => void;
+  /** Available options */
+  options: SelectSheetOption<T>[];
+  /** Currently selected value(s) */
+  value: T | T[] | null;
+  /** Callback when selection changes */
+  onChange: (value: T | T[] | null) => void;
+
+  // -------------------------------------------------------------------------
+  // Position Props
+  // -------------------------------------------------------------------------
+
+  /**
+   * Vertical position of the sheet
+   * - "center": Centered modal dialog
+   * - "top": Anchored to top of screen
+   * - "bottom": Bottom sheet anchored to screen bottom
+   * @default "center"
+   */
+  position?: SelectSheetPosition;
+
+  // -------------------------------------------------------------------------
+  // Behavior Props
+  // -------------------------------------------------------------------------
+
+  /**
+   * Selection mode
+   * @default "single"
+   */
+  mode?: SelectSheetMode;
+
+  /**
+   * Whether to close immediately on single selection
+   * @default true (for single mode), false (for multiple mode)
+   */
+  closeOnSelect?: boolean;
+
+  /**
+   * Position of the selection indicator (checkbox/radio button)
+   * @default "right"
+   */
+  indicatorPosition?: SelectSheetIndicatorPosition;
+
+  // -------------------------------------------------------------------------
+  // Content Props
+  // -------------------------------------------------------------------------
+
+  /** Dialog/sheet title */
+  title?: string;
+  /** Done button text (multiple mode) */
+  doneText?: string;
+
+  // -------------------------------------------------------------------------
+  // Layout Props
+  // -------------------------------------------------------------------------
+
+  /**
+   * Custom height of the list container.
+   * If not provided, calculates based on option count (max 70% of viewport).
+   */
+  listHeight?: number;
+
+  /** Whether to show dividers between options */
+  showDividers?: boolean;
+
+  // -------------------------------------------------------------------------
+  // Accessibility Props
+  // -------------------------------------------------------------------------
+
+  /** Test ID for testing */
+  testID?: string;
+  /** Accessibility label */
+  accessibilityLabel?: string;
+}
+
+// =============================================================================
+// INTERNAL TYPES
+// =============================================================================
+
+/**
+ * Internal hook state for managing temporary selections.
+ */
+export interface SelectSheetState<T = string> {
+  /** Temporary selections before confirming (multiple mode) */
+  tempSelections: T[];
+  /** Search query for filtering options */
+  searchQuery: string;
+}
+
+/**
+ * Option row component props.
+ */
+export interface SelectSheetOptionRowProps<T = string> {
+  /** Option data */
+  option: SelectSheetOption<T>;
+  /** Whether this option is selected */
+  isSelected: boolean;
+  /** Whether multiple selection is enabled */
+  isMultiple: boolean;
+  /** Callback when option is pressed */
+  onPress: () => void;
+  /** Whether to show bottom divider */
+  showDivider: boolean;
+  /** Position of the selection indicator */
+  indicatorPosition: SelectSheetIndicatorPosition;
+  /** Pre-computed accessibility props from hook */
+  a11yProps: import("react-native").AccessibilityProps;
+  /** Test ID for testing */
+  testID?: string;
+}
+
+/**
+ * Computed layout values from hook.
+ */
+export interface SelectSheetLayout {
+  /** Calculated list height */
+  listHeight: number;
+}