@charcuterie/ui 3.10.0 → 3.12.0

package/src/CopyButton/CopyButton.stories.tsx

@@ -0,0 +1,111 @@
+import type { Meta, StoryObj } from "@storybook/react"
+import { userEvent, within } from "storybook/test"
+
+import {
+  StoryCell,
+  StoryRow,
+  StorySection,
+} from "../board.storyHelpers.tsx"
+import { CopyButton } from "./CopyButton.tsx"
+
+const meta = {
+  title: "Components/Actions/CopyButton",
+  component: CopyButton,
+  parameters: { layout: "padded" },
+  // The component's own defaults, restated — Storybook does not
+  // seed `args` from docgen, so an unstated default shows in the
+  // props table with nothing selected in its control.
+  args: {
+    appearance: "solid",
+    confirmDuration: 2000,
+    intent: "accent",
+    isDisabled: false,
+    size: "md",
+    value: "335590",
+  },
+} satisfies Meta<typeof CopyButton>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {}
+
+/**
+ * The confirmation, held open. `confirmDuration` is enormous here so
+ * the state can be read, hovered and screenshotted — a two-second
+ * default is right in an app and useless in a docs page.
+ */
+export const Confirmed: Story = {
+  args: {
+    confirmDuration: 600_000,
+    // Injected, not real. A headless browser refuses
+    // `navigator.clipboard` outright — the document is not focused —
+    // so a story that used the real one would document the *failure*
+    // state under a name that promises the success one.
+    copy: () => true,
+    value: "335590",
+  },
+  // Driven, not faked: the story presses the button the way a reader
+  // would. No assertion — those live in `CopyButton.test.tsx`.
+  play: async ({ canvasElement }) => {
+    await userEvent.click(
+      within(canvasElement).getByRole("button", {
+        name: "Copy",
+      }),
+    )
+  },
+}
+
+/**
+ * The clipboard refused. Injected rather than provoked: a story
+ * cannot revoke the permission, and the failure path is the half of
+ * this component the hand-rolled copies in the fleet do not have.
+ */
+export const Refused: Story = {
+  args: {
+    confirmDuration: 600_000,
+    copy: () => false,
+  },
+  play: async ({ canvasElement }) => {
+    await userEvent.click(
+      within(canvasElement).getByRole("button", {
+        name: "Copy",
+      }),
+    )
+  },
+}
+
+/** Every appearance, so a toolbar's ghost copy is a real option. */
+export const AllAppearances: Story = {
+  render: (args) => (
+    <StorySection title="Appearances">
+      <StoryRow>
+        <StoryCell label="solid">
+          <CopyButton {...args} appearance="solid" />
+        </StoryCell>
+        <StoryCell label="soft">
+          <CopyButton {...args} appearance="soft" />
+        </StoryCell>
+        <StoryCell label="outline">
+          <CopyButton {...args} appearance="outline" />
+        </StoryCell>
+        <StoryCell label="ghost">
+          <CopyButton {...args} appearance="ghost" />
+        </StoryCell>
+      </StoryRow>
+    </StorySection>
+  ),
+}
+
+/**
+ * A caller's own words. The label is content, so a one-off surface
+ * that copies something specific says which thing it copies.
+ */
+export const OwnLabels: Story = {
+  args: {
+    children: "Copy code",
+    copiedLabel: "Code copied",
+    value: "335590",
+  },
+}

package/src/CopyButton/CopyButton.test.tsx

