@praxiis/ui 0.0.1

package/src/primitives/layout/ScrollView.tsx

@@ -0,0 +1,63 @@
+import React, { forwardRef } from "react";
+import {
+  ScrollView as RNScrollView,
+  ScrollViewProps as RNScrollViewProps,
+} from "react-native";
+import {
+  backgroundColor,
+  BackgroundColorProps,
+  composeRestyleFunctions,
+  layout,
+  LayoutProps,
+  spacing,
+  SpacingProps,
+  useRestyle,
+} from "@shopify/restyle";
+import { RestyleTheme } from "../../core/restyle";
+
+/**
+ * Restyle props that can be applied to ScrollView
+ */
+export type ScrollViewRestyleProps = SpacingProps<RestyleTheme> &
+  LayoutProps<RestyleTheme> &
+  BackgroundColorProps<RestyleTheme>;
+
+export type ScrollViewProps = ScrollViewRestyleProps & RNScrollViewProps;
+
+/** Ref type for the ScrollView component — the underlying React Native ScrollView instance. */
+export type ScrollViewRef = RNScrollView;
+
+const restyleFunctions = composeRestyleFunctions<
+  RestyleTheme,
+  ScrollViewRestyleProps
+>([spacing, layout, backgroundColor]);
+
+/**
+ * ScrollView — Restyled ScrollView component
+ *
+ * A ScrollView wrapper that accepts Restyle props (padding, margin, flex, backgroundColor)
+ * while preserving all native ScrollView functionality and supporting ref forwarding.
+ *
+ * @example
+ * ```tsx
+ * <ScrollView
+ *   ref={scrollRef}
+ *   horizontal
+ *   paddingHorizontal="md"
+ *   showsHorizontalScrollIndicator={false}
+ *   contentContainerStyle={{ gap: 8 }}
+ * >
+ *   {items.map((item) => (
+ *     <Chip key={item.id} label={item.name} />
+ *   ))}
+ * </ScrollView>
+ * ```
+ */
+export const ScrollView = forwardRef<RNScrollView, ScrollViewProps>(
+  function ScrollView(props, ref) {
+    const { style, ...rest } = useRestyle(restyleFunctions, props);
+    return <RNScrollView ref={ref} style={style} {...rest} />;
+  },
+);
+
+ScrollView.displayName = "ScrollView";

package/src/primitives/layout/Stack.tsx

