@multiplatform.one/components 6.1.0 → 6.4.0

package/src/feedback/store.ts

@@ -0,0 +1,71 @@
+/**
+ * Module-level store for notify() banner / inline alert / dialog surfaces.
+ * Toast delivery uses the existing Toast store (`showToast`).
+ */
+
+import type { NotifyAction, NotifyScope, NotifySeverity, NotifySurface } from "./route";
+
+export interface FeedbackEntry {
+  id: string;
+  surface: Exclude<NotifySurface, "toast">;
+  severity: NotifySeverity;
+  scope: NotifyScope;
+  title?: string;
+  body: string;
+  action?: NotifyAction;
+  dismissible: boolean;
+}
+
+let entries: FeedbackEntry[] = [];
+let counter = 0;
+const listeners = new Set<() => void>();
+
+function emit() {
+  for (const listener of listeners) listener();
+}
+
+export function getFeedback(): FeedbackEntry[] {
+  return entries;
+}
+
+export function subscribeFeedback(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+export function pushFeedback(entry: Omit<FeedbackEntry, "id"> & { id?: string }): string {
+  const id = entry.id ?? `mp-feedback-${++counter}`;
+  const next: FeedbackEntry = {
+    ...entry,
+    dismissible: entry.dismissible ?? true,
+    id,
+  };
+  // Dialogs replace any open dialog; banners/alerts stack.
+  if (next.surface === "dialog") {
+    entries = [...entries.filter((e) => e.surface !== "dialog"), next];
+  } else {
+    entries = [...entries, next];
+  }
+  emit();
+  return id;
+}
+
+export function dismissFeedback(id: string): void {
+  const before = entries.length;
+  entries = entries.filter((e) => e.id !== id);
+  if (entries.length !== before) emit();
+}
+
+export function dismissFeedbackBySurface(surface: FeedbackEntry["surface"]): void {
+  const before = entries.length;
+  entries = entries.filter((e) => e.surface !== surface);
+  if (entries.length !== before) emit();
+}
+
+/** Hard-reset (tests / story decorators). */
+export function resetFeedback(): void {
+  entries = [];
+  emit();
+}

package/src/hooks/index.ts

@@ -1,2 +1,4 @@
 export * from "./useAssets";
 export * from "./useClipboard";
+export * from "./useDirection";
+export * from "./useDocumentTitle";

package/src/hooks/useClipboard.spec.tsx

@@ -72,6 +72,32 @@ describe("useClipboard", () => {
     });
     expect(result.current.hasCopied).toBe(false);
   });
