@multiplatform.one/components 6.0.4 → 6.3.0

package/src/feedback/Notify.stories.tsx

@@ -0,0 +1,175 @@
+import { action } from "@multiplatform.one/storybook";
+import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
+import { Button } from "@multiplatform.one/forms";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { useEffect, type ReactNode } from "react";
+import { Paragraph, SizableText, XStack, YStack } from "tamagui";
+import { notify, NotifyHost, NotifyRegion, resetFeedback, type NotifyEvent } from "./index";
+import { resetToasts } from "../Toast/store";
+
+/** Demo region frame rides the knobs (G-15 story honesty): a pinned $3
+ * radius held a 7px arc at borderRadius:none (UX-P06). */
+function DemoRegion({ children }: { children: ReactNode }) {
+  const { knobProps } = useResolvedKnobs();
+  return (
+    <YStack
+      {...knobProps.gap}
+      {...knobProps.panelPadding}
+      borderWidth={1}
+      borderColor="$borderColor"
+      {...knobProps.containerRadius}
+    >
+      {children}
+    </YStack>
+  );
+}
+
+function StoryReset() {
+  useEffect(() => {
+    resetToasts();
+    resetFeedback();
+    return () => {
+      resetToasts();
+      resetFeedback();
+    };
+  }, []);
+  return null;
+}
+
+const meta: Meta = {
+  title: "Components/Notify",
+  parameters: {
+    status: { type: "beta" },
+    docs: {
+      description: {
+        component:
+          "Semantic `notify({ severity, scope, blocking, action, title, body })` router (DG-FB-01..04). Success/info page → toast; error/warning page → sticky banner; field/section → inline Alert; error|warning + blocking → ConfirmDialog (alertdialog; error is destructive). Errors never auto-dismiss; action toasts stay ≥10s.",
+      },
+    },
+  },
+};
+export default meta;
+
+type Story = StoryObj;
+
+const cases: Array<{ label: string; event: NotifyEvent }> = [
+  {
+    label: "success → toast",
+    event: { severity: "success", scope: "page", body: "Customer record updated." },
+  },
+  {
+    label: "info page → toast",
+    event: {
+      severity: "info",
+      scope: "page",
+      title: "Heads up",
+      body: "A new version is available.",
+    },
+  },
+  {
+    label: "success + action (≥10s)",
+    event: {
+      severity: "success",
+      scope: "page",
+      body: "Message archived.",
+      action: { label: "Undo", onPress: () => action("undo")() },
+    },
+  },
+  {
+    label: "error page → banner",
+    event: {
+      severity: "error",
+      scope: "page",
+      title: "Save failed",
+      body: "The server rejected the request.",
+      action: { label: "Retry", onPress: () => action("retry")() },
+    },
+  },
+  {
+    label: "error + blocking → dialog",
+    event: {
+      severity: "error",
+      scope: "page",
+      blocking: true,
+      title: "Payment failed",
+      body: "Your card was declined. Update payment method to continue.",
+      action: { label: "Update payment", onPress: () => action("update-payment")() },
+    },
+  },
+  {
+    label: "warning + blocking → dialog",
+    event: {
+      severity: "warning",
+      scope: "page",
+      blocking: true,
+      title: "Unsaved changes",
+      body: "Leave this page? Your edits will be lost.",
+      action: { label: "Leave anyway", onPress: () => action("leave")() },
+    },
+  },
+  {
+    label: "info section → alert",
+    event: {
+      severity: "info",
+      scope: "section",
+      title: "Address check",
+      body: "Confirm the shipping address before submitting.",
+    },
+  },
+  {
+    label: "error field → alert",
+    event: {
+      severity: "error",
+      scope: "field",
+      title: "Invalid email",
+      body: "Enter a valid email address.",
+    },
+  },
+];
+
+/** Fire every routing branch from buttons; host renders toast/banner/dialog/regions. */
+export const RoutingTable: Story = {
+  name: "Routing table",
+  render: () => (
+    <NotifyHost>
+      <StoryReset />
+      <YStack gap="$4" padding="$4" maxWidth={720}>
+        <SizableText fontWeight="700" fontSize="$5">
+          notify() routing
+        </SizableText>
+        <Paragraph size="$3" color="$color11">
+          Success and page info go to toast. Page errors/warnings become sticky banners. Field and
+          section scopes render inline alerts in the regions below. Blocking error/warning opens a
+          ConfirmDialog (alertdialog; Escape/Cancel dismisses; error confirm is destructive).
+        </Paragraph>
+        <XStack gap="$2" flexWrap="wrap">
+          {cases.map(({ label, event: ev }) => (
+            <Button
+              key={label}
+              onPress={() => {
+                action("notify")(ev);
+                notify(ev);
+              }}
+            >
+              {label}
+            </Button>
+          ))}
+        </XStack>
+        <DemoRegion>
+          <SizableText fontWeight="600">Section region</SizableText>
+          <NotifyRegion scope="section" />
+          <Paragraph size="$2" color="$color10">
+            Section-scoped notify() alerts land here.
+          </Paragraph>
+        </DemoRegion>
+        <DemoRegion>
+          <SizableText fontWeight="600">Field region</SizableText>
+          <NotifyRegion scope="field" compact />
+          <Paragraph size="$2" color="$color10">
+            Field-scoped notify() alerts land here.
+          </Paragraph>
+        </DemoRegion>
+      </YStack>
+    </NotifyHost>
+  ),
+};

