Advanced Guides - Flows and Interactions

Platform support (current): iOS and Android only. Web is not officially supported yet and may be added in future releases.

Focused recipes for gestures, async lifecycle flows, grouping controls, boundary refs, and typed template facades.

All examples use package-root imports only.

6. Gesture-Heavy Interaction Tuning

Use when: swipe/drag behavior must be stable in complex touch environments.

Deck interaction note:

• collapsed stack still expands via deck swipe gesture
• expanded stack now collapses from the dedicated collapse handle (not from in-content pull)
• collapse handle drag uses deckGesture.collapseHandle thresholds (inherits deckGesture globals by default)

import { toast } from "react-native-toast-system";

function showGestureProbe() {
  toast.show({
    title: "Swipe / drag me",
    pauseOnDrag: true,
    dismissible: true,
    gesture: {
      enabled: true,
      dismissThreshold: 42,
      cancelThreshold: 10,
      velocityThreshold: 800,
    },
  });
}

import { ToastHost } from "react-native-toast-system";

<ToastHost
  hostId="default"
  interactionMode="deck"
  config={{
    deckGesture: {
      collapseHandle: {
        dismissThreshold: 42,
        velocityThreshold: 800,
      },
    },
    collapseHandleStyle: {
      width: 40,
      backgroundColor: "#94A3B8",
      opacity: 0.95,
    },
  }}
/>;

Expected outcome:

• drag pauses timer and swipe thresholds behave consistently

Failure signals:

• accidental dismissals or impossible dismiss gestures

7. Promise Lifecycle Flow

Use when: async work should map to loading/success/error user feedback.

import { toast } from "react-native-toast-system";

async function saveProfile() {
  await toast.promise(api.save(), {
    loading: { title: "Saving" },
    success: (value) => ({ title: "Saved", description: String(value) }),
    error: (error) => ({ title: "Save failed", description: String(error) }),
  });
}

Expected outcome:

• loading toast transitions to success/error in the same interaction flow

Failure signals:

• loading toast remains stale due to uncaught promise or missing handler path

8. Grouped Flow Patterns

Use when: one logical flow should evolve in place instead of stacking duplicates.

import { toast } from "react-native-toast-system";

async function syncFlow() {
  const groupId = "sync:main";

  toast.show({
    title: "Sync started",
    groupId,
    groupBehavior: "update-in-group",
    persistent: true,
  });

  await api.sync();

  toast.show({
    title: "Sync complete",
    groupId,
    groupBehavior: "update-in-group",
    variant: "success",
    duration: 1800,
  });
}

Expected outcome:

• flow transitions update the same logical group instead of creating noisy stacks

Failure signals:

• repeated progress toasts accumulate without collapsing/update behavior

9. Group-Scoped Control Helpers

Use when: an entire flow channel must be updated or dismissed at once.

import { toast } from "react-native-toast-system";

toast.updateGroup("sync:main", { description: "Still syncing..." });
toast.dismissGroup("sync:main", "dismiss");

Expected outcome:

• all matching group toasts update/dismiss together

Failure signals:

• stale group members stay visible due to inconsistent group IDs

10. Controller Ref for Boundary Surfaces

Use when: hooks are awkward inside isolated modal/sheet composition boundaries.

import { useRef } from "react";
import { ToastHost, type ToastController } from "react-native-toast-system";

const controllerRef = useRef<ToastController | null>(null);

<ToastHost hostId="sheet" controllerRef={controllerRef} />;

controllerRef.current?.show({ title: "Boundary-triggered toast" });

Expected outcome:

• imperative flows can target boundary-local host safely

Failure signals:

• ref remains null because host is not mounted yet

11. Typed Template Facade

Use when: teams need strict template-name safety for design-system toasts.

import { Button } from "react-native";
import { createToastSystem } from "react-native-toast-system";

const { ToastProvider, ToastViewport, toast } = createToastSystem({
  templates: {
    appDefault: ({ context }) => <MyTemplate context={context} />,
  },
});

function App() {
  return (
    <ToastProvider>
      <Button title="Typed template toast" onPress={() => toast.show({ template: "appDefault" })} />
      <ToastViewport />
    </ToastProvider>
  );
}

Expected outcome:

• only registered template names compile in toast.show(...)

Failure signals:

• type errors when using unregistered template names

Validation Pairing

For integration-heavy recipes, run:

• pnpm run typecheck
• pnpm run test
• pnpm run example:validate
• pnpm run example:start and execute the manual checks listed in example/README.md