+
+  it("should not claim success when the clipboard write is denied", async () => {
+    const testText = "test text";
+    mockWriteText.mockRejectedValueOnce(new Error("NotAllowedError"));
+    const { result } = renderHook(() => useClipboard(testText));
+    let success: boolean | undefined;
+    await act(async () => {
+      success = await result.current.onCopy();
+    });
+    expect(success).toBe(false);
+    expect(result.current.hasCopied).toBe(false);
+    expect(result.current.hasCopyFailed).toBe(true);
+  });
+
+  it("should reset hasCopyFailed after timeout", async () => {
+    mockWriteText.mockRejectedValueOnce(new Error("NotAllowedError"));
+    const { result } = renderHook(() => useClipboard("x", { timeout: 1500 }));
+    await act(async () => {
+      await result.current.onCopy();
+    });
+    expect(result.current.hasCopyFailed).toBe(true);
+    act(() => {
+      vi.advanceTimersByTime(1500);
+    });
+    expect(result.current.hasCopyFailed).toBe(false);
+  });
 });
 
 describe("copyToClipboard", () => {

package/src/hooks/useClipboard.ts

@@ -11,31 +11,38 @@ export interface UseClipboardOptions {
 }
 
 /**
- * Hook for copying text to the clipboard with a "copied" state indicator.
+ * Hook for copying text to the clipboard with "copied" / "copy failed" state indicators.
  *
  * @param text - Default text to copy
- * @param options - `timeout` in ms before `hasCopied` resets (default 1500)
- * @returns `{ value, onCopy, hasCopied }`
+ * @param options - `timeout` in ms before `hasCopied` / `hasCopyFailed` reset (default 1500)
+ * @returns `{ value, onCopy, hasCopied, hasCopyFailed }`
  *
- * `onCopy` accepts an optional string argument to override the default text.
+ * `onCopy` accepts an optional string argument to override the default text and
+ * resolves to whether the clipboard write succeeded. `hasCopied` only becomes
+ * true when the write actually resolved successfully; a rejected/denied write
+ * sets `hasCopyFailed` instead.
  */
 export function useClipboard(text = "", options?: UseClipboardOptions) {
   const timeout = options?.timeout ?? 1500;
   const [hasCopied, setHasCopied] = useState(false);
+  const [hasCopyFailed, setHasCopyFailed] = useState(false);
 
   const onCopy = useEvent(async (overrideText?: string | unknown) => {
     const textToCopy = typeof overrideText === "string" ? overrideText : text;
-    await copyToClipboard(textToCopy);
-    setHasCopied(true);
+    const success = await copyToClipboard(textToCopy).catch(() => false);
+    setHasCopied(success);
+    setHasCopyFailed(!success);
+    return success;
   });
 
   useEffect(() => {
-    if (!hasCopied) return;
+    if (!hasCopied && !hasCopyFailed) return;
     const id = setTimeout(() => {
       setHasCopied(false);
+      setHasCopyFailed(false);
     }, timeout);
     return () => clearTimeout(id);
-  }, [timeout, hasCopied]);
+  }, [timeout, hasCopied, hasCopyFailed]);
 
-  return { value: text, onCopy, hasCopied };
+  return { value: text, onCopy, hasCopied, hasCopyFailed };
 }

package/src/hooks/useDirection.native.ts

@@ -0,0 +1,16 @@
+/**
+ * useDirection (native) — see useDirection.ts for the contract.
+ *
+ * React Native exposes direction through `I18nManager.isRTL`, which is fixed
+ * for the app session (changing it requires a reload), so no subscription is
+ * needed — the value cannot change while mounted.
+ */
+
+import { I18nManager } from "react-native";
+
+export type Direction = "ltr" | "rtl";
+
+/** Returns the current writing direction (`"ltr"` | `"rtl"`). */
+export function useDirection(): Direction {
+  return I18nManager.isRTL ? "rtl" : "ltr";
+}

package/src/hooks/useDirection.spec.tsx

@@ -0,0 +1,89 @@
+/**
+ * useDirection — web direction detection (RTL audit backlog #1).
+ * Covers the document-level `dir` resolution order (body wins over html),
+ * non-explicit values falling through, live reaction to `dir` flips
+ * (MutationObserver), and the ltr default.
+ */
+
+import { act, renderHook } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+import { useDirection } from "./useDirection";
+
+const clearDirs = () => {
+  document.documentElement.removeAttribute("dir");
+  document.body.removeAttribute("dir");
+};
+
+afterEach(clearDirs);
+
+describe("useDirection (web)", () => {
+  it("defaults to ltr when no dir attribute is set", () => {
+    clearDirs();
+    const { result } = renderHook(() => useDirection());
+    expect(result.current).toBe("ltr");
+  });
+
+  it("reads dir=rtl set before mount (probe pattern: dir at first paint)", () => {
+    // Element-level reflected property, exactly what the RTL probe init
+    // script sets. (happy-dom does not reflect the `document.dir` setter
+    // onto <html dir>, so tests use the element form browsers reflect.)
+    document.documentElement.dir = "rtl";
+    const { result } = renderHook(() => useDirection());
+    expect(result.current).toBe("rtl");
+  });
+
+  it("prefers the body dir over the html dir (nearest attribute wins)", () => {
+    document.documentElement.setAttribute("dir", "rtl");
+    document.body.setAttribute("dir", "ltr");
+    const { result } = renderHook(() => useDirection());
+    expect(result.current).toBe("ltr");
+
+    document.body.setAttribute("dir", "rtl");
+    document.documentElement.setAttribute("dir", "ltr");
+    const { result: flipped } = renderHook(() => useDirection());
+    expect(flipped.current).toBe("rtl");
+  });
+
+  it('treats "auto" and empty dir values as non-explicit and falls through', () => {
+    document.body.setAttribute("dir", "auto");
+    document.documentElement.setAttribute("dir", "rtl");
+    const { result } = renderHook(() => useDirection());
+    expect(result.current).toBe("rtl");
+
+    document.documentElement.setAttribute("dir", "");
+    const { result: fallback } = renderHook(() => useDirection());
+    expect(fallback.current).toBe("ltr");
+  });
+
+  it("reacts to runtime dir flips in both directions (MutationObserver)", async () => {
+    clearDirs();
+    const { result } = renderHook(() => useDirection());
+    expect(result.current).toBe("ltr");
+
+    await act(async () => {
+      document.documentElement.dir = "rtl";
+    });
+    expect(result.current).toBe("rtl");
+
+    await act(async () => {
+      document.documentElement.dir = "ltr";
+    });
+    expect(result.current).toBe("ltr");
+  });
+
+  it("reacts to body-level dir changes", async () => {
+    clearDirs();
+    const { result } = renderHook(() => useDirection());
+    expect(result.current).toBe("ltr");
+
+    await act(async () => {
+      document.body.setAttribute("dir", "rtl");
+    });
+    expect(result.current).toBe("rtl");
+
+    await act(async () => {
+      document.body.removeAttribute("dir");
+    });
+    expect(result.current).toBe("ltr");
+  });
+});

