@praxiis/ui 0.0.1

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

@@ -0,0 +1,43 @@
+/**
+ * Modal Component
+ *
+ * Barrel export for the Modal dialog overlay component and related types.
+ *
+ * @example
+ * ```tsx
+ * import { Modal, type ModalProps, type ModalSize } from '@/design-system/primitives/overlays/Modal';
+ *
+ * <Modal
+ *   visible={isVisible}
+ *   onClose={handleClose}
+ *   title="Confirm Action"
+ *   position="center"
+ *   size="md"
+ *   primaryAction={{ label: "Confirm", onPress: handleConfirm }}
+ * >
+ *   <Text>Are you sure?</Text>
+ * </Modal>
+ * ```
+ */
+
+export { Modal } from "./Modal";
+export { useModalLogic } from "./useModalLogic";
+
+export type {
+  ModalProps,
+  ModalPosition,
+  ModalAction,
+  ModalA11yParams,
+  ModalA11yProps,
+  UseModalLogicParams,
+  UseModalLogicReturn,
+} from "./Modal.types";
+
+export {
+  getAnimationType,
+} from "./Modal.helpers";
+
+export {
+  getModalA11y,
+  getModalCloseButtonA11yProps,
+} from "./Modal.a11y";

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

@@ -0,0 +1,103 @@
+/**
+ * Modal Logic Hook
+ *
+ * Extracts all computational logic from the Modal component.
+ * Returns memoized values for optimal render performance.
+ *
+ * Responsibilities:
+ * - Determine animation type
+ * - Handle backdrop press behavior
+ * - Generate accessibility props
+ *
+ * The component (Modal.tsx) is a "dumb view" that only renders
+ * the pre-computed values from this hook.
+ *
+ * @see Modal.tsx - Component consuming this hook
+ * @see Modal.helpers.ts - Pure calculation functions
+ */
+
+import { useCallback, useMemo } from "react";
+
+import { useDesignSystem } from "../../../provider";
+import { getModalA11y, getModalCloseButtonA11yProps } from "./Modal.a11y";
+import { getAnimationType } from "./Modal.helpers";
+import type { UseModalLogicParams, UseModalLogicReturn } from "./Modal.types";
+
+/**
+ * Orchestrates Modal rendering logic and state management.
+ * 
+ * Handles:
+ * - Animation type determination based on position
+ * - Backdrop press handling with configurable behavior
+ * - Accessibility props generation with modal role
+ * 
+ * @param params - Configuration object for modal behavior
+ * @param params.onClose - Callback when modal should close
+ * @param params.title - Modal title text
+ * @param params.position - Modal position ('center' | 'bottom')
+ * @param params.closeOnBackdropPress - Whether to close on backdrop press
+ * @param params.accessibilityLabel - Custom a11y label
+ * 
+ * @returns Computed values for rendering Modal
+ * @returns {function} handleBackdropPress - Backdrop press handler
+ * @returns {string} animationType - RN Modal animation type
+ * @returns {object} a11yProps - Accessibility props with modal role
+ * 
+ * @performance This hook uses useMemo() and useCallback() for optimization
+ * 
+ * @example
+ * const { handleBackdropPress, animationType, a11yProps } = useModalLogic({
+ *   onClose: () => setVisible(false),
+ *   title: "Confirm Action",
+ *   position: "center",
+ *   closeOnBackdropPress: true,
+ * });
+ */
+export function useModalLogic({
+  onClose,
+  title,
+  position,
+  closeOnBackdropPress,
+  accessibilityLabel,
+}: UseModalLogicParams): UseModalLogicReturn {
+  const { labels: t } = useDesignSystem();
+  const animationType = getAnimationType(position);
+
+  const handleBackdropPress = useCallback(() => {
+    if (closeOnBackdropPress) {
+      onClose();
+    }
+  }, [closeOnBackdropPress, onClose]);
+
+  const positionLabels = useMemo(() => ({
+    bottom: t.designSystem.modal.positionBottom,
+    top: t.designSystem.modal.positionTop,
+    center: t.designSystem.modal.positionCenter,
+  }), [t]);
+
+  const a11yProps = useMemo(
+    () => getModalA11y({
+      title,
+      position,
+      accessibilityLabel,
+      fallbackTitle: t.designSystem.modal.fallbackTitle,
+      positionLabels,
+    }),
+    [title, position, accessibilityLabel, t, positionLabels]
+  );
+
+  const closeButtonA11yProps = useMemo(
+    () => getModalCloseButtonA11yProps({
+      closeLabel: t.designSystem.modal.closeLabel,
+      closeHint: t.designSystem.modal.closeHint,
+    }),
+    [t]
+  );
+
+  return {
+    handleBackdropPress,
+    animationType,
+    a11yProps,
+    closeButtonA11yProps,
+  };
+}

