react-native-toast-message-library 0.0.0-stage → 0.1.0

package/src/themes/light.js

@@ -0,0 +1,64 @@
+const light = {
+  name: 'light',
+  colors: {
+    success: {
+      background: '#ECFDF3',
+      text: '#05603A',
+      border: '#ABEFC6',
+      icon: '#079455',
+      iconText: '#FFFFFF',
+    },
+    error: {
+      background: '#FEF3F2',
+      text: '#912018',
+      border: '#FECDCA',
+      icon: '#D92D20',
+      iconText: '#FFFFFF',
+    },
+    warning: {
+      background: '#FFFAEB',
+      text: '#93370D',
+      border: '#FEDF89',
+      icon: '#B54708',
+      iconText: '#FFFFFF',
+    },
+    info: {
+      background: '#EFF8FF',
+      text: '#175CD3',
+      border: '#B2DDFF',
+      icon: '#1570EF',
+      iconText: '#FFFFFF',
+    },
+    custom: {
+      background: '#FFFFFF',
+      text: '#101828',
+      border: '#E4E7EC',
+      icon: '#475467',
+      iconText: '#FFFFFF',
+    },
+  },
+  actionColor: undefined,
+  closeColor: undefined,
+  progressTrack: 'rgba(0,0,0,0.08)',
+  borderRadius: 14,
+  borderWidth: 1,
+  padding: 14,
+  spacing: 10,
+  iconSize: 24,
+  typography: {
+    titleSize: 15,
+    titleWeight: '700',
+    messageSize: 14,
+    messageWeight: '400',
+    fontFamily: undefined,
+  },
+  shadow: {
+    color: '#101828',
+    opacity: 0.14,
+    radius: 12,
+    offsetY: 4,
+    elevation: 6,
+  },
+};
+
+export default light;

package/src/utils/constants.js

@@ -0,0 +1,40 @@
+export const TOAST_TYPES = ['success', 'error', 'warning', 'info', 'custom'];
+export const POSITIONS = [
+  'top',
+  'bottom',
+  'center',
+  'top-left',
+  'top-right',
+  'bottom-left',
+  'bottom-right',
+];
+export const ANIMATIONS = ['fade', 'slide', 'zoom', 'none'];
+export const DISMISS_REASONS = [
+  'timeout',
+  'manual',
+  'swipe',
+  'close',
+  'action',
+  'press',
+  'hideAll',
+];
+
+export const TYPE_LABELS = {
+  success: 'Success',
+  error: 'Error',
+  warning: 'Warning',
+  info: 'Info',
+  custom: '',
+};
+
+export const DEFAULT_CONFIG = {
+  position: 'top',
+  duration: 3000,
+  animation: 'slide',
+  animationDuration: 250,
+  maxVisible: 3,
+  closeButton: false,
+  swipeToDismiss: true,
+  progress: false,
+  haptics: false,
+};

package/src/utils/createAnnouncer.js

@@ -0,0 +1,46 @@
+import { AccessibilityInfo } from 'react-native';
+
+/**
+ * Throttled screen-reader announcements (used on iOS, which has no live
+ * regions). If several toasts appear at once, only the most recent message
+ * waiting is spoken after the minimum gap, so VoiceOver is not interrupted
+ * repeatedly.
+ */
+export default function createAnnouncer(minGap = 1500) {
+  let lastAt = 0;
+  let pending = null;
+  let timer = null;
+
+  function speak(message) {
+    lastAt = Date.now();
+    AccessibilityInfo.announceForAccessibility(message);
+  }
+
+  return {
+    announce(message) {
+      const wait = lastAt + minGap - Date.now();
+      if (wait <= 0 && timer == null) {
+        speak(message);
+        return;
+      }
+      pending = message;
+      if (timer == null) {
+        timer = setTimeout(() => {
+          timer = null;
+          const next = pending;
+          pending = null;
+          if (next != null) {
+            speak(next);
+          }
+        }, Math.max(wait, 0));
+      }
+    },
+    cancel() {
+      if (timer != null) {
+        clearTimeout(timer);
+      }
+      timer = null;
+      pending = null;
+    },
+  };
+}

package/src/utils/generateToastId.js

@@ -0,0 +1,10 @@
+let counter = 0;
+
+/**
+ * Returns an id that is unique for the lifetime of the JS runtime.
+ * A monotonically increasing counter is enough because ids never leave the app.
+ */
+export default function generateToastId() {
+  counter += 1;
+  return `toast-${counter}`;
+}

package/src/utils/normalizeToastOptions.js