package/src/hooks/useDirection.ts

@@ -0,0 +1,67 @@
+/**
+ * useDirection — the catalog's runtime direction source (RTL audit backlog #1).
+ *
+ * CSS logical properties mirror layout for free, but directional *glyphs*
+ * (prev/next carets, expand arrows) and JS-measured geometry need to know the
+ * writing direction at runtime. This hook is that source.
+ *
+ * Web: reads the document-level `dir` attribute — `<body dir>` wins over
+ * `<html dir>` (the nearer attribute governs content per bidi inheritance);
+ * `"auto"` and empty values fall through. A MutationObserver keeps the value
+ * live, so flipping `document.dir` at runtime (e.g. the RTL probe, a locale
+ * switcher) re-renders consumers. SSR-safe via `useSyncExternalStore`: the
+ * server snapshot is `"ltr"`, hydration renders with it (no mismatch), and
+ * React re-checks the client snapshot immediately after.
+ *
+ * Native (`useDirection.native.ts`): `I18nManager.isRTL`, which is fixed for
+ * the app session (RN requires a reload to change direction).
+ */
+
+import { useSyncExternalStore } from "react";
+
+export type Direction = "ltr" | "rtl";
+
+function normalizeDir(value: string | null | undefined): Direction | undefined {
+  if (value === "rtl") return "rtl";
+  if (value === "ltr") return "ltr";
+  // "" / "auto" / unknown → not an explicit direction; keep resolving.
+  return undefined;
+}
+
+function readDocumentDirection(): Direction {
+  if (typeof document === "undefined") return "ltr";
+  return (
+    normalizeDir(document.body?.getAttribute("dir")) ??
+    normalizeDir(document.documentElement?.getAttribute("dir")) ??
+    "ltr"
+  );
+}
+
+function subscribe(onChange: () => void): () => void {
+  if (typeof document === "undefined" || typeof MutationObserver === "undefined") {
+    return () => {};
+  }
+  const observer = new MutationObserver(onChange);
+  // One observer catches <html dir>, <body dir>, and any nested island —
+  // snapshot equality in useSyncExternalStore drops the irrelevant ones.
+  observer.observe(document.documentElement, {
+    attributes: true,
+    attributeFilter: ["dir"],
+    subtree: true,
+  });
+  return () => observer.disconnect();
+}
+
+const getServerSnapshot = (): Direction => "ltr";
+
+/**
+ * Returns the current writing direction (`"ltr"` | `"rtl"`).
+ *
+ * Use it to mirror directional chrome that CSS logical properties cannot
+ * reach — swap paired glyphs (CaretLeft ⇄ CaretRight) when the icon encodes
+ * direction-of-travel. Do NOT mirror direction-neutral glyphs (search,
+ * close, checkmarks).
+ */
+export function useDirection(): Direction {
+  return useSyncExternalStore(subscribe, readDocumentDirection, getServerSnapshot);
+}

