@praxiis/ui 0.0.1

package/src/primitives/inputs/SegmentedControl/SegmentedControl.tsx

@@ -0,0 +1,224 @@
+/**
+ * SegmentedControl Component
+ *
+ * @description Toggle control for switching between multiple options - Atom
+ *
+ * SegmentedControl provides a horizontal row of mutually exclusive options.
+ * Ideal for filtering, view switching, and binary choices.
+ *
+ * ## Size Scale
+ * | Size | Height | Segment H | Text Variant | Use Case |
+ * |------|--------|-----------|--------------|----------|
+ * | sm   | 36px   | 28px      | labelSmall   | Compact filters |
+ * | md   | 44px   | 36px      | labelMedium  | Standard (default) |
+ * | lg   | 52px   | 44px      | labelLarge   | Prominent controls |
+ *
+ * ## Variants
+ * - `default`: Neutral background, white selected segment
+ * - `filled`: Subtle background, primary color selected segment
+ * - `outline`: Bordered container, primary color selected segment
+ *
+ * ## Features
+ * - Responsive size prop (phone/tablet breakpoints)
+ * - Three visual variants
+ * - Individual segment disable support
+ * - Theme-aware colors via Restyle
+ * - Full accessibility support (radiogroup pattern)
+ * - Memoized for performance
+ * - Spreads rest props for composability
+ *
+ * @see SegmentedControl.types.ts - Type definitions
+ * @see SegmentedControl.helpers.ts - Style calculation functions
+ * @see SegmentedControl.a11y.ts - Accessibility props
+ *
+ * @example
+ * // Basic usage
+ * <SegmentedControl
+ *   options={[
+ *     { value: "day", label: "Day" },
+ *     { value: "week", label: "Week" },
+ *     { value: "month", label: "Month" },
+ *   ]}
+ *   selectedValue={view}
+ *   onValueChange={setView}
+ * />
+ *
+ * @example
+ * // Different sizes and variants
+ * <SegmentedControl
+ *   options={options}
+ *   selectedValue={value}
+ *   onValueChange={setValue}
+ *   size="lg"
+ *   variant="filled"
+ * />
+ *
+ * @example
+ * // With margin (composable via rest props)
+ * <SegmentedControl
+ *   options={options}
+ *   selectedValue={value}
+ *   onValueChange={setValue}
+ *   marginBottom="lg"
+ * />
+ */
+
+import {
+  backgroundColor,
+  border,
+  createRestyleComponent,
+  createVariant,
+  layout,
+  spacing,
+  spacingShorthand,
+} from "@shopify/restyle";
+import React, { memo, useCallback } from "react";
+import { Pressable } from "react-native";
+import { RestyleTheme } from "../../../core/restyle";
+import { Box } from "../../layout";
+import { Text } from "../../typography";
+import { SEGMENT_TEXT_VARIANT } from "./SegmentedControl.helpers";
+import {
+  BaseSegmentedControlProps,
+  SegmentedControlProps,
+  SegmentedControlSize,
+} from "./SegmentedControl.types";
+import { useSegmentedControlLogic } from "./useSegmentedControlLogic";
+
+/**
+ * Base SegmentedControl container with Restyle variant support.
+ * @internal
+ */
+const BaseSegmentedControlContainer = createRestyleComponent<
+  BaseSegmentedControlProps,
+  RestyleTheme
+>(
+  [
+    createVariant({ themeKey: "segmentedControlVariants" }),
+    createVariant({ themeKey: "segmentedControlSizes", property: "size" }),
+    backgroundColor,
+    border,
+    layout,
+    spacing,
+    spacingShorthand,
+  ],
+  Box,
+);
+
+/**
+ * Base Segment container with Restyle variant support.
+ * @internal
+ */
+const BaseSegmentContainer = createRestyleComponent<
+  BaseSegmentedControlProps,
+  RestyleTheme
+>(
+  [
+    createVariant({
+      themeKey: "segmentedControlSegmentSizes",
+      property: "size",
+    }),
+    backgroundColor,
+    border,
+    layout,
+    spacing,
+    spacingShorthand,
+  ],
+  Box,
+);
+
+/**
+ * Base Pressable segment with Restyle support.
+ * @internal
+ */
+const BaseSegmentPressable = createRestyleComponent<
+  BaseSegmentedControlProps & { onPress?: () => void; disabled?: boolean },
+  RestyleTheme
+>([layout, spacing, spacingShorthand], Pressable);
+
+function SegmentedControlComponent({
+  options,
+  selectedValue,
+  onValueChange,
+  size = "md",
+  variant = "default",
+  disabled = false,
+  testID,
+  style,
+  ...rest
+}: SegmentedControlProps) {
+  const {
+    containerStyles,
+    getSegmentStyles,
+    getTextColor,
+    handlePress,
+    containerA11y,
+    getSegmentA11y,
+  } = useSegmentedControlLogic({
+    options,
+    selectedValue,
+    onValueChange,
+    size,
+    variant,
+    disabled,
+  });
+
+  const handleSegmentPress = useCallback(
+    (value: string, segmentDisabled?: boolean) => {
+      handlePress(value, segmentDisabled);
+    },
+    [handlePress],
+  );
+
+  return (
+    <BaseSegmentedControlContainer
+      variant={variant}
+      size={size}
+      backgroundColor={containerStyles.backgroundColor}
+      opacity={disabled ? 0.5 : 1}
+      testID={testID}
+      style={style}
+      {...containerA11y}
+      {...rest}
+    >
+      {options.map((option, index) => {
+        const isSelected = option.value === selectedValue;
+        const isDisabled = disabled || option.disabled === true;
+        const segmentStyles = getSegmentStyles(isSelected, isDisabled);
+        const textColor = getTextColor(isSelected, isDisabled);
+        const segmentA11yProps = getSegmentA11y(option, index, isSelected);
+
+        return (
+          <BaseSegmentPressable
+            key={option.value}
+            flex={1}
+            onPress={() => handleSegmentPress(option.value, option.disabled)}
+            disabled={isDisabled}
+            testID={testID ? `${testID}-segment-${option.value}` : undefined}
+            {...segmentA11yProps}
+          >
+            <BaseSegmentContainer
+              size={size}
+              backgroundColor={segmentStyles.backgroundColor}
+              borderRadius={segmentStyles.borderRadius}
+            >
+              <Text
+                variant={
+                  SEGMENT_TEXT_VARIANT[size as SegmentedControlSize] ??
+                  "labelMedium"
+                }
+                color={textColor}
+                numberOfLines={1}
+              >
+                {option.label}
+              </Text>
+            </BaseSegmentContainer>
+          </BaseSegmentPressable>
+        );
+      })}
+    </BaseSegmentedControlContainer>
+  );
+}
+
+export const SegmentedControl = memo(SegmentedControlComponent);
+SegmentedControl.displayName = "SegmentedControl";

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

