@multiplatform.one/components 6.6.0 → 7.0.0

package/src/Toast/store.ts

@@ -5,10 +5,33 @@
  * to mount — the @tamagui/toast ToastProvider machinery is self-contained
  * inside <ToastViewport />). Subscribers are notified on every mutation via
  * useSyncExternalStore-compatible subscribe/getSnapshot.
+ *
+ * ## Expiry policy (house defaults, resolved at show time)
+ *
+ * | intent            | default duration      | dismiss affordance          |
+ * |-------------------|-----------------------|-----------------------------|
+ * | accent / success  | 5s (TOAST_DEFAULT_MS) | optional (default shown)    |
+ * | warning           | 8s (TOAST_WARNING_MS) | optional (default shown)    |
+ * | error             | 12s (TOAST_ERROR_MS)  | FORCED — always shown       |
+ * | any + action      | ≥10s (ACTION_MIN)     | per intent                  |
+ * | sticky            | never auto-expires    | FORCED — always shown       |
+ *
+ * Errors persist longer than success but still auto-expire at the ceiling —
+ * a toast is transient feedback, not a status surface (page-scoped errors
+ * belong on the notify() banner route). `sticky: true` is the explicit
+ * caller opt-out, and a sticky or error toast can never ship without its
+ * close affordance: an unremovable overlay card would sit over live UI
+ * forever (the iOS drawer-blocking defect this policy retires).
  */
 
 export type ToastIntent = "accent" | "success" | "warning" | "error";
 
+/** House auto-dismiss for accent/success toasts (DG-FB-02 one-liner confirmations). */
+export const TOAST_DEFAULT_MS = 5_000;
+/** Warnings hold a little longer than confirmations. */
+export const TOAST_WARNING_MS = 8_000;
+/** Error ceiling: persists longer, but still expires unless `sticky`. */
+export const TOAST_ERROR_MS = 12_000;
 /** Minimum auto-dismiss when a toast carries an action (DG-FB-04 / Polaris). */
 export const TOAST_ACTION_MIN_MS = 10_000;
 
@@ -32,22 +55,35 @@ export interface ToastShowOptions {
   /** Semantic intent — colors the accent bar + icon. Default "accent". */
   intent?: ToastIntent;
   /**
-   * Auto-dismiss after this many ms. `0` or `Infinity` = persistent (stays
-   * until dismissed). Omit to use the viewport default (5000ms).
+   * Auto-dismiss after this many ms. Omit for the house per-intent default
+   * (5s accent/success, 8s warning, 12s error). `0` or `Infinity` are the
+   * legacy persistent escape and resolve to `sticky`.
    */
   duration?: number;
+  /**
+   * Keep the toast until explicitly dismissed. Forces the dismiss (X)
+   * affordance — a sticky toast without one would be unremovable.
+   */
+  sticky?: boolean;
   /** Optional action button (e.g. Undo) */
   action?: ToastActionOptions;
-  /** Show the close (X) button. Default true. */
+  /**
+   * Show the close (X) button. Default true. Ignored (forced true, DEV warn)
+   * for error and sticky toasts — those must stay dismissable by hand.
+   */
   dismissible?: boolean;
   /** Stable id — re-showing the same id replaces the existing toast */
   id?: string;
 }
 
-export interface ToastEntry extends ToastShowOptions {
+export interface ToastEntry extends Omit<ToastShowOptions, "duration" | "sticky"> {
   id: string;
   intent: ToastIntent;
   dismissible: boolean;
+  /** Resolved auto-dismiss in ms; `0` = persistent (sticky). */
+  duration: number;
+  /** Never auto-expires (explicit opt-in or legacy duration 0/Infinity). */
+  sticky: boolean;
   /** false while the exit animation plays, then the entry is removed */
   open: boolean;
 }
@@ -75,15 +111,51 @@ export function subscribeToasts(listener: () => void): () => void {
   };
 }
 