package/src/feedback/NotifyHost.tsx

@@ -0,0 +1,139 @@
+/**
+ * Host for notify() non-toast surfaces: page banners + blocking dialogs.
+ * Also mounts ToastViewport so a single root host covers all routes.
+ *
+ * Blocking error/warning routes render `<ConfirmDialog>` (alertdialog) — W7.
+ */
+
+import { useMemo, useSyncExternalStore, type ReactNode } from "react";
+import { zIndex } from "@multiplatform.one/forms";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { useTranslation } from "react-i18next";
+import { YStack } from "tamagui";
+import { Alert, type AlertIntent } from "../Alert";
+import { ToastViewport, type ToastViewportProps } from "../Toast";
+import { ConfirmDialog } from "./ConfirmDialog";
+import { dismissFeedback, getFeedback, subscribeFeedback, type FeedbackEntry } from "./store";
+
+export interface NotifyHostProps {
+  /** Mount ToastViewport (default true). Pass false if the app already mounts one. */
+  toastViewport?: boolean | ToastViewportProps;
+  children?: ReactNode;
+}
+
+function useFeedbackEntries(): FeedbackEntry[] {
+  return useSyncExternalStore(subscribeFeedback, getFeedback, getFeedback);
+}
+
+function BannerStack({ entries }: { entries: FeedbackEntry[] }) {
+  // SP-GAP + SP-PAD (LC-18): the banner region's stack gap and page inset
+  // ride the space knob through the complete fragments.
+  const { knobProps } = useResolvedKnobs();
+  if (entries.length === 0) return null;
+  return (
+    <YStack {...knobProps.gap} width="100%" {...knobProps.panelPadding} zIndex={zIndex.loading}>
+      {entries.map((entry) => (
+        <Alert
+          key={entry.id}
+          intent={entry.severity as AlertIntent}
+          title={entry.title}
+          dismissible={entry.dismissible}
+          onDismiss={() => dismissFeedback(entry.id)}
+          actionLabel={entry.action?.label}
+          onAction={entry.action?.onPress}
+        >
+          {entry.body}
+        </Alert>
+      ))}
+    </YStack>
+  );
+}
+
+/**
+ * Blocking notify() surface → ConfirmDialog.
+ * error → destructive confirm; warning → warning confirm; Escape/Cancel dismisses.
+ */
+function FeedbackDialog({ entry }: { entry: FeedbackEntry | undefined }) {
+  const { t } = useTranslation();
+  const open = entry != null;
+  return (
+    <ConfirmDialog
+      open={open}
+      title={entry?.title ?? entry?.severity ?? ""}
+      body={entry?.body}
+      confirmLabel={entry?.action?.label ?? t("OK")}
+      cancelLabel={t("Cancel")}
+      destructive={entry?.severity === "error"}
+      warning={entry?.severity === "warning"}
+      onConfirm={() => {
+        entry?.action?.onPress();
+        if (entry) dismissFeedback(entry.id);
+      }}
+      onCancel={() => {
+        if (entry) dismissFeedback(entry.id);
+      }}
+      onOpenChange={(next) => {
+        if (!next && entry) dismissFeedback(entry.id);
+      }}
+    />
+  );
+}
+
+/**
+ * Inline region for section/field-scoped alerts from `notify()`.
+ * Place next to the relevant form section or field.
+ */
+export function NotifyRegion({
+  scope,
+  compact,
+}: {
+  scope: "section" | "field";
+  compact?: boolean;
+}) {
+  const all = useFeedbackEntries();
+  // SP-GAP (LC-18): inline alert stacking rides the space knob.
+  const { knobProps } = useResolvedKnobs();
+  const entries = useMemo(
+    () => all.filter((e) => e.surface === "alert" && e.scope === scope),
+    [all, scope],
+  );
+  if (entries.length === 0) return null;
+  return (
+    <YStack {...knobProps.gap} width="100%">
+      {entries.map((entry) => (
+        <Alert
+          key={entry.id}
+          intent={entry.severity as AlertIntent}
+          title={entry.title}
+          compact={compact}
+          dismissible={entry.dismissible}
+          onDismiss={() => dismissFeedback(entry.id)}
+          actionLabel={entry.action?.label}
+          onAction={entry.action?.onPress}
+        >
+          {entry.body}
+        </Alert>
+      ))}
+    </YStack>
+  );
+}
+
+/**
+ * App/story root host: page banners, blocking dialog, and (optionally) toast viewport.
+ */
+export function NotifyHost({ toastViewport = true, children }: NotifyHostProps) {
+  const all = useFeedbackEntries();
+  const banners = useMemo(() => all.filter((e) => e.surface === "banner"), [all]);
+  const dialog = useMemo(() => all.find((e) => e.surface === "dialog"), [all]);
+  const viewportProps =
+    toastViewport === true ? {} : toastViewport === false ? null : toastViewport;
+
+  return (
+    <>
+      <BannerStack entries={banners} />
+      {children}
+      <FeedbackDialog entry={dialog} />
+      {viewportProps != null ? <ToastViewport {...viewportProps} /> : null}
+    </>
+  );
+}

