@applicaster/quick-brick-core 16.0.0-alpha.8525514228 → 16.0.0-alpha.8716141508

package/App/ModalProvider/ModalBottomSheet/DraggableBottomSheet/__tests__/index.test.tsx

@@ -0,0 +1,88 @@
+import React from "react";
+import { View } from "react-native";
+import { render } from "@testing-library/react-native";
+import { State } from "react-native-gesture-handler";
+import { DraggableBottomSheet } from "../index";
+
+// Render the gesture handlers as passthrough Views so we can mount the sheet
+// and drive its release handler directly. State stays real (we need ACTIVE).
+jest.mock("react-native-gesture-handler", () => {
+  const RN = require("react-native");
+  const ReactActual = require("react");
+  const actual = jest.requireActual("react-native-gesture-handler");
+
+  const Passthrough = ReactActual.forwardRef(({ children }: any, _ref: any) => (
+    <RN.View>{children}</RN.View>
+  ));
+
+  return {
+    __esModule: true,
+    ...actual,
+    PanGestureHandler: Passthrough,
+    TapGestureHandler: Passthrough,
+  };
+});
+
+// height 800, sheetHeight 400, no header:
+//   SnapPoints.top = 800 - 400 = 400 (lastSnap after mount)
+//   SnapPoints.threshold = max(800 - 400 / 2, 100) = 600
+// Release dismisses when lastSnap + translationY + 0.05 * velocityY > 600,
+// i.e. once the drag+toss pushes past 200px.
+const mountSheet = () => {
+  const dismiss = jest.fn();
+  const ref = React.createRef<DraggableBottomSheet>();
+
+  render(
+    <DraggableBottomSheet
+      ref={ref}
+      header={() => null}
+      dismiss={dismiss}
+      visible={true}
+      sheetHeight={400}
+      width={320}
+      height={800}
+      hasHeader={false}
+      maxWidth={320}
+    >
+      <View testID="child" />
+    </DraggableBottomSheet>
+  );
+
+  return { instance: ref.current as DraggableBottomSheet, dismiss };
+};
+
+const release = (
+  instance: DraggableBottomSheet,
+  translationY: number,
+  velocityY = 0
+) =>
+  instance._onHandlerStateChange({
+    nativeEvent: { oldState: State.ACTIVE, translationY, velocityY },
+  });
+
+describe("DraggableBottomSheet release", () => {
+  // Mounting an open sheet schedules a deferred animateIn via setTimeout. Keep
+  // it on fake timers so it never fires into a torn-down Jest environment.
+  beforeEach(() => jest.useFakeTimers());
+
+  afterEach(() => {
+    jest.clearAllTimers();
+    jest.useRealTimers();
+  });
+
+  it("dismisses when the release lands past the threshold", () => {
+    const { instance, dismiss } = mountSheet();
+
+    release(instance, 300);
+
+    expect(dismiss).toHaveBeenCalledTimes(1);
+  });
+
+  it("springs back (does not dismiss) when the release is below the threshold", () => {
+    const { instance, dismiss } = mountSheet();
+
+    release(instance, 50);
+
+    expect(dismiss).not.toHaveBeenCalled();
+  });
+});

package/App/ModalProvider/ModalBottomSheet/DraggableBottomSheet/index.tsx

@@ -1,15 +1,24 @@
-import React, { Component, ReactChild, ReactElement } from "react";
+import React, { Component, ReactElement } from "react";
 import { Animated, StyleSheet, View, Easing } from "react-native";
 import {
   PanGestureHandler,
-  NativeViewGestureHandler,
   State,
   TapGestureHandler,
 } from "react-native-gesture-handler";
 
 import { SnapPoints } from "./SnapPoints";
-
-const USE_NATIVE_DRIVER = true;
+import {
+  BottomSheetContext,
+  BottomSheetContextValue,
+} from "@applicaster/zapp-react-native-utils/bottomSheet";
+
+// Must stay false: the sheet drives _dragY from old-API PanGestureHandler
+// onGestureEvent props via RN Animated.event. This RNGH version cannot attach
+// a native (useNativeDriver: true) Animated.event to those handlers — it leaks
+// the AnimatedEvent object into the JS event path and throws "Expected
+// onGestureHandlerEvent listener to be a function". Native-threaded dragging
+// needs the full reanimated + Gesture-API migration (tracked separately).
+const USE_NATIVE_DRIVER = false;
 const HEADER_HEIGHT = 44;
 
 const ANIMATION_DURATION = 400;
