@tempoxyz/ds 0.3.10 → 0.3.13

package/dist/docs/product/components/popover.md

@@ -0,0 +1,544 @@
+# Popover
+
+Opens a non-modal popup anchored to a trigger.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Popover.tsx)
+
+## Overview
+
+Popover renders a non-modal dialog anchored to a trigger, opened on click, for interactive or longer content.
+
+## Examples
+
+### Basic
+
+```tsx
+import { Button, Popover, style } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <Popover.Root>
+      <Popover.Trigger render={<Button variant="secondary" />}>Network fee</Popover.Trigger>
+      <Popover.Popup>
+        <Popover.Title>Network fee</Popover.Title>
+        <Popover.Description>Paid in the token you send.</Popover.Description>
+        <div {...styles.actions()}>
+          <Popover.Close render={<Button size="small" variant="secondary" />}>Got it</Popover.Close>
+        </div>
+      </Popover.Popup>
+    </Popover.Root>
+  )
+}
+
+namespace styles {
+  export const actions = style({ marginTop: '16' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Popover/Basic.tsx)
+
+### Side
+
+Set `side` on `Popover.Popup` to `top`, `right`, `bottom` (default), or `left`. Add `Popover.Arrow` to point toward the trigger.
+
+```tsx
+import { Button, Popover } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <Popover.Root>
+      <Popover.Trigger render={<Button variant="secondary" />}>With arrow</Popover.Trigger>
+      <Popover.Popup side="right">
+        <Popover.Arrow />
+        <Popover.Title>Estimated arrival</Popover.Title>
+        <Popover.Description>About one minute.</Popover.Description>
+      </Popover.Popup>
+    </Popover.Root>
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Popover/Side.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { Popover } from '@tempoxyz/ds'
+
+<Popover.Root>
+  <Popover.Trigger />
+  <Popover.Popup>
+    <Popover.Arrow />
+    <Popover.Title />
+    <Popover.Description />
+    <Popover.Close />
+  </Popover.Popup>
+</Popover.Root>
+```
+
+## Guidelines
+
+### When to Use
+
+* Explain a value with a sentence and a link, such as the methodology behind a throughput tile.
+* Show details on demand, such as the breakdown of a network fee.
+* Edit one setting in place, such as the label of a saved address.
+
+### When Not to Use
+
+* Use a [Tooltip](tooltip.md) for a short label on an icon button.
+* Use a [Menu](menu.md) for a list of actions.
+* Use [Select](select.md), [Combobox](combobox.md), or [DatePicker](date-picker.md) to choose a value.
+* Use a [Dialog](dialog.md) for a task with several fields or full attention.
+* Use a [Drawer](drawer.md) for long content.
+* Use visible text for information everyone needs, such as an error or a required step.
+
+### Keep Content Small
+
+A popover holds a title, a sentence or two, and at most two controls. `Popover.Popup` grows up to the available width, so give text popovers a `maxWidth`, such as 20rem.
+
+**Do:** Explain a metric with a title, one sentence, and a link.
+
+```tsx
+/**
+ * Do example for "Keep Content Small" on the Popover page.
+ * Explain a metric with a title, one sentence, and a link.
+ * @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.header()}>
+        <span {...styles.label()}>Throughput</span>
+        <Button aria-label="About throughput" shape="icon" size="small" variant="tertiary">
+          <InfoCircle />
+        </Button>
+      </div>
+      <div {...styles.popup()}>
+        <span {...styles.title()}>Throughput</span>
+        <p {...styles.description()}>Transactions per second, averaged over each block.</p>
+        <span {...styles.link()}>View methodology</span>
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const description = style({
+    color: 'content.secondary',
+    margin: '0 !custom',
+    typography: 'body.b2',
+  })
+
+  export const header = style({ alignItems: 'center', columnGap: '4', display: 'flex' })
+
+  export const label = style({ color: 'content.primary', typography: 'body.b2Strong' })
+
+  export const link = style({
+    color: 'content.primary',
+    textDecorationLine: 'underline !custom',
+    typography: 'body.b2Strong',
+  })
+
+  export const popup = style({
+    backgroundColor: 'background.elevated',
+    borderRadius: 'sm',
+    boxShadow: 'regular',
+    boxSizing: 'border-box',
+    display: 'flex',
+    flexDirection: 'column',
+    padding: '20',
+    rowGap: '8',
+    width: '15rem !custom',
+  })
+
+  export const stack = style({
+    alignItems: 'flex-start',
+    display: 'flex',
+    flexDirection: 'column',
+    rowGap: '8',
+  })
+
+  export const title = style({ color: 'content.primary', typography: 'body.b1Strong' })
+}
+```
+
+**Don't:** Build a multi-field form in a popover. Use a [Dialog](dialog.md).
+
+```tsx
+/**
+ * Don't example for "Keep Content Small" on the Popover page.
+ * Don't build a multi-field form in a popover. Use a Dialog.
+ * @module
+ */
+import { Button, style, TextInput } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.popup()}>
+      <span {...styles.title()}>New webhook</span>
+      <TextInput.Group>
+        <TextInput.Control aria-label="Endpoint URL" placeholder="Endpoint URL" />
+      </TextInput.Group>
+      <TextInput.Group>
+        <TextInput.Control aria-label="Events" placeholder="Events" />
+      </TextInput.Group>
+      <TextInput.Group>
+        <TextInput.Control aria-label="Signing secret" placeholder="Signing secret" />
+      </TextInput.Group>
+      <div {...styles.actions()}>
+        <Button size="small" variant="secondary">
+          Cancel
+        </Button>
+        <Button size="small">Create webhook</Button>
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const actions = style({
+    columnGap: '8',
+    display: 'flex',
+    justifyContent: 'flex-end',
+    marginTop: '4',
+  })
+
+  export const popup = style({
+    backgroundColor: 'background.elevated',
+    borderRadius: 'sm',
+    boxShadow: 'regular',
+    boxSizing: 'border-box',
+    display: 'flex',
+    flexDirection: 'column',
+    padding: '20',
+    rowGap: '8',
+    width: '16rem !custom',
+  })
+
+  export const title = style({ color: 'content.primary', typography: 'body.b1Strong' })
+}
+```
+
+### Add Hover Without Replacing Click
+
+* **Click (default):** `Popover.Trigger` toggles on click, which covers a mouse, a tap, and Enter or Space.
+* **Hover and Click (openOnHover):** For info icons on dashboards. Opens after 300ms of hover, and click still works.
+
+### Offer a Close Action for Controls
+
+Escape and an outside press close a popover. If it holds controls, add a `Popover.Close` button, such as Cancel or Done, for touch screens.
+
+**Do:** Add a `Popover.Close` action beside the controls.
+
+```tsx
+/**
+ * Do example for "Offer a Close Action for Controls" on the Popover page.
+ * Add a `Popover.Close` action beside the controls.
+ * @module
+ */
+import { Button, style, TextInput } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.popup()}>
+      <span {...styles.title()}>Address label</span>
+      <TextInput.Group>
+        <TextInput.Control aria-label="Label" defaultValue="Alex, main wallet" />
+      </TextInput.Group>
+      <div {...styles.actions()}>
+        <Button size="small" variant="secondary">
+          Cancel
+        </Button>
+        <Button size="small">Save label</Button>
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const actions = style({
+    columnGap: '8',
+    display: 'flex',
+    justifyContent: 'flex-end',
+    marginTop: '4',
+  })
+
+  export const popup = style({
+    backgroundColor: 'background.elevated',
+    borderRadius: 'sm',
+    boxShadow: 'regular',
+    boxSizing: 'border-box',
+    display: 'flex',
+    flexDirection: 'column',
+    padding: '20',
+    rowGap: '8',
+    width: '16rem !custom',
+  })
+
+  export const title = style({ color: 'content.primary', typography: 'body.b1Strong' })
+}
+```
+
+**Don't:** Rely on Escape or an outside press to leave a popover with controls.
+
+```tsx
+/**
+ * Don't example for "Offer a Close Action for Controls" on the Popover page.
+ * Don't rely on Escape or an outside press to leave a popover with controls.
+ * @module
+ */
+import { style, TextInput } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.popup()}>
+      <span {...styles.title()}>Address label</span>
+      <TextInput.Group>
+        <TextInput.Control aria-label="Label" defaultValue="Alex, main wallet" />
+      </TextInput.Group>
+    </div>
+  )
+}
+
+namespace styles {
+  export const popup = style({
+    backgroundColor: 'background.elevated',
+    borderRadius: 'sm',
+    boxShadow: 'regular',
+    boxSizing: 'border-box',
+    display: 'flex',
+    flexDirection: 'column',
+    padding: '20',
+    rowGap: '8',
+    width: '16rem !custom',
+  })
+
+  export const title = style({ color: 'content.primary', typography: 'body.b1Strong' })
+}
+```
+
+### Point at Small Triggers
+
+`Popover.Popup` opens 8px from its trigger. If the trigger is small, such as an info icon in a table header, add `Popover.Arrow`.
+
+**Do:** Add `Popover.Arrow` to point at a small trigger.
+
+```tsx
+/**
+ * Do example for "Point at Small Triggers" on the Popover page.
+ * Add `Popover.Arrow` to point at a small trigger.
+ * @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.header()}>
+        <span {...styles.column()}>
+          Fee
+          <Button aria-label="About fee" shape="icon" size="small" variant="tertiary">
+            <InfoCircle />
+          </Button>
+        </span>
+        <span {...styles.column()}>
+          Throughput
+          <Button aria-label="About throughput" shape="icon" size="small" variant="tertiary">
+            <InfoCircle />
+          </Button>
+        </span>
+      </div>
+      <div {...styles.popup()}>
+        {/* Popover.Arrow needs an open popup, so this preview draws its shape in place. */}
+        <svg
+          aria-hidden="true"
+          fill="currentColor"
+          height="10"
+          viewBox="0 0 20 10"
+          width="20"
+          {...styles.arrow()}
+        >
+          <path d="M0 10C4 10 7 7 8.6 4.6a2 2 0 0 1 2.8 0C13 7 16 10 20 10Z" />
+        </svg>
+        <p {...styles.description()}>Paid in the token you send, about 0.01 USDC.</p>
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const arrow = style({
+    color: 'background.elevated',
+    left: '4.25rem !custom',
+    position: 'absolute',
+    top: '-10px !custom',
+  })
+
+  export const column = style({
+    alignItems: 'center',
+    color: 'content.secondary',
+    columnGap: '2px !custom',
+    display: 'flex',
+    typography: 'body.b3',
+  })
+
+  export const description = style({
+    color: 'content.secondary',
+    margin: '0 !custom',
+    typography: 'body.b2',
+  })
+
+  export const header = style({ columnGap: '24', display: 'flex', paddingInlineStart: '24' })
+
+  export const popup = style({
+    backgroundColor: 'background.elevated',
+    borderRadius: 'sm',
+    boxShadow: 'regular',
+    boxSizing: 'border-box',
+    padding: '16',
+    position: 'relative',
+    width: '15rem !custom',
+  })
+
+  export const stack = style({ display: 'flex', flexDirection: 'column', rowGap: '8' })
+}
+```
+
+**Don't:** Leave the popup's trigger unclear among small icons.
+
+```tsx
+/**
+ * Don't example for "Point at Small Triggers" on the Popover page.
+ * Don't leave the popup's trigger unclear among small icons.
+ * @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.header()}>
+        <span {...styles.column()}>
+          Fee
+          <Button aria-label="About fee" shape="icon" size="small" variant="tertiary">
+            <InfoCircle />
+          </Button>
+        </span>
+        <span {...styles.column()}>
+          Throughput
+          <Button aria-label="About throughput" shape="icon" size="small" variant="tertiary">
+            <InfoCircle />
+          </Button>
+        </span>
+      </div>
+      <div {...styles.popup()}>
+        <p {...styles.description()}>Paid in the token you send, about 0.01 USDC.</p>
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const column = style({
+    alignItems: 'center',
+    color: 'content.secondary',
+    columnGap: '2px !custom',
+    display: 'flex',
+    typography: 'body.b3',
+  })
+
+  export const description = style({
+    color: 'content.secondary',
+    margin: '0 !custom',
+    typography: 'body.b2',
+  })
+
+  export const header = style({ columnGap: '24', display: 'flex', paddingInlineStart: '24' })
+
+  export const popup = style({
+    backgroundColor: 'background.elevated',
+    borderRadius: 'sm',
+    boxShadow: 'regular',
+    boxSizing: 'border-box',
+    padding: '16',
+    width: '15rem !custom',
+  })
+
+  export const stack = style({ display: 'flex', flexDirection: 'column', rowGap: '8' })
+}
+```
+
+## Content
+
+### Title With the Subject
+
+Name the value or setting, such as Network fee, with no question. Put the explanation in `Popover.Description`.
+
+### Lead With the Answer
+
+Start with the explanation, such as Transactions per second, averaged over each block. Keep it under about 25 words.
+
+## Accessibility
+
+### Semantics
+
+* **Popover.Trigger (button):** Announces a dialog that click and keyboard open.
+* **Popover.Popup (dialog):** A non-modal dialog, named by its title.
+* **Popover.Title (h2):** Names the popup.
+* **Popover.Description (p):** Describes the popup to screen readers.
+* **Popover.Arrow (aria-hidden):** Decorative and hidden from assistive technology.
+
+### Keyboard
+
+* **Open and Activate (Enter or Space):** Opens the popover from the trigger, and activates the focused control in it.
+* **Move Through the Popup (Tab):** Moves through the controls in the popup. Past the last control, the popover closes.
+* **Return to the Trigger (Shift+Tab):** From the first control, moves focus back to the trigger.
+* **Close the Popover (Escape):** Closes the popover.
+
+### Focus
+
+* **Opening (initialFocus):** Focus moves to the first control, or to the popup on touch. Pass `initialFocus` to change it.
+* **Non-Modal (modal):** Focus is not trapped, and the page stays interactive unless you set `modal`.
+* **Outside Press:** A press outside the popup closes it.
+* **Closing (finalFocus):** Escape or an outside press returns focus to the trigger. If the trigger is gone, pass `finalFocus`.
+
+### Your Responsibilities
+
+* **Render Popover.Title:** Always render a title, so the dialog has an accessible name.
+* **Name Icon-Only Triggers (aria-label):** Name the trigger's subject, such as "About throughput".
+
+## Related
+
+[Tooltip](tooltip.md)
+
+Use for short labels on icon buttons.
+
+[Dialog](dialog.md)
+
+Use for focused tasks that block the page.
+
+[Drawer](drawer.md)
+
+Use for long content and bottom sheets.
+
+[Menu](menu.md)
+
+Use for lists of actions.
+
+[Dashboards](../patterns/dashboards.md)
+
+Covers explaining metrics.