@tempoxyz/ds 0.3.9 → 0.3.11

package/dist/docs/components/tooltip.md

@@ -0,0 +1,490 @@
+# Tooltip
+
+Shows a short label for a control on hover or focus.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Tooltip.tsx)
+
+Figma: [Tooltip](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=3084-1076) (`Tooltip.Popup`)
+
+## Overview
+
+A tooltip is a visual label that opens on hover and keyboard focus.
+
+## Examples
+
+### Basic
+
+```tsx
+import { Button, Tooltip } from '@tempoxyz/ds'
+import { Plus } from '@tempoxyz/ds/icons'
+
+export function Demo() {
+  return (
+    <Tooltip.Provider>
+      <Tooltip.Root>
+        <Tooltip.Trigger
+          render={<Button aria-label="Add funds" shape="icon" variant="secondary" />}
+        >
+          <Plus />
+        </Tooltip.Trigger>
+        <Tooltip.Popup>Add funds</Tooltip.Popup>
+      </Tooltip.Root>
+    </Tooltip.Provider>
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Tooltip/Basic.tsx)
+
+### Side
+
+Set `side` on `Tooltip.Popup` to `top` (default), `bottom`, `left`, or `right`.
+
+```tsx
+import { Button, Tooltip } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <Tooltip.Provider>
+      <Tooltip.Root>
+        <Tooltip.Trigger render={<Button variant="secondary" />}>Bottom</Tooltip.Trigger>
+        <Tooltip.Popup side="bottom">Shown below the trigger</Tooltip.Popup>
+      </Tooltip.Root>
+    </Tooltip.Provider>
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Tooltip/Side.tsx)
+
+### Disabled
+
+Wrap a disabled control in a focusable trigger. Disabled elements receive no pointer or focus events.
+
+```tsx
+import { Button, Tooltip } from '@tempoxyz/ds'
+import { Refresh } from '@tempoxyz/ds/icons'
+
+export function Demo() {
+  return (
+    <Tooltip.Provider>
+      <Tooltip.Root>
+        <Tooltip.Trigger render={<span tabIndex={0} />}>
+          <Button aria-label="Refresh balances" disabled shape="icon" variant="secondary">
+            <Refresh />
+          </Button>
+        </Tooltip.Trigger>
+        <Tooltip.Popup>Refresh balances</Tooltip.Popup>
+      </Tooltip.Root>
+    </Tooltip.Provider>
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Tooltip/Disabled.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { Tooltip } from '@tempoxyz/ds'
+
+<Tooltip.Provider>
+  <Tooltip.Root>
+    <Tooltip.Trigger />
+    <Tooltip.Popup />
+  </Tooltip.Root>
+</Tooltip.Provider>
+```
+
+## Guidelines
+
+### When to Use
+
+* Label an icon-only button, such as Refresh balances, Filter activity, or Settings.
+* Name a control whose icon is ambiguous, such as an arrow that could mean Send or Export.
+
+### When Not to Use
+
+* Use a [Popover](/docs/components/popover) with `openOnHover` on `Popover.Trigger` for info icons, such as the explanation beside a dashboard metric.
+* Use visible text, such as a `Field.Description` from [Field](/docs/components/field), for fees, limits, requirements, and errors.
+* Use an [Alert](/docs/components/alert) for warnings.
+* Write the reason for a disabled [Button](/docs/components/button) in nearby text, not in a tooltip.
+* Don't add a tooltip to a [Button](/docs/components/button) with a visible label. It repeats the label and covers nearby content.
+
+### Use Tooltips as Labels Only
+
+Focus stays on the trigger while the tooltip is open, so Tab can't reach a link or button inside it.
+
+**Do:** Name the action of an icon-only button in a few words.
+
+```tsx
+/**
+ * Do example for "Use Tooltips as Labels Only" on the Tooltip page.
+ * Name the action of an icon-only button in a few words.
+ * @module
+ */
+import { Button, style } from '@tempoxyz/ds'
+import { Filter } from '@tempoxyz/ds/icons'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.stack()}>
+      <div {...styles.tooltip()}>Filter activity</div>
+      <Button aria-label="Filter activity" shape="icon" variant="secondary">
+        <Filter />
+      </Button>
+    </div>
+  )
+}
+
+namespace styles {
+  export const stack = style({
+    alignItems: 'center',
+    display: 'flex',
+    flexDirection: 'column',
+    rowGap: '8',
+  })
+
+  export const tooltip = style({
+    backgroundColor: 'content.primary',
+    borderRadius: 'xs',
+    color: 'background.primary',
+    paddingBlock: '6px !custom',
+    paddingInline: '12',
+    typography: 'body.b3',
+  })
+}
+```
+
+**Don't:** Put links, buttons, or other controls in a tooltip. Use a
+[Popover](/docs/components/popover).
+
+```tsx
+/**
+ * Don't example for "Use Tooltips as Labels Only" on the Tooltip page.
+ * Don't put links, buttons, or other controls in a tooltip. Use a Popover.
+ * @module
+ */
+import { Button, style } from '@tempoxyz/ds'
+import { InfoCircle } from '@tempoxyz/ds/icons'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.stack()}>
+      <div {...styles.tooltip()}>
+        Fees depend on network load. <span {...styles.link()}>Learn more</span>
+      </div>
+      <Button aria-label="About network fees" shape="icon" size="small" variant="tertiary">
+        <InfoCircle />
+      </Button>
+    </div>
+  )
+}
+
+namespace styles {
+  export const link = style({ textDecorationLine: 'underline !custom' })
+
+  export const stack = style({
+    alignItems: 'center',
+    display: 'flex',
+    flexDirection: 'column',
+    rowGap: '8',
+  })
+
+  export const tooltip = style({
+    backgroundColor: 'content.primary',
+    borderRadius: 'xs',
+    color: 'background.primary',
+    maxWidth: '14rem !custom',
+    paddingBlock: '6px !custom',
+    paddingInline: '12',
+    typography: 'body.b3',
+  })
+}
+```
+
+### Keep Essential Information Visible
+
+Touch input never opens a tooltip, and screen readers don't announce it. Show amounts, fees, and requirements as text on the page.
+
+**Do:** Show the fee and its explanation as visible text.
+
+```tsx
+/**
+ * Do example for "Keep Essential Information Visible" on the Tooltip page.
+ * Show the fee and its explanation as visible text.
+ * @module
+ */
+import { style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      <div {...styles.text()}>
+        <span {...styles.label()}>Network fee</span>
+        <span {...styles.hint()}>Paid in the token you send</span>
+      </div>
+      <span {...styles.value()}>0.001 USDC</span>
+    </div>
+  )
+}
+
+namespace styles {
+  export const hint = style({ color: 'content.secondary', typography: 'body.b3' })
+
+  export const label = style({ color: 'content.primary', typography: 'body.b2Strong' })
+
+  export const row = style({
+    alignItems: 'center',
+    columnGap: '24',
+    display: 'flex',
+    justifyContent: 'space-between',
+    width: '16rem !custom',
+  })
+
+  export const text = style({ display: 'flex', flexDirection: 'column', rowGap: '4' })
+
+  export const value = style({ color: 'content.primary', typography: 'body.b2' })
+}
+```
+
+**Don't:** Hide a value you need to decide behind a tooltip.
+
+```tsx
+/**
+ * Don't example for "Keep Essential Information Visible" on the Tooltip page.
+ * Don't hide a value you need to decide behind a tooltip.
+ * @module
+ */
+import { Button, style } from '@tempoxyz/ds'
+import { InfoCircle } from '@tempoxyz/ds/icons'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.stack()}>
+      <div {...styles.tooltip()}>0.001 USDC, paid in the token you send</div>
+      <div {...styles.row()}>
+        <span {...styles.label()}>Network fee</span>
+        <Button aria-label="Network fee" shape="icon" size="small" variant="tertiary">
+          <InfoCircle />
+        </Button>
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const label = style({ color: 'content.primary', typography: 'body.b2Strong' })
+
+  export const row = style({ alignItems: 'center', columnGap: '4', display: 'flex' })
+
+  export const stack = style({
+    alignItems: 'flex-end',
+    display: 'flex',
+    flexDirection: 'column',
+    rowGap: '8',
+  })
+
+  export const tooltip = style({
+    backgroundColor: 'content.primary',
+    borderRadius: 'xs',
+    color: 'background.primary',
+    paddingBlock: '6px !custom',
+    paddingInline: '12',
+    typography: 'body.b3',
+  })
+}
+```
+
+### Group Tooltips With a Provider
+
+* **Toolbars (Tooltip.Provider):** Wrap a row of icon buttons, so once one tooltip opens, its neighbors open instantly.
+* **Single Triggers (600ms):** Keep the default `delay`. Shorter delays flash tooltips as the pointer passes.
+
+### Place Tooltips Clear of Related Content
+
+`Tooltip.Popup` flips when it would overflow the viewport. Set `side="bottom"` for triggers in a header or top toolbar.
+
+**Do:** Choose a side that keeps the value the control acts on visible.
+
+```tsx
+/**
+ * Do example for "Place Tooltips Clear of Related Content" on the Tooltip page.
+ * Choose a side that keeps the value the control acts on visible.
+ * @module
+ */
+import { Button, style } from '@tempoxyz/ds'
+import { Refresh } from '@tempoxyz/ds/icons'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.card()}>
+      <span {...styles.label()}>Balance</span>
+      <div {...styles.row()}>
+        <span {...styles.value()}>1,250.00 USDC</span>
+        <span {...styles.anchor()}>
+          <Button aria-label="Refresh balance" shape="icon" size="small" variant="secondary">
+            <Refresh />
+          </Button>
+          <span {...styles.tooltip()}>Refresh balance</span>
+        </span>
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const anchor = style({ display: 'flex', position: 'relative' })
+
+  export const card = style({
+    display: 'flex',
+    flexDirection: 'column',
+    height: '7rem !custom',
+    rowGap: '4',
+    width: '17rem !custom',
+  })
+
+  export const label = style({ color: 'content.secondary', typography: 'body.b3' })
+
+  export const row = style({ alignItems: 'center', columnGap: '8', display: 'flex' })
+
+  // Tooltips render in a portal, so this preview places one with the popup's styles, below the trigger.
+  export const tooltip = style({
+    backgroundColor: 'content.primary',
+    borderRadius: 'xs',
+    color: 'background.primary',
+    paddingBlock: '6px !custom',
+    paddingInline: '12',
+    position: 'absolute',
+    right: '0',
+    top: 'calc(100% + 8px) !custom',
+    typography: 'body.b3',
+    whiteSpace: 'nowrap',
+  })
+
+  export const value = style({ color: 'content.primary', typography: 'heading.h2' })
+}
+```
+
+**Don't:** Let the tooltip cover the value beside its trigger.
+
+```tsx
+/**
+ * Don't example for "Place Tooltips Clear of Related Content" on the Tooltip page.
+ * Don't let the tooltip cover the value beside its trigger.
+ * @module
+ */
+import { Button, style } from '@tempoxyz/ds'
+import { Refresh } from '@tempoxyz/ds/icons'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.card()}>
+      <span {...styles.label()}>Balance</span>
+      <div {...styles.row()}>
+        <span {...styles.value()}>1,250.00 USDC</span>
+        <span {...styles.anchor()}>
+          <Button aria-label="Refresh balance" shape="icon" size="small" variant="secondary">
+            <Refresh />
+          </Button>
+          <span {...styles.tooltip()}>Refresh balance</span>
+        </span>
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const anchor = style({ display: 'flex', position: 'relative' })
+
+  export const card = style({
+    display: 'flex',
+    flexDirection: 'column',
+    height: '7rem !custom',
+    rowGap: '4',
+    width: '17rem !custom',
+  })
+
+  export const label = style({ color: 'content.secondary', typography: 'body.b3' })
+
+  export const row = style({ alignItems: 'center', columnGap: '8', display: 'flex' })
+
+  // Tooltips render in a portal, so this preview places one with the popup's styles, left of the trigger.
+  export const tooltip = style({
+    backgroundColor: 'content.primary',
+    borderRadius: 'xs',
+    color: 'background.primary',
+    paddingBlock: '6px !custom',
+    paddingInline: '12',
+    position: 'absolute',
+    right: 'calc(100% + 8px) !custom',
+    top: '50% !custom',
+    transform: 'translateY(-50%) !custom',
+    typography: 'body.b3',
+    whiteSpace: 'nowrap',
+  })
+
+  export const value = style({ color: 'content.primary', typography: 'heading.h2' })
+}
+```
+
+## Content
+
+### Write a Few Words
+
+Use one to four words. Name the action, such as Refresh balances, not the icon, such as Circular arrows.
+
+## Accessibility
+
+A tooltip is visual only, so the trigger needs its own accessible name.
+
+### Semantics
+
+* **Tooltip.Trigger (button):** Keeps the role of the element it renders.
+* **Tooltip.Popup:** Has no role and isn't linked to the trigger, so it neither names nor describes it. Mounts only while open.
+* **Contrast (elevated):** Sets primary text on the elevated fill in both schemes.
+
+### Keyboard
+
+* **Open on Focus (Tab):** Focus on the trigger opens the tooltip at once.
+* **Close the Tooltip (Escape):** Closes the tooltip while focus stays on the trigger.
+
+### Focus
+
+* **No Focus:** The tooltip never takes focus and holds no interactive content.
+* **Pointer:** Opens after 600ms of hover. The pointer can move onto the popup without closing it.
+* **Touch:** Touch input never opens it, so no task may depend on one.
+
+### Your Responsibilities
+
+* **Name Icon-Only Triggers (aria-label):** Name an icon-only trigger with the tooltip text.
+
+## Related
+
+[Popover](/docs/components/popover)
+
+Use for info icons and interactive content.
+
+[Button](/docs/components/button)
+
+Use for icon-only buttons.
+
+[CopyButton](/docs/components/copy-button)
+
+Use for a copy action that names itself.
+
+[Field](/docs/components/field)
+
+Use for descriptions that stay visible.
+
+[Dashboards](/docs/patterns/dashboards)
+
+Covers metric explanations.