package/src/hooks/useDocumentTitle.spec.tsx

@@ -0,0 +1,88 @@
+/**
+ * DG-COPY-04 — document titles are reverse breadcrumbs.
+ * Covers pure composition (reverse order, separators, empty parts) and the
+ * hook's document.title assignment semantics.
+ */
+
+import { renderHook } from "@testing-library/react";
+import { beforeEach, describe, expect, it } from "vitest";
+import {
+  composeDocumentTitle,
+  useDocumentTitle,
+  type DocumentTitleTrail,
+} from "./useDocumentTitle";
+
+describe("composeDocumentTitle", () => {
+  it("reverses a breadcrumb trail into Leaf – Section – App", () => {
+    expect(
+      composeDocumentTitle([{ label: "Desk" }, { label: "Pokemon" }, { label: "Pikachu" }]),
+    ).toBe("Pikachu – Pokemon – Desk");
+  });
+
+  it("accepts plain strings and drops empty or nullish parts", () => {
+    expect(composeDocumentTitle(["Desk", null, { label: "   " }, "Todo", undefined])).toBe(
+      "Todo – Desk",
+    );
+  });
+
+  it("returns an empty string for empty or missing trails", () => {
+    expect(composeDocumentTitle([])).toBe("");
+    expect(composeDocumentTitle(null)).toBe("");
+    expect(composeDocumentTitle(undefined)).toBe("");
+  });
+
+  it("supports a custom separator", () => {
+    expect(composeDocumentTitle(["App", "Leaf"], " | ")).toBe("Leaf | App");
+  });
+
+  it("does not mutate the given trail", () => {
+    const trail = [{ label: "Desk" }, { label: "Todo" }];
+    composeDocumentTitle(trail);
+    expect(trail.map((p) => p.label)).toEqual(["Desk", "Todo"]);
+  });
+});
+
+describe("useDocumentTitle", () => {
+  beforeEach(() => {
+    document.title = "initial title";
+  });
+
+  it("sets document.title to the reverse breadcrumb trail (DG-COPY-04)", () => {
+    const { result } = renderHook(() =>
+      useDocumentTitle([{ label: "Desk" }, { label: "Todo" }, { label: "TODO-001" }]),
+    );
+    expect(result.current).toBe("TODO-001 – Todo – Desk");
+    expect(document.title).toBe("TODO-001 – Todo – Desk");
+  });
+
+  it("updates document.title when the trail changes", () => {
+    const { rerender } = renderHook(
+      ({ trail }: { trail: DocumentTitleTrail }) => useDocumentTitle(trail),
+      {
+        initialProps: { trail: ["Desk", "Todo"] as DocumentTitleTrail },
+      },
+    );
+    expect(document.title).toBe("Todo – Desk");
+
+    rerender({ trail: ["Desk", "Pokemon", "Pikachu"] });
+    expect(document.title).toBe("Pikachu – Pokemon – Desk");
+  });
+
+  it("leaves document.title untouched for an empty trail", () => {
+    renderHook(() => useDocumentTitle([]));
+    expect(document.title).toBe("initial title");
+  });
+
+  it("composes without assigning when enabled=false", () => {
+    const { result } = renderHook(() => useDocumentTitle(["Desk", "Todo"], { enabled: false }));
+    expect(result.current).toBe("Todo – Desk");
+    expect(document.title).toBe("initial title");
+  });
+
+  it("keeps the last title after unmount (navigation overwrites; unmount does not blank)", () => {
+    const { unmount } = renderHook(() => useDocumentTitle(["Desk", "Todo"]));
+    expect(document.title).toBe("Todo – Desk");
+    unmount();
+    expect(document.title).toBe("Todo – Desk");
+  });
+});

package/src/hooks/useDocumentTitle.ts