@@ -0,0 +1,42 @@
+import { DEFAULT_CONFIG } from './constants';
+import validateToastOptions from './validateToastOptions';
+
+/**
+ * Converts the argument passed to `show()` (string or object) into a fully
+ * resolved options object by applying the provider defaults. The result is a
+ * new object; the caller's input is never mutated.
+ *
+ * @param {string|number|object} input
+ * @param {object} defaults provider-level defaults
+ */
+export default function normalizeToastOptions(input, defaults = {}) {
+  const raw =
+    typeof input === 'string' || typeof input === 'number'
+      ? { message: String(input) }
+      : input;
+
+  validateToastOptions(raw);
+
+  const base = { ...DEFAULT_CONFIG, ...defaults };
+  const resolved = { ...raw };
+
+  resolved.type = raw.type || 'custom';
+  ['position', 'animation', 'animationDuration', 'duration'].forEach(key => {
+    resolved[key] = raw[key] != null ? raw[key] : base[key];
+  });
+  ['closeButton', 'swipeToDismiss', 'progress', 'haptics'].forEach(key => {
+    resolved[key] = raw[key] != null ? raw[key] : base[key];
+  });
+  resolved.dismissOnPress = raw.dismissOnPress === true;
+  resolved.dismissOnAction = raw.dismissOnAction !== false;
+  resolved.offsetX = raw.offsetX != null ? raw.offsetX : base.offsetX;
+  resolved.offsetY = raw.offsetY != null ? raw.offsetY : base.offsetY;
+  if (raw.message != null) {
+    resolved.message = String(raw.message);
+  }
+  if (raw.title != null) {
+    resolved.title = String(raw.title);
+  }
+
+  return resolved;
+}

package/src/utils/safeArea.js

@@ -0,0 +1,34 @@
+import { createContext, useContext } from 'react';
+import { Platform, StatusBar } from 'react-native';
+
+// react-native-safe-area-context is an optional peer dependency. Metro treats a
+// require() inside try/catch as optional, so the library works without it.
+let ExternalInsetsContext = null;
+try {
+  ExternalInsetsContext =
+    require('react-native-safe-area-context').SafeAreaInsetsContext;
+} catch (error) {
+  ExternalInsetsContext = null;
+}
+
+const FallbackContext = createContext(null);
+const InsetsContext = ExternalInsetsContext || FallbackContext;
+
+function fallbackInsets() {
+  if (Platform.OS === 'android') {
+    return { top: StatusBar.currentHeight || 0, bottom: 0, left: 0, right: 0 };
+  }
+  // Conservative values for devices with a notch / Dynamic Island. Install
+  // react-native-safe-area-context (and add a SafeAreaProvider) for exact values.
+  return { top: 47, bottom: 34, left: 0, right: 0 };
+}
+
+/**
+ * Priority: explicit `override` prop > react-native-safe-area-context
+ * (when installed and a SafeAreaProvider is mounted) > platform fallback.
+ */
+export default function useToastInsets(override) {
+  const external = useContext(InsetsContext);
+  const base = external || fallbackInsets();
+  return { top: 0, bottom: 0, left: 0, right: 0, ...base, ...override };
+}

package/src/utils/validateToastOptions.js