-/** Resolve duration: action toasts stay ≥10s; `0` / `Infinity` stay persistent. */
-function resolveToastDuration(
-  duration: number | undefined,
-  hasAction: boolean,
-): number | undefined {
-  if (duration === 0 || duration === Number.POSITIVE_INFINITY) return duration;
-  if (!hasAction) return duration;
-  if (duration === undefined) return TOAST_ACTION_MIN_MS;
-  return Math.max(duration, TOAST_ACTION_MIN_MS);
+function intentDefaultDuration(intent: ToastIntent): number {
+  if (intent === "error") return TOAST_ERROR_MS;
+  if (intent === "warning") return TOAST_WARNING_MS;
+  return TOAST_DEFAULT_MS;
+}
+
+/**
+ * Resolve the expiry + dismissibility policy for a show() payload.
+ * Exported for tests — the table above is the contract.
+ */
+export function resolveToastPolicy(options: ToastShowOptions): {
+  duration: number;
+  sticky: boolean;
+  dismissible: boolean;
+} {
+  const intent = options.intent ?? "accent";
+  const hasAction = options.action != null;
+  const sticky =
+    options.sticky === true ||
+    options.duration === 0 ||
+    options.duration === Number.POSITIVE_INFINITY;
+
+  let duration: number;
+  if (sticky) {
+    duration = 0;
+  } else {
+    const base = options.duration ?? intentDefaultDuration(intent);
+    duration = hasAction ? Math.max(base, TOAST_ACTION_MIN_MS) : base;
+  }
+
+  // Error + sticky toasts must carry the close affordance: without expiry
+  // (or with the long error ceiling) the X is the user's only way out.
+  const mustStayDismissible = sticky || intent === "error";
+  let dismissible = options.dismissible ?? true;
+  if (mustStayDismissible && !dismissible) {
+    if (process.env.NODE_ENV !== "production") {
+      console.warn(
+        `[toast] dismissible: false ignored for ${sticky ? "sticky" : "error"} toast ` +
+          `"${options.title}" — persistent toasts must stay dismissable by hand.`,
+      );
+    }
+    dismissible = true;
+  }
+
+  return { duration, sticky, dismissible };
 }
 
 /** Show a toast. Returns its id (usable with `dismissToast`). */
@@ -94,12 +166,13 @@ export function showToast(options: ToastShowOptions): string {
     clearTimeout(pendingRemoval);
     removalTimers.delete(id);
   }
-  const duration = resolveToastDuration(options.duration, options.action != null);
+  const { duration, sticky, dismissible } = resolveToastPolicy(options);
   const entry: ToastEntry = {
     intent: "accent",
-    dismissible: true,
     ...options,
-    ...(duration !== undefined ? { duration } : {}),
+    duration,
+    sticky,
+    dismissible,
     id,
     open: true,
   };
@@ -140,3 +213,64 @@ export function resetToasts(): void {
   entries = [];
   emit();
 }
+
+// ── Viewport singleton registry ───────────────────────────────
+//
+// The store is module-level, so two mounted <ToastViewport /> hosts would
+// each render every toast (double cards, double announcements). The first
+// mounted viewport owns rendering; later mounts no-op (DEV warn) and take
+// over automatically when the owner unmounts — so a screen-level viewport
+// (pokemon list) and a shell-level one (backoffice) can coexist.
+
+let viewportClaimants: string[] = [];
+const viewportListeners = new Set<() => void>();
+let warnedDuplicateViewport = false;
+
+function emitViewport() {
+  for (const listener of viewportListeners) listener();
+}
+
+/** @internal Claim viewport ownership (first claimant renders). */
+export function claimToastViewport(id: string): void {
+  if (viewportClaimants.includes(id)) return;
+  viewportClaimants = [...viewportClaimants, id];
+  if (
+    viewportClaimants.length > 1 &&
+    !warnedDuplicateViewport &&
+    process.env.NODE_ENV !== "production"
+  ) {
+    warnedDuplicateViewport = true;
+    console.warn(
+      "[toast] a second ToastViewport mounted — the first mounted viewport renders " +
+        "and this one no-ops. Mount one viewport at the app shell (NotifyHost includes it).",
+    );
+  }
+  emitViewport();
+}
+
+/** @internal Release a claim; the next claimant (if any) takes over. */
+export function releaseToastViewport(id: string): void {
+  if (!viewportClaimants.includes(id)) return;
+  viewportClaimants = viewportClaimants.filter((claimant) => claimant !== id);
+  emitViewport();
+}
+
+/** @internal Current owning viewport id (undefined while none mounted). */
+export function getToastViewportOwner(): string | undefined {
+  return viewportClaimants[0];
+}
+
+/** @internal Subscribe to ownership changes (useSyncExternalStore shape). */
+export function subscribeToastViewport(listener: () => void): () => void {
+  viewportListeners.add(listener);
+  return () => {
+    viewportListeners.delete(listener);
+  };
+}
+
+/** @internal test helper */
+export function __resetToastViewportRegistry(): void {
+  viewportClaimants = [];
+  warnedDuplicateViewport = false;
+  emitViewport();
+}

package/src/Tooltip/Tooltip.lc50.spec.tsx

@@ -0,0 +1,52 @@
+/**
+ * @vitest-environment jsdom
+ */
+
+/**
+ * LC-82 TEXT-RIDES-TEXT (catalog arm): Tooltip's content slot wraps ALL bare
+ * string/number content — runs of adjacent strings coalesce into TooltipText
+ * — so `{label}{cond ? suffix : ""}` renders the concatenated text instead
+ * of tripping the native "Text strings must be rendered within a <Text>
+ * component" invariant.
+ *
+ * The slot is specced via the exported `wrapTooltipContent` (the exact
+ * function the component renders into TooltipContent): tamagui's Tooltip
+ * popper never mounts its content in jsdom/happy-dom (no layout), so the
+ * open-tooltip path cannot be driven in unit tests — every other spec in the
+ * repo mocks Tooltip away entirely.
+ */
+
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { View } from "tamagui";
+import { wrapTooltipContent } from "./index";
+
+describe("Tooltip LC-82 TEXT-RIDES-TEXT", () => {
+  it("renders array-of-strings content as one concatenated wrapped run", () => {
+    renderWithProviders(<View>{wrapTooltipContent(["Save", " (Cmd+S)"], {})}</View>);
+    const content = screen.getByText("Save (Cmd+S)");
+    expect(content).toBeInTheDocument();
+    expect(content.tagName).not.toBe("DIV");
+  });
+
+  it('renders the origin shape `{label}{cond ? suffix : ""}` when the condition is false', () => {
+    const count: number = 0;
+    renderWithProviders(
+      <View>{wrapTooltipContent(["Refresh", count !== 0 ? ` (${count})` : ""], {})}</View>,
+    );
+    const content = screen.getByText("Refresh");
+    expect(content.tagName).not.toBe("DIV");
+  });
+
+  it("still renders a singleton string content wrapped", () => {
+    renderWithProviders(<View>{wrapTooltipContent("Hint", {})}</View>);
+    const content = screen.getByText("Hint");
+    expect(content.tagName).not.toBe("DIV");
+  });
+
+  it("passes element content through untouched", () => {
+    const node = <View testID="custom-content" />;
+    expect(wrapTooltipContent(node, {})).toBe(node);
+  });
+});

package/src/Tooltip/Tooltip.spec.tsx

@@ -0,0 +1,99 @@
+/**
+ * @vitest-environment jsdom
+ */
+
+import { fireEvent } from "@testing-library/react";
+import { __resetDevWarnSeen } from "@multiplatform.one/theme";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { Button } from "@multiplatform.one/forms";
+import {
+  Tooltip,
+  __resetTooltipSkipForTests,
+  noteTooltipClosed,
+  resolveTooltipDelay,
+  resolveTooltipPadRecipe,
+  resolveTooltipSizeRecipe,
+  tooltipPadRecipes,
+  tooltipSizeRecipes,
+  TOOLTIP_COLLISION_PADDING_PX,
+  TOOLTIP_DEFAULT_DELAY_MS,
+  TOOLTIP_OFFSET_PX,
+  TOOLTIP_SKIP_DELAY_MS,
+} from "./index";
+
+describe("Tooltip size vs space recipes", () => {
+  it("size steps max-width and does not change pad", () => {
+    expect(resolveTooltipSizeRecipe("small").maxWidth).toBe(tooltipSizeRecipes.small.maxWidth);
+    expect(resolveTooltipSizeRecipe("large").maxWidth).toBe(tooltipSizeRecipes.large.maxWidth);
+    expect(resolveTooltipSizeRecipe("small").maxWidth).not.toBe(
+      resolveTooltipSizeRecipe("large").maxWidth,
+    );
+    expect(resolveTooltipPadRecipe("medium")).toEqual(tooltipPadRecipes.medium);
+  });
+
+  it("space steps pad and does not change max-width", () => {
+    expect(resolveTooltipPadRecipe("small")).toEqual(tooltipPadRecipes.small);
+    expect(resolveTooltipPadRecipe("large")).toEqual(tooltipPadRecipes.large);
+    expect(resolveTooltipPadRecipe("small")).not.toEqual(resolveTooltipPadRecipe("large"));
+    expect(resolveTooltipSizeRecipe("medium").maxWidth).toBe(tooltipSizeRecipes.medium.maxWidth);
+  });
+
+  it("nested bubble recipes stay below the 44px press floor", () => {
+    expect(tooltipSizeRecipes.medium.maxWidth).toBeGreaterThan(44);
+    expect(tooltipPadRecipes.medium.paddingVertical).not.toBe("$4");
+    expect(TOOLTIP_OFFSET_PX).toBe(4);
+    expect(TOOLTIP_COLLISION_PADDING_PX).toBe(8);
+  });
+});
+
+describe("Tooltip skip delay (Radix / Spectrum cooldown)", () => {
+  beforeEach(() => {
+    __resetTooltipSkipForTests();
+  });
+
+  it("uses the warmup delay until a tooltip has just closed", () => {
+    expect(resolveTooltipDelay(TOOLTIP_DEFAULT_DELAY_MS, 1_000)).toBe(TOOLTIP_DEFAULT_DELAY_MS);
+  });
+
+  it("skips the delay inside the cooldown window", () => {
+    noteTooltipClosed(1_000);
+    expect(resolveTooltipDelay(TOOLTIP_DEFAULT_DELAY_MS, 1_000 + 10)).toBe(0);
+    expect(resolveTooltipDelay(TOOLTIP_DEFAULT_DELAY_MS, 1_000 + TOOLTIP_SKIP_DELAY_MS + 1)).toBe(
+      TOOLTIP_DEFAULT_DELAY_MS,
+    );
+  });
+});
+
+describe("Tooltip interaction", () => {
+  beforeEach(() => {
+    __resetDevWarnSeen();
+    __resetTooltipSkipForTests();
+  });
+
+  afterEach(() => {
+    __resetDevWarnSeen();
+    __resetTooltipSkipForTests();
+  });
+
+  it("does not wrap the trigger when disabled", () => {
+    const { container } = renderWithProviders(
+      <Tooltip content="Nope" disabled>
+        <Button>Idle</Button>
+      </Tooltip>,
+    );
+    expect(container.querySelector("[data-tooltip='content']")).toBeNull();
+    expect(container.textContent).toContain("Idle");
+  });
+
+  it("Escape closes a controlled open tooltip without moving focus into it", () => {
+    const onOpenChange = vi.fn();
+    renderWithProviders(
+      <Tooltip content="Hint" open onOpenChange={onOpenChange}>
+        <Button>Edit</Button>
+      </Tooltip>,
+    );
+    fireEvent.keyDown(document, { key: "Escape" });
+    expect(onOpenChange).toHaveBeenCalledWith(false);
+  });
+});

package/src/Tooltip/Tooltip.stories.tsx

@@ -1,4 +1,5 @@
 import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
+import { PrinterIcon } from "@phosphor-icons/react";
 import { Button } from "@multiplatform.one/forms";
 import { YStack, XStack } from "tamagui";
 import { Tooltip } from "./index";
@@ -46,6 +47,28 @@ export const Placements: Story = {
   ),
 };
 
+export const LongContent: Story = {
+  render: () => (
+    <YStack padding="$8" alignItems="center">
+      <Tooltip content="Saving applies your new settings right away. You can change them later from Preferences.">
+        <Button>Save</Button>
+      </Tooltip>
+    </YStack>
+  ),
+};
+
+export const IconOnly: Story = {
+  render: () => (
+    <YStack padding="$8" alignItems="center">
+      <Tooltip content="Print">
+        <Button circular aria-label="Print">
+          <PrinterIcon />
+        </Button>
+      </Tooltip>
+    </YStack>
+  ),
+};
+
 export const Disabled: Story = {
   render: () => (
     <YStack padding="$8" alignItems="center">