@tempoxyz/ds 0.3.10 → 0.3.11

package/dist/docs/components/copy-button.md

@@ -0,0 +1,642 @@
+# CopyButton
+
+Copies a value to the clipboard and confirms the copy.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/CopyButton.tsx)
+
+## Overview
+
+A copy button is an icon-only button that writes a value to the clipboard and confirms the copy for two seconds.
+
+## Examples
+
+### Basic
+
+```tsx
+import { CopyButton } from '@tempoxyz/ds'
+
+export function Demo() {
+  return <CopyButton value="0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" />
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/CopyButton/Basic.tsx)
+
+### Size
+
+Set `size` to `small` (default), `medium`, or `large`.
+
+```tsx
+import { CopyButton, style } from '@tempoxyz/ds'
+
+const address = '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'
+
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      {(['small', 'medium', 'large'] as const).map((size) => (
+        <CopyButton key={size} size={size} value={address} />
+      ))}
+    </div>
+  )
+}
+
+namespace styles {
+  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '12' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/CopyButton/Size.tsx)
+
+### Variant
+
+Set `variant` to any [Button](/docs/components/button) variant, such as `tertiary` (default) or `secondary`.
+
+```tsx
+import { CopyButton, style } from '@tempoxyz/ds'
+
+const address = '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'
+
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      <CopyButton value={address} />
+      <CopyButton value={address} variant="secondary" />
+      <CopyButton size="medium" value={address} variant="secondary" />
+    </div>
+  )
+}
+
+namespace styles {
+  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '12' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/CopyButton/Variant.tsx)
+
+### Disabled
+
+```tsx
+import { CopyButton } from '@tempoxyz/ds'
+
+export function Demo() {
+  return <CopyButton disabled value="0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" />
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/CopyButton/Disabled.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { CopyButton } from '@tempoxyz/ds'
+
+<CopyButton />
+```
+
+## Guidelines
+
+### When to Use
+
+* Copy a value you'd otherwise select by hand, such as a webhook ID or an invite link.
+* Add copying beside a value in your own layout, such as a table cell.
+
+### When Not to Use
+
+* Use [Hex](/docs/components/hex) with `copy` for addresses and transaction hashes. It truncates the middle and adds this button.
+* Use [Snippet](/docs/components/snippet) for a command or code value.
+* Use [SecretValue](/docs/components/secret-value) for API keys and other secrets that stay hidden until revealed.
+* Use a [Button](/docs/components/button) for other actions, such as Share or Download.
+
+### Place It Right After the Value
+
+Put the button on the same line, immediately after the value. Give each value its own button.
+
+**Do:** Place a copy button directly after each value.
+
+```tsx
+/**
+ * Do example for "Place It Right After the Value" on the CopyButton page.
+ * Place a copy button directly after each value.
+ * @module
+ */
+import { CopyButton, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.rows()}>
+      <div {...styles.row()}>
+        <span {...styles.label()}>Webhook ID</span>
+        <span {...styles.value()}>
+          wh_51c8e20d
+          <CopyButton aria-label="Copy webhook ID" value="wh_51c8e20d" />
+        </span>
+      </div>
+      <div {...styles.row()}>
+        <span {...styles.label()}>Key ID</span>
+        <span {...styles.value()}>
+          key_9f2c41a7
+          <CopyButton aria-label="Copy key ID" value="key_9f2c41a7" />
+        </span>
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const label = style({ color: 'content.secondary', typography: 'body.b2' })
+
+  export const row = style({
+    alignItems: 'center',
+    display: 'flex',
+    justifyContent: 'space-between',
+    minHeight: '32',
+  })
+
+  export const rows = style({
+    display: 'flex',
+    flexDirection: 'column',
+    rowGap: '8',
+    width: '16rem !custom',
+  })
+
+  export const value = style({
+    alignItems: 'center',
+    color: 'content.primary',
+    columnGap: '4',
+    display: 'flex',
+    typography: 'mono.m1',
+  })
+}
+```
+
+**Don't:** Place one copy button away from the values, where its target is unclear.
+
+```tsx
+/**
+ * Don't example for "Place It Right After the Value" on the CopyButton page.
+ * Don't place one copy button away from the values, where its target is unclear.
+ * @module
+ */
+import { CopyButton, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.rows()}>
+      <div {...styles.header()}>
+        <span {...styles.title()}>Webhook</span>
+        <CopyButton aria-label="Copy" value="wh_51c8e20d" />
+      </div>
+      <div {...styles.row()}>
+        <span {...styles.label()}>Webhook ID</span>
+        <span {...styles.value()}>wh_51c8e20d</span>
+      </div>
+      <div {...styles.row()}>
+        <span {...styles.label()}>Key ID</span>
+        <span {...styles.value()}>key_9f2c41a7</span>
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const header = style({
+    alignItems: 'center',
+    display: 'flex',
+    justifyContent: 'space-between',
+    marginBottom: '4',
+  })
+
+  export const label = style({ color: 'content.secondary', typography: 'body.b2' })
+
+  export const row = style({
+    alignItems: 'center',
+    display: 'flex',
+    justifyContent: 'space-between',
+    minHeight: '32',
+  })
+
+  export const rows = style({
+    display: 'flex',
+    flexDirection: 'column',
+    rowGap: '8',
+    width: '16rem !custom',
+  })
+
+  export const title = style({ color: 'content.primary', typography: 'body.b1Strong' })
+
+  export const value = style({ color: 'content.primary', typography: 'mono.m1' })
+}
+```
+
+### Copy the Full Value
+
+Pass the complete value to `value`, even when the screen shows a shortened form.
+
+**Do:** Copy the complete value behind a shortened display.
+
+```tsx
+/**
+ * Do example for "Copy the Full Value" on the CopyButton page.
+ * Copy the complete value behind a shortened display.
+ * @module
+ */
+import { CopyButton, style } from '@tempoxyz/ds'
+
+const url = 'https://hooks.tempo.xyz/v1/payments/wh_51c8e20d'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.stack()}>
+      <span {...styles.value()}>
+        hooks.tempo.xyz/…/wh_51c8e20d
+        <CopyButton aria-label="Copy webhook URL" copied value={url} />
+      </span>
+      <div {...styles.clipboard()}>
+        <span {...styles.label()}>Clipboard</span>
+        <span {...styles.copied()}>{url}</span>
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const clipboard = style({
+    backgroundColor: 'container.regular',
+    borderRadius: '2xs',
+    display: 'flex',
+    flexDirection: 'column',
+    paddingBlock: '8',
+    paddingInline: '12',
+    rowGap: '2px !custom',
+  })
+
+  export const copied = style({ color: 'content.primary', typography: 'mono.m1' })
+
+  export const label = style({ color: 'content.secondary', typography: 'body.b3' })
+
+  export const stack = style({
+    display: 'flex',
+    flexDirection: 'column',
+    rowGap: '8',
+    width: '17rem !custom',
+  })
+
+  export const value = style({
+    alignItems: 'center',
+    color: 'content.primary',
+    columnGap: '4',
+    display: 'flex',
+    typography: 'mono.m1',
+  })
+}
+```
+
+**Don't:** Copy the shortened text that the screen shows.
+
+```tsx
+/**
+ * Don't example for "Copy the Full Value" on the CopyButton page.
+ * Don't copy the shortened text that the screen shows.
+ * @module
+ */
+import { CopyButton, style } from '@tempoxyz/ds'
+
+const display = 'hooks.tempo.xyz/…/wh_51c8e20d'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.stack()}>
+      <span {...styles.value()}>
+        {display}
+        <CopyButton aria-label="Copy webhook URL" copied value={display} />
+      </span>
+      <div {...styles.clipboard()}>
+        <span {...styles.label()}>Clipboard</span>
+        <span {...styles.copied()}>{display}</span>
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const clipboard = style({
+    backgroundColor: 'container.regular',
+    borderRadius: '2xs',
+    display: 'flex',
+    flexDirection: 'column',
+    paddingBlock: '8',
+    paddingInline: '12',
+    rowGap: '2px !custom',
+  })
+
+  export const copied = style({ color: 'content.primary', typography: 'mono.m1' })
+
+  export const label = style({ color: 'content.secondary', typography: 'body.b3' })
+
+  export const stack = style({
+    display: 'flex',
+    flexDirection: 'column',
+    rowGap: '8',
+    width: '17rem !custom',
+  })
+
+  export const value = style({
+    alignItems: 'center',
+    color: 'content.primary',
+    columnGap: '4',
+    display: 'flex',
+    typography: 'mono.m1',
+  })
+}
+```
+
+### Keep the Built-In Confirmation
+
+After a copy, the icon turns into a check for two seconds and screen readers announce Copied. If the clipboard refuses the write, the button shows no confirmation and doesn't call `onCopy`, so keep the value selectable as text.
+
+**Do:** Let the check icon confirm the copy.
+
+```tsx
+/**
+ * Do example for "Keep the Built-In Confirmation" on the CopyButton page.
+ * Let the check icon confirm the copy.
+ * @module
+ */
+import { CopyButton, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.stack()}>
+      <div {...styles.row()}>
+        <span {...styles.label()}>Webhook ID</span>
+        <span {...styles.value()}>
+          wh_51c8e20d
+          <CopyButton aria-label="Copy webhook ID" copied value="wh_51c8e20d" />
+        </span>
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const label = style({ color: 'content.secondary', typography: 'body.b2' })
+
+  export const row = style({
+    alignItems: 'center',
+    display: 'flex',
+    justifyContent: 'space-between',
+    minHeight: '32',
+  })
+
+  export const stack = style({
+    display: 'flex',
+    flexDirection: 'column',
+    rowGap: '16',
+    width: '16rem !custom',
+  })
+
+  export const value = style({
+    alignItems: 'center',
+    color: 'content.primary',
+    columnGap: '4',
+    display: 'flex',
+    typography: 'mono.m1',
+  })
+}
+```
+
+**Don't:** Add a [Toast](/docs/components/toast) or text such as Copied to clipboard.
+
+```tsx
+/**
+ * Don't example for "Keep the Built-In Confirmation" on the CopyButton page.
+ * Don't add a Toast or text such as Copied to clipboard.
+ * @module
+ */
+import { CopyButton, style } from '@tempoxyz/ds'
+import { CheckCircle } from '@tempoxyz/ds/icons'
+
+// Toasts render in a portal, so this preview draws one in place with the toast's styles.
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.stack()}>
+      <div {...styles.row()}>
+        <span {...styles.label()}>Webhook ID</span>
+        <span {...styles.value()}>
+          wh_51c8e20d
+          <CopyButton aria-label="Copy webhook ID" copied value="wh_51c8e20d" />
+        </span>
+      </div>
+      <div {...styles.toast()}>
+        <CheckCircle {...styles.icon()} />
+        <span {...styles.title()}>Copied to clipboard</span>
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const icon = style({ color: 'content.positive', flexShrink: '0 !custom', fontSize: '20' })
+
+  export const label = style({ color: 'content.secondary', typography: 'body.b2' })
+
+  export const row = style({
+    alignItems: 'center',
+    display: 'flex',
+    justifyContent: 'space-between',
+    minHeight: '32',
+  })
+
+  export const stack = style({
+    display: 'flex',
+    flexDirection: 'column',
+    rowGap: '16',
+    width: '16rem !custom',
+  })
+
+  export const title = style({ color: 'content.primary', typography: 'body.b2Strong' })
+
+  export const toast = style({
+    alignItems: 'center',
+    backgroundColor: 'background.elevated',
+    borderRadius: 'sm',
+    boxShadow: 'regular',
+    boxSizing: 'border-box',
+    columnGap: '12',
+    display: 'flex',
+    paddingBlock: '16',
+    paddingInline: '20',
+  })
+
+  export const value = style({
+    alignItems: 'center',
+    color: 'content.primary',
+    columnGap: '4',
+    display: 'flex',
+    typography: 'mono.m1',
+  })
+}
+```
+
+### Choose a Variant by Context
+
+* **Text (default):** Inline values in rows, tables, and cards.
+* **Secondary (secondary):** A standalone value you mainly copy, such as an invite link.
+
+Keep `small` beside body text. Use `medium` or `large` in touch layouts, or beside a large value or a control of that size.
+
+### Let a Clickable Row Copy
+
+If a whole row copies on press, handle the copy in the row and pass `copied` to the button. The button shows the confirmation without a second copy. [Snippet](/docs/components/snippet) and [SecretValue](/docs/components/secret-value) work this way.
+
+**Do:** Pass `copied` so the button confirms the row's copy.
+
+```tsx
+/**
+ * Do example for "Let a Clickable Row Copy" on the CopyButton page.
+ * Pass `copied` so the button confirms the row's copy.
+ * @module
+ */
+import { CopyButton, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      <span {...styles.label()}>Invite link</span>
+      <span {...styles.value()}>
+        tempo.xyz/invite/7kq2
+        <CopyButton aria-label="Copy invite link" copied value="https://tempo.xyz/invite/7kq2" />
+      </span>
+    </div>
+  )
+}
+
+namespace styles {
+  export const label = style({ color: 'content.secondary', typography: 'body.b2' })
+
+  // The pressed row draws its hover background, since the preview is inert.
+  export const row = style({
+    alignItems: 'center',
+    backgroundColor: 'container.regular',
+    borderRadius: 'xs',
+    boxSizing: 'border-box',
+    display: 'flex',
+    justifyContent: 'space-between',
+    minHeight: '40',
+    paddingInline: '12',
+    width: '17rem !custom',
+  })
+
+  export const value = style({
+    alignItems: 'center',
+    color: 'content.primary',
+    columnGap: '4',
+    display: 'flex',
+    typography: 'mono.m1',
+  })
+}
+```
+
+**Don't:** Leave the button unconfirmed after the row copies.
+
+```tsx
+/**
+ * Don't example for "Let a Clickable Row Copy" on the CopyButton page.
+ * Don't leave the button unconfirmed after the row copies.
+ * @module
+ */
+import { CopyButton, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      <span {...styles.label()}>Invite link</span>
+      <span {...styles.value()}>
+        tempo.xyz/invite/7kq2
+        <CopyButton aria-label="Copy invite link" value="https://tempo.xyz/invite/7kq2" />
+      </span>
+    </div>
+  )
+}
+
+namespace styles {
+  export const label = style({ color: 'content.secondary', typography: 'body.b2' })
+
+  // The pressed row draws its hover background, since the preview is inert.
+  export const row = style({
+    alignItems: 'center',
+    backgroundColor: 'container.regular',
+    borderRadius: 'xs',
+    boxSizing: 'border-box',
+    display: 'flex',
+    justifyContent: 'space-between',
+    minHeight: '40',
+    paddingInline: '12',
+    width: '17rem !custom',
+  })
+
+  export const value = style({
+    alignItems: 'center',
+    color: 'content.primary',
+    columnGap: '4',
+    display: 'flex',
+    typography: 'mono.m1',
+  })
+}
+```
+
+## Accessibility
+
+A copy button renders an icon-only [Button](/docs/components/button) with a visually hidden status message. It follows the [WAI-ARIA Authoring Practices button pattern](https://www.w3.org/WAI/ARIA/apg/patterns/button/).
+
+### Semantics
+
+* **Button (button):** A native button. Enter and Space copy, and it joins the tab order.
+* **Name (aria-label):** Defaults to "Copy" and the value. Shows on hover, not on focus or touch.
+* **Copied State (2s):** After a copy, the name changes to "Copied", then returns.
+* **Status Region (status):** A polite live region holds the confirmation text.
+* **Disabled (disabled):** Removes the button from the tab order unless you set `focusableWhenDisabled`.
+* **Clipboard Fallback (execCommand):** Copies where the Clipboard API is unavailable, such as insecure contexts and some iframes.
+
+### Keyboard
+
+* **Move Focus to the Button (Tab):** Moves focus to the button.
+* **Copy the Value (Enter or Space):** Copies the value.
+
+### Your Responsibilities
+
+* **Name What It Copies (aria-label):** Name the value, such as "Copy address". A raw address reads poorly.
+* **Announce Parent Failures (copied):** If a parent copies on its own click, announce failures from that parent.
+
+## Related
+
+[Hex](/docs/components/hex)
+
+Use for addresses and hashes with copying built in.
+
+[Snippet](/docs/components/snippet)
+
+Use for commands and code.
+
+[SecretValue](/docs/components/secret-value)
+
+Use for API keys and secrets.
+
+[Button](/docs/components/button)
+
+Use for other icon-only actions.
+
+[Blockchain Values](/docs/patterns/blockchain-values)
+
+Covers showing addresses, hashes, and amounts.