@@ -0,0 +1,227 @@
+import {
+  composeStories,
+  composeStory,
+} from "@storybook/react"
+import {
+  expect,
+  fn,
+  userEvent,
+  waitFor,
+} from "storybook/test"
+import { test, vi } from "vitest"
+
+import { expectNoAxeViolations } from "../expectNoAxeViolations.testHelpers.ts"
+import { mountStory } from "../mountStory.testHelpers.ts"
+import { expectAgentDrivable } from "../testing/index.ts"
+import meta, * as stories from "./CopyButton.stories.tsx"
+import { copyText } from "./copyText.ts"
+
+const { Confirmed, Default, Refused } =
+  composeStories(stories)
+
+test("is a button an agent can find by role and name", async () => {
+  const { canvas } = await mountStory(Default)
+
+  const button = expectAgentDrivable(canvas, {
+    name: "Copy",
+    role: "button",
+  })
+
+  // Never `submit`. A copy control inside a form that reloads the
+  // page is a bug every repo in the fleet has shipped once.
+  await expect(button).toHaveAttribute("type", "button")
+})
+
+test("copies the value and confirms in place", async () => {
+  const copy = fn(async () => true)
+
+  const { canvas } = await mountStory(
+    composeStory({ args: { copy, value: "335590" } }, meta),
+  )
+
+  await userEvent.click(
+    canvas.getByRole("button", { name: "Copy" }),
+  )
+
+  await expect(copy).toHaveBeenCalledWith("335590")
+  // The press and its proof are the same object — no toast, no
+  // second place to look.
+  await expect(
+    canvas.getByRole("button", { name: "Copied" }),
+  ).toBeVisible()
+})
+
+/**
+ * The half the four hand-rolled copies in the fleet do not have.
+ *
+ * A refused clipboard has to *say so*, because the consumer's next
+ * move usually destroys the thing that held the value — mail-sifter
+ * marks the mail done on a copy.
+ */
+test("says so when the clipboard refuses", async () => {
+  const onCopy = fn()
+
+  const { canvas } = await mountStory(
+    composeStory(
+      { args: { copy: () => false, onCopy } },
+      meta,
+    ),
+  )
+
+  await userEvent.click(
+    canvas.getByRole("button", { name: "Copy" }),
+  )
+
+  await expect(
+    canvas.getByRole("button", { name: "Copy failed" }),
+  ).toBeVisible()
+  await expect(onCopy).toHaveBeenCalledWith(false, "335590")
+})
+
+test("tells the caller what happened, both ways", async () => {
+  const onCopy = fn()
+
+  const { canvas } = await mountStory(
+    composeStory(
+      { args: { copy: async () => true, onCopy } },
+      meta,
+    ),
+  )
+
+  await userEvent.click(
+    canvas.getByRole("button", { name: "Copy" }),
+  )
+
+  await expect(onCopy).toHaveBeenCalledWith(true, "335590")
+})
+
+/**
+ * A focused button whose own accessible name changes is not
+ * reliably announced, so the outcome is written into a live region
+ * as well.
+ */
+test("announces the outcome in a status region", async () => {
+  const { canvas } = await mountStory(Confirmed)
+
+  await expect(
+    canvas.getByRole("status"),
+  ).toHaveTextContent("Copied to the clipboard.")
+})
+
+test("the failure says what to do instead", async () => {
+  const { canvas } = await mountStory(Refused)
+
+  await expect(
+    canvas.getByRole("status"),
+  ).toHaveTextContent(
+    "The clipboard refused. Select the value and press Control C.",
+  )
+})
+
+/** The confirmation goes back on its own. */
+test("returns to the resting label", async () => {
+  const { canvas } = await mountStory(
+    composeStory(
+      { args: { confirmDuration: 20, copy: () => true } },
+      meta,
+    ),
+  )
+
+  await userEvent.click(
+    canvas.getByRole("button", { name: "Copy" }),
+  )
+  await expect(
+    canvas.getByRole("button", { name: "Copied" }),
+  ).toBeVisible()
+
+  await waitFor(async () => {
+    await expect(
+      canvas.getByRole("button", { name: "Copy" }),
+    ).toBeVisible()
+  })
+})
+
+/**
+ * A caller's `onClick` runs first and can call it off — the escape
+ * hatch for "confirm before this leaves the screen".
+ */
+test("a prevented click copies nothing", async () => {
+  const copy = fn(() => true)
+
+  const { canvas } = await mountStory(
+    composeStory(
+      {
+        args: {
+          copy,
+          onClick: (event: MouseEvent) => {
+            event.preventDefault()
+          },
+        },
+      },
+      meta,
+    ),
+  )
+
+  await userEvent.click(
+    canvas.getByRole("button", { name: "Copy" }),
+  )
+
+  await expect(copy).not.toHaveBeenCalled()
+})
+
+test("has no axe violations", async () => {
+  const { canvasElement } = await mountStory(Default)
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+/**
+ * `copyText`'s own contract, exercised here rather than in a
+ * node-side `.ts` file, because it is a DOM routine and the `ui`
+ * project has no DOM.
+ *
+ * The real clipboard is unavailable in this chromium — the document
+ * is not focused, so `navigator.clipboard.writeText` rejects — which
+ * makes this an honest test of the fallback chain rather than of the
+ * happy path.
+ */
+test("copyText reports failure rather than throwing", async () => {
+  const execCommand = vi
+    .spyOn(document, "execCommand")
+    .mockReturnValue(false)
+
+  await expect(copyText("335590")).resolves.toBe(false)
+
+  execCommand.mockRestore()
+})
+
+test("copyText falls back to the selection route", async () => {
+  const execCommand = vi
+    .spyOn(document, "execCommand")
+    .mockReturnValue(true)
+
+  await expect(copyText("335590")).resolves.toBe(true)
+  await expect(execCommand).toHaveBeenCalledWith("copy")
+
+  execCommand.mockRestore()
+})
+
+/**
+ * The textarea is a means, not a side effect. A leaked one is a
+ * focusable, screen-reader-visible node holding the copied value,
+ * left in the document for good.
+ */
+test("copyText leaves no textarea behind", async () => {
+  const execCommand = vi
+    .spyOn(document, "execCommand")
+    .mockImplementation(() => {
+      throw new Error("refused mid-copy")
+    })
+
+  await expect(copyText("335590")).resolves.toBe(false)
+  await expect(
+    document.querySelectorAll("textarea"),
+  ).toHaveLength(0)
+
+  execCommand.mockRestore()
+})

package/src/CopyButton/CopyButton.tsx

@@ -0,0 +1,155 @@
+import type { ReactNode } from "react"
+import { useEffect, useRef, useState } from "react"
+import type { ButtonProps } from "../Button/Button.tsx"
+import { Button } from "../Button/Button.tsx"
+import { VisuallyHidden } from "../VisuallyHidden/VisuallyHidden.tsx"
+import { copyText as defaultCopyText } from "./copyText.ts"
+
+/** Where the button is in the one action it performs. */
+export type CopyStatus = "copied" | "failed" | "idle"
+
+export type CopyButtonProps = Omit<
+  ButtonProps,
+  "children" | "isLoading" | "loadingLabel" | "onCopy"
+> & {
+  /**
+   * How long the confirmation stays up, in milliseconds.
+   *
+   * Long enough to be read after the eye has moved back to the form
+   * being filled in, short enough that a second copy of a *different*
+   * value is not mistaken for the first one's tick.
+   */
+  confirmDuration?: number
+  /** Resting label. A word, not a glyph — this library ships no icons. */
+  children?: ReactNode
+  /** Shown while the copy is confirmed. */
+  copiedLabel?: ReactNode
+  /**
+   * The clipboard write, injected. Swapped in tests and in a host
+   * that owns its own clipboard bridge (Electron, a kiosk shell).
+   */
+  copy?: (value: string) => Promise<boolean> | boolean
+  /** Shown when the clipboard refused. */
+  failedLabel?: ReactNode
+  /**
+   * Told what actually happened, every press.
+   *
+   * `isCopied` is the point of the callback rather than a detail: a
+   * consumer that files the mail away on a copy must not file it away
+   * on a copy the browser refused.
+   */
+  onCopy?: (isCopied: boolean, value: string) => void
+  /** The string that goes on the clipboard. */
+  value: string
+}
+
+/**
+ * A button that puts a string on the clipboard and says so.
+ *
+ * From a consumer, like `Alert` and `BadgeButton` before it: four
+ * repos spell this shape by hand — mux-magic's YAML dialog flips its
+ * own label on a `setTimeout`, spoolbuddy carries a 15-line
+ * `copyToClipboard` with the `execCommand` fallback inline, bambuddy
+ * copies a download link from two menus, and mail-sifter's
+ * verification-code banner is the fourth. None of the four agree on
+ * what happens when the clipboard says no, and three of them cannot
+ * tell.
+ *
+ * **The confirmation is the button, not a toast.** The press and the
+ * proof are the same object, so the eye does not travel; a toast is
+ * right for something that happened *elsewhere*. A consumer that
+ * wants both still gets `onCopy`.
+ *
+ * **The label is a word.** `Copy` → `Copied`, and the intent goes
+ * with it, because a colour change alone is not a message and a tick
+ * glyph is an icon this library does not ship.
+ *
+ * **It announces.** A screen reader is not reliably told that a
+ * focused button's own name changed, so the outcome is also written
+ * into a `role="status"` region — and the failure says what to do
+ * next rather than only that it went wrong.
+ *
+ * **The timer is cancelled on unmount and on a re-press**, which is
+ * the bug in two of the four hand-rolled copies: press, navigate
+ * away, and a `setState` lands on nothing.
+ */
+export const CopyButton = ({
+  appearance = "solid",
+  children = "Copy",
+  confirmDuration = 2000,
+  copiedLabel = "Copied",
+  copy = defaultCopyText,
+  failedLabel = "Copy failed",
+  intent = "accent",
+  onClick,
+  onCopy,
+  value,
+  ...buttonProps
+}: CopyButtonProps): ReactNode => {
+  const [status, setStatus] = useState<CopyStatus>("idle")
+  const timerRef =
+    useRef<ReturnType<typeof setTimeout>>(undefined)
+
+  // One cleanup covers both the unmount and the re-press: every path
+  // that starts a timer clears the previous one first.
+  useEffect(
+    () => () => {
+      clearTimeout(timerRef.current)
+    },
+    [],
+  )
+
+  const settle = (next: CopyStatus) => {
+    setStatus(next)
+    clearTimeout(timerRef.current)
+    timerRef.current = setTimeout(() => {
+      setStatus("idle")
+    }, confirmDuration)
+  }
+
+  const handleClick: NonNullable<ButtonProps["onClick"]> = (
+    event,
+  ) => {
+    onClick?.(event)
+    if (event.defaultPrevented) return
+
+    void (async () => {
+      const isCopied = await copy(value)
+      settle(isCopied ? "copied" : "failed")
+      onCopy?.(isCopied, value)
+    })()
+  }
+
+  const label =
+    status === "copied"
+      ? copiedLabel
+      : status === "failed"
+        ? failedLabel
+        : children
+
+  return (
+    <>
+      <Button
+        {...buttonProps}
+        appearance={appearance}
+        intent={
+          status === "copied"
+            ? "success"
+            : status === "failed"
+              ? "danger"
+              : intent
+        }
+        onClick={handleClick}
+      >
+        {label}
+      </Button>
+      <VisuallyHidden role="status">
+        {status === "copied"
+          ? "Copied to the clipboard."
+          : status === "failed"
+            ? "The clipboard refused. Select the value and press Control C."
+            : ""}
+      </VisuallyHidden>
+    </>
+  )
+}

package/src/CopyButton/copyText.ts

@@ -0,0 +1,68 @@
+/**
+ * Put a string on the clipboard, and say whether it landed.
+ *
+ * Three routes, tried in order, because the fleet runs in all three
+ * conditions:
+ *
+ *  1. **`navigator.clipboard.writeText`.** The real API. It exists
+ *     only in a *secure context*, which a `devshare` URL and
+ *     `localhost` both are — and a plain `http://storeman.octen:8080`
+ *     dev server is not.
+ *  2. **A hidden `<textarea>` plus `document.execCommand("copy")`.**
+ *     Deprecated, and kept anyway: it is the only thing that works in
+ *     an insecure context, spoolbuddy already hand-rolls exactly this
+ *     block, and the alternative is a Copy button that silently does
+ *     nothing on the household's own LAN.
+ *  3. **Give up and report it.** A caller that marks mail done on a
+ *     copy must not mark it done on a copy that never happened.
+ *
+ * Never throws. The boolean is the whole result, so a call site is an
+ * `if` rather than a `try`.
+ */
+export const copyText = async (
+  value: string,
+): Promise<boolean> => {
+  try {
+    // `writeText` rejects on a denied permission and on a document
+    // that is not focused — both real, both recoverable below.
+    await globalThis.navigator?.clipboard?.writeText(value)
+    return true
+  } catch {
+    // Fall through to the legacy route.
+  }
+
+  return copyBySelection(value)
+}
+
+/**
+ * The pre-Clipboard-API route.
+ *
+ * The textarea is positioned off-screen rather than hidden: a
+ * `display: none` element has no selection to copy, and
+ * `visibility: hidden` is no better. `readOnly` stops the mobile
+ * keyboard appearing for the frame it is in the document.
+ */
+const copyBySelection = (value: string): boolean => {
+  const owner = globalThis.document
+  if (!owner?.body) return false
+
+  const field = owner.createElement("textarea")
+  field.value = value
+  field.readOnly = true
+  field.setAttribute("aria-hidden", "true")
+  field.style.position = "fixed"
+  field.style.insetInlineStart = "-9999px"
+  field.style.top = "0"
+
+  owner.body.append(field)
+
+  try {
+    field.select()
+
+    return owner.execCommand("copy")
+  } catch {
+    return false
+  } finally {
+    field.remove()
+  }
+}

package/src/index.ts

@@ -98,6 +98,7 @@ export type {
   CardSurface,
 } from "./Card/Card.tsx"
 export { Card } from "./Card/Card.tsx"
+export type { CardAccentEdge } from "./Card/cardAccentEdge.ts"
 export type { CheckboxProps } from "./Checkbox/Checkbox.tsx"
 export { Checkbox } from "./Checkbox/Checkbox.tsx"
 export type { ColorSchemeSwitcherProps } from "./ColorSchemeSwitcher/ColorSchemeSwitcher.tsx"
@@ -109,6 +110,12 @@ export type {
 export { ColorSchemeToggle } from "./ColorSchemeToggle/ColorSchemeToggle.tsx"
 export type { ComboboxProps } from "./Combobox/Combobox.tsx"
 export { Combobox } from "./Combobox/Combobox.tsx"
+export type {
+  CopyButtonProps,
+  CopyStatus,
+} from "./CopyButton/CopyButton.tsx"
+export { CopyButton } from "./CopyButton/CopyButton.tsx"
+export { copyText } from "./CopyButton/copyText.ts"
 export {
   CATEGORICAL_APPEARANCE_CLASS,
   CATEGORICAL_CONTENT_CLASS,

package/src/sourceRules.test.ts

@@ -459,7 +459,13 @@ test("the barrel is the only place components are re-exported", async () => {
   // member of `Badge/` and so stays out of this count and out of the
   // barrel as a component. Its PROPS type is exported, because a
   // consumer writing a wrapper needs to name the visual half.
-  expect(componentNames.length).toBe(53)
+  //
+  // `CopyButton` — the clipboard write, with a failure state — is
+  // +1 -> 54. `copyText.ts` is its member: it stays out of this
+  // count by the `<Name>/<Name>.tsx` rule, and it IS exported from
+  // the barrel as a function, because a host with its own clipboard
+  // bridge needs the fallback chain without the button.
+  expect(componentNames.length).toBe(54)
 
   for (const name of componentNames) {
     expect(barrel).toContain(`export { ${name} }`)