@@ -24,7 +33,7 @@ const styles = StyleSheet.create({
 });
 
 type Props = {
-  children: ReactChild;
+  children: ReactElement;
   header: (boolean) => ReactElement;
   dismiss: () => void;
   visible: boolean;
@@ -49,35 +58,24 @@ export class DraggableBottomSheet extends Component<Props, ComponentState> {
   _isMounted = false;
   _animatedIn = false;
   _animating = false;
-  _lastScrollYValue: number;
-  _lastScrollY: Animated.Value;
   _dragY: Animated.Value;
-  _reverseLastScrollY: Animated.AnimatedInterpolation<number>;
   _translateYOffset: Animated.Value;
   _translateY: Animated.AnimatedInterpolation<number>;
   _snapPoints: SnapPoints;
   _prevContentHeight = 0;
+  _bottomSheetContextValue: BottomSheetContextValue;
 
   _callWhenMounted: () => void | null;
 
-  _onRegisterLastScroll: (...args: any[]) => void;
+  // One shared JS Animated.event feeds _dragY for every drag handler (top
+  // handle, header drag-area, body). Safe because useNativeDriver is false — the
+  // event is a plain JS listener that setValue's _dragY for whichever handler
+  // is active, and only one gesture is ever active at a time.
   _onGestureEvent: (...args: any[]) => void;
 
   constructor(props) {
     super(props);
 
-    this._lastScrollYValue = 0;
-    this._lastScrollY = new Animated.Value(0);
-
-    this._onRegisterLastScroll = Animated.event(
-      [{ nativeEvent: { contentOffset: { y: this._lastScrollY } } }],
-      { useNativeDriver: USE_NATIVE_DRIVER }
-    );
-
-    this._lastScrollY.addListener(({ value }) => {
-      this._lastScrollYValue = value;
-    });
-
     this._dragY = new Animated.Value(0);
 
     this._onGestureEvent = Animated.event(
@@ -85,10 +83,11 @@ export class DraggableBottomSheet extends Component<Props, ComponentState> {
       { useNativeDriver: USE_NATIVE_DRIVER }
     );
 
-    this._reverseLastScrollY = Animated.multiply(
-      new Animated.Value(-1),
-      this._lastScrollY
-    );
+    this._bottomSheetContextValue = {
+      masterDrawerRef: this.masterdrawer,
+      onDragGestureEvent: this._onGestureEvent,
+      onDragStateChange: this._onHeaderHandlerStateChange,
+    };
 
     const initialSnapPoints = new SnapPoints(props.height, props.sheetHeight);
 
@@ -181,7 +180,7 @@ export class DraggableBottomSheet extends Component<Props, ComponentState> {
 
     this._translateY = Animated.add(
       this._translateYOffset,
-      Animated.add(this._dragY, this._reverseLastScrollY)
+      this._dragY
     ).interpolate({
       inputRange: [this._snapPoints.top, this._snapPoints.bottom],
       outputRange: [this._snapPoints.top, this._snapPoints.bottom],
@@ -226,10 +225,6 @@ export class DraggableBottomSheet extends Component<Props, ComponentState> {
       return;
     }
 
-    if (nativeEvent.oldState === State.BEGAN) {
-      this._lastScrollY.setValue(0);
-    }
-
     this._onHandlerStateChange({ nativeEvent });
   };
 
@@ -240,8 +235,7 @@ export class DraggableBottomSheet extends Component<Props, ComponentState> {
 
     if (nativeEvent.oldState === State.ACTIVE) {
       const { velocityY } = nativeEvent;
-      let { translationY } = nativeEvent;
-      translationY -= this._lastScrollYValue;
+      const { translationY } = nativeEvent;
       const dragToss = 0.05;
 
       const endOffsetY =
@@ -300,7 +294,7 @@ export class DraggableBottomSheet extends Component<Props, ComponentState> {
           >
             <PanGestureHandler
               ref={this.drawerheader}
-              simultaneousHandlers={[this.scroll, this.masterdrawer]}
+              simultaneousHandlers={[this.masterdrawer]}
               shouldCancelWhenOutside={false}
               onGestureEvent={this._onGestureEvent}
               onHandlerStateChange={this._onHeaderHandlerStateChange}
@@ -309,31 +303,11 @@ export class DraggableBottomSheet extends Component<Props, ComponentState> {
                 {this.props?.header(this.state.dragging)}
               </Animated.View>
             </PanGestureHandler>
-            <PanGestureHandler
-              ref={this.drawer}
-              simultaneousHandlers={[this.scroll, this.masterdrawer]}
-              shouldCancelWhenOutside={false}
-              onGestureEvent={this._onGestureEvent}
-              onHandlerStateChange={this._onHandlerStateChange}
-            >
+            <BottomSheetContext.Provider value={this._bottomSheetContextValue}>
               <Animated.View style={styles.container}>
-                <NativeViewGestureHandler
-                  ref={this.scroll}
-                  waitFor={this.masterdrawer}
-                  simultaneousHandlers={this.drawer}
-                >
-                  <Animated.ScrollView
-                    bounces={false}
-                    onScrollBeginDrag={this._onRegisterLastScroll}
-                    scrollEventThrottle={1}
-                    scrollEnabled={false}
-                    showsVerticalScrollIndicator={false}
-                  >
-                    {this.props.children}
-                  </Animated.ScrollView>
-                </NativeViewGestureHandler>
+                {this.props.children}
               </Animated.View>
-            </PanGestureHandler>
+            </BottomSheetContext.Provider>
           </Animated.View>
         </View>
       </TapGestureHandler>

package/App/NotificationToastRenderer/NotificationToastManager.ts

@@ -0,0 +1,203 @@
+import { subscriber } from "@applicaster/zapp-react-native-utils/functionUtils";
+import { subscriberFor } from "@applicaster/zapp-react-native-utils/reactHooks/useSubscriberFor";
+
+// events accepted on the shared cross-package event bus (see useSubscriberFor),
+// so packages that must not depend on quick-brick-core (e.g. OfflineHandler in
+// zapp-react-native-ui-components) can trigger a toast by event name alone,
+// without importing notificationToastManager directly.
+const unwrapEventPayload = (payload: unknown) =>
+  Array.isArray(payload) ? payload[0] : payload;
+
+export const NOTIFICATION_TOAST_EVENTS = {
+  SHOW_TOAST: "showToast", // in: request to enqueue a toast
+  DISMISS: "dismiss", // in: renderer/user dismissed the visible toast early
+  SHOW: "show", // out: renderer should display this toast
+  HIDE: "hide", // out: renderer should hide the current toast
+} as const;
+
+export interface ToastStyle {
+  backgroundColor?: string;
+  color?: string;
+  fontFamily?: string;
+  fontSize?: number;
+  lineHeight?: number;
+  letterSpacing?: number;
+}
+
+export interface ToastPayload {
+  id?: string;
+  message: string;
+  extraMessage?: string; // secondary line; TV renderers show it as a subtitle, mobile ignores it
+  timeout?: number; // ms; if omitted, toast stays until dismissed
+  style?: ToastStyle;
+  [key: string]: unknown;
+}
+
+class NotificationToastManager {
+  private static instance: NotificationToastManager;
+
+  private eventHandler = subscriber();
+  private queue: ToastPayload[] = [];
+  private hideTimer: ReturnType<typeof setTimeout> | null = null;
+  private isShowing = false;
+  private nextId = 0;
+
+  private constructor() {
+    // subscribe to the shared event bus so other packages can trigger toasts
+    subscriberFor(
+      NOTIFICATION_TOAST_EVENTS.SHOW_TOAST,
+      this.handleShowToastEvent
+    );
+
+    subscriberFor(NOTIFICATION_TOAST_EVENTS.DISMISS, this.handleDismiss);
+
+    this.getCurrentState = this.getCurrentState.bind(this);
+    this.subscribe = this.subscribe.bind(this);
+  }
+
+  static getInstance(): NotificationToastManager {
+    if (!NotificationToastManager.instance) {
+      NotificationToastManager.instance = new NotificationToastManager();
+    }
+
+    return NotificationToastManager.instance;
+  }
+
+  on(event: string, callback: (...args: any[]) => void) {
+    this.eventHandler.on(event, callback);
+  }
+
+  removeHandler(event: string, callback: (...args: any[]) => void) {
+    this.eventHandler.removeHandler(event, callback);
+  }
+
+  showToast(payload: ToastPayload) {
+    this.handleShowToast(payload);
+  }
+
+  dismiss() {
+    this.handleDismiss();
+  }
+
+  getCurrentState() {
+    return this.queue[0] ?? null;
+  }
+
+  subscribe(callback) {
+    this.eventHandler.on(NOTIFICATION_TOAST_EVENTS.SHOW, callback);
+
+    this.eventHandler.on(NOTIFICATION_TOAST_EVENTS.HIDE, callback);
+
+    return () => {
+      this.eventHandler.removeHandler(NOTIFICATION_TOAST_EVENTS.SHOW, callback);
+
+      this.eventHandler.removeHandler(NOTIFICATION_TOAST_EVENTS.HIDE, callback);
+    };
+  }
+
+  // subscriberFor's shared bus can deliver the raw payload (component emitters,
+  // see useSubscriberFor) or an args array (postEvent-style callers) - accept both.
+  private handleShowToastEvent = (payload: unknown) => {
+    if (!payload) {
+      console.warn(
+        "NotificationToastManager: Invalid showToast payload:",
+        payload
+      );
+
+      return;
+    }
+
+    const unwrappedPayload = unwrapEventPayload(payload) as ToastPayload;
+
+    if (!unwrappedPayload || typeof unwrappedPayload.message !== "string") {
+      console.warn(
+        "NotificationToastManager: Invalid showToast payload:",
+        payload
+      );
+
+      return;
+    }
+
+    this.handleShowToast(unwrappedPayload);
+  };
+
+  private handleShowToast = (payload: ToastPayload) => {
+    const item = { ...payload, id: payload.id ?? String(this.nextId++) };
+
+    const queuedIndex = this.queue.findIndex((queued) => queued.id === item.id);
+
+    if (queuedIndex === -1) {
+      this.queue.push(item);
+    } else if (queuedIndex === 0 && this.isShowing) {
+      // this id is the toast currently on screen - swap its content in place
+      // (new one appears in front of it) and dismiss the old timer/content
+      this.clearTimer();
+      this.queue[0] = item;
+      this.eventHandler.invokeHandler(NOTIFICATION_TOAST_EVENTS.SHOW, item);
+
+      if (item.timeout) {
+        this.hideTimer = setTimeout(() => this.finishCurrent(), item.timeout);
+      }
+
+      return;
+    } else {
+      // still queued, not yet shown - update it in place instead of duplicating
+      this.queue[queuedIndex] = item;
+
+      return;
+    }
+
+    if (!this.isShowing) {
+      this.processNext();
+    }
+  };
+
+  private handleDismiss = () => {
+    if (!this.isShowing) {
+      return;
+    }
+
+    this.finishCurrent();
+  };
+
+  private processNext() {
+    const next = this.queue[0];
+
+    if (!next) {
+      this.isShowing = false;
+
+      return;
+    }
+
+    this.isShowing = true;
+    this.eventHandler.invokeHandler(NOTIFICATION_TOAST_EVENTS.SHOW, next);
+
+    if (next.timeout) {
+      this.hideTimer = setTimeout(() => this.finishCurrent(), next.timeout);
+    }
+  }
+
+  private finishCurrent() {
+    this.clearTimer();
+    this.queue.shift();
+    this.eventHandler.invokeHandler(NOTIFICATION_TOAST_EVENTS.HIDE);
+    this.isShowing = false;
+    this.processNext();
+  }
+
+  private clearTimer() {
+    if (this.hideTimer) {
+      clearTimeout(this.hideTimer);
+      this.hideTimer = null;
+    }
+  }
+
+  public reset(): void {
+    this.clearTimer();
+    this.queue = [];
+    this.isShowing = false;
+    this.nextId = 0;
+  }
+}
+
+export const notificationToastManager = NotificationToastManager.getInstance();

package/App/NotificationToastRenderer/NotificationToastRenderer.tsx

@@ -0,0 +1,102 @@
+import React, { useEffect, useRef, useState } from "react";
+import {
+  View,
+  Text,
+  Animated,
+  StyleSheet,
+  TouchableWithoutFeedback,
+  ViewStyle,
+} from "react-native";
+
+import { notificationToastManager } from "./NotificationToastManager";
+import { useNotificationToastState } from "./useNotificationToastState";
+import { useNotificationHeight } from "./useNotificationHeight";
+
+const styles = StyleSheet.create({
+  notificationView: {
+    flex: 1,
+    position: "absolute",
+    alignItems: "center",
+    justifyContent: "center",
+    top: 0,
+    left: 0,
+    right: 0,
+  },
+});
+
+type NumberBoolean = 0 | 1;
+
+export const NotificationToastRenderer = ({ children }) => {
+  const { statusHeight, notificationHeight } = useNotificationHeight();
+
+  const toast = useNotificationToastState();
+
+  const [notificationOpacity, setNotificationOpacity] =
+    useState<NumberBoolean>(0);
+
+  const yPosition = useRef(new Animated.Value(0)).current;
+
+  const backgroundColor = toast?.style?.backgroundColor ?? "#000";
+  const color = toast?.style?.color ?? "#fff";
+
+  const textStyles = {
+    color,
+    fontFamily: toast?.style?.fontFamily,
+    fontSize: toast?.style?.fontSize,
+    lineHeight: toast?.style?.lineHeight,
+    letterSpacing: toast?.style?.letterSpacing,
+  };
+
+  const animatedViewStyles: ViewStyle = {
+    ...styles.notificationView,
+    transform: [
+      {
+        translateY: yPosition.interpolate({
+          inputRange: [0, 1],
+          outputRange: [-notificationHeight, 0],
+        }),
+      },
+    ],
+    opacity: notificationOpacity,
+    height: notificationHeight,
+    width: "100%",
+
+    backgroundColor,
+  };
+
+  useEffect(() => {
+    if (toast) {
+      setNotificationOpacity(1);
+
+      Animated.timing(yPosition, {
+        toValue: 1,
+        useNativeDriver: true,
+        duration: 300,
+      }).start();
+    } else {
+      Animated.timing(yPosition, {
+        toValue: 0,
+        useNativeDriver: true,
+        duration: 300,
+      }).start(() => setNotificationOpacity(0));
+    }
+  }, [toast]);
+
+  return (
+    <View testID="NotificationToastRenderer" style={StyleSheet.absoluteFill}>
+      {children}
+      <TouchableWithoutFeedback
+        testID="NotificationToastRenderer-touchable"
+        style={styles.notificationView}
+        onPress={() => notificationToastManager.dismiss()}
+      >
+        <Animated.View style={animatedViewStyles}>
+          <View style={{ height: statusHeight, backgroundColor }} />
+          <Text testID="NotificationToastRenderer-message" style={textStyles}>
+            {toast?.message}
+          </Text>
+        </Animated.View>
+      </TouchableWithoutFeedback>
+    </View>
+  );
+};

package/App/NotificationToastRenderer/NotificationToastRenderer.web.tsx

@@ -0,0 +1,61 @@
+import * as React from "react";
+
+import { notificationToastManager } from "./NotificationToastManager";
+import { useNotificationToastState } from "./useNotificationToastState";
+
+const styles: Record<string, React.CSSProperties> = {
+  body: {
+    position: "absolute",
+    bottom: 0,
+    left: 0,
+    right: 0,
+    width: 1920,
+    height: 200,
+    background:
+      "linear-gradient(180deg, rgba(17,17,17,0.9) 0%, rgba(17,17,17,1) 49%, rgba(0,0,0,0.85) 100%)",
+    display: "flex",
+    alignItems: "center",
+    justifyContent: "center",
+    flexDirection: "column",
+    color: "#fff",
+    paddingBottom: 15,
+  },
+  title: {
+    fontSize: 28,
+    margin: 0,
+    padding: 0,
+  },
+  subtitle: {
+    fontSize: 20,
+    margin: 0,
+    padding: 0,
+  },
+};
+
+export const NotificationToastRenderer = ({ children }) => {
+  const toast = useNotificationToastState();
+
+  return (
+    <div
+      data-testid="NotificationToastRenderer"
+      onClick={() => notificationToastManager.dismiss()}
+    >
+      {children}
+      {toast ? (
+        <div
+          data-testid="NotificationToastRenderer-touchable"
+          style={styles.body}
+        >
+          <div style={styles.title}>
+            <h2 data-testid="NotificationToastRenderer-message">
+              {toast.message}
+            </h2>
+          </div>
+          {toast.extraMessage ? (
+            <h4 style={styles.subtitle}>{toast.extraMessage}</h4>
+          ) : null}
+        </div>
+      ) : null}
+    </div>
+  );
+};

package/App/NotificationToastRenderer/__tests__/NotificationToastManager.test.ts

@@ -0,0 +1,213 @@
+import {
+  notificationToastManager,
+  NOTIFICATION_TOAST_EVENTS,
+} from "../NotificationToastManager";
+import { postEvent } from "@applicaster/zapp-react-native-utils/reactHooks/useSubscriberFor";
+
+jest.useFakeTimers();
+
+// notificationToastManager is a module-level singleton with a private
+// queue/isShowing/nextId, so every test must register its handlers through
+// `on()` (tracked below for cleanup) and fully drain the queue afterwards -
+// otherwise state leaks into the next test.
+describe("NotificationToastManager", () => {
+  let registered: Array<[string, (...args: any[]) => void]> = [];
+
+  const on = (event: string, handler: (...args: any[]) => void) => {
+    notificationToastManager.on(event, handler);
+    registered.push([event, handler]);
+  };
+
+  beforeAll(() => {
+    jest.spyOn(console, "log").mockImplementation(() => {});
+  });
+
+  afterAll(() => {
+    (console.log as jest.Mock).mockRestore();
+  });
+
+  afterEach(() => {
+    registered.forEach(([event, handler]) =>
+      notificationToastManager.removeHandler(event, handler)
+    );
+
+    registered = [];
+
+    // drain whatever is left showing/queued so the next test starts clean
+    notificationToastManager.reset();
+
+    jest.clearAllTimers();
+    jest.restoreAllMocks();
+    jest.spyOn(console, "log").mockImplementation(() => {});
+  });
+
+  it("emits SHOW with the toast payload when showToast is called", () => {
+    const onShow = jest.fn();
+    on(NOTIFICATION_TOAST_EVENTS.SHOW, onShow);
+
+    notificationToastManager.showToast({ id: "t1", message: "hello" });
+
+    expect(onShow).toHaveBeenCalledWith(
+      expect.objectContaining({ id: "t1", message: "hello" }),
+      expect.any(Function)
+    );
+  });
+
+  it("auto-generates distinct ids for payloads that don't provide one", () => {
+    const onShow = jest.fn();
+    on(NOTIFICATION_TOAST_EVENTS.SHOW, onShow);
+
+    notificationToastManager.showToast({ message: "first" });
+    const firstId = onShow.mock.calls[0][0].id;
+
+    notificationToastManager.dismiss();
+
+    notificationToastManager.showToast({ message: "second" });
+    const secondId = onShow.mock.calls[1][0].id;
+
+    expect(typeof firstId).toBe("string");
+    expect(firstId).not.toEqual(secondId);
+  });
+
+  it("keeps a caller-provided id instead of generating one", () => {
+    const onShow = jest.fn();
+    on(NOTIFICATION_TOAST_EVENTS.SHOW, onShow);
+
+    notificationToastManager.showToast({ id: "custom-id", message: "hi" });
+
+    expect(onShow).toHaveBeenCalledWith(
+      expect.objectContaining({ id: "custom-id" }),
+      expect.any(Function)
+    );
+  });
+
+  it("queues a second toast and shows it only after the first is dismissed", () => {
+    const onShow = jest.fn();
+    on(NOTIFICATION_TOAST_EVENTS.SHOW, onShow);
+
+    notificationToastManager.showToast({ id: "a", message: "first" });
+    notificationToastManager.showToast({ id: "b", message: "second" });
+
+    expect(onShow).toHaveBeenCalledTimes(1);
+
+    expect(onShow).toHaveBeenCalledWith(
+      expect.objectContaining({ id: "a" }),
+      expect.any(Function)
+    );
+
+    notificationToastManager.dismiss();
+
+    expect(onShow).toHaveBeenCalledTimes(2);
+
+    expect(onShow).toHaveBeenLastCalledWith(
+      expect.objectContaining({ id: "b" }),
+      expect.any(Function)
+    );
+  });
+
+  it("auto-hides after the timeout and advances to the next queued toast", () => {
+    const onShow = jest.fn();
+    const onHide = jest.fn();
+    on(NOTIFICATION_TOAST_EVENTS.SHOW, onShow);
+    on(NOTIFICATION_TOAST_EVENTS.HIDE, onHide);
+
+    notificationToastManager.showToast({
+      id: "a",
+      message: "first",
+      timeout: 1000,
+    });
+
+    notificationToastManager.showToast({ id: "b", message: "second" });
+
+    jest.advanceTimersByTime(1000);
+
+    expect(onHide).toHaveBeenCalledTimes(1);
+
+    expect(onShow).toHaveBeenLastCalledWith(
+      expect.objectContaining({ id: "b" }),
+      expect.any(Function)
+    );
+  });
+
+  it("does nothing when dismiss is called with no toast showing", () => {
+    const onHide = jest.fn();
+    on(NOTIFICATION_TOAST_EVENTS.HIDE, onHide);
+
+    notificationToastManager.dismiss();
+
+    expect(onHide).not.toHaveBeenCalled();
+  });
+
+  it("updates a still-queued (not yet shown) toast in place instead of duplicating it", () => {
+    const onShow = jest.fn();
+    on(NOTIFICATION_TOAST_EVENTS.SHOW, onShow);
+
+    notificationToastManager.showToast({ id: "a", message: "first" });
+    notificationToastManager.showToast({ id: "b", message: "second" });
+    notificationToastManager.showToast({ id: "b", message: "second updated" });
+
+    notificationToastManager.dismiss();
+
+    expect(onShow).toHaveBeenCalledTimes(2);
+
+    expect(onShow).toHaveBeenLastCalledWith(
+      expect.objectContaining({ id: "b", message: "second updated" }),
+      expect.any(Function)
+    );
+  });
+
+  it("swaps the content of the currently visible toast when re-shown with the same id", () => {
+    const onShow = jest.fn();
+    on(NOTIFICATION_TOAST_EVENTS.SHOW, onShow);
+
+    notificationToastManager.showToast({
+      id: "a",
+      message: "first",
+      timeout: 5000,
+    });
+
+    notificationToastManager.showToast({ id: "a", message: "first updated" });
+
+    expect(onShow).toHaveBeenCalledTimes(2);
+
+    expect(onShow).toHaveBeenLastCalledWith(
+      expect.objectContaining({ id: "a", message: "first updated" }),
+      expect.any(Function)
+    );
+
+    // old timer must have been cleared, not still pending
+    jest.advanceTimersByTime(5000);
+    expect(onShow).toHaveBeenCalledTimes(2);
+  });
+
+  it("routes cross-package showToast events via the shared event bus", () => {
+    const onShow = jest.fn();
+    on(NOTIFICATION_TOAST_EVENTS.SHOW, onShow);
+
+    postEvent(NOTIFICATION_TOAST_EVENTS.SHOW_TOAST, [
+      { id: "bus", message: "from event bus" },
+    ]);
+
+    expect(onShow).toHaveBeenCalledWith(
+      expect.objectContaining({ id: "bus", message: "from event bus" }),
+      expect.any(Function)
+    );
+  });
+
+  it("stops emitting to a handler after it has been removed", () => {
+    const onShow = jest.fn();
+    notificationToastManager.on(NOTIFICATION_TOAST_EVENTS.SHOW, onShow);
+
+    notificationToastManager.removeHandler(
+      NOTIFICATION_TOAST_EVENTS.SHOW,
+      onShow
+    );
+
+    notificationToastManager.showToast({
+      id: "removed-handler",
+      message: "hello",
+    });
+
+    expect(onShow).not.toHaveBeenCalled();
+  });
+});

package/App/NotificationToastRenderer/__tests__/NotificationToastRenderer.test.tsx

@@ -0,0 +1,85 @@
+import React from "react";
+import { Text } from "react-native";
+import { act, fireEvent, render } from "@testing-library/react-native";
+
+import { notificationToastManager } from "../NotificationToastManager";
+import { NotificationToastRenderer } from "../NotificationToastRenderer";
+
+jest.mock("react-native-safe-area-context", () => ({
+  useSafeAreaInsets: () => ({ top: 44 }),
+}));
+
+describe("NotificationToastRenderer", () => {
+  beforeAll(() => {
+    jest.spyOn(console, "log").mockImplementation(() => {});
+  });
+
+  afterAll(() => {
+    (console.log as jest.Mock).mockRestore();
+  });
+
+  afterEach(() => {
+    // drain whatever is left showing/queued so the next test starts clean
+    for (let i = 0; i < 10; i++) {
+      notificationToastManager.dismiss();
+    }
+
+    jest.restoreAllMocks();
+    jest.spyOn(console, "log").mockImplementation(() => {});
+  });
+
+  it("renders its children", () => {
+    const { getByText } = render(
+      <NotificationToastRenderer>
+        <Text>child content</Text>
+      </NotificationToastRenderer>
+    );
+
+    expect(getByText("child content")).toBeTruthy();
+  });
+
+  it("shows no message before any toast is emitted", () => {
+    const { getByTestId } = render(<NotificationToastRenderer />);
+
+    expect(
+      getByTestId("NotificationToastRenderer-message").props.children
+    ).toBeUndefined();
+  });
+
+  it("displays the message from a toast emitted by the manager", () => {
+    const { getByTestId } = render(<NotificationToastRenderer />);
+
+    act(() => {
+      notificationToastManager.showToast({ message: "You are offline" });
+    });
+
+    expect(
+      getByTestId("NotificationToastRenderer-message").props.children
+    ).toBe("You are offline");
+  });
+
+  it("applies the toast's style to the message text", () => {
+    const { getByTestId } = render(<NotificationToastRenderer />);
+
+    act(() => {
+      notificationToastManager.showToast({
+        message: "styled",
+        style: { color: "#123456", fontSize: 20 },
+      });
+    });
+
+    expect(
+      getByTestId("NotificationToastRenderer-message").props.style
+    ).toEqual(expect.objectContaining({ color: "#123456", fontSize: 20 }));
+  });
+
+  it("dismisses the toast when the touchable area is pressed", () => {
+    const dismissSpy = jest.spyOn(notificationToastManager, "dismiss");
+
+    const { getByTestId } = render(<NotificationToastRenderer />);
+
+    fireEvent.press(getByTestId("NotificationToastRenderer-touchable"));
+
+    expect(dismissSpy).toHaveBeenCalled();
+  });
+});

package/App/NotificationToastRenderer/__tests__/NotificationToastRenderer.web.test.tsx

@@ -0,0 +1,90 @@
+import React from "react";
+import { Text } from "react-native";
+import TestRenderer, { act } from "react-test-renderer";
+
+import { notificationToastManager } from "../NotificationToastManager";
+import { NotificationToastRenderer } from "../NotificationToastRenderer.web";
+
+// This variant renders plain DOM tags (div/h2/h4) for web, which
+// @testing-library/react-native's `render` cannot host-detect, so it is
+// exercised directly with react-test-renderer instead.
+describe("NotificationToastRenderer (web)", () => {
+  beforeAll(() => {
+    jest.spyOn(console, "log").mockImplementation(() => {});
+  });
+
+  afterAll(() => {
+    (console.log as jest.Mock).mockRestore();
+  });
+
+  afterEach(() => {
+    for (let i = 0; i < 10; i++) {
+      notificationToastManager.dismiss();
+    }
+
+    jest.restoreAllMocks();
+    jest.spyOn(console, "log").mockImplementation(() => {});
+  });
+
+  const createRenderer = (element: React.ReactElement) => {
+    let renderer;
+
+    act(() => {
+      renderer = TestRenderer.create(element);
+    });
+
+    return renderer;
+  };
+
+  it("renders its children", () => {
+    const renderer = createRenderer(
+      <NotificationToastRenderer>
+        <Text>child content</Text>
+      </NotificationToastRenderer>
+    );
+
+    expect(renderer.root.findByType(Text).props.children).toBe("child content");
+  });
+
+  it("renders nothing for the toast body until a toast is shown", () => {
+    const renderer = createRenderer(<NotificationToastRenderer />);
+
+    expect(
+      renderer.root.findAll(
+        (node) =>
+          node.props["data-testid"] === "NotificationToastRenderer-touchable"
+      )
+    ).toHaveLength(0);
+  });
+
+  it("shows the toast message once the manager emits one", () => {
+    const renderer = createRenderer(<NotificationToastRenderer />);
+
+    act(() => {
+      notificationToastManager.showToast({ message: "You are offline" });
+    });
+
+    const message = renderer.root.find(
+      (node) =>
+        node.props["data-testid"] === "NotificationToastRenderer-message"
+    );
+
+    expect(message.props.children).toBe("You are offline");
+  });
+
+  it("dismisses the toast when the root element is clicked", () => {
+    const dismissSpy = jest.spyOn(notificationToastManager, "dismiss");
+
+    const renderer = createRenderer(<NotificationToastRenderer />);
+
+    const root = renderer.root.find(
+      (node) => node.props["data-testid"] === "NotificationToastRenderer"
+    );
+
+    act(() => {
+      root.props.onClick();
+    });
+
+    expect(dismissSpy).toHaveBeenCalled();
+  });
+});

package/App/NotificationToastRenderer/__tests__/useNotificationHeight.test.tsx

@@ -0,0 +1,58 @@
+import { renderHook } from "@testing-library/react-native";
+
+let mockInsets = { top: 0 };
+const mockGetNavbarHeight = jest.fn();
+
+jest.mock("react-native-safe-area-context", () => ({
+  useSafeAreaInsets: () => mockInsets,
+}));
+
+jest.mock("@applicaster/zapp-react-native-utils/reactHooks/layout", () => ({
+  getNavbarHeight: () => mockGetNavbarHeight(),
+}));
+
+import { useNotificationHeight } from "../useNotificationHeight";
+
+describe("useNotificationHeight", () => {
+  beforeEach(() => {
+    mockGetNavbarHeight.mockClear();
+  });
+
+  it("adds the safe area top inset to the nav bar height", () => {
+    mockInsets = { top: 44 };
+    mockGetNavbarHeight.mockReturnValueOnce(56);
+
+    const { result } = renderHook(() => useNotificationHeight());
+
+    expect(result.current).toEqual({
+      statusHeight: 44,
+      notificationHeight: 100,
+    });
+  });
+
+  it("falls back to a 0 status height when there is no top inset", () => {
+    mockInsets = { top: 0 };
+    mockGetNavbarHeight.mockReturnValueOnce(44);
+
+    const { result } = renderHook(() => useNotificationHeight());
+
+    expect(result.current).toEqual({
+      statusHeight: 0,
+      notificationHeight: 44,
+    });
+  });
+
+  it("uses getNavbarHeight for the nav bar height", () => {
+    mockInsets = { top: 20 };
+    mockGetNavbarHeight.mockReturnValueOnce(56);
+
+    const { result } = renderHook(() => useNotificationHeight());
+
+    expect(mockGetNavbarHeight).toHaveBeenCalled();
+
+    expect(result.current).toEqual({
+      statusHeight: 20,
+      notificationHeight: 76,
+    });
+  });
+});

package/App/NotificationToastRenderer/__tests__/useNotificationToastState.test.ts

@@ -0,0 +1,112 @@
+import { act, renderHook } from "@testing-library/react-native";
+
+import { notificationToastManager } from "../NotificationToastManager";
+import { useNotificationToastState } from "../useNotificationToastState";
+
+jest.useFakeTimers();
+
+describe("useNotificationToastState", () => {
+  beforeAll(() => {
+    jest.spyOn(console, "log").mockImplementation(() => {});
+  });
+
+  afterAll(() => {
+    (console.log as jest.Mock).mockRestore();
+  });
+
+  afterEach(() => {
+    // drain whatever is left showing/queued so the next test starts clean;
+    // the hook's own effect cleanup (on unmount) removes its SHOW/HIDE
+    // handlers automatically via RNTL's auto-cleanup.
+    for (let i = 0; i < 10; i++) {
+      notificationToastManager.dismiss();
+    }
+
+    jest.restoreAllMocks();
+    jest.spyOn(console, "log").mockImplementation(() => {});
+  });
+
+  it("starts with no toast", () => {
+    const { result } = renderHook(() => useNotificationToastState());
+
+    expect(result.current).toBeNull();
+  });
+
+  it("reflects the toast emitted by the manager's SHOW event", () => {
+    const { result } = renderHook(() => useNotificationToastState());
+
+    act(() => {
+      notificationToastManager.showToast({ message: "hello" });
+    });
+
+    expect(result.current).toEqual(
+      expect.objectContaining({ message: "hello" })
+    );
+  });
+
+  it("clears the toast when the manager emits HIDE", () => {
+    const { result } = renderHook(() => useNotificationToastState());
+
+    act(() => {
+      notificationToastManager.showToast({ message: "hello" });
+    });
+
+    expect(result.current).not.toBeNull();
+
+    act(() => {
+      notificationToastManager.dismiss();
+    });
+
+    expect(result.current).toBeNull();
+  });
+
+  it("stops updating after unmount", () => {
+    const { result, unmount } = renderHook(() => useNotificationToastState());
+
+    unmount();
+
+    act(() => {
+      notificationToastManager.showToast({ message: "after unmount" });
+    });
+
+    expect(result.current).toBeNull();
+  });
+
+  it("subscribes on mount and disposes the subscription on unmount", () => {
+    const dispose = jest.fn();
+
+    const subscribeSpy = jest
+      .spyOn(notificationToastManager, "subscribe")
+      .mockReturnValue(dispose);
+
+    const { unmount } = renderHook(() => useNotificationToastState());
+
+    expect(subscribeSpy).toHaveBeenCalledWith(expect.any(Function));
+    expect(dispose).not.toHaveBeenCalled();
+
+    unmount();
+
+    expect(dispose).toHaveBeenCalledTimes(1);
+  });
+
+  it("subscribe registers SHOW/HIDE handlers and its disposer removes them", () => {
+    const callback = jest.fn();
+
+    const dispose = notificationToastManager.subscribe(callback);
+
+    act(() => {
+      notificationToastManager.showToast({ message: "hello" }); // emits SHOW
+    });
+
+    expect(callback).toHaveBeenCalled();
+
+    callback.mockClear();
+    dispose();
+
+    act(() => {
+      notificationToastManager.showToast({ message: "again" }); // emits SHOW
+    });
+
+    expect(callback).not.toHaveBeenCalled();
+  });
+});

package/App/NotificationToastRenderer/index.tsx

@@ -0,0 +1,5 @@
+export { notificationToastManager } from "./NotificationToastManager";
+
+export { NotificationToastRenderer } from "./NotificationToastRenderer";
+
+export { useNotificationHeight } from "./useNotificationHeight";

package/App/NotificationToastRenderer/useNotificationHeight.tsx

@@ -0,0 +1,13 @@
+import { useSafeAreaInsets } from "react-native-safe-area-context";
+import { getNavbarHeight } from "@applicaster/zapp-react-native-utils/reactHooks/layout";
+
+export const useNotificationHeight = () => {
+  const insets = useSafeAreaInsets();
+
+  const navBarHeight = getNavbarHeight();
+
+  const statusHeight = insets.top;
+  const notificationHeight = statusHeight + navBarHeight;
+
+  return { statusHeight, notificationHeight };
+};

package/App/NotificationToastRenderer/useNotificationToastState.tsx

@@ -0,0 +1,12 @@
+import * as React from "react";
+
+import { notificationToastManager } from "./NotificationToastManager";
+
+export const useNotificationToastState = () => {
+  const state = React.useSyncExternalStore(
+    notificationToastManager.subscribe,
+    notificationToastManager.getCurrentState
+  );
+
+  return state;
+};

package/App/index.tsx

@@ -31,6 +31,7 @@ import { withActionExecutor } from "@applicaster/zapp-react-native-utils/actions
 import { withScreenDataContextProvider } from "@applicaster/zapp-react-native-ui-components/Contexts/ScreenDataContext";
 import { LogicAggregatorContainer } from "./LogicAggregatorContainer";
 import { LoadingOverlay } from "./LoadingOverlay";
+import { NotificationToastRenderer } from "./NotificationToastRenderer";
 import { ZappAppWrapper } from "./components/ZappAppWrapper";
 
 interface AppOptions {
@@ -67,11 +68,13 @@ const App = ({
               <ErrorBoundary>
                 <URLSchemeListener>
                   <SplashLoader>
-                    <OfflineHandler>
-                      <Layout>
-                        <RouteManager />
-                      </Layout>
-                    </OfflineHandler>
+                    <NotificationToastRenderer>
+                      <OfflineHandler>
+                        <Layout>
+                          <RouteManager />
+                        </Layout>
+                      </OfflineHandler>
+                    </NotificationToastRenderer>
                   </SplashLoader>
                   <ModalProvider />
                 </URLSchemeListener>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@applicaster/quick-brick-core",
-  "version": "16.0.0-alpha.8525514228",
+  "version": "16.0.0-alpha.8716141508",
   "description": "Core package for Applicaster's Quick Brick App",
   "main": "index.js",
   "types": "index.d.ts",
@@ -28,13 +28,13 @@
   },
   "homepage": "https://github.com/applicaster/quickbrick#readme",
   "dependencies": {
-    "@applicaster/applicaster-types": "16.0.0-alpha.8525514228",
-    "@applicaster/quick-brick-core-plugins": "16.0.0-alpha.8525514228",
-    "@applicaster/zapp-pipes-v2-client": "16.0.0-alpha.8525514228",
-    "@applicaster/zapp-react-native-bridge": "16.0.0-alpha.8525514228",
-    "@applicaster/zapp-react-native-redux": "16.0.0-alpha.8525514228",
-    "@applicaster/zapp-react-native-ui-components": "16.0.0-alpha.8525514228",
-    "@applicaster/zapp-react-native-utils": "16.0.0-alpha.8525514228",
+    "@applicaster/applicaster-types": "16.0.0-alpha.8716141508",
+    "@applicaster/quick-brick-core-plugins": "16.0.0-alpha.8716141508",
+    "@applicaster/zapp-pipes-v2-client": "16.0.0-alpha.8716141508",
+    "@applicaster/zapp-react-native-bridge": "16.0.0-alpha.8716141508",
+    "@applicaster/zapp-react-native-redux": "16.0.0-alpha.8716141508",
+    "@applicaster/zapp-react-native-ui-components": "16.0.0-alpha.8716141508",
+    "@applicaster/zapp-react-native-utils": "16.0.0-alpha.8716141508",
     "atob": "^2.1.2",
     "axios": "^0.28.0",
     "btoa": "^1.2.1",