package/src/primitives/overlays/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Overlays Module
+ *
+ * Barrel export for overlay components (Modal, Sheet, etc.).
+ */
+
+export {
+  Modal,
+  type ModalProps,
+  type ModalPosition,
+  type ModalAction,
+} from "./Modal";

package/src/primitives/typography/Text.tsx

@@ -0,0 +1,51 @@
+/**
+ * Text Component
+ *
+ * @description Text primitive with Restyle typography integration - Atom
+ *
+ * Text is the base text component with access to all theme
+ * typography variants and color tokens.
+ *
+ * ## Typography Variants
+ * | Variant       | Size | Weight   | Use Case |
+ * |---------------|------|----------|----------|
+ * | displayLarge  | 48px | Bold     | Hero sections |
+ * | displayMedium | 36px | Bold     | Page titles |
+ * | displaySmall  | 30px | Bold     | Section headers |
+ * | headingLarge  | 24px | Semibold | Card titles |
+ * | headingMedium | 20px | Semibold | Subsections |
+ * | headingSmall  | 17px | Semibold | List headers |
+ * | bodyLarge     | 17px | Regular  | Primary content |
+ * | bodyMedium    | 15px | Regular  | Default body |
+ * | bodySmall     | 13px | Regular  | Secondary content |
+ * | labelLarge    | 17px | Medium   | Large buttons |
+ * | labelMedium   | 15px | Medium   | Buttons, inputs |
+ * | labelSmall    | 13px | Medium   | Small buttons |
+ * | caption       | 13px | Regular  | Help text |
+ * | captionSmall  | 11px | Regular  | Timestamps |
+ * | overline      | 11px | Semibold | Section labels |
+ *
+ * @see tokens/typography.ts - Typography token definitions
+ * @see core/restyle/restyleTheme.ts - Text variant configurations
+ *
+ * @example
+ * // Basic usage
+ * <Text variant="bodyMedium">Hello World</Text>
+ *
+ * @example
+ * // With color
+ * <Text variant="headingLarge" color="accentPrimary">
+ *   Welcome
+ * </Text>
+ *
+ * @example
+ * // Responsive variant
+ * <Text variant={{ phone: "bodyMedium", tablet: "bodyLarge" }}>
+ *   Responsive text
+ * </Text>
+ */
+
+import { createText } from "@shopify/restyle";
+import { RestyleTheme } from "../../core/restyle";
+
+export const Text = createText<RestyleTheme>();

package/src/primitives/typography/index.ts

@@ -0,0 +1 @@
+export * from "./Text";

package/src/provider/DesignSystemContext.ts

@@ -0,0 +1,22 @@
+import { createContext, useContext } from "react";
+import type { DesignSystemLabels } from "../i18n";
+import { en } from "../i18n";
+
+export interface DesignSystemContextValue {
+  labels: DesignSystemLabels;
+}
+
+export const DesignSystemContext = createContext<DesignSystemContextValue>({
+  labels: en,
+});
+
+/**
+ * Access the design system context.
+ *
+ * @example
+ * const { labels } = useDesignSystem();
+ * const loadingText = labels.designSystem.button.loadingLabel;
+ */
+export function useDesignSystem(): DesignSystemContextValue {
+  return useContext(DesignSystemContext);
+}

package/src/provider/DesignSystemProvider.tsx