@@ -0,0 +1,127 @@
+import { ANIMATIONS, POSITIONS, TOAST_TYPES } from './constants';
+
+const PREFIX = '[react-native-toast-message-library]';
+
+function fail(message) {
+  throw new TypeError(`${PREFIX} ${message}`);
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function checkFunction(options, key) {
+  if (options[key] != null && typeof options[key] !== 'function') {
+    fail(`"${key}" must be a function, received ${typeof options[key]}.`);
+  }
+}
+
+function checkEnum(options, key, allowed) {
+  if (options[key] != null && !allowed.includes(options[key])) {
+    fail(
+      `Invalid ${key} "${String(
+        options[key],
+      )}". Expected one of: ${allowed.join(', ')}.`,
+    );
+  }
+}
+
+function checkNonNegativeNumber(options, key) {
+  const value = options[key];
+  if (value == null) {
+    return;
+  }
+  if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
+    fail(`"${key}" must be a finite number >= 0, received ${String(value)}.`);
+  }
+}
+
+function checkBoolean(options, key) {
+  if (options[key] != null && typeof options[key] !== 'boolean') {
+    fail(`"${key}" must be a boolean, received ${typeof options[key]}.`);
+  }
+}
+
+/**
+ * Validates an options object (after strings have been converted to objects).
+ * Throws a TypeError with an actionable message on the first problem found.
+ */
+export default function validateToastOptions(options) {
+  if (!isPlainObject(options)) {
+    fail(
+      'toast options must be a string or an object, e.g. toast.show({ message: "Saved" }).',
+    );
+  }
+
+  checkEnum(options, 'type', TOAST_TYPES);
+  checkEnum(options, 'position', POSITIONS);
+  checkEnum(options, 'animation', ANIMATIONS);
+  checkNonNegativeNumber(options, 'duration');
+  checkNonNegativeNumber(options, 'animationDuration');
+  checkNonNegativeNumber(options, 'offsetX');
+  checkNonNegativeNumber(options, 'offsetY');
+
+  if (
+    options.id != null &&
+    typeof options.id !== 'string' &&
+    typeof options.id !== 'number'
+  ) {
+    fail('"id" must be a string or a number.');
+  }
+
+  ['title', 'message'].forEach(key => {
+    const value = options[key];
+    if (
+      value != null &&
+      typeof value !== 'string' &&
+      typeof value !== 'number'
+    ) {
+      fail(`"${key}" must be a string or number, received ${typeof value}.`);
+    }
+  });
+
+  ['onPress', 'onDismiss', 'onAction', 'onShow', 'render'].forEach(key =>
+    checkFunction(options, key),
+  );
+
+  [
+    'closeButton',
+    'swipeToDismiss',
+    'progress',
+    'haptics',
+    'dismissOnPress',
+    'dismissOnAction',
+  ].forEach(key => checkBoolean(options, key));
+
+  if (options.action != null) {
+    if (!isPlainObject(options.action)) {
+      fail('"action" must be an object like { label: "Undo" }.');
+    }
+    if (
+      typeof options.action.label !== 'string' ||
+      options.action.label.trim() === ''
+    ) {
+      fail('"action.label" must be a non-empty string.');
+    }
+  }
+
+  if (
+    options.shadow != null &&
+    options.shadow !== false &&
+    !isPlainObject(options.shadow)
+  ) {
+    fail('"shadow" must be false or an object.');
+  }
+
+  const hasContent =
+    options.message != null ||
+    (options.title != null && options.title !== '') ||
+    typeof options.render === 'function';
+  if (!hasContent) {
+    fail(
+      'a toast needs at least a "message", a "title" or a "render" function.',
+    );
+  }
+
+  return options;
+}

package/types/index.d.ts