@@ -0,0 +1,76 @@
+/**
+ * useDocumentTitle — DG-COPY-04 "document titles are reverse breadcrumbs".
+ *
+ * Composes "Leaf – Section – App" from a breadcrumb-ordered trail (root
+ * first, exactly as passed to `<Breadcrumbs items>`) and assigns it to
+ * `document.title` on web. Native (and SSR) is a no-op — there is no
+ * `document`. An empty composed title never blanks the current one.
+ */
+
+import { useEffect, useMemo } from "react";
+
+/** Anything with a breadcrumb-style label (BreadcrumbItem is assignable). */
+export interface DocumentTitlePart {
+  label?: string | null;
+}
+
+/**
+ * Breadcrumb-ordered trail (root → leaf). Plain strings and items with a
+ * `label` are accepted; empty / nullish parts are dropped.
+ */
+export type DocumentTitleTrail = ReadonlyArray<
+  DocumentTitlePart | string | null | undefined
+> | null;
+
+/** En dash with hair spaces per DG-COPY-04: "Leaf – Section – App". */
+export const DOCUMENT_TITLE_SEPARATOR = " – ";
+
+/**
+ * Pure composition: reverse the trail (leaf first) and join. Exported for
+ * unit tests and non-hook callers.
+ */
+export function composeDocumentTitle(
+  trail: DocumentTitleTrail | undefined,
+  separator: string = DOCUMENT_TITLE_SEPARATOR,
+): string {
+  if (!trail) return "";
+  const labels = trail
+    .map((part) => (typeof part === "string" ? part : (part?.label ?? "")))
+    .map((label) => label.trim())
+    .filter(Boolean);
+  return labels.reverse().join(separator);
+}
+
+export interface UseDocumentTitleOptions {
+  /** Separator between parts. Default `" – "`. */
+  separator?: string;
+  /** Pass false to compose without assigning `document.title`. */
+  enabled?: boolean;
+}
+
+/**
+ * Sets `document.title` to the reverse of the given breadcrumb trail.
+ * Returns the composed title (empty string when the trail has no labels —
+ * in that case the current document title is left untouched).
+ *
+ * @example
+ * // breadcrumbs = [{ label: "Desk" }, { label: "Pokemon" }, { label: "Pikachu" }]
+ * useDocumentTitle(breadcrumbs); // document.title === "Pikachu – Pokemon – Desk"
+ */
+export function useDocumentTitle(
+  trail: DocumentTitleTrail | undefined,
+  options: UseDocumentTitleOptions = {},
+): string {
+  const { separator = DOCUMENT_TITLE_SEPARATOR, enabled = true } = options;
+  const title = useMemo(() => composeDocumentTitle(trail, separator), [trail, separator]);
+
+  useEffect(() => {
+    if (!enabled || !title) return;
+    // Web-only (DG-COPY-04 wires the native equivalent through navigation
+    // titles, not this hook). `document` is absent on React Native and SSR.
+    if (typeof document === "undefined") return;
+    document.title = title;
+  }, [title, enabled]);
+
+  return title;
+}

package/src/icons/CheckRegular.stories.tsx