@@ -0,0 +1,121 @@
+/**
+ * DesignSystemProvider
+ *
+ * Single provider for the design system. Combines:
+ * - Restyle theme (light/dark based on system color scheme)
+ * - i18n labels with built-in defaults and optional overrides
+ *
+ * @example
+ * // Basic — English defaults, auto light/dark
+ * <DesignSystemProvider>
+ *   <App />
+ * </DesignSystemProvider>
+ *
+ * @example
+ * // Reactive to app language
+ * const { language } = useAppI18n();
+ * <DesignSystemProvider language={language}>
+ *   <App />
+ * </DesignSystemProvider>
+ *
+ * @example
+ * // With partial overrides on top of the active language
+ * <DesignSystemProvider language="es" overrides={{ designSystem: { button: { loadingLabel: "Guardando..." } } }}>
+ *   <App />
+ * </DesignSystemProvider>
+ *
+ * @example
+ * // With custom themes from outside the package
+ * <DesignSystemProvider lightTheme={myBrandLightTheme} darkTheme={myBrandDarkTheme}>
+ *   <App />
+ * </DesignSystemProvider>
+ */
+
+import { ThemeProvider } from "@shopify/restyle";
+import React, { ReactNode, useMemo } from "react";
+import { useColorScheme } from "react-native";
+import type { RestyleTheme } from "../core/restyle";
+import { restyleDarkTheme, restyleLightTheme } from "../core/restyle/restyleTheme";
+import { en, es } from "../i18n";
+import type { DesignSystemLabels, DesignSystemLabelsOverride } from "../i18n";
+import { DesignSystemContext } from "./DesignSystemContext";
+
+/** Languages with built-in label sets. */
+export type DesignSystemLanguage = "en" | "es";
+
+const builtInLabels: Record<DesignSystemLanguage, DesignSystemLabels> = {
+  en,
+  es,
+};
+
+export interface DesignSystemProviderProps {
+  children: ReactNode;
+  /** Active language — switches the built-in label set. Defaults to "en". */
+  language?: DesignSystemLanguage;
+  /** Partial overrides applied on top of the active language's labels. */
+  overrides?: DesignSystemLabelsOverride;
+  /**
+   * Custom light theme. When provided, replaces the built-in light theme.
+   * Must be a valid Restyle theme created with `createTheme`.
+   */
+  lightTheme?: RestyleTheme;
+  /**
+   * Custom dark theme. When provided, replaces the built-in dark theme.
+   * Must be a valid Restyle theme created with `createTheme`.
+   */
+  darkTheme?: RestyleTheme;
+}
+
+function deepMerge<T extends object>(
+  base: T,
+  overrides: Record<string, unknown> | undefined,
+): T {
+  if (!overrides) return base;
+  const result = { ...base };
+  const baseRecord = base as Record<string, unknown>;
+  for (const key of Object.keys(overrides)) {
+    const overrideVal = overrides[key];
+    if (
+      overrideVal &&
+      typeof overrideVal === "object" &&
+      !Array.isArray(overrideVal)
+    ) {
+      result[key as keyof T] = deepMerge(
+        (baseRecord[key] ?? {}) as Record<string, unknown>,
+        overrideVal as Record<string, unknown>,
+      ) as T[keyof T];
+    } else if (overrideVal !== undefined) {
+      result[key as keyof T] = overrideVal as T[keyof T];
+    }
+  }
+  return result;
+}
+
+export function DesignSystemProvider({
+  children,
+  language = "en",
+  overrides,
+  lightTheme,
+  darkTheme,
+}: DesignSystemProviderProps) {
+  const isDark = useColorScheme() === "dark";
+
+  const activeTheme = isDark
+    ? (darkTheme ?? restyleDarkTheme)
+    : (lightTheme ?? restyleLightTheme);
+
+  const labels = useMemo<DesignSystemLabels>(() => {
+    const base = builtInLabels[language] ?? en;
+    return overrides ? deepMerge(base, overrides) : base;
+  }, [language, overrides]);
+
+  const contextValue = useMemo(() => ({ labels }), [labels]);
+
+  return (
+    <DesignSystemContext.Provider value={contextValue}>
+      <ThemeProvider theme={activeTheme}>
+        {children}
+      </ThemeProvider>
+    </DesignSystemContext.Provider>
+  );
+}

package/src/provider/index.ts