@@ -0,0 +1,203 @@
+import * as React from 'react';
+import { StyleProp, TextStyle, ViewStyle } from 'react-native';
+
+export type ToastType = 'success' | 'error' | 'warning' | 'info' | 'custom';
+export type ToastPosition =
+  | 'top'
+  | 'bottom'
+  | 'center'
+  | 'top-left'
+  | 'top-right'
+  | 'bottom-left'
+  | 'bottom-right';
+export type ToastAnimation = 'fade' | 'slide' | 'zoom' | 'none';
+export type ToastDismissReason =
+  | 'timeout'
+  | 'manual'
+  | 'swipe'
+  | 'close'
+  | 'action'
+  | 'press'
+  | 'hideAll';
+
+export type ToastId = string;
+
+/** Argument passed to onPress / onAction and to `render`. */
+export interface ToastCallbackInfo {
+  id: ToastId;
+  type: ToastType;
+  /** Dismisses this toast (reason "manual"). */
+  hide: () => boolean;
+}
+
+export interface ToastColors {
+  background: string;
+  text: string;
+  border: string;
+  icon: string;
+}
+
+export interface ToastRenderInfo extends ToastCallbackInfo {
+  colors: ToastColors;
+  theme: ToastTheme;
+}
+
+export interface ToastShadow {
+  color?: string;
+  opacity?: number;
+  radius?: number;
+  offsetY?: number;
+  elevation?: number;
+}
+
+export interface ToastAction {
+  label: string;
+  accessibilityLabel?: string;
+}
+
+export interface ToastOptions {
+  /** Reusing an id updates that toast in place. Generated when omitted. */
+  id?: string | number;
+  type?: ToastType;
+  /** Defaults to "Success" / "Error" / "Warning" / "Info". Use '' or null to hide. */
+  title?: string | number | null;
+  message?: string | number;
+  /** ms. 0 keeps the toast until dismissed. Default 3000. */
+  duration?: number;
+  position?: ToastPosition;
+  animation?: ToastAnimation;
+  animationDuration?: number;
+  /** Extra horizontal / vertical distance from the edge, added to the provider offset. */
+  offsetX?: number;
+  offsetY?: number;
+
+  /** false hides the icon; an element or a function renders a custom one. */
+  icon?:
+    | false
+    | React.ReactElement
+    | ((info: { type: ToastType; color: string; size: number }) => React.ReactNode);
+  /** Replaces the icon + title + message area. */
+  render?: (info: ToastRenderInfo) => React.ReactNode;
+
+  closeButton?: boolean;
+  closeAccessibilityLabel?: string;
+  swipeToDismiss?: boolean;
+  progress?: boolean;
+  haptics?: boolean;
+  action?: ToastAction;
+  dismissOnPress?: boolean;
+  /** Default true. */
+  dismissOnAction?: boolean;
+
+  backgroundColor?: string;
+  textColor?: string;
+  borderColor?: string;
+  iconColor?: string;
+  borderRadius?: number;
+  padding?: number;
+  /** false removes the shadow. */
+  shadow?: false | ToastShadow;
+  containerStyle?: StyleProp<ViewStyle>;
+  titleStyle?: StyleProp<TextStyle>;
+  messageStyle?: StyleProp<TextStyle>;
+  accessibilityLabel?: string;
+
+  /** Called when the toast becomes visible (after leaving the queue). */
+  onShow?: (id: ToastId) => void;
+  onPress?: (info: ToastCallbackInfo) => void;
+  onAction?: (info: ToastCallbackInfo) => void;
+  /** Called once, when dismissal starts, also for toasts cancelled while queued. */
+  onDismiss?: (reason: ToastDismissReason, id: ToastId) => void;
+}
+
+export type ToastShortcutOptions = Omit<ToastOptions, 'type' | 'message'> & {
+  message?: ToastOptions['message'];
+};
+
+export interface ToastApi {
+  /** Throws a TypeError on invalid options. Returns the toast id. */
+  show(options: ToastOptions | string): ToastId;
+  success(message: string | ToastShortcutOptions, options?: ToastShortcutOptions): ToastId;
+  error(message: string | ToastShortcutOptions, options?: ToastShortcutOptions): ToastId;
+  warning(message: string | ToastShortcutOptions, options?: ToastShortcutOptions): ToastId;
+  info(message: string | ToastShortcutOptions, options?: ToastShortcutOptions): ToastId;
+  /** true if a toast was dismissed (visible or queued). */
+  hide(id: ToastId | number): boolean;
+  /** Returns how many toasts were dismissed. */
+  hideAll(): number;
+  /** Without an id: is any toast visible? */
+  isVisible(id?: ToastId | number): boolean;
+}
+
+export interface ToastTypeColors {
+  background: string;
+  text: string;
+  border: string;
+  icon: string;
+  /** Colour of the glyph drawn inside the built-in icon badge. */
+  iconText: string;
+}
+
+export interface ToastTheme {
+  name: string;
+  colors: Record<ToastType, ToastTypeColors>;
+  actionColor?: string;
+  closeColor?: string;
+  progressTrack: string;
+  borderRadius: number;
+  borderWidth: number;
+  padding: number;
+  spacing: number;
+  iconSize: number;
+  typography: {
+    titleSize: number;
+    titleWeight: TextStyle['fontWeight'];
+    messageSize: number;
+    messageWeight: TextStyle['fontWeight'];
+    fontFamily?: string;
+  };
+  shadow: Required<ToastShadow>;
+}
+
+type DeepPartial<T> = { [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K] };
+export type ToastThemeOverrides = DeepPartial<ToastTheme> & { extends?: 'light' | 'dark' };
+
+export interface Insets {
+  top?: number;
+  bottom?: number;
+  left?: number;
+  right?: number;
+}
+
+export interface ToastProviderProps {
+  children?: React.ReactNode;
+  /** 'system' follows the device colour scheme. Objects are merged over the light theme (or `extends`). */
+  theme?: 'light' | 'dark' | 'system' | ToastThemeOverrides;
+  position?: ToastPosition;
+  duration?: number;
+  animation?: ToastAnimation;
+  animationDuration?: number;
+  /** Max toasts on screen at once; the rest wait in a FIFO queue. Default 3. */
+  maxVisible?: number;
+  closeButton?: boolean;
+  swipeToDismiss?: boolean;
+  progress?: boolean;
+  haptics?: boolean;
+  /** Gap between stacked toasts. Defaults to the theme's spacing. */
+  spacing?: number;
+  offset?: { x?: number; y?: number };
+  /** Overrides detected safe-area insets. */
+  insets?: Insets;
+  /** Registers this provider for the imperative `Toast` API. */
+  global?: boolean;
+  /** Style of the wrapper View (default { flex: 1 }). */
+  style?: StyleProp<ViewStyle>;
+}
+
+export const ToastProvider: React.FC<ToastProviderProps>;
+export function useToast(): ToastApi;
+/** Imperative API. Requires <ToastProvider global>; throws if none is mounted. */
+export const Toast: ToastApi;
+export function createTheme(base?: 'light' | 'dark', overrides?: ToastThemeOverrides): ToastTheme;
+export const lightTheme: ToastTheme;
+export const darkTheme: ToastTheme;