@@ -0,0 +1,187 @@
+/**
+ * SegmentedControl Component Types
+ *
+ * Type definitions for the SegmentedControl component and its related hooks/helpers.
+ * All types are explicitly exported for external consumption.
+ *
+ * @see SegmentedControl.tsx - Component implementation
+ */
+
+import {
+  BoxProps,
+  ResponsiveValue,
+  VariantProps,
+} from "@shopify/restyle";
+import { StyleProp, ViewProps, ViewStyle } from "react-native";
+import { RestyleTheme } from "../../../core/restyle";
+
+// =============================================================================
+// VARIANT TYPES
+// =============================================================================
+
+/**
+ * Segment option configuration.
+ */
+export interface SegmentOption {
+  /** Unique identifier for the segment */
+  value: string;
+  /** Display label for the segment */
+  label: string;
+  /** Optional icon name to display */
+  icon?: string;
+  /** Whether this segment is disabled */
+  disabled?: boolean;
+}
+
+/**
+ * Size preset for the SegmentedControl component.
+ *
+ * - `sm`: 36px height - Compact filters, dense UIs
+ * - `md`: 44px height - Standard control (default)
+ * - `lg`: 52px height - Prominent controls, tablets
+ */
+export type SegmentedControlSize = Exclude<
+  keyof RestyleTheme["segmentedControlSizes"],
+  "defaults"
+>;
+
+/**
+ * Visual variant for the SegmentedControl component.
+ *
+ * - `default`: Neutral background, white selected segment
+ * - `outline`: Bordered container, primary color selected
+ */
+export type SegmentedControlVariant = Exclude<
+  keyof RestyleTheme["segmentedControlVariants"],
+  "defaults"
+>;
+
+// =============================================================================
+// RESTYLE PROP TYPES
+// =============================================================================
+
+type SegmentedControlVariantProps = VariantProps<
+  RestyleTheme,
+  "segmentedControlVariants"
+>;
+type SegmentedControlSizeProps = VariantProps<
+  RestyleTheme,
+  "segmentedControlSizes",
+  "size"
+>;
+
+/** Base props combining Restyle Box props with ViewProps and variant props */
+export type BaseSegmentedControlProps = SegmentedControlVariantProps &
+  SegmentedControlSizeProps &
+  BoxProps<RestyleTheme> &
+  ViewProps;
+
+// =============================================================================
+// COMPONENT PROPS
+// =============================================================================
+
+/**
+ * Props for SegmentedControl component.
+ *
+ * @example
+ * // Basic usage
+ * <SegmentedControl
+ *   options={[
+ *     { value: "day", label: "Day" },
+ *     { value: "week", label: "Week" },
+ *   ]}
+ *   selectedValue={view}
+ *   onValueChange={setView}
+ * />
+ *
+ * @example
+ * // With different size and variant
+ * <SegmentedControl
+ *   options={options}
+ *   selectedValue={value}
+ *   onValueChange={setValue}
+ *   size="lg"
+ *   variant="outline"
+ * />
+ *
+ * @example
+ * // With spacing props (composable)
+ * <SegmentedControl
+ *   options={options}
+ *   selectedValue={value}
+ *   onValueChange={setValue}
+ *   marginBottom="lg"
+ * />
+ */
+export interface SegmentedControlProps
+  extends Omit<BaseSegmentedControlProps, "variant"> {
+  /** Array of segment options */
+  options: SegmentOption[];
+  /** Currently selected value */
+  selectedValue: string;
+  /** Callback when selection changes */
+  onValueChange: (value: string) => void;
+  /** Size variant (supports responsive values) */
+  size?: ResponsiveValue<SegmentedControlSize, RestyleTheme["breakpoints"]>;
+  /** Visual variant (supports responsive values) */
+  variant?: ResponsiveValue<SegmentedControlVariant, RestyleTheme["breakpoints"]>;
+  /** Whether the entire control is disabled */
+  disabled?: boolean;
+  /** Test ID for testing */
+  testID?: string;
+  /** Custom style overrides */
+  style?: StyleProp<ViewStyle>;
+}
+
+// =============================================================================
+// HOOK TYPES
+// =============================================================================
+
+/**
+ * Props passed to the logic hook.
+ */
+export interface UseSegmentedControlLogicProps {
+  options: SegmentOption[];
+  selectedValue: string;
+  onValueChange: (value: string) => void;
+  size: ResponsiveValue<SegmentedControlSize, RestyleTheme["breakpoints"]>;
+  variant: ResponsiveValue<SegmentedControlVariant, RestyleTheme["breakpoints"]>;
+  disabled: boolean;
+}
+
+/**
+ * Return type for useSegmentedControlLogic hook.
+ */
+export interface UseSegmentedControlLogicReturn {
+  /** Computed container styles */
+  containerStyles: {
+    backgroundColor: keyof RestyleTheme["colors"];
+    borderRadius: keyof RestyleTheme["borderRadii"];
+    padding: keyof RestyleTheme["spacing"];
+  };
+  /** Computed segment styles based on selection state */
+  getSegmentStyles: (
+    isSelected: boolean,
+    isDisabled: boolean
+  ) => {
+    backgroundColor: keyof RestyleTheme["colors"];
+    borderRadius: keyof RestyleTheme["borderRadii"];
+    paddingVertical: keyof RestyleTheme["spacing"];
+    paddingHorizontal: keyof RestyleTheme["spacing"];
+  };
+  /** Computed text color based on selection state */
+  getTextColor: (
+    isSelected: boolean,
+    isDisabled: boolean
+  ) => keyof RestyleTheme["colors"];
+  /** Handle segment press */
+  handlePress: (value: string, disabled?: boolean) => void;
+  /** Accessibility props for container */
+  containerA11y: Record<string, unknown>;
+  /** Get accessibility props for a segment */
+  getSegmentA11y: (
+    option: SegmentOption,
+    index: number,
+    isSelected: boolean
+  ) => Record<string, unknown>;
+}

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

