@praxiis/ui 0.0.1

package/src/primitives/feedback/Toast/ToastProvider.tsx

@@ -0,0 +1,241 @@
+/**
+ * Toast Provider
+ *
+ * Provider component that manages the toast notification queue
+ * and renders toasts at a configured position on screen.
+ *
+ * ## Features
+ * - Queue management with max visible limit
+ * - Auto-dismiss with configurable duration
+ * - Position at top or bottom of screen
+ * - Safe area aware positioning
+ * - Smooth stacked animations
+ *
+ * @see ToastContext.tsx - Context and useToast hook
+ * @see Toast.tsx - Toast component
+ *
+ * @example
+ * // In your app root
+ * <ToastProvider position="bottom" maxVisible={3}>
+ *   <App />
+ * </ToastProvider>
+ *
+ * @example
+ * // In any child component
+ * const toast = useToast();
+ * toast.success("Saved successfully!");
+ */
+
+import React, { useCallback, useMemo, useRef, useState } from "react";
+import { useSafeAreaInsets } from "react-native-safe-area-context";
+import { Box } from "../../layout";
+import { Toast } from "./Toast";
+import { generateToastId } from "./Toast.helpers";
+import {
+  ShowToastOptions,
+  ToastConfig,
+  ToastContainerProps,
+  ToastContextValue,
+} from "./Toast.types";
+import { ToastContext } from "./ToastContext";
+
+/** Default duration for auto-dismiss in ms */
+const DEFAULT_DURATION = 3000;
+
+/** Default max visible toasts */
+const DEFAULT_MAX_VISIBLE = 3;
+
+interface ToastProviderProps extends ToastContainerProps {
+  /** Child components */
+  children: React.ReactNode;
+}
+
+/**
+ * Provider component for toast notifications.
+ *
+ * Wrap your app with this provider to enable toast notifications
+ * from anywhere using the useToast hook.
+ *
+ * @example
+ * <ToastProvider position="bottom">
+ *   <App />
+ * </ToastProvider>
+ */
+export function ToastProvider({
+  children,
+  position = "bottom",
+  maxVisible = DEFAULT_MAX_VISIBLE,
+  testID,
+}: ToastProviderProps) {
+  const [toasts, setToasts] = useState<ToastConfig[]>([]);
+  const timersRef = useRef<Map<string, NodeJS.Timeout>>(new Map());
+  const insets = useSafeAreaInsets();
+
+  // Clean up timer for a toast
+  const clearTimer = useCallback((id: string) => {
+    const timer = timersRef.current.get(id);
+    if (timer) {
+      clearTimeout(timer);
+      timersRef.current.delete(id);
+    }
+  }, []);
+
+  // Dismiss a specific toast
+  const dismiss = useCallback(
+    (id: string) => {
+      clearTimer(id);
+      setToasts((prev) => prev.filter((toast) => toast.id !== id));
+    },
+    [clearTimer],
+  );
+
+  // Dismiss all toasts
+  const dismissAll = useCallback(() => {
+    timersRef.current.forEach((_, id) => clearTimer(id));
+    setToasts([]);
+  }, [clearTimer]);
+
+  // Show a new toast
+  const show = useCallback(
+    (options: ShowToastOptions): string => {
+      const id = generateToastId();
+      const duration = options.duration ?? DEFAULT_DURATION;
+
+      const config: ToastConfig = {
+        id,
+        message: options.message,
+        variant: options.variant ?? "info",
+        duration,
+        action: options.action,
+        dismissible: options.dismissible ?? true,
+        iconName: options.iconName,
+        accessibilityLabel: options.accessibilityLabel,
+      };
+
+      setToasts((prev) => {
+        // Remove oldest if at max capacity
+        const newToasts = [...prev, config];
+        if (newToasts.length > maxVisible) {
+          const removed = newToasts.shift();
+          if (removed) {
+            clearTimer(removed.id);
+          }
+        }
+        return newToasts;
+      });
+
+      // Set auto-dismiss timer if duration > 0
+      if (duration > 0) {
+        const timer = setTimeout(() => {
+          dismiss(id);
+        }, duration);
+        timersRef.current.set(id, timer as unknown as NodeJS.Timeout);
+      }
+
+      return id;
+    },
+    [maxVisible, clearTimer, dismiss],
+  );
+
+  // Convenience methods for each variant
+  const success = useCallback(
+    (
+      message: string,
+      options?: Omit<ShowToastOptions, "message" | "variant">,
+    ) => show({ ...options, message, variant: "success" }),
+    [show],
+  );
+
+  const error = useCallback(
+    (
+      message: string,
+      options?: Omit<ShowToastOptions, "message" | "variant">,
+    ) => show({ ...options, message, variant: "error" }),
+    [show],
+  );
+
+  const warning = useCallback(
+    (
+      message: string,
+      options?: Omit<ShowToastOptions, "message" | "variant">,
+    ) => show({ ...options, message, variant: "warning" }),
+    [show],
+  );
+
+  const info = useCallback(
+    (
+      message: string,
+      options?: Omit<ShowToastOptions, "message" | "variant">,
+    ) => show({ ...options, message, variant: "info" }),
+    [show],
+  );
+
+  // Memoize context value
+  const contextValue: ToastContextValue = useMemo(
+    () => ({
+      show,
+      success,
+      error,
+      warning,
+      info,
+      dismiss,
+      dismissAll,
+    }),
+    [show, success, error, warning, info, dismiss, dismissAll],
+  );
+
+  // Calculate container position styles
+  const containerStyle = useMemo(() => {
+    const baseStyle = {
+      position: "absolute" as const,
+      left: 16,
+      right: 16,
+      zIndex: 9999,
+    };
+
+    if (position === "top") {
+      return {
+        ...baseStyle,
+        top: insets.top + 8,
+      };
+    }
+
+    return {
+      ...baseStyle,
+      bottom: insets.bottom + 8,
+    };
+  }, [position, insets]);
+
+  return (
+    <ToastContext.Provider value={contextValue}>
+      {children}
+
+      {/* Toast container */}
+      {toasts.length > 0 && (
+        <Box
+          style={containerStyle}
+          gap="xs"
+          testID={testID}
+          pointerEvents="box-none"
+        >
+          {toasts.map((toast) => (
+            <Toast
+              key={toast.id}
+              id={toast.id}
+              message={toast.message}
+              variant={toast.variant}
+              action={toast.action}
+              dismissible={toast.dismissible}
+              iconName={toast.iconName}
+              accessibilityLabel={toast.accessibilityLabel}
+              onDismiss={() => dismiss(toast.id)}
+              testID={testID ? `${testID}-toast-${toast.id}` : undefined}
+            />
+          ))}
+        </Box>
+      )}
+    </ToastContext.Provider>
+  );
+}
+
+ToastProvider.displayName = "ToastProvider";