@@ -0,0 +1,75 @@
+import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
+import { Paragraph, Theme, XStack, YStack } from "tamagui";
+import { CheckRegular } from "./CheckRegular";
+
+const meta: Meta<typeof CheckRegular> = {
+  title: "Components/CheckRegular",
+  component: CheckRegular,
+  parameters: {
+    status: { type: "beta" },
+    docs: {
+      description: {
+        component:
+          "Check icon wrapped with themed(): resolves color from the theme (token name, theme key, or CSS color) and size from size tokens.",
+      },
+    },
+  },
+  argTypes: {
+    color: { control: "text" },
+    size: { control: "text" },
+  },
+  args: {
+    size: "24",
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof CheckRegular>;
+
+export const Default: Story = {
+  name: "Main",
+  render: (args) => (
+    <CheckRegular
+      color={args.color}
+      size={/^\d+$/.test(String(args.size)) ? Number(args.size) : (args.size as any)}
+    />
+  ),
+};
+
+export const ColorModes: Story = {
+  render: () => (
+    <YStack gap="$3">
+      <XStack gap="$4" alignItems="center">
+        <Paragraph width={160}>default (theme color)</Paragraph>
+        <CheckRegular size={24} />
+      </XStack>
+      <XStack gap="$4" alignItems="center">
+        <Paragraph width={160}>theme key color10</Paragraph>
+        <CheckRegular size={24} color="color10" />
+      </XStack>
+      <XStack gap="$4" alignItems="center">
+        <Paragraph width={160}>CSS tomato</Paragraph>
+        <CheckRegular size={24} color="tomato" />
+      </XStack>
+      <XStack gap="$4" alignItems="center">
+        <Paragraph width={160}>green Theme wrapper</Paragraph>
+        <Theme name="green">
+          <CheckRegular size={24} />
+        </Theme>
+      </XStack>
+    </YStack>
+  ),
+};
+
+export const Sizes: Story = {
+  render: () => (
+    <XStack gap="$4" alignItems="center">
+      <CheckRegular size={0} />
+      <CheckRegular size={12} />
+      <CheckRegular size={16} />
+      <CheckRegular size={24} />
+      <CheckRegular size={48} />
+      <CheckRegular size="$4" />
+    </XStack>
+  ),
+};

package/src/icons/MinusRegular.stories.tsx

@@ -0,0 +1,84 @@
+import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
+import { Paragraph, Theme, XStack, YStack } from "tamagui";
+import { MinusRegular } from "./MinusRegular";
+
+const meta: Meta<typeof MinusRegular> = {
+  title: "Components/MinusRegular",
+  component: MinusRegular,
+  parameters: {
+    status: { type: "beta" },
+    docs: {
+      description: {
+        component:
+          "Minus icon wrapped with themed(): used for indeterminate checkbox state; color and size resolve through the theme.",
+      },
+    },
+  },
+  argTypes: {
+    color: { control: "text" },
+    size: { control: "text" },
+  },
+  args: {
+    size: "24",
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof MinusRegular>;
+
+export const Default: Story = {
+  name: "Main",
+  render: (args) => (
+    <MinusRegular
+      color={args.color}
+      size={/^\d+$/.test(String(args.size)) ? Number(args.size) : (args.size as any)}
+    />
+  ),
+};
+
+export const ColorModes: Story = {
+  render: () => (
+    <YStack gap="$3">
+      <XStack gap="$4" alignItems="center">
+        <Paragraph width={160}>default (theme color)</Paragraph>
+        <MinusRegular size={24} />
+      </XStack>
+      <XStack gap="$4" alignItems="center">
+        <Paragraph width={160}>theme key color10</Paragraph>
+        <MinusRegular size={24} color="color10" />
+      </XStack>
+      <XStack gap="$4" alignItems="center">
+        <Paragraph width={160}>CSS tomato</Paragraph>
+        <MinusRegular size={24} color="tomato" />
+      </XStack>
+      <XStack gap="$4" alignItems="center">
+        <Paragraph width={160}>green Theme wrapper</Paragraph>
+        <Theme name="green">
+          <MinusRegular size={24} />
+        </Theme>
+      </XStack>
+    </YStack>
+  ),
+};
+
+export const IndeterminateSizes: Story = {
+  render: () => (
+    <XStack gap="$4" alignItems="center">
+      {[12, 16, 20, 24, 32, 48].map((size) => (
+        <YStack
+          key={size}
+          width={size + 8}
+          height={size + 8}
+          alignItems="center"
+          justifyContent="center"
+          borderWidth={1}
+          borderColor="$color8"
+          borderRadius="$2"
+          backgroundColor="$color3"
+        >
+          <MinusRegular size={size} />
+        </YStack>
+      ))}
+    </XStack>
+  ),
+};

package/src/icons/index.ts

@@ -1,2 +1,3 @@
 export * from "./CheckRegular";
 export * from "./MinusRegular";
+export * from "./lucide";

package/src/icons/lucide.ts

@@ -0,0 +1,5 @@
+/** Thin re-export so apps/packages/features never import @tamagui/lucide-icons-2. */
+export { Eye, EyeOff, Github, Info, Mail } from "@tamagui/lucide-icons-2";
+// Aliased: bare `Menu` collides with tamagui's Menu compound under `export *`.
+// Package root re-exports this as `Menu` after the tamagui star (see index.ts).
+export { Menu as MenuIcon } from "@tamagui/lucide-icons-2";