@@ -0,0 +1,69 @@
+/**
+ * HStack / VStack Components
+ *
+ * @description Convenience layout primitives for flex-based stacking - Atom
+ *
+ * Thin wrappers around Box that set sensible flexDirection defaults,
+ * eliminating the most common Box boilerplate in consumer code.
+ *
+ * ## Components
+ * | Component | Direction | Use Case |
+ * |-----------|-----------|----------|
+ * | HStack    | row       | Toolbars, inline groups |
+ * | VStack    | column    | Vertical lists, form fields |
+ *
+ * All Box/Restyle props are forwarded — spacing, colors, borders, etc.
+ * For edge cases like `row-reverse`, use `Box` directly.
+ *
+ * @example
+ * // Vertical stack with gap
+ * <VStack gap="md" padding="lg">
+ *   <Text>First</Text>
+ *   <Text>Second</Text>
+ * </VStack>
+ *
+ * @example
+ * // Horizontal stack centered
+ * <HStack gap="sm" alignItems="center">
+ *   <Icon name="check" />
+ *   <Text>Confirmed</Text>
+ * </HStack>
+ */
+
+import React, { memo } from "react";
+import { Box, BoxRestyleProps } from "./Box";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type HStackProps = BoxRestyleProps;
+export type VStackProps = BoxRestyleProps;
+
+// ---------------------------------------------------------------------------
+// Components
+// ---------------------------------------------------------------------------
+
+/**
+ * Horizontal stack (row direction). All Box props forwarded.
+ */
+function HStackComponent({ style, ...rest }: HStackProps) {
+  return <Box flexDirection="row" style={style} {...rest} />;
+}
+
+/**
+ * Vertical stack (column direction). All Box props forwarded.
+ */
+function VStackComponent({ style, ...rest }: VStackProps) {
+  return <Box flexDirection="column" style={style} {...rest} />;
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+export const HStack = memo(HStackComponent);
+HStack.displayName = "HStack";
+
+export const VStack = memo(VStackComponent);
+VStack.displayName = "VStack";

package/src/primitives/layout/index.ts

@@ -0,0 +1,40 @@
+/**
+ * Layout Components Module
+ *
+ * Components that structure and organize space.
+ *
+ * Note: Box and AnimatedBox are core primitives — import from "@/design-system/core".
+ */
+
+export * from "./AnimatedBox";
+export * from "./Box";
+export * from "./Stack";
+
+export {
+  Divider,
+  type DividerColor,
+  type DividerOrientation,
+  type DividerProps,
+  type DividerSpacing,
+  type DividerThickness,
+} from "./Divider";
+
+export {
+  FlatList,
+  type FlatListProps,
+  type FlatListRef,
+  type FlatListRestyleProps,
+} from "./FlatList";
+
+export {
+  Pressable,
+  type PressableProps,
+  type PressableRestyleProps,
+} from "./Pressable";
+
+export {
+  ScrollView,
+  type ScrollViewProps,
+  type ScrollViewRef,
+  type ScrollViewRestyleProps,
+} from "./ScrollView";

package/src/primitives/navigation/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Navigation Components Module
+ *
+ * Components that orient the user within the app.
+ */
+

package/src/primitives/overlays/Modal/Modal.helpers.ts

@@ -0,0 +1,31 @@
+/**
+ * Modal Helper Functions
+ *
+ * Pure utility functions for Modal component.
+ * All values derived from tokens/scales.ts for consistency.
+ *
+ * @see tokens/scales.ts - MODAL_LAYOUT
+ */
+
+import type { ModalPosition } from "./Modal.types";
+
+// =============================================================================
+// ANIMATION HELPERS
+// =============================================================================
+
+/**
+ * Get the animation type based on modal position.
+ *
+ * - center: fade (standard dialog)
+ * - top: slide (slides down from top)
+ * - bottom: slide (slides up from bottom)
+ *
+ * @param position - Modal position
+ * @returns RN Modal animationType
+ */
+export function getAnimationType(
+  position: ModalPosition
+): "fade" | "slide" | "none" {
+  if (position === "center") return "fade";
+  return "slide";
+}

package/src/primitives/overlays/Modal/Modal.tsx

@@ -0,0 +1,264 @@
+/**
+ * Modal Component
+ *
+ * @description Dialog overlay for focused user interactions - Molecule
+ *
+ * Modal presents content in a focused overlay that requires user attention.
+ * Supports multiple positions (center, top, bottom) with appropriate
+ * animations and safe area handling.
+ *
+ * ## 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
+ * - Three position variants with matching animations
+ * - Optional title and close button header
+ * - Primary and secondary action buttons in footer
+ * - Backdrop press to dismiss
+ * - Safe area aware (status bar + home indicator)
+ * - Full accessibility support (dialog role)
+ * - Memoized for performance
+ *
+ * @see Modal.types.ts - Type definitions
+ * @see Modal.helpers.ts - Animation type resolution
+ * @see Modal.a11y.ts - Accessibility prop generation
+ * @see tokens/scales.ts - MODAL_LAYOUT
+ *
+ * @example
+ * // Basic usage
+ * <Modal visible={isOpen} onClose={handleClose} title="Confirm">
+ *   <Text>Are you sure?</Text>
+ * </Modal>
+ *
+ * @example
+ * // With actions
+ * <Modal
+ *   visible={isOpen}
+ *   onClose={handleClose}
+ *   title="Delete Item"
+ *   position="center"
+ *   primaryAction={{ label: "Delete", onPress: handleDelete }}
+ *   secondaryAction={{ label: "Cancel", onPress: handleClose }}
+ *   accessibilityLabel="Delete confirmation dialog"
+ * />
+ *
+ * @example
+ * // Bottom sheet style
+ * <Modal
+ *   visible={isOpen}
+ *   onClose={handleClose}
+ *   title="Options"
+ *   position="bottom"
+ * >
+ *   <Button title="Share" onPress={handleShare} />
+ *   <Button title="Edit" onPress={handleEdit} />
+ * </Modal>
+ */
+
+import React, { memo } from "react";
+import { Pressable, Modal as RNModal, StyleSheet } from "react-native";
+import { useSafeAreaInsets } from "react-native-safe-area-context";
+import { MODAL_LAYOUT } from "../../../tokens/scales";
+import { Button } from "../../actions/Button";
+import { IconButton } from "../../actions/IconButton";
+import { Box } from "../../layout";
+import { Text } from "../../typography";
+import type { ModalProps } from "./Modal.types";
+import { useModalLogic } from "./useModalLogic";
+
+// =============================================================================
+// COMPONENT IMPLEMENTATION
+// =============================================================================
+
+function ModalComponent({
+  visible,
+  onClose,
+  children,
+  title,
+  position = "center",
+  closeOnBackdropPress = true,
+  showCloseButton = true,
+  primaryAction,
+  secondaryAction,
+  testID,
+  accessibilityLabel,
+}: ModalProps) {
+  const insets = useSafeAreaInsets();
+
+  const { handleBackdropPress, animationType, a11yProps, closeButtonA11yProps } = useModalLogic({
+    visible,
+    onClose,
+    title,
+    position,
+    closeOnBackdropPress,
+    showCloseButton,
+    accessibilityLabel,
+  });
+
+  // Safe area aware container padding — modal floats inside safe areas
+  const containerPadding = {
+    paddingTop:
+      position === "top"
+        ? insets.top + MODAL_LAYOUT.horizontalMargin
+        : position === "center"
+          ? MODAL_LAYOUT.horizontalMargin
+          : MODAL_LAYOUT.horizontalMargin,
+    paddingBottom:
+      position === "bottom"
+        ? insets.bottom + MODAL_LAYOUT.horizontalMargin
+        : position === "center"
+          ? MODAL_LAYOUT.horizontalMargin
+          : MODAL_LAYOUT.horizontalMargin,
+    paddingHorizontal: MODAL_LAYOUT.horizontalMargin,
+  };
+
+  const containerStyle =
+    position === "bottom"
+      ? styles.bottomContainer
+      : position === "top"
+        ? styles.topContainer
+        : styles.centerContainer;
+
+  const hasFooter = !!primaryAction || !!secondaryAction;
+  const hasHeader = !!title || showCloseButton;
+
+  return (
+    <RNModal
+      visible={visible}
+      transparent
+      animationType={animationType}
+      onRequestClose={onClose}
+      statusBarTranslucent
+    >
+      <Pressable
+        style={[styles.overlay, containerStyle, containerPadding]}
+        onPress={handleBackdropPress}
+      >
+        <Pressable style={styles.sheet} onPress={(e) => e.stopPropagation()}>
+          <Box
+            testID={testID}
+            backgroundColor="surfaceElevated"
+            borderRadius="xl"
+            overflow="hidden"
+            {...a11yProps}
+          >
+            {/* Header */}
+            {hasHeader && (
+              <Box
+                flexDirection="row"
+                alignItems="center"
+                justifyContent="space-between"
+                paddingHorizontal="lg"
+                paddingVertical="md"
+                borderBottomWidth={1}
+                borderBottomColor="borderSubtle"
+              >
+                {title ? (
+                  <Box flex={1} marginRight={showCloseButton ? "sm" : "none"}>
+                    <Text variant="headingSmall">{title}</Text>
+                  </Box>
+                ) : (
+                  <Box flex={1} />
+                )}
+                {showCloseButton && (
+                  <IconButton
+                    iconName="close"
+                    variant="ghost"
+                    size="sm"
+                    onPress={onClose}
+                    accessibilityLabel={closeButtonA11yProps.accessibilityLabel}
+                    accessibilityHint={closeButtonA11yProps.accessibilityHint}
+                  />
+                )}
+              </Box>
+            )}
+
+            {/* Body (children) */}
+            <Box paddingHorizontal="lg" paddingVertical="md">
+              {children}
+            </Box>
+
+            {/* Footer */}
+            {hasFooter && (
+              <Box
+                paddingHorizontal="lg"
+                paddingVertical="md"
+                borderTopWidth={1}
+                borderTopColor="borderSubtle"
+                flexDirection="row"
+                justifyContent="flex-end"
+                gap="sm"
+              >
+                {secondaryAction && (
+                  <Button
+                    title={secondaryAction.label}
+                    variant="outline"
+                    size="md"
+                    onPress={secondaryAction.onPress}
+                    isLoading={secondaryAction.loading}
+                    disabled={secondaryAction.disabled}
+                    testID={testID ? `${testID}-secondary-action` : undefined}
+                  />
+                )}
+                {primaryAction && (
+                  <Button
+                    title={primaryAction.label}
+                    variant="solid"
+                    size="md"
+                    onPress={primaryAction.onPress}
+                    isLoading={primaryAction.loading}
+                    disabled={primaryAction.disabled}
+                    testID={testID ? `${testID}-primary-action` : undefined}
+                  />
+                )}
+              </Box>
+            )}
+          </Box>
+        </Pressable>
+      </Pressable>
+    </RNModal>
+  );
+}
+
+// =============================================================================
+// STYLES (POSITIONING ONLY - COLORS FROM THEME)
+// =============================================================================
+
+const styles = StyleSheet.create({
+  overlay: {
+    flex: 1,
+    backgroundColor: `rgba(0, 0, 0, ${MODAL_LAYOUT.overlayOpacity})`,
+  },
+  centerContainer: {
+    justifyContent: "center",
+    alignItems: "center",
+  },
+  topContainer: {
+    justifyContent: "flex-start",
+    alignItems: "center",
+  },
+  bottomContainer: {
+    justifyContent: "flex-end",
+    alignItems: "center",
+  },
+  sheet: {
+    width: "100%",
+    maxWidth: MODAL_LAYOUT.tabletMaxWidth,
+    alignItems: "stretch",
+  },
+});
+
+// =============================================================================
+// EXPORTS
+// =============================================================================
+
+export const Modal = memo(ModalComponent);
+Modal.displayName = "Modal";

package/src/primitives/overlays/Modal/Modal.types.ts

@@ -0,0 +1,193 @@
+/**
+ * Modal Component Types
+ *
+ * Type definitions for the Modal dialog overlay component.
+ *
+ * Width behavior:
+ * - Phone: Full width minus lg (16px) horizontal padding on each side
+ * - Tablet (≥768px): Capped at 480px max-width (phone-like experience)
+ *
+ * @see tokens/scales.ts - MODAL_LAYOUT
+ */
+
+import type { ReactNode } from "react";
+import type { AccessibilityProps } from "react-native";
+
+// =============================================================================
+// VARIANT TYPES (Explicitly exported for external use)
+// =============================================================================
+
+/**
+ * Modal position controlling vertical placement.
+ *
+ * - `center`: Centered vertically (default, standard dialog)
+ * - `top`: Anchored to top of screen (notifications, alerts)
+ * - `bottom`: Anchored to bottom of screen (action sheets)
+ */
+export type ModalPosition = "center" | "top" | "bottom";
+
+// =============================================================================
+// ACTION TYPES
+// =============================================================================
+
+/**
+ * Action button configuration for modal footer.
+ */
+export interface ModalAction {
+  /** Button label text */
+  label: string;
+  /** Press handler */
+  onPress: () => void;
+  /** Whether the action is in a loading state */
+  loading?: boolean;
+  /** Whether the action is disabled */
+  disabled?: boolean;
+}
+
+// =============================================================================
+// COMPONENT PROPS
+// =============================================================================
+
+/**
+ * Modal component props.
+ *
+ * @example
+ * ```tsx
+ * <Modal
+ *   visible={isVisible}
+ *   onClose={handleClose}
+ *   title="Confirm Action"
+ *   position="center"
+ * >
+ *   <Text>Are you sure you want to proceed?</Text>
+ * </Modal>
+ * ```
+ */
+export interface ModalProps {
+  // -------------------------------------------------------------------------
+  // Required Props
+  // -------------------------------------------------------------------------
+
+  /** Whether the modal is visible */
+  visible: boolean;
+  /** Callback when modal should close */
+  onClose: () => void;
+  /** Modal content */
+  children: ReactNode;
+
+  // -------------------------------------------------------------------------
+  // Content Props
+  // -------------------------------------------------------------------------
+
+  /** Modal title displayed in the header */
+  title?: string;
+
+  // -------------------------------------------------------------------------
+  // Position Props
+  // -------------------------------------------------------------------------
+
+  /**
+   * Vertical position of the modal
+   * @default "center"
+   */
+  position?: ModalPosition;
+
+  // -------------------------------------------------------------------------
+  // Behavior Props
+  // -------------------------------------------------------------------------
+
+  /**
+   * Whether tapping the backdrop closes the modal
+   * @default true
+   */
+  closeOnBackdropPress?: boolean;
+
+  /**
+   * Whether to show the close button in the header
+   * @default true
+   */
+  showCloseButton?: boolean;
+
+  // -------------------------------------------------------------------------
+  // Action Props
+  // -------------------------------------------------------------------------
+
+  /** Primary action button (e.g., "Confirm", "Save") */
+  primaryAction?: ModalAction;
+  /** Secondary action button (e.g., "Cancel") */
+  secondaryAction?: ModalAction;
+
+  // -------------------------------------------------------------------------
+  // Accessibility Props
+  // -------------------------------------------------------------------------
+
+  /** Test ID for testing */
+  testID?: string;
+  /** Accessibility label override */
+  accessibilityLabel?: string;
+}
+
+// =============================================================================
+// INTERNAL TYPES
+// =============================================================================
+
+/**
+ * Parameters for useModalLogic hook.
+ */
+export interface UseModalLogicParams {
+  visible: boolean;
+  onClose: () => void;
+  title?: string;
+  position: ModalPosition;
+  closeOnBackdropPress: boolean;
+  showCloseButton: boolean;
+  accessibilityLabel?: string;
+}
+
+/**
+ * Return value from useModalLogic hook.
+ */
+export interface UseModalLogicReturn {
+  /** Handler for backdrop press */
+  handleBackdropPress: () => void;
+  /** Animation type for the RN Modal */
+  animationType: "fade" | "slide" | "none";
+  /** Accessibility props for the modal container */
+  a11yProps: AccessibilityProps;
+  /** Accessibility props for the close button */
+  closeButtonA11yProps: {
+    accessible: true;
+    accessibilityRole: "button";
+    accessibilityLabel: string;
+    accessibilityHint: string;
+  };
+}
+
+/**
+ * Parameters for getModalA11y function.
+ */
+export interface ModalA11yParams {
+  title?: string;
+  position: ModalPosition;
+  accessibilityLabel?: string;
+  fallbackTitle: string;
+  positionLabels: { bottom: string; top: string; center: string };
+}
+
+/**
+ * Parameters for getModalCloseButtonA11yProps function.
+ */
+export interface ModalCloseButtonA11yParams {
+  closeLabel: string;
+  closeHint: string;
+}
+
+/**
+ * Accessibility props returned by getModalA11y.
+ */
+export interface ModalA11yProps {
+  accessible: true;
+  accessibilityRole: "none";
+  accessibilityLabel: string;
+  accessibilityViewIsModal: true;
+}