package/src/primitives/feedback/Toast/index.ts

@@ -0,0 +1,59 @@
+/**
+ * Toast Module
+ *
+ * Toast notifications for user feedback with variants for
+ * success, error, warning, and info states.
+ *
+ * @example
+ * // Using the provider and hook
+ * import { ToastProvider, useToast } from "@/design-system/primitives/feedback/Toast";
+ *
+ * // In app root
+ * <ToastProvider position="bottom">
+ *   <App />
+ * </ToastProvider>
+ *
+ * // In any component
+ * const toast = useToast();
+ * toast.success("Saved!");
+ * toast.error("Failed to save");
+ * toast.warning("Low battery");
+ * toast.info("New update available");
+ *
+ * @example
+ * // Direct Toast component usage (advanced)
+ * import { Toast } from "@/design-system/primitives/feedback/Toast";
+ *
+ * <Toast
+ *   id="toast-1"
+ *   message="Changes saved"
+ *   variant="success"
+ *   onDismiss={() => handleDismiss("toast-1")}
+ * />
+ */
+
+// Main component
+export { Toast } from "./Toast";
+
+// Provider and context
+export { ToastProvider } from "./ToastProvider";
+export { ToastContext, useToast } from "./ToastContext";
+
+// Types
+export type {
+  ToastProps,
+  ToastVariant,
+  ToastPosition,
+  ToastConfig,
+  ToastAction,
+  ToastContainerProps,
+  ShowToastOptions,
+  ToastContextValue,
+  BaseToastProps,
+} from "./Toast.types";
+
+// Helpers (for testing or advanced usage)
+export { generateToastId } from "./Toast.helpers";
+
+// Accessibility
+export * from "./Toast.a11y";

package/src/primitives/feedback/Toast/useToastLogic.ts