package/dist/docs/components/verification-code.md

@@ -0,0 +1,116 @@
+# VerificationCode
+
+Shows a code that a person compares with the one another app shows.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/VerificationCode.tsx)
+
+Figma: [Content/Verification Code](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=5227-3952) (`VerificationCode.Root`)
+
+## Overview
+
+A verification code renders a centered box with a label above a large code. A person reads the code and checks that it matches the code on another device or app, such as in a device sign-in.
+
+## Examples
+
+### Basic
+
+```tsx
+import { VerificationCode } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <VerificationCode.Root>
+      <VerificationCode.Label>Confirm this code matches Claude</VerificationCode.Label>
+      <VerificationCode.Value>WXYZ-4821</VerificationCode.Value>
+    </VerificationCode.Root>
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/VerificationCode/Basic.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { VerificationCode } from '@tempoxyz/ds'
+
+<VerificationCode.Root>
+  <VerificationCode.Label />
+  <VerificationCode.Value />
+</VerificationCode.Root>
+```
+
+## Guidelines
+
+### When to Use
+
+* Confirm a device sign-in by matching the code that an app or a terminal shows.
+* Pair two devices by a code that both show.
+
+### When Not to Use
+
+* Use [OtpField](/docs/components/otp-field) when the person types a code.
+* Use [Snippet](/docs/components/snippet) for a command or a value to copy.
+
+### Match the Other Device
+
+**Do:** Name the app that shows the code, and keep its grouping.
+
+```tsx
+import { VerificationCode } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <VerificationCode.Root>
+      <VerificationCode.Label>Confirm this code matches Claude</VerificationCode.Label>
+      <VerificationCode.Value>WXYZ-4821</VerificationCode.Value>
+    </VerificationCode.Root>
+  )
+}
+```
+
+**Don't:** Regroup the code, or leave out where it comes from.
+
+```tsx
+import { VerificationCode } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <VerificationCode.Root>
+      <VerificationCode.Label>Your code</VerificationCode.Label>
+      <VerificationCode.Value>WX YZ 48 21</VerificationCode.Value>
+    </VerificationCode.Root>
+  )
+}
+```
+
+## Content
+
+### Write the Label
+
+Start the label with the action, such as Confirm this code matches Claude. Name the app or device that shows the other code.
+
+## Accessibility
+
+A verification code renders a `<div>` with the label in a `<p>` and the code in a `<span>`. Screen readers read the label, then the code.
+
+### Semantics
+
+* **Label (p):** Screen readers read the label before the code.
+* **Value (translate=no):** Browsers do not translate the code, and a click selects all of it.
+
+### Your Responsibilities
+
+* **Keep the Code on Screen (SC 3.3.8):** Show the code until the sign-in finishes, so people can compare it.
+
+## Related
+
+[OtpField](/docs/components/otp-field)
+
+Use for a code that a person types.
+
+[Snippet](/docs/components/snippet)
+
+Use for a command or a value to copy.