@praxiis/ui 0.0.1

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

@@ -0,0 +1,190 @@
+/**
+ * Toast Component
+ *
+ * @description Toast notification for feedback messages - Atom
+ *
+ * Toast provides temporary, non-blocking notifications to users.
+ * It supports success, error, warning, and info variants with
+ * configurable duration, dismiss behavior, and optional actions.
+ *
+ * ## Variants
+ * | Variant | Use Case |
+ * |---------|----------|
+ * | success | Operation completed successfully |
+ * | error   | Operation failed, requires attention |
+ * | warning | Caution, potential issue |
+ * | info    | Informational message |
+ *
+ * ## Features
+ * - Four semantic variants (success, error, warning, info)
+ * - Auto-dismiss with configurable duration
+ * - Manual dismiss with close button
+ * - Optional action button
+ * - Smooth enter/exit animations
+ * - Full accessibility support (WCAG 4.1.3)
+ *
+ * @performance
+ * - Wrapped with React.memo() to prevent unnecessary re-renders
+ * - Uses useMemo() for color token resolution and icon determination
+ * - Animated.timing with native driver for smooth 60fps slide animations
+ * - Auto-dismiss timer cleared on unmount to prevent memory leaks
+ *
+ * @see Toast.types.ts - Type definitions
+ * @see Toast.helpers.ts - Pure calculation functions
+ * @see Toast.a11y.ts - Accessibility prop generation
+ * @see ToastProvider.tsx - Provider for toast context
+ *
+ * @example
+ * // Basic usage
+ * <Toast
+ *   id="toast-1"
+ *   message="Changes saved successfully"
+ *   variant="success"
+ *   onDismiss={() => removeToast("toast-1")}
+ * />
+ *
+ * @example
+ * // With action button
+ * <Toast
+ *   id="toast-2"
+ *   message="Item deleted"
+ *   variant="info"
+ *   action={{ label: "Undo", onPress: handleUndo }}
+ *   onDismiss={() => removeToast("toast-2")}
+ * />
+ */
+
+import {
+  border,
+  createRestyleComponent,
+  createVariant,
+  layout,
+  spacing,
+  spacingShorthand,
+} from "@shopify/restyle";
+import React, { memo, useCallback } from "react";
+import { RestyleTheme } from "../../../core/restyle";
+import { BaseThemeColor } from "../../../types";
+import { useEntranceAnimation } from "../../../hooks/animations";
+import { Button } from "../../actions/Button";
+import { IconButton } from "../../actions/IconButton";
+import { Icon } from "../../content/Icon";
+import { AnimatedBox, Box } from "../../layout";
+import { Text } from "../../typography";
+import { BaseToastProps, ToastProps } from "./Toast.types";
+import { useToastLogic } from "./useToastLogic";
+
+/**
+ * Base container with Restyle variant support.
+ * @internal
+ */
+const BaseToastContainer = createRestyleComponent<BaseToastProps, RestyleTheme>(
+  [
+    createVariant({ themeKey: "toastVariants" }),
+    border,
+    layout,
+    spacing,
+    spacingShorthand,
+  ],
+  Box,
+);
+
+function ToastComponent({
+  id,
+  message,
+  variant = "info",
+  onDismiss,
+  action,
+  dismissible = true,
+  iconName,
+  testID,
+  accessibilityLabel,
+  ...rest
+}: ToastProps) {
+  const {
+    backgroundColorToken,
+    borderColorToken,
+    iconColorToken,
+    textColorToken,
+    resolvedIconName,
+    a11yProps,
+  } = useToastLogic({
+    variant,
+    iconName,
+    accessibilityLabel,
+    message,
+  });
+
+  const { animatedStyle, dismiss } = useEntranceAnimation({
+    spring: { tension: 50, friction: 8 },
+  });
+
+  const handleDismiss = useCallback(() => {
+    dismiss(onDismiss);
+  }, [dismiss, onDismiss]);
+
+  const handleActionPress = useCallback(() => {
+    action?.onPress();
+  }, [action]);
+
+  return (
+    <AnimatedBox style={animatedStyle}>
+      <BaseToastContainer
+        variant={variant}
+        backgroundColor={backgroundColorToken as BaseThemeColor}
+        borderColor={borderColorToken as BaseThemeColor}
+        borderWidth={1}
+        borderRadius="md"
+        padding="sm"
+        flexDirection="row"
+        alignItems="center"
+        gap="sm"
+        testID={testID}
+        {...a11yProps}
+        {...rest}
+      >
+        {/* Status icon */}
+        <Icon
+          name={resolvedIconName}
+          size="md"
+          color={iconColorToken}
+          accessibilityLabel={resolvedIconName}
+        />
+
+        {/* Message */}
+        <Box flex={1}>
+          <Text variant="bodySmall" color={textColorToken as BaseThemeColor} numberOfLines={2}>
+            {message}
+          </Text>
+        </Box>
+
+        {/* Action button */}
+        {action && (
+          <Button
+            title={action.label}
+            onPress={handleActionPress}
+            variant="ghost"
+            size="sm"
+            color={iconColorToken as BaseThemeColor}
+            accessibilityLabel={action.label}
+          />
+        )}
+
+        {/* Close button */}
+        {dismissible && (
+          <IconButton
+            iconName="close"
+            onPress={handleDismiss}
+            variant="ghost"
+            size="sm"
+            color={iconColorToken as BaseThemeColor}
+            accessibilityLabel="Dismiss notification"
+          />
+        )}
+      </BaseToastContainer>
+    </AnimatedBox>
+  );
+}
+
+export const Toast = memo(ToastComponent);
+Toast.displayName = "Toast";

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