@@ -0,0 +1,112 @@
+/**
+ * Toast Logic Hook
+ *
+ * Extracts all computational logic from the Toast component.
+ * Returns memoized values for optimal render performance.
+ *
+ * Responsibilities:
+ * - Map variant to color tokens
+ * - Resolve icon based on variant
+ * - Generate accessibility props
+ *
+ * @see Toast.tsx - Component consuming this hook
+ * @see Toast.helpers.ts - Pure calculation functions
+ */
+
+import { useDesignSystem } from "../../../provider";
+import { useResponsiveProp } from "@shopify/restyle";
+import { useMemo } from "react";
+import { getToastA11y } from "./Toast.a11y";
+import {
+  getToastBackgroundColor,
+  getToastBorderColor,
+  getToastIcon,
+  getToastIconColor,
+  getToastTextColor,
+} from "./Toast.helpers";
+import { ToastVariant, UseToastLogicParams, UseToastLogicReturn } from "./Toast.types";
+
+/**
+ * Orchestrates Toast rendering logic and state management.
+ * 
+ * Handles:
+ * - Responsive variant resolution
+ * - Color token mapping (background, border, icon, text)
+ * - Icon resolution based on variant (auto or custom)
+ * - Accessibility props generation with semantic roles
+ * 
+ * @param params - Configuration object for toast behavior
+ * @param params.variant - Semantic variant ('info' | 'success' | 'warning' | 'error')
+ * @param params.iconName - Optional custom icon (overrides variant default)
+ * @param params.accessibilityLabel - Custom a11y label
+ * @param params.message - Toast message text
+ * 
+ * @returns Computed values for rendering Toast
+ * @returns {string} themeVariantKey - Resolved variant identifier
+ * @returns {string} backgroundColorToken - Background color token
+ * @returns {string} borderColorToken - Border color token
+ * @returns {string} iconColorToken - Icon color token
+ * @returns {string} textColorToken - Text color token
+ * @returns {string} resolvedIconName - Icon name (variant default or custom)
+ * @returns {object} a11yProps - Accessibility props with semantic role
+ * 
+ * @performance This hook uses useMemo() for color and icon resolution
+ * 
+ * @example
+ * const {
+ *   backgroundColorToken,
+ *   iconColorToken,
+ *   resolvedIconName,
+ *   a11yProps,
+ * } = useToastLogic({
+ *   variant: "success",
+ *   message: "Changes saved successfully",
+ * });
+ */
+export function useToastLogic({
+  variant,
+  iconName,
+  accessibilityLabel,
+  message,
+}: UseToastLogicParams): UseToastLogicReturn {
+  const { labels: t } = useDesignSystem();
+
+  const resolvedVariant = (useResponsiveProp(variant) ?? "info") as ToastVariant;
+
+  const variantPrefixes = useMemo(() => ({
+    success: t.designSystem.toast.prefixSuccess,
+    error: t.designSystem.toast.prefixError,
+    warning: t.designSystem.toast.prefixWarning,
+    info: t.designSystem.toast.prefixInfo,
+  }), [t]);
+
+  const colorTokens = useMemo(
+    () => ({
+      backgroundColorToken: getToastBackgroundColor(resolvedVariant),
+      borderColorToken: getToastBorderColor(resolvedVariant),
+      iconColorToken: getToastIconColor(resolvedVariant),
+      textColorToken: getToastTextColor(resolvedVariant),
+    }),
+    [resolvedVariant]
+  );
+
+  const resolvedIconName = getToastIcon(resolvedVariant, iconName);
+
+  const a11yProps = useMemo(
+    () =>
+      getToastA11y({
+        variant: resolvedVariant,
+        accessibilityLabel,
+        message,
+        variantPrefixes,
+      }),
+    [resolvedVariant, accessibilityLabel, message, variantPrefixes]
+  );
+
+  return {
+    themeVariantKey: resolvedVariant,
+    ...colorTokens,
+    resolvedIconName,
+    a11yProps,
+  };
+}

package/src/primitives/feedback/index.ts

@@ -0,0 +1,45 @@
+/**
+ * Feedback Components Module
+ *
+ * Components that provide visual feedback to users during
+ * loading states, errors, and other system events.
+ *
+ * @example
+ * import { Spinner, ProgressBar, Skeleton, EmptyState, Toast, useToast, ToastProvider } from "@/design-system/primitives/feedback";
+ */
+
+export {
+  ProgressBar,
+  type ProgressBarProps,
+  type ProgressBarSize,
+} from "./ProgressBar";
+
+export {
+  Skeleton,
+  type SkeletonAnimation,
+  type SkeletonProps,
+  type SkeletonSize,
+  type SkeletonVariant,
+} from "./Skeleton";
+
+export {
+  Spinner,
+  type SpinnerProps,
+  type SpinnerSize,
+} from "./Spinner";
+
+export {
+  Toast,
+  ToastProvider,
+  ToastContext,
+  useToast,
+  generateToastId,
+  type ToastProps,
+  type ToastVariant,
+  type ToastPosition,
+  type ToastConfig,
+  type ToastAction,
+  type ToastContainerProps,
+  type ShowToastOptions,
+  type ToastContextValue,
+} from "./Toast";

package/src/primitives/index.ts

