@heyramzi/ui 7.0.0 → 8.0.0

package/src/components/copy/clipboard.test.ts

@@ -0,0 +1,206 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vite-plus/test";
+import { copyRichText, copyText } from "./clipboard.js";
+
+// Mock navigator.clipboard
+const mockClipboard = {
+  write: vi.fn(),
+  writeText: vi.fn(),
+};
+
+// Mock ClipboardItem
+const mockClipboardItem = vi.fn();
+
+describe("clipboard", () => {
+  beforeEach(() => {
+    vi.stubGlobal("navigator", { clipboard: mockClipboard });
+    vi.stubGlobal("ClipboardItem", mockClipboardItem);
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  describe("copyRichText", () => {
+    it("copies HTML with modern Clipboard API", async () => {
+      mockClipboard.write.mockResolvedValue(undefined);
+
+      const result = await copyRichText("<p>Hello <strong>World</strong></p>", "Hello World");
+
+      expect(result).toBe(true);
+      expect(mockClipboardItem).toHaveBeenCalledWith({
+        "text/html": expect.any(Blob),
+        "text/plain": expect.any(Blob),
+      });
+      expect(mockClipboard.write).toHaveBeenCalledTimes(1);
+    });
+
+    it("extracts plain text from HTML when not provided", async () => {
+      mockClipboard.write.mockResolvedValue(undefined);
+
+      await copyRichText("<p>Test</p>");
+
+      // Verify ClipboardItem was called with both HTML and plain text blobs
+      expect(mockClipboardItem).toHaveBeenCalled();
+    });
+
+    it("falls back to plain text when Clipboard API fails", async () => {
+      mockClipboard.write.mockRejectedValue(new Error("Not supported"));
+      mockClipboard.writeText.mockResolvedValue(undefined);
+
+      const result = await copyRichText("<p>Test</p>", "Test");
+
+      expect(result).toBe(true);
+      expect(mockClipboard.writeText).toHaveBeenCalledWith("Test");
+    });
+
+    it("returns false when both methods fail", async () => {
+      mockClipboard.write.mockRejectedValue(new Error("Not supported"));
+      mockClipboard.writeText.mockRejectedValue(new Error("Blocked"));
+
+      const result = await copyRichText("<p>Test</p>", "Test");
+
+      expect(result).toBe(false);
+    });
+
+    it("creates correct blob types", async () => {
+      mockClipboard.write.mockResolvedValue(undefined);
+
+      await copyRichText("<b>Bold</b>", "Bold");
+
+      const clipboardItemCall = mockClipboardItem.mock.calls[0][0];
+
+      expect(clipboardItemCall["text/html"]).toBeInstanceOf(Blob);
+      expect(clipboardItemCall["text/html"].type).toBe("text/html");
+      expect(clipboardItemCall["text/plain"]).toBeInstanceOf(Blob);
+      expect(clipboardItemCall["text/plain"].type).toBe("text/plain");
+    });
+  });
+
+  describe("copyText", () => {
+    it("copies text successfully", async () => {
+      mockClipboard.writeText.mockResolvedValue(undefined);
+
+      const result = await copyText("Hello World");
+
+      expect(result).toBe(true);
+      expect(mockClipboard.writeText).toHaveBeenCalledWith("Hello World");
+    });
+
+    it("returns false on failure", async () => {
+      mockClipboard.writeText.mockRejectedValue(new Error("Permission denied"));
+
+      const result = await copyText("Test");
+
+      expect(result).toBe(false);
+    });
+
+    it("handles empty string", async () => {
+      mockClipboard.writeText.mockResolvedValue(undefined);
+
+      const result = await copyText("");
+
+      expect(result).toBe(true);
+      expect(mockClipboard.writeText).toHaveBeenCalledWith("");
+    });
+
+    it("handles special characters", async () => {
+      mockClipboard.writeText.mockResolvedValue(undefined);
+
+      const result = await copyText("Hello <>&\"' World");
+
+      expect(result).toBe(true);
+      expect(mockClipboard.writeText).toHaveBeenCalledWith("Hello <>&\"' World");
+    });
+  });
+});
+
+// Test htmlToPlainText server-side conversion (via copyRichText behavior)
+describe("htmlToPlainText (server-side)", () => {
+  beforeEach(() => {
+    // Remove document to simulate server environment
+    vi.stubGlobal("document", undefined);
+    vi.stubGlobal("navigator", {
+      clipboard: {
+        write: vi.fn().mockRejectedValue(new Error("Server")),
+        writeText: vi.fn().mockResolvedValue(undefined),
+      },
+    });
+    vi.stubGlobal("ClipboardItem", vi.fn());
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("converts line breaks", async () => {
+    const mockWriteText = vi.fn().mockResolvedValue(undefined);
+    vi.stubGlobal("navigator", {
+      clipboard: {
+        write: vi.fn().mockRejectedValue(new Error()),
+        writeText: mockWriteText,
+      },
+    });
+
+    await copyRichText("Line 1<br>Line 2<br/>Line 3");
+
+    expect(mockWriteText).toHaveBeenCalledWith("Line 1\nLine 2\nLine 3");
+  });
+
+  it("converts paragraph tags", async () => {
+    const mockWriteText = vi.fn().mockResolvedValue(undefined);
+    vi.stubGlobal("navigator", {
+      clipboard: {
+        write: vi.fn().mockRejectedValue(new Error()),
+        writeText: mockWriteText,
+      },
+    });
+
+    await copyRichText("<p>Para 1</p><p>Para 2</p>");
+
+    expect(mockWriteText).toHaveBeenCalledWith("Para 1\n\nPara 2");
+  });
+
+  it("converts list items to bullets", async () => {
+    const mockWriteText = vi.fn().mockResolvedValue(undefined);
+    vi.stubGlobal("navigator", {
+      clipboard: {
+        write: vi.fn().mockRejectedValue(new Error()),
+        writeText: mockWriteText,
+      },
+    });
+
+    await copyRichText("<ul><li>Item 1</li><li>Item 2</li></ul>");
+
+    expect(mockWriteText).toHaveBeenCalledWith("• Item 1\n• Item 2");
+  });
+
+  it("strips remaining HTML tags", async () => {
+    const mockWriteText = vi.fn().mockResolvedValue(undefined);
+    vi.stubGlobal("navigator", {
+      clipboard: {
+        write: vi.fn().mockRejectedValue(new Error()),
+        writeText: mockWriteText,
+      },
+    });
+
+    await copyRichText("<div><span>Hello</span> <strong>World</strong></div>");
+
+    expect(mockWriteText).toHaveBeenCalledWith("Hello World");
+  });
+
+  it("decodes HTML entities", async () => {
+    const mockWriteText = vi.fn().mockResolvedValue(undefined);
+    vi.stubGlobal("navigator", {
+      clipboard: {
+        write: vi.fn().mockRejectedValue(new Error()),
+        writeText: mockWriteText,
+      },
+    });
+
+    // The function decodes &nbsp; to space, &amp; to &, &lt; to <, &gt; to >
+    await copyRichText("Hello&nbsp;World &amp; Friends &lt;3&gt;");
+
+    expect(mockWriteText).toHaveBeenCalledWith("Hello World & Friends <3>");
+  });
+});

package/src/components/copy/clipboard.ts

@@ -0,0 +1,49 @@
+import { tryCatchAsync } from "@heyramzi/utils";
+
+/**
+ * The one write to the clipboard. A rejected permission, a missing gesture and
+ * an insecure origin get one answer: false. The caller decides what to show.
+ */
+
+/** Plain text. Returns false when the browser refused the write. */
+export async function copyText(value: string): Promise<boolean> {
+  const result = await tryCatchAsync(() => navigator.clipboard.writeText(value));
+  return result.ok;
+}
+
+/**
+ * HTML plus a plain-text twin: Gmail keeps the formatting, Cmd+Shift+V stays
+ * readable. Falls back to plain text.
+ */
+export async function copyRichText(html: string, plainText?: string): Promise<boolean> {
+  const text = plainText ?? htmlToPlainText(html);
+  const result = await tryCatchAsync(() =>
+    navigator.clipboard.write([
+      new ClipboardItem({
+        "text/html": new Blob([html], { type: "text/html" }),
+        "text/plain": new Blob([text], { type: "text/plain" }),
+      }),
+    ]),
+  );
+  return result.ok ? true : copyText(text);
+}
+
+/** The plain-text twin of an HTML fragment. */
+export function htmlToPlainText(html: string): string {
+  if (typeof document === "undefined") {
+    return html
+      .replace(/<br\s*\/?>/gi, "\n")
+      .replace(/<\/p>/gi, "\n\n")
+      .replace(/<\/li>/gi, "\n")
+      .replace(/<li>/gi, "• ")
+      .replace(/<[^>]+>/g, "")
+      .replace(/&nbsp;/g, " ")
+      .replace(/&amp;/g, "&")
+      .replace(/&lt;/g, "<")
+      .replace(/&gt;/g, ">")
+      .trim();
+  }
+  const div = document.createElement("div");
+  div.innerHTML = html;
+  return div.textContent || div.innerText || "";
+}

package/src/components/copy/copied.svelte.ts

@@ -0,0 +1,39 @@
+import { copyText } from "./clipboard.js";
+
+/**
+ * The copied flag for a surface whose affordance is a whole row or card rather
+ * than a `CopyButton`. Keyed, so one instance serves a list of rows.
+ */
+export class Copied {
+  /** The key that last copied, or null. Empty string when a surface has one. */
+  key = $state<string | null>(null);
+  #timer: ReturnType<typeof setTimeout> | null = null;
+
+  /** True when anything copied; with a key, true only for that one. */
+  is(key = ""): boolean {
+    return this.key === key;
+  }
+
+  /** Writes, then holds the check for `hold` ms. False when the write failed. */
+  async copy(value: string, key = "", hold = 1400): Promise<boolean> {
+    if (!(await copyText(value))) return false;
+    this.mark(key, hold);
+    return true;
+  }
+
+  /** The confirmation without the write, for a copy this class did not make. */
+  mark(key = "", hold = 1400): void {
+    this.key = key;
+    if (this.#timer) clearTimeout(this.#timer);
+    this.#timer = setTimeout(() => {
+      this.key = null;
+      this.#timer = null;
+    }, hold);
+  }
+
+  reset(): void {
+    if (this.#timer) clearTimeout(this.#timer);
+    this.#timer = null;
+    this.key = null;
+  }
+}

package/src/components/copy/copy-button.svelte

@@ -0,0 +1,175 @@
+<script lang="ts">
+/**
+ * The one copy control. No `text` prop draws the icon button; `text` draws the
+ * chip. `agent` marks a payload written for a model.
+ */
+
+// =========================
+// IMPORTS
+// =========================
+import { Check, Copy, StarFour } from "phosphor-svelte";
+import { cn } from "@heyramzi/utils";
+import { buttonVariants } from "../../shadcn/button/index.js";
+import type { HTMLButtonAttributes } from "svelte/elements";
+import { copyText } from "./clipboard.js";
+
+// =========================
+// TYPES
+// =========================
+interface Props extends Omit<HTMLButtonAttributes, "value" | "onclick" | "children"> {
+	/**
+	 * What lands on the clipboard. A function runs on the click, so a long list
+	 * doesn't build every prompt up front. It may return a promise.
+	 */
+	value: string | (() => string | Promise<string>);
+	/** Names the thing being copied, for a screen reader and the tooltip. */
+	label?: string;
+	/** Announced when the write lands; see `announce`. */
+	copiedLabel?: string;
+	/** The chip's visible text. Its presence is what makes this a chip. */
+	text?: string;
+	/** Marks the payload as an instruction for an AI rather than a raw string. */
+	agent?: boolean;
+	/**
+	 * `sm` matches `OpenIn`, for the icon row inside a calendar chip. `md` is
+	 * the 28px icon `Button`, for a toolbar that sits beside other icon buttons.
+	 */
+	size?: "default" | "md" | "sm";
+	/**
+	 * The icon button's `Button` variant: ghost unless it sits beside an outline
+	 * one. `inline` is for the chip: it takes the surrounding text's font and
+	 * colour, and the icon trails it.
+	 */
+	variant?: "ghost" | "outline" | "inline";
+	/**
+	 * How a screen reader hears the copy. `region` keeps the name fixed and
+	 * announces `copiedLabel` in a live region. `name` swaps the button's own name
+	 * to `copiedLabel` (write it in full) and has no region, for a page that
+	 * renders hundreds of these.
+	 */
+	announce?: "region" | "name";
+	/** Runs after a write that landed, for a toast the call site owns. */
+	onCopied?: () => void;
+	class?: string;
+}
+
+// =========================
+// PROPS
+// =========================
+let {
+	value,
+	label = "Copy",
+	copiedLabel = "Copied",
+	text,
+	agent = false,
+	size = "default",
+	variant = "ghost",
+	announce = "region",
+	onCopied,
+	class: className,
+	...restProps
+}: Props = $props();
+
+// =========================
+// STATE
+// =========================
+let copied = $state(false);
+let resetAt: ReturnType<typeof setTimeout> | undefined;
+
+// =========================
+// DERIVED
+// =========================
+const inline = $derived(text !== undefined && variant === "inline");
+
+// =========================
+// FUNCTIONS
+// =========================
+async function copy(event: MouseEvent) {
+	// Rows and cards are clickable; taking the payload out of one must not also
+	// open the record it belongs to.
+	event.stopPropagation();
+	event.preventDefault();
+	const payload = typeof value === "function" ? await value() : value;
+	if (!(await copyText(payload))) return;
+	copied = true;
+	clearTimeout(resetAt);
+	resetAt = setTimeout(() => (copied = false), 1400);
+	onCopied?.();
+}
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+<button
+	{...restProps}
+	type="button"
+	onclick={copy}
+	title={label}
+	aria-label={announce === "name" && copied ? copiedLabel : label}
+	class={cn(
+		"group/copy t-press shrink-0 outline-none focus-visible:ring-3 focus-visible:ring-ring/50",
+		text === undefined
+			? size === "sm"
+				? "grid size-5 place-items-center rounded-md hover:bg-accent"
+				: buttonVariants({
+					variant: variant === "outline" ? "outline" : "ghost",
+					size: size === "md" ? "sm" : "default",
+					icon: true,
+				})
+			: inline
+				? "inline-flex cursor-copy items-baseline gap-1.5 transition-colors hover:text-foreground"
+				: "flex items-center gap-1 rounded px-1.5 py-0.5 font-mono text-xs tabular-nums text-muted-foreground/70 transition-colors hover:bg-muted hover:text-foreground",
+		className,
+	)}
+>
+	<!-- One slot, two glyphs, per the transitions-dev icon-swap: the check
+	     arrives on the bounce, the copy glyph leaves without one. -->
+	<span
+		class={cn(
+			"relative grid place-items-center",
+			text === undefined && size !== "sm" ? "size-4" : "size-3",
+			inline && "order-last self-center opacity-60 transition-opacity group-hover/copy:opacity-100",
+		)}
+	>
+		<Check
+			class={cn(
+				"col-start-1 row-start-1 size-full transition-[opacity,transform] duration-[var(--duration-fast)] ease-[var(--ease-smooth-out)]",
+				inline ? "text-current" : "text-success-800 dark:text-success-400",
+				copied ? "scale-100 opacity-100" : "scale-50 opacity-0",
+			)}
+			weight="bold"
+			aria-hidden="true"
+		/>
+		{#if agent}
+			<StarFour
+				class={cn(
+					"col-start-1 row-start-1 size-full text-brand-indigo/70 transition-[opacity,color] duration-[var(--duration-fast)] ease-[var(--ease-smooth-out)] group-hover/copy:text-brand-indigo",
+					copied ? "opacity-0" : "opacity-100",
+				)}
+				weight="bold"
+				aria-hidden="true"
+			/>
+		{:else}
+			<Copy
+				class={cn(
+					"col-start-1 row-start-1 size-full transition-[opacity,color] duration-[var(--duration-fast)] ease-[var(--ease-smooth-out)]",
+					inline
+						? "text-current"
+						: "text-muted-foreground group-hover/copy:text-foreground",
+					copied ? "opacity-0" : "opacity-100",
+				)}
+				aria-hidden="true"
+			/>
+		{/if}
+	</span>
+
+	{#if text !== undefined}
+		<span>{text}</span>
+	{/if}
+
+	<!-- The swap is invisible to a reader who cannot see it. -->
+	{#if announce === "region"}
+		<span aria-live="polite" class="sr-only">{copied ? copiedLabel : ""}</span>
+	{/if}
+</button>

package/src/components/copy/copy-button.test.ts

@@ -0,0 +1,110 @@
+import { flushSync, mount, unmount } from "svelte";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vite-plus/test";
+import CopyButton from "./copy-button.svelte";
+
+type Props = { value: string; [key: string]: unknown };
+
+// jsdom ships no clipboard, so the write is stubbed and asserted on directly.
+function stubClipboard(result: Promise<void> = Promise.resolve()) {
+  const writeText = vi.fn().mockReturnValue(result);
+  vi.stubGlobal("navigator", { clipboard: { writeText } });
+  return writeText;
+}
+
+function render(props: Props) {
+  const target = document.createElement("div");
+  document.body.appendChild(target);
+  const app = mount(CopyButton, { target, props });
+  flushSync();
+  return {
+    button: target.querySelector("button")!,
+    target,
+    done: () => {
+      void unmount(app);
+      target.remove();
+    },
+  };
+}
+
+async function click(button: HTMLButtonElement) {
+  button.click();
+  await vi.advanceTimersByTimeAsync(0);
+  flushSync();
+}
+
+describe("CopyButton", () => {
+  beforeEach(() => vi.useFakeTimers());
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.unstubAllGlobals();
+  });
+
+  it("puts the value on the clipboard", async () => {
+    const writeText = stubClipboard();
+    const { button, done } = render({ value: "26011200", text: "26011200" });
+    await click(button);
+    expect(writeText).toHaveBeenCalledWith("26011200");
+    done();
+  });
+
+  it("names what it copies, so the button is not just a value", () => {
+    stubClipboard();
+    const { button, done } = render({ value: "abc123", text: "abc123", label: "Copy API key abc123" });
+    expect(button.getAttribute("aria-label")).toBe("Copy API key abc123");
+    done();
+  });
+
+  it("announces in a live region by default and keeps its name", async () => {
+    stubClipboard();
+    const { button, target, done } = render({ value: "x", label: "Copy id", copiedLabel: "Copied" });
+    await click(button);
+    expect(target.querySelector("[aria-live]")?.textContent).toBe("Copied");
+    expect(button.getAttribute("aria-label")).toBe("Copy id");
+    done();
+  });
+
+  // A page of 500 codes would read as a wall of live regions, so the name carries it.
+  it("announce name: no live region, the accessible name says it copied, then rests", async () => {
+    stubClipboard();
+    const { button, target, done } = render({
+      value: "25070080",
+      text: "25070080",
+      label: "Copy CN code 25070080",
+      copiedLabel: "CN code 25070080 copied",
+      announce: "name",
+    });
+    expect(target.querySelector("[aria-live]")).toBeNull();
+    await click(button);
+    expect(button.getAttribute("aria-label")).toBe("CN code 25070080 copied");
+    await vi.advanceTimersByTimeAsync(1500);
+    flushSync();
+    expect(button.getAttribute("aria-label")).toBe("Copy CN code 25070080");
+    done();
+  });
+
+  it("calls onCopied after a write that landed", async () => {
+    stubClipboard();
+    const onCopied = vi.fn();
+    const { button, done } = render({ value: "x", onCopied });
+    await click(button);
+    expect(onCopied).toHaveBeenCalledOnce();
+    done();
+  });
+
+  it("keeps the resting state when the browser refuses the clipboard", async () => {
+    const writeText = stubClipboard(Promise.reject(new Error("denied")));
+    const onCopied = vi.fn();
+    const { button, done } = render({
+      value: "x",
+      label: "Copy x",
+      copiedLabel: "x copied",
+      announce: "name",
+      onCopied,
+    });
+    await click(button);
+    expect(writeText).toHaveBeenCalled();
+    expect(button.getAttribute("aria-label")).toBe("Copy x");
+    expect(onCopied).not.toHaveBeenCalled();
+    done();
+  });
+});

package/src/components/copy/index.ts

@@ -0,0 +1,3 @@
+export { default as CopyButton } from "./copy-button.svelte";
+export { copyText, copyRichText, htmlToPlainText } from "./clipboard.js";
+export { Copied } from "./copied.svelte.js";