package/src/feedback/index.ts

@@ -0,0 +1,22 @@
+export {
+  routeNotify,
+  type NotifyAction,
+  type NotifyEvent,
+  type NotifyRoute,
+  type NotifyScope,
+  type NotifySeverity,
+  type NotifySurface,
+  type NotifyToastIntent,
+} from "./route";
+export { notify } from "./notify";
+export { NotifyHost, NotifyRegion, type NotifyHostProps } from "./NotifyHost";
+export { ConfirmDialog, type ConfirmDialogProps } from "./ConfirmDialog";
+export {
+  dismissFeedback,
+  dismissFeedbackBySurface,
+  getFeedback,
+  pushFeedback,
+  resetFeedback,
+  subscribeFeedback,
+  type FeedbackEntry,
+} from "./store";

package/src/feedback/notify.spec.ts

@@ -0,0 +1,180 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { getToasts, resetToasts, TOAST_ACTION_MIN_MS } from "../Toast/store";
+import { notify } from "./notify";
+import { routeNotify, type NotifyEvent } from "./route";
+import { getFeedback, resetFeedback } from "./store";
+
+afterEach(() => {
+  resetToasts();
+  resetFeedback();
+});
+
+const action = { label: "Retry", onPress: vi.fn() };
+
+function event(
+  partial: Partial<NotifyEvent> & Pick<NotifyEvent, "severity" | "scope">,
+): NotifyEvent {
+  return { body: "Something happened.", ...partial };
+}
+
+describe("routeNotify (DG-FB-01 routing table)", () => {
+  it("success → toast (any scope)", () => {
+    expect(routeNotify(event({ severity: "success", scope: "page" })).surface).toBe("toast");
+    expect(routeNotify(event({ severity: "success", scope: "field" })).surface).toBe("toast");
+    expect(routeNotify(event({ severity: "success", scope: "section" })).surface).toBe("toast");
+  });
+
+  it("info page → toast; info section/field → inline alert", () => {
+    expect(routeNotify(event({ severity: "info", scope: "page" })).surface).toBe("toast");
+    expect(routeNotify(event({ severity: "info", scope: "section" })).surface).toBe("alert");
+    expect(routeNotify(event({ severity: "info", scope: "field" })).surface).toBe("alert");
+  });
+
+  it("error page → banner; error section/field → alert", () => {
+    expect(routeNotify(event({ severity: "error", scope: "page" })).surface).toBe("banner");
+    expect(routeNotify(event({ severity: "error", scope: "section" })).surface).toBe("alert");
+    expect(routeNotify(event({ severity: "error", scope: "field" })).surface).toBe("alert");
+  });
+
+  it("error+blocking → dialog (never toast)", () => {
+    const route = routeNotify(event({ severity: "error", scope: "page", blocking: true }));
+    expect(route.surface).toBe("dialog");
+    expect(route.duration).toBe(0);
+  });
+
+  it("warning+blocking → dialog; warning page → banner", () => {
+    expect(routeNotify(event({ severity: "warning", scope: "page", blocking: true })).surface).toBe(
+      "dialog",
+    );
+    expect(routeNotify(event({ severity: "warning", scope: "page" })).surface).toBe("banner");
+  });
+
+  it("blocking is ignored for success/info (stay on toast/alert path)", () => {
+    expect(routeNotify(event({ severity: "success", scope: "page", blocking: true })).surface).toBe(
+      "toast",
+    );
+    expect(routeNotify(event({ severity: "info", scope: "page", blocking: true })).surface).toBe(
+      "toast",
+    );
+  });
+
+  it("errors never auto-dismiss (duration 0 on banner/alert/dialog)", () => {
+    for (const scope of ["page", "section", "field"] as const) {
+      const route = routeNotify(event({ severity: "error", scope }));
+      expect(route.duration).toBe(0);
+      expect(route.surface).not.toBe("toast");
+    }
+    expect(routeNotify(event({ severity: "error", scope: "page", blocking: true })).duration).toBe(
+      0,
+    );
+  });
+
+  it("toast with action gets ≥10s duration (DG-FB-04)", () => {
+    const route = routeNotify(event({ severity: "success", scope: "page", action }));
+    expect(route.surface).toBe("toast");
+    expect(route.duration).toBe(TOAST_ACTION_MIN_MS);
+  });
+
+  it("dismissibility gate: error banners are NOT dismissible; warning banners are", () => {
+    expect(routeNotify(event({ severity: "error", scope: "page" })).dismissible).toBe(false);
+    expect(routeNotify(event({ severity: "warning", scope: "page" })).dismissible).toBe(true);
+  });
+
+  it("dismissibility gate: info/success surfaces stay dismissible", () => {
+    expect(routeNotify(event({ severity: "info", scope: "page" })).dismissible).toBe(true);
+    expect(routeNotify(event({ severity: "info", scope: "section" })).dismissible).toBe(true);
+    expect(routeNotify(event({ severity: "success", scope: "page" })).dismissible).toBe(true);
+  });
+
+  it("dismissibility gate: explicit dismissible ejects the error-banner gate", () => {
+    expect(
+      routeNotify(event({ severity: "error", scope: "page", dismissible: true })).dismissible,
+    ).toBe(true);
+    expect(
+      routeNotify(event({ severity: "warning", scope: "page", dismissible: false })).dismissible,
+    ).toBe(false);
+  });
+
+  it("maps info → accent toast intent", () => {
+    expect(routeNotify(event({ severity: "info", scope: "page" })).toastIntent).toBe("accent");
+    expect(routeNotify(event({ severity: "success", scope: "page" })).toastIntent).toBe("success");
+    expect(routeNotify(event({ severity: "error", scope: "page" })).toastIntent).toBe("error");
+  });
+});
+
+describe("notify() delivery", () => {
+  it("success path shows a one-liner toast", () => {
+    const route = notify({
+      severity: "success",
+      scope: "page",
+      body: "Customer record updated.",
+    });
+    expect(route.surface).toBe("toast");
+    const toasts = getToasts();
+    expect(toasts).toHaveLength(1);
+    expect(toasts[0]?.title).toBe("Customer record updated.");
+    expect(toasts[0]?.intent).toBe("success");
+    expect(getFeedback()).toHaveLength(0);
+  });
+
+  it("success with title+body puts body in description", () => {
+    notify({
+      severity: "success",
+      scope: "page",
+      title: "Saved",
+      body: "Customer record updated.",
+    });
+    expect(getToasts()[0]?.title).toBe("Saved");
+    expect(getToasts()[0]?.description).toBe("Customer record updated.");
+  });
+
+  it("error page pushes a sticky banner (not toast)", () => {
+    const route = notify({
+      severity: "error",
+      scope: "page",
+      title: "Save failed",
+      body: "The server rejected the request.",
+    });
+    expect(route.surface).toBe("banner");
+    expect(getToasts()).toHaveLength(0);
+    expect(getFeedback()).toHaveLength(1);
+    expect(getFeedback()[0]?.surface).toBe("banner");
+    expect(getFeedback()[0]?.severity).toBe("error");
+    // House gate: error banner carries dismissible=false into the store.
+    expect(getFeedback()[0]?.dismissible).toBe(false);
+  });
+
+  it("error+blocking pushes a dialog", () => {
+    const route = notify({
+      severity: "error",
+      scope: "page",
+      blocking: true,
+      title: "Payment failed",
+      body: "Your card was declined.",
+      action,
+    });
+    expect(route.surface).toBe("dialog");
+    expect(getFeedback()[0]?.surface).toBe("dialog");
+    expect(getToasts()).toHaveLength(0);
+  });
+
+  it("section info pushes an inline alert", () => {
+    const route = notify({
+      severity: "info",
+      scope: "section",
+      body: "Review the shipping address.",
+    });
+    expect(route.surface).toBe("alert");
+    expect(getFeedback()[0]?.scope).toBe("section");
+  });
+
+  it("action toast duration is enforced at delivery (≥10s)", () => {
+    notify({
+      severity: "success",
+      scope: "page",
+      body: "Archived.",
+      action,
+    });
+    expect(getToasts()[0]?.duration).toBeGreaterThanOrEqual(TOAST_ACTION_MIN_MS);
+  });
+});