@@ -0,0 +1,270 @@
+/**
+ * Toast Component Types
+ *
+ * Type definitions for the Toast component and its related hooks/helpers.
+ *
+ * @see Toast.tsx - Component implementation
+ */
+
+import { BoxProps, ResponsiveValue, VariantProps } from "@shopify/restyle";
+import { ViewProps } from "react-native";
+import { RestyleTheme } from "../../../core/restyle";
+import { RestyleColor, MaterialIconName } from "../../../types";
+
+// =============================================================================
+// VARIANT TYPES
+// =============================================================================
+
+/**
+ * Visual variants for the Toast indicating status/feedback type.
+ *
+ * - `success`: Positive feedback, operation completed
+ * - `error`: Error state, operation failed
+ * - `warning`: Caution, potential issue
+ * - `info`: Informational message
+ */
+export type ToastVariant = Exclude<
+  keyof RestyleTheme["toastVariants"],
+  "defaults"
+>;
+
+/**
+ * Position of the toast on screen.
+ *
+ * - `top`: Display at top of screen
+ * - `bottom`: Display at bottom of screen
+ */
+export type ToastPosition = "top" | "bottom";
+
+// =============================================================================
+// RESTYLE PROP TYPES
+// =============================================================================
+
+/** Restyle props for Toast variant */
+type ToastVariantProps = VariantProps<RestyleTheme, "toastVariants">;
+
+/** Combined restyle props for base toast */
+export type BaseToastProps = ToastVariantProps &
+  BoxProps<RestyleTheme> &
+  ViewProps;
+
+// =============================================================================
+// TOAST DATA TYPES
+// =============================================================================
+
+/**
+ * Action button configuration for toast.
+ */
+export interface ToastAction {
+  /** Label text for the action button */
+  label: string;
+  /** Callback when action is pressed */
+  onPress: () => void;
+}
+
+/**
+ * Configuration for a single toast notification.
+ */
+export interface ToastConfig {
+  /** Unique identifier for the toast */
+  id: string;
+  /** Message to display */
+  message: string;
+  /** Visual variant indicating status */
+  variant: ToastVariant;
+  /** Duration in ms before auto-dismiss (0 = no auto-dismiss) */
+  duration?: number;
+  /** Optional action button */
+  action?: ToastAction;
+  /** Whether to show close button */
+  dismissible?: boolean;
+  /** Optional custom icon name (defaults based on variant) */
+  iconName?: MaterialIconName;
+  /** Accessibility label override */
+  accessibilityLabel?: string;
+}
+
+// =============================================================================
+// COMPONENT PROPS
+// =============================================================================
+
+/**
+ * Props for the Toast component.
+ *
+ * @example
+ * <Toast
+ *   message="Changes saved successfully"
+ *   variant="success"
+ *   onDismiss={() => removeToast(id)}
+ * />
+ */
+export interface ToastProps extends Omit<BaseToastProps, "variant"> {
+  /** Unique identifier for the toast */
+  id: string;
+
+  /** Message to display */
+  message: string;
+
+  /**
+   * Visual variant indicating status (supports responsive values).
+   * @default "info"
+   */
+  variant?: ResponsiveValue<ToastVariant, RestyleTheme["breakpoints"]>;
+
+  /**
+   * Callback when toast is dismissed (close button or auto-dismiss).
+   */
+  onDismiss: () => void;
+
+  /** Optional action button */
+  action?: ToastAction;
+
+  /**
+   * Whether to show close button.
+   * @default true
+   */
+  dismissible?: boolean;
+
+  /** Optional custom icon name (defaults based on variant) */
+  iconName?: MaterialIconName;
+
+  /** Test ID for testing frameworks */
+  testID?: string;
+
+  /** Accessibility label override */
+  accessibilityLabel?: string;
+}
+
+/**
+ * Props for the ToastContainer component that manages toast positioning and queue.
+ */
+export interface ToastContainerProps {
+  /**
+   * Position of toasts on screen.
+   * @default "bottom"
+   */
+  position?: ToastPosition;
+
+  /**
+   * Maximum number of visible toasts.
+   * @default 3
+   */
+  maxVisible?: number;
+
+  /** Test ID for testing frameworks */
+  testID?: string;
+}
+
+// =============================================================================
+// HOOK TYPES
+// =============================================================================
+
+/**
+ * Parameters for useToastLogic hook.
+ */
+export interface UseToastLogicParams {
+  variant: ResponsiveValue<ToastVariant, RestyleTheme["breakpoints"]>;
+  iconName?: MaterialIconName;
+  accessibilityLabel?: string;
+  message: string;
+}
+
+/**
+ * Return value from useToastLogic hook.
+ */
+export interface UseToastLogicReturn {
+  /** Theme variant key for restyle */
+  themeVariantKey: ToastVariant;
+  /** Background color token */
+  backgroundColorToken: RestyleColor;
+  /** Border color token */
+  borderColorToken: RestyleColor;
+  /** Icon color token */
+  iconColorToken: RestyleColor;
+  /** Text color token */
+  textColorToken: RestyleColor;
+  /** Resolved icon name based on variant */
+  resolvedIconName: MaterialIconName;
+  /** Accessibility props */
+  a11yProps: ToastA11yProps;
+}
+
+// =============================================================================
+// CONTEXT TYPES
+// =============================================================================
+
+/**
+ * Options for showing a toast via useToast hook.
+ */
+export interface ShowToastOptions {
+  /** Message to display */
+  message: string;
+  /**
+   * Visual variant indicating status.
+   * @default "info"
+   */
+  variant?: ToastVariant;
+  /**
+   * Duration in ms before auto-dismiss.
+   * @default 3000
+   */
+  duration?: number;
+  /** Optional action button */
+  action?: ToastAction;
+  /**
+   * Whether to show close button.
+   * @default true
+   */
+  dismissible?: boolean;
+  /** Optional custom icon name */
+  iconName?: MaterialIconName;
+  /** Accessibility label override */
+  accessibilityLabel?: string;
+}
+
+/**
+ * Toast context value returned by useToast hook.
+ */
+export interface ToastContextValue {
+  /** Show a toast notification */
+  show: (options: ShowToastOptions) => string;
+  /** Show a success toast */
+  success: (message: string, options?: Omit<ShowToastOptions, "message" | "variant">) => string;
+  /** Show an error toast */
+  error: (message: string, options?: Omit<ShowToastOptions, "message" | "variant">) => string;
+  /** Show a warning toast */
+  warning: (message: string, options?: Omit<ShowToastOptions, "message" | "variant">) => string;
+  /** Show an info toast */
+  info: (message: string, options?: Omit<ShowToastOptions, "message" | "variant">) => string;
+  /** Dismiss a specific toast by ID */
+  dismiss: (id: string) => void;
+  /** Dismiss all toasts */
+  dismissAll: () => void;
+}
+
+// =============================================================================
+// ACCESSIBILITY TYPES
+// =============================================================================
+
+/**
+ * Parameters for generating toast accessibility props.
+ */
+export interface ToastA11yParams {
+  /** Toast variant for role announcement */
+  variant: ToastVariant;
+  /** Custom accessibility label */
+  accessibilityLabel?: string;
+  /** Toast message */
+  message: string;
+  /** Translated prefix per variant */
+  variantPrefixes: Record<ToastVariant, string>;
+}
+
+/**
+ * Accessibility props returned by getToastA11y.
+ */
+export interface ToastA11yProps {
+  accessibilityLabel: string;
+  accessibilityRole: "alert";
+  accessibilityLiveRegion: "polite" | "assertive";
+}

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