@@ -0,0 +1,7 @@
+export { DesignSystemProvider } from "./DesignSystemProvider";
+export type {
+  DesignSystemLanguage,
+  DesignSystemProviderProps,
+} from "./DesignSystemProvider";
+export { useDesignSystem } from "./DesignSystemContext";
+export type { DesignSystemContextValue } from "./DesignSystemContext";

package/src/providers/ThemeProvider/createTheme.ts

@@ -0,0 +1,304 @@
+/**
+ * El Sendero Design System - Theme Factory
+ *
+ * Create custom themes by extending the base theme with overrides.
+ *
+ * @example
+ * const myTheme = createTheme(defaultTheme, {
+ *   colors: {
+ *     accent: {
+ *       primary: '#8B5CF6', // Purple accent
+ *     }
+ *   }
+ * });
+ */
+
+import { Theme, ThemeOverrides, DeepPartial } from './types';
+import { lightTheme, darkTheme } from './defaultTheme';
+
+// =============================================================================
+// DEEP MERGE UTILITY
+// =============================================================================
+
+/**
+ * Deep merge two objects, with source values overriding target
+ */
+function deepMerge<T extends object>(
+  target: T,
+  source: DeepPartial<T>
+): T {
+  const result = { ...target };
+
+  for (const key in source) {
+    if (Object.prototype.hasOwnProperty.call(source, key)) {
+      const sourceValue = source[key as keyof typeof source];
+      const targetValue = (target as Record<string, unknown>)[key];
+
+      if (
+        sourceValue !== null &&
+        typeof sourceValue === 'object' &&
+        !Array.isArray(sourceValue) &&
+        targetValue !== null &&
+        typeof targetValue === 'object' &&
+        !Array.isArray(targetValue)
+      ) {
+        result[key as keyof T] = deepMerge(
+          targetValue as Record<string, unknown>,
+          sourceValue as DeepPartial<Record<string, unknown>>
+        ) as T[keyof T];
+      } else if (sourceValue !== undefined) {
+        result[key as keyof T] = sourceValue as T[keyof T];
+      }
+    }
+  }
+
+  return result;
+}
+
+// =============================================================================
+// CREATE THEME
+// =============================================================================
+
+/**
+ * Create a custom theme by extending a base theme with overrides.
+ *
+ * @param baseTheme - The theme to extend (usually defaultTheme)
+ * @param overrides - Partial theme object with your customizations
+ * @returns A complete Theme object with your overrides applied
+ *
+ * @example
+ * // Create a sage-accented theme
+ * const sageTheme = createTheme(defaultTheme, {
+ *   name: 'Sage',
+ *   colors: {
+ *     accent: {
+ *       primary: '#6B8F6B',
+ *       primaryHover: '#557255',
+ *       primaryPressed: '#445944',
+ *     }
+ *   }
+ * });
+ *
+ * @example
+ * // Create a more rounded theme
+ * const softTheme = createTheme(defaultTheme, {
+ *   radii: {
+ *     md: 16,
+ *     lg: 24,
+ *     xl: 32,
+ *   }
+ * });
+ */
+export function createTheme(
+  baseTheme: Theme,
+  overrides: ThemeOverrides
+): Theme {
+  return deepMerge(baseTheme, overrides);
+}
+
+// =============================================================================
+// CREATE THEME PAIR
+// =============================================================================
+
+/**
+ * Create both light and dark versions of a custom theme.
+ *
+ * @param overrides - Overrides to apply to both light and dark themes
+ * @param lightOverrides - Additional overrides for light theme only
+ * @param darkOverrides - Additional overrides for dark theme only
+ * @returns Object with light and dark theme variants
+ *
+ * @example
+ * const { light, dark } = createThemePair(
+ *   { name: 'MyBrand' },
+ *   { colors: { accent: { primary: '#A68B6A' } } }, // Light-specific
+ *   { colors: { accent: { primary: '#C4A285' } } }  // Dark-specific
+ * );
+ */
+export function createThemePair(
+  overrides: ThemeOverrides = {},
+  lightOverrides: ThemeOverrides = {},
+  darkOverrides: ThemeOverrides = {}
+): { light: Theme; dark: Theme } {
+  return {
+    light: createTheme(
+      createTheme(lightTheme, overrides),
+      lightOverrides
+    ),
+    dark: createTheme(
+      createTheme(darkTheme, overrides),
+      darkOverrides
+    ),
+  };
+}
+
+// =============================================================================
+// PRESET THEMES
+// =============================================================================
+
+/**
+ * Horizon Default - Blue with a calming feel
+ */
+export const horizonTheme = createThemePair({
+  name: 'Horizon',
+});
+
+/**
+ * Sage Theme - Green-focused for hope and growth
+ */
+export const sageTheme = createThemePair(
+  { name: 'Sage' },
+  {
+    colors: {
+      accent: {
+        primary: '#6B8F6B',
+        primaryHover: '#557255',
+        primaryPressed: '#445944',
+      },
+      text: {
+        link: '#6B8F6B',
+      },
+      border: {
+        focus: '#6B8F6B',
+      },
+    },
+  },
+  {
+    colors: {
+      accent: {
+        primary: '#8FAF8F',
+        primaryHover: '#B3C7B3',
+        primaryPressed: '#6B8F6B',
+      },
+      text: {
+        link: '#8FAF8F',
+      },
+      border: {
+        focus: '#8FAF8F',
+      },
+    },
+  }
+);
+
+/**
+ * Sunset Theme - Warm coral/peach for energy and comfort
+ */
+export const sunsetTheme = createThemePair(
+  { name: 'Sunset' },
+  {
+    colors: {
+      accent: {
+        primary: '#E8836B',
+        primaryHover: '#CC6B55',
+        primaryPressed: '#A85545',
+      },
+      text: {
+        link: '#E8836B',
+      },
+      border: {
+        focus: '#E8836B',
+      },
+    },
+  },
+  {
+    colors: {
+      accent: {
+        primary: '#FF9B85',
+        primaryHover: '#FFBAA8',
+        primaryPressed: '#E8836B',
+      },
+      text: {
+        link: '#FF9B85',
+      },
+      border: {
+        focus: '#FF9B85',
+      },
+    },
+  }
+);
+
+/**
+ * Ocean Theme - Teal/cyan accents, calming water vibes
+ */
+export const oceanTheme = createThemePair(
+  {
+    colors: {
+      accent: {
+        primary: '#0E9AA5',
+        primaryHover: '#0B7E87',
+        primaryPressed: '#086269',
+      },
+      text: { link: '#0E9AA5' },
+      border: { focus: '#0E9AA5' },
+    },
+  },
+  {
+    colors: {
+      accent: {
+        primary: '#2DD4BF',
+        primaryHover: '#5EEAD4',
+        primaryPressed: '#0E9AA5',
+      },
+      text: { link: '#2DD4BF' },
+      border: { focus: '#2DD4BF' },
+    },
+  }
+);
+
+/**
+ * Lavender Theme - Soft purple accents, relaxing and spiritual
+ */
+export const lavenderTheme = createThemePair(
+  { name: 'Lavender' },
+  {
+    colors: {
+      accent: {
+        primary: '#8B5CF6',
+        primaryHover: '#7C3AED',
+        primaryPressed: '#6D28D9',
+      },
+      text: { link: '#8B5CF6' },
+      border: { focus: '#8B5CF6' },
+    },
+  },
+  {
+    colors: {
+      accent: {
+        primary: '#A78BFA',
+        primaryHover: '#C4B5FD',
+        primaryPressed: '#8B5CF6',
+      },
+      text: { link: '#A78BFA' },
+      border: { focus: '#A78BFA' },
+    },
+  }
+);
+
+/**
+ * Rose Theme - Warm pink/rose accents, gentle and nurturing
+ */
+export const roseTheme = createThemePair(
+  { name: 'Rose' },
+  {
+    colors: {
+      accent: {
+        primary: '#E11D6C',
+        primaryHover: '#BE185D',
+        primaryPressed: '#9D174D',
+      },
+      text: { link: '#E11D6C' },
+      border: { focus: '#E11D6C' },
+    },
+  },
+  {
+    colors: {
+      accent: {
+        primary: '#F472B6',
+        primaryHover: '#F9A8D4',
+        primaryPressed: '#E11D6C',
+      },
+      text: { link: '#F472B6' },
+      border: { focus: '#F472B6' },
+    },
+  }
+);