@@ -0,0 +1,158 @@
+/**
+ * Design System Components
+ *
+ * Barrel export for all design system components.
+ * Grouped by interaction model.
+ *
+ * ## Categories
+ *
+ * - **actions**    — User triggers something (Button, IconButton)
+ * - **inputs**     — User provides data/selection (TextInput, Checkbox, Switch, etc.)
+ * - **content**    — Presents information (Avatar, Badge, Card, Icon, etc.)
+ * - **feedback**   — System communicates state (Spinner, Toast, Skeleton, etc.)
+ * - **layout**     — Structures space (Divider, Box)
+ * - **navigation** — Orients the user (Header)
+ * - **overlays**   — Elevated surfaces (Modal)
+ *
+ * ## Touch Targets
+ * All interactive components meet 44px minimum (Apple HIG)
+ * via container size or hitSlop.
+ *
+ * @see tokens/scales.ts - Mathematical constants (ICON_RATIOS, touch targets)
+ */
+
+// ─── Actions ────────────────────────────────────────────────────────────────
+export {
+  Button,
+  IconButton,
+  type ButtonProps,
+  type ButtonRef,
+  type ButtonSize,
+  type ButtonVariant,
+  type IconButtonProps,
+  type IconButtonSize,
+  type IconButtonVariant,
+} from "./actions";
+
+// ─── Inputs ─────────────────────────────────────────────────────────────────
+export {
+  Checkbox,
+  RadioButton,
+  SegmentedControl,
+  SelectSheet,
+  Switch,
+  TextInput,
+  type CheckboxProps,
+  type CheckboxRef,
+  type CheckboxSize,
+  type RadioButtonProps,
+  type RadioButtonRef,
+  type RadioButtonSize,
+  type SegmentedControlProps,
+  type SegmentedControlSize,
+  type SegmentedControlVariant,
+  type SegmentOption,
+  type SelectSheetIndicatorPosition,
+  type SelectSheetMode,
+  type SelectSheetOption,
+  type SelectSheetPosition,
+  type SelectSheetProps,
+  type SwitchProps,
+  type SwitchRef,
+  type SwitchSize,
+  type TextInputProps,
+  type TextInputRef,
+  type TextInputSize,
+  type TextInputVariant,
+} from "./inputs";
+
+// ─── Content ────────────────────────────────────────────────────────────────
+export {
+  Avatar,
+  Badge,
+  Card,
+  Chip,
+  Icon,
+  type AvatarProps,
+  type AvatarSize,
+  type AvatarStatus,
+  type BadgeProps,
+  type BadgeSize,
+  type BadgeVariant,
+  type CardProps,
+  type CardVariant,
+  type ChipProps,
+  type ChipSize,
+  type ChipVariant,
+  type IconName,
+  type IconProps,
+} from "./content";
+
+// ─── Feedback ───────────────────────────────────────────────────────────────
+export {
+  generateToastId,
+  ProgressBar,
+  Skeleton,
+  Spinner,
+  Toast,
+  ToastContext,
+  ToastProvider,
+  useToast,
+  type ProgressBarProps,
+  type ProgressBarSize,
+  type ShowToastOptions,
+  type SkeletonAnimation,
+  type SkeletonProps,
+  type SkeletonSize,
+  type SkeletonVariant,
+  type SpinnerProps,
+  type SpinnerSize,
+  type ToastAction,
+  type ToastConfig,
+  type ToastContainerProps,
+  type ToastContextValue,
+  type ToastPosition,
+  type ToastProps,
+  type ToastVariant,
+} from "./feedback";
+
+// ─── Layout ─────────────────────────────────────────────────────────────────
+export {
+  AnimatedBox,
+  Box,
+  Divider,
+  FlatList,
+  HStack,
+  Pressable,
+  ScrollView,
+  VStack,
+  type BoxRestyleProps,
+  type DividerColor,
+  type DividerOrientation,
+  type DividerProps,
+  type DividerSpacing,
+  type DividerThickness,
+  type FlatListProps,
+  type FlatListRef,
+  type FlatListRestyleProps,
+  type HStackProps,
+  type PressableProps,
+  type PressableRestyleProps,
+  type ScrollViewProps,
+  type ScrollViewRef,
+  type ScrollViewRestyleProps,
+  type VStackProps,
+} from "./layout";
+
+// ─── Navigation ─────────────────────────────────────────────────────────────
+// (Header moved to design-system/components)
+
+// ─── Overlays ───────────────────────────────────────────────────────────────
+export {
+  Modal,
+  type ModalAction,
+  type ModalPosition,
+  type ModalProps,
+} from "./overlays";
+
+export * from "./typography";