package/src/feedback/notify.ts

@@ -0,0 +1,54 @@
+/**
+ * Semantic `notify()` — severity × scope × blocking → toast / banner / alert / dialog.
+ *
+ * Mount `<NotifyHost />` once (app root / story) so banners and dialogs render.
+ * Inline `alert` surfaces need a `<NotifyRegion scope="section"|"field" />`
+ * near the relevant content. Toast still needs `<ToastViewport />` (included
+ * in NotifyHost by default).
+ */
+
+import { showToast } from "../Toast/store";
+import { routeNotify, type NotifyEvent, type NotifyRoute } from "./route";
+import { pushFeedback } from "./store";
+
+export type { NotifyEvent, NotifyRoute };
+
+function toastTitle(route: NotifyRoute): { title: string; description?: string } {
+  // Success path is a one-liner toast (DG-FB-02/03): prefer title, else body.
+  if (route.title) {
+    return { title: route.title, description: route.body };
+  }
+  return { title: route.body };
+}
+
+/**
+ * Route a semantic feedback event and deliver it to the matching surface.
+ * Returns the route decision (useful for tests / debugging).
+ */
+export function notify(event: NotifyEvent): NotifyRoute {
+  const route = routeNotify(event);
+
+  if (route.surface === "toast") {
+    const { title, description } = toastTitle(route);
+    showToast({
+      title,
+      description,
+      intent: route.toastIntent,
+      duration: route.duration,
+      action: route.action,
+      dismissible: route.dismissible,
+    });
+    return route;
+  }
+
+  pushFeedback({
+    surface: route.surface,
+    severity: route.severity,
+    scope: route.scope,
+    title: route.title,
+    body: route.body,
+    action: route.action,
+    dismissible: route.dismissible,
+  });
+  return route;
+}