@@ -0,0 +1,96 @@
+/**
+ * Toast Context
+ *
+ * Context for managing toast notifications across the app.
+ * Provides methods to show, dismiss, and manage toast queue.
+ *
+ * @see ToastProvider.tsx - Provider implementation
+ * @see Toast.tsx - Toast component
+ *
+ * @example
+ * // In a component
+ * const toast = useToast();
+ * toast.success("Changes saved!");
+ */
+
+import { createContext, useContext } from "react";
+import { ToastContextValue } from "./Toast.types";
+
+/**
+ * Default context value that throws if used outside provider.
+ * @internal
+ */
+const defaultContextValue: ToastContextValue = {
+  show: () => {
+    throw new Error("useToast must be used within a ToastProvider");
+  },
+  success: () => {
+    throw new Error("useToast must be used within a ToastProvider");
+  },
+  error: () => {
+    throw new Error("useToast must be used within a ToastProvider");
+  },
+  warning: () => {
+    throw new Error("useToast must be used within a ToastProvider");
+  },
+  info: () => {
+    throw new Error("useToast must be used within a ToastProvider");
+  },
+  dismiss: () => {
+    throw new Error("useToast must be used within a ToastProvider");
+  },
+  dismissAll: () => {
+    throw new Error("useToast must be used within a ToastProvider");
+  },
+};
+
+/**
+ * Toast context for managing toast notifications.
+ * @internal
+ */
+export const ToastContext = createContext<ToastContextValue>(defaultContextValue);
+
+/**
+ * Hook to access toast methods from anywhere in the app.
+ *
+ * Must be used within a ToastProvider.
+ *
+ * @returns Toast context with show/dismiss methods
+ * @throws Error if used outside ToastProvider
+ *
+ * @example
+ * // Show different toast types
+ * const toast = useToast();
+ *
+ * toast.success("Profile updated!");
+ * toast.error("Failed to save changes");
+ * toast.warning("Your session will expire soon");
+ * toast.info("New features available");
+ *
+ * @example
+ * // With options
+ * const toast = useToast();
+ *
+ * toast.show({
+ *   message: "Item deleted",
+ *   variant: "info",
+ *   duration: 5000,
+ *   action: {
+ *     label: "Undo",
+ *     onPress: () => undoDelete(),
+ *   },
+ * });
+ *
+ * @example
+ * // Dismiss toasts
+ * const toast = useToast();
+ * const id = toast.success("Saved!");
+ *
+ * // Later...
+ * toast.dismiss(id); // Dismiss specific toast
+ * toast.dismissAll(); // Dismiss all toasts
+ */
+export function useToast(): ToastContextValue {
+  const context = useContext(ToastContext);
+  return context;
+}