@@ -0,0 +1,39 @@
+/**
+ * SegmentedControl Component
+ *
+ * @description Toggle control for switching between multiple options
+ *
+ * @example
+ * import { SegmentedControl } from "@/design-system";
+ *
+ * <SegmentedControl
+ *   options={[
+ *     { value: "day", label: "Day" },
+ *     { value: "week", label: "Week" },
+ *   ]}
+ *   selectedValue={view}
+ *   onValueChange={setView}
+ * />
+ */
+
+export { SegmentedControl } from "./SegmentedControl";
+export type {
+  BaseSegmentedControlProps,
+  SegmentedControlProps,
+  SegmentedControlSize,
+  SegmentedControlVariant,
+  SegmentOption,
+  UseSegmentedControlLogicProps,
+  UseSegmentedControlLogicReturn,
+} from "./SegmentedControl.types";
+export { useSegmentedControlLogic } from "./useSegmentedControlLogic";
+export {
+  getContainerStyles,
+  getSegmentStyles,
+  getTextColor,
+  validateOptions,
+} from "./SegmentedControl.helpers";
+export {
+  getSegmentA11y,
+  getSegmentedControlContainerA11y,
+} from "./SegmentedControl.a11y";

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

@@ -0,0 +1,151 @@
+import { useDesignSystem } from "../../../provider";
+import { useResponsiveProp } from "@shopify/restyle";
+import { useCallback, useMemo } from "react";
+import {
+  getSegmentA11y,
+  getSegmentedControlContainerA11y,
+} from "./SegmentedControl.a11y";
+import {
+  getContainerStyles,
+  getSegmentStyles as getSegmentStylesHelper,
+  getTextColor as getTextColorHelper,
+} from "./SegmentedControl.helpers";
+import type {
+  SegmentedControlSize,
+  SegmentedControlVariant,
+  SegmentOption,
+  UseSegmentedControlLogicProps,
+  UseSegmentedControlLogicReturn,
+} from "./SegmentedControl.types";
+
+/**
+ * Orchestrates SegmentedControl rendering logic and state management.
+ *
+ * Handles:
+ * - Responsive size and variant resolution
+ * - Container style calculation
+ * - Segment style computation based on selection state
+ * - Text color determination per segment
+ * - Press handling with disabled state check
+ * - Accessibility props for container and individual segments
+ *
+ * @param props - Configuration object for segmented control behavior
+ * @param props.options - Array of segment options with values and labels
+ * @param props.selectedValue - Currently selected segment value
+ * @param props.onValueChange - Callback when selection changes
+ * @param props.size - Size variant ('sm' | 'md' | 'lg')
+ * @param props.variant - Visual variant ('default' | 'emphasized')
+ * @param props.disabled - Whether entire control is disabled
+ *
+ * @returns Computed values for rendering SegmentedControl
+ * @returns {object} containerStyles - Container style configuration
+ * @returns {function} getSegmentStyles - Returns styles for a segment
+ * @returns {function} getTextColor - Returns text color for a segment
+ * @returns {function} handlePress - Press handler for segments
+ * @returns {object} containerA11y - Container accessibility props
+ * @returns {function} getSegmentA11y - Returns a11y props for a segment
+ *
+ * @performance This hook uses useMemo() and useCallback() for optimization
+ *
+ * @example
+ * const {
+ *   containerStyles,
+ *   getSegmentStyles,
+ *   getTextColor,
+ *   handlePress,
+ *   getSegmentA11y
+ * } = useSegmentedControlLogic({
+ *   options: [
+ *     { value: "day", label: "Day" },
+ *     { value: "week", label: "Week" },
+ *     { value: "month", label: "Month" }
+ *   ],
+ *   selectedValue: "week",
+ *   onValueChange: setValue,
+ *   size: "md",
+ * });
+ */
+export function useSegmentedControlLogic({
+  options,
+  selectedValue,
+  onValueChange,
+  size,
+  variant,
+  disabled,
+}: UseSegmentedControlLogicProps): UseSegmentedControlLogicReturn {
+  const { labels: t } = useDesignSystem();
+  const resolvedSize = (useResponsiveProp(size) ?? "md") as SegmentedControlSize;
+  const resolvedVariant = (useResponsiveProp(variant) ?? "default") as SegmentedControlVariant;
+
+  // Memoize container styles
+  const containerStyles = getContainerStyles(resolvedSize, resolvedVariant);
+
+  // Memoize i18n params for container a11y
+  const containerI18n = useMemo(
+    () => ({
+      containerLabel: t.designSystem.segmentedControl.containerLabel,
+      optionsLabel: t.designSystem.segmentedControl.options,
+    }),
+    [t],
+  );
+
+  // Memoize container accessibility
+  const containerA11y = getSegmentedControlContainerA11y(options.length, containerI18n);
+
+  // Memoize i18n params for segment a11y
+  const segmentI18n = useMemo(
+    () => ({
+      selectedLabel: t.designSystem.segmentedControl.selected,
+      currentlySelectedHint: t.designSystem.segmentedControl.currentlySelected,
+      doubleTapToSelectHint: t.designSystem.segmentedControl.doubleTapToSelect,
+      ofLabel: t.designSystem.segmentedControl.of,
+    }),
+    [t],
+  );
+
+  // Get segment styles based on selection state
+  const getSegmentStyles = useCallback(
+    (isSelected: boolean, isDisabled: boolean) =>
+      getSegmentStylesHelper(
+        resolvedSize,
+        resolvedVariant,
+        isSelected,
+        isDisabled,
+      ),
+    [resolvedSize, resolvedVariant],
+  );
+
+  // Get text color based on selection state
+  const getTextColor = useCallback(
+    (isSelected: boolean, isDisabled: boolean) =>
+      getTextColorHelper(resolvedVariant, isSelected, isDisabled),
+    [resolvedVariant],
+  );
+
+  // Handle segment press
+  const handlePress = useCallback(
+    (value: string, segmentDisabled?: boolean) => {
+      if (disabled || segmentDisabled || value === selectedValue) {
+        return;
+      }
+      onValueChange(value);
+    },
+    [disabled, selectedValue, onValueChange],
+  );
+
+  // Get accessibility props for a segment
+  const getSegmentA11yProps = useCallback(
+    (option: SegmentOption, index: number, isSelected: boolean) =>
+      getSegmentA11y(option, index, options.length, isSelected, segmentI18n),
+    [options.length, segmentI18n],
+  );
+
+  return {
+    containerStyles,
+    getSegmentStyles,
+    getTextColor,
+    handlePress,
+    containerA11y,
+    getSegmentA11y: getSegmentA11yProps,
+  };
+}