package/src/feedback/route.ts

@@ -0,0 +1,118 @@
+/**
+ * Pure severity × scope × blocking → surface router (DG-FB-01..04).
+ *
+ * Devs declare *what happened*; this picks *how it appears*. Side-effecting
+ * delivery lives in `notify.ts` so unit tests can assert the table without
+ * mounting hosts.
+ */
+
+import { TOAST_ACTION_MIN_MS } from "../Toast/store";
+
+export type NotifySeverity = "info" | "success" | "warning" | "error";
+export type NotifyScope = "page" | "section" | "field";
+export type NotifySurface = "toast" | "banner" | "alert" | "dialog";
+
+export interface NotifyAction {
+  label: string;
+  onPress: () => void;
+}
+
+export interface NotifyEvent {
+  severity: NotifySeverity;
+  scope: NotifyScope;
+  /** Escalate to a blocking dialog (error/warning only). Ignored for info/success. */
+  blocking?: boolean;
+  action?: NotifyAction;
+  title?: string;
+  body: string;
+  /**
+   * Eject: override the severity-gated dismissibility. House default: error
+   * banners are NOT dismissible (they persist until the error state clears);
+   * every other surface/severity is dismissible.
+   */
+  dismissible?: boolean;
+}
+
+/** Toast intent mapping: info rides accent (same as Alert's info→accent theme). */
+export type NotifyToastIntent = "accent" | "success" | "warning" | "error";
+
+export interface NotifyRoute {
+  surface: NotifySurface;
+  severity: NotifySeverity;
+  scope: NotifyScope;
+  /** Toast intent (info → accent). Banner/alert/dialog use `severity` as Alert intent. */
+  toastIntent: NotifyToastIntent;
+  title?: string;
+  body: string;
+  action?: NotifyAction;
+  /**
+   * Auto-dismiss for toast surfaces. `0` = persistent.
+   * Errors never auto-dismiss (DG-FB-02); action toasts stay ≥10s (DG-FB-04).
+   */
+  duration: number | undefined;
+  dismissible: boolean;
+}
+
+function toastDuration(action?: NotifyAction): number | undefined {
+  return action ? TOAST_ACTION_MIN_MS : undefined;
+}
+
+/**
+ * Decide the feedback surface for a semantic event.
+ *
+ * Routing table:
+ * | severity | scope           | blocking | surface                          |
+ * |----------|-----------------|----------|----------------------------------|
+ * | success  | *               | *        | toast                            |
+ * | info     | page            | *        | toast                            |
+ * | info     | section \| field| *        | alert (inline)                   |
+ * | warning  | *               | true     | dialog                           |
+ * | warning  | page            | false    | banner (sticky)                  |
+ * | warning  | section \| field| false    | alert (inline)                   |
+ * | error    | *               | true     | dialog                           |
+ * | error    | page            | false    | banner (sticky)                  |
+ * | error    | section \| field| false    | alert (inline)                   |
+ *
+ * Errors never route to an auto-dismissing toast.
+ */
+export function routeNotify(event: NotifyEvent): NotifyRoute {
+  const { severity, scope, blocking = false, action, title, body } = event;
+  const toastIntent: NotifyToastIntent = severity === "info" ? "accent" : severity;
+  const base = {
+    severity,
+    scope,
+    toastIntent,
+    title,
+    body,
+    action,
+    dismissible: event.dismissible ?? true,
+  } as const;
+
+  if (blocking && (severity === "error" || severity === "warning")) {
+    return { ...base, surface: "dialog", duration: 0 };
+  }
+
+  if (severity === "success") {
+    return { ...base, surface: "toast", duration: toastDuration(action) };
+  }
+
+  if (severity === "info") {
+    if (scope === "page") {
+      return { ...base, surface: "toast", duration: toastDuration(action) };
+    }
+    return { ...base, surface: "alert", duration: 0 };
+  }
+
+  // warning | error — non-blocking
+  if (scope === "page") {
+    // House dismissibility gate: error banners persist until the error state
+    // clears — no close (X) by default. Warning banners stay dismissible.
+    return {
+      ...base,
+      surface: "banner",
+      duration: 0,
+      dismissible: event.dismissible ?? severity !== "error",
+    };
+  }
+  return { ...base, surface: "alert", duration: 0 };
+}