@tempoxyz/ds 0.3.10 → 0.3.13

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

@@ -0,0 +1,627 @@
+# Tabs
+
+Switches between related views.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Tabs.tsx)
+
+Figma: [Controls/Tab](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=5227-3285) (`Tabs.Tab`), [Tab](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=1186-3208) (`Tabs.Tab`)
+
+## Overview
+
+Tabs render an underlined or pill tab list over a set of panels. Use them for related content, and use links for page navigation.
+
+## Examples
+
+### Basic
+
+```tsx
+import { Tabs } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <Tabs.Root defaultValue="overview">
+      <Tabs.List aria-label="Sections">
+        <Tabs.Tab value="overview">Overview</Tabs.Tab>
+        <Tabs.Tab value="activity">Activity</Tabs.Tab>
+        <Tabs.Tab value="settings">Settings</Tabs.Tab>
+        <Tabs.Indicator />
+      </Tabs.List>
+      <Tabs.Panel value="overview">Overview content</Tabs.Panel>
+      <Tabs.Panel value="activity">Activity content</Tabs.Panel>
+      <Tabs.Panel value="settings">Settings content</Tabs.Panel>
+    </Tabs.Root>
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Tabs/Basic.tsx)
+
+### Size
+
+Set `size` on `Tabs.List` to `small`, `medium` (default), or `large`, for 32px, 40px, or 56px tabs.
+
+```tsx
+import { Stack, Tabs } from '@tempoxyz/ds'
+import { Plus } from '@tempoxyz/ds/icons'
+
+export function Demo() {
+  return (
+    <Stack align="start" gap="24">
+      {(['small', 'medium', 'large'] as const).map((size) => (
+        <Tabs.Root defaultValue="overview" key={size}>
+          <Tabs.List aria-label={`Sections ${size}`} size={size}>
+            <Tabs.Tab value="overview">Overview</Tabs.Tab>
+            <Tabs.Tab value="activity">
+              <Plus />
+              Activity
+            </Tabs.Tab>
+            <Tabs.Tab disabled value="settings">
+              Settings
+            </Tabs.Tab>
+            <Tabs.Indicator />
+          </Tabs.List>
+          <Tabs.Panel value="overview">Overview content</Tabs.Panel>
+          <Tabs.Panel value="activity">Activity content</Tabs.Panel>
+        </Tabs.Root>
+      ))}
+    </Stack>
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Tabs/Size.tsx)
+
+### Disabled
+
+Set `disabled` on a `Tabs.Tab` to skip it during selection.
+
+```tsx
+import { Tabs } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <Tabs.Root defaultValue="overview">
+      <Tabs.List aria-label="Sections">
+        <Tabs.Tab value="overview">Overview</Tabs.Tab>
+        <Tabs.Tab value="activity">Activity</Tabs.Tab>
+        <Tabs.Tab disabled value="settings">
+          Settings
+        </Tabs.Tab>
+        <Tabs.Indicator />
+      </Tabs.List>
+      <Tabs.Panel value="overview">Overview content</Tabs.Panel>
+      <Tabs.Panel value="activity">Activity content</Tabs.Panel>
+    </Tabs.Root>
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Tabs/Disabled.tsx)
+
+### Expand
+
+Set `expand` on `Tabs.List` to stretch the tabs across the available width.
+
+```tsx
+import { Tabs } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <Tabs.Root defaultValue="activity" style={{ width: '20rem' }}>
+      <Tabs.List aria-label="Account" expand>
+        <Tabs.Tab value="activity">Activity</Tabs.Tab>
+        <Tabs.Tab value="assets">Assets</Tabs.Tab>
+        <Tabs.Tab value="keys">Keys</Tabs.Tab>
+        <Tabs.Indicator />
+      </Tabs.List>
+    </Tabs.Root>
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Tabs/Expand.tsx)
+
+### Pill
+
+Set `variant="pill"` on `Tabs.List` for filled tabs. The fill marks the active tab, so a pill list takes no `Tabs.Indicator`. Pill tabs are 32px, 40px, or 48px tall.
+
+```tsx
+import { Stack, Tabs } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <Stack align="start" gap="24">
+      {(['small', 'medium', 'large'] as const).map((size) => (
+        <Tabs.Root defaultValue="all" key={size}>
+          <Tabs.List aria-label={`Transfers ${size}`} size={size} variant="pill">
+            <Tabs.Tab value="all">All</Tabs.Tab>
+            <Tabs.Tab value="payments">Payments</Tabs.Tab>
+            <Tabs.Tab value="payouts">Payouts</Tabs.Tab>
+          </Tabs.List>
+        </Tabs.Root>
+      ))}
+    </Stack>
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Tabs/Pill.tsx)
+
+### Appearance
+
+Set `appearance` on a pill `Tabs.List` to `base` (default) on the page, `inverse` on an inverse surface, or `overlay` over an image or video.
+
+```tsx
+import { Stack, Tabs, variants } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <Stack gap="16">
+      {(['base', 'inverse', 'overlay'] as const).map((appearance) => (
+        <div key={appearance} {...styles.surface({ appearance })}>
+          <Tabs.Root defaultValue="all">
+            <Tabs.List
+              appearance={appearance}
+              aria-label={`Transfers ${appearance}`}
+              variant="pill"
+            >
+              <Tabs.Tab value="all">All</Tabs.Tab>
+              <Tabs.Tab value="payments">Payments</Tabs.Tab>
+              <Tabs.Tab value="payouts">Payouts</Tabs.Tab>
+            </Tabs.List>
+          </Tabs.Root>
+        </div>
+      ))}
+    </Stack>
+  )
+}
+
+namespace styles {
+  export const surface = variants({
+    base: { borderRadius: 'sm', padding: '16' },
+    variants: {
+      appearance: {
+        base: { backgroundColor: 'background.primary' },
+        inverse: { backgroundColor: 'inverse.background.primary' },
+        overlay: {
+          backgroundImage: 'linear-gradient(135deg, #4471ed, #7e59e4) !custom',
+        },
+      },
+    },
+  })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Tabs/Appearance.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { Tabs } from '@tempoxyz/ds'
+
+<Tabs.Root>
+  <Tabs.List>
+    <Tabs.Tab />
+    <Tabs.Indicator />
+  </Tabs.List>
+  <Tabs.Panel />
+</Tabs.Root>
+```
+
+## Guidelines
+
+### When to Use
+
+* Switch between views of one subject at the same level, such as a webhook's Overview, Deliveries, and Settings.
+* Split a dense page into parts used one at a time, such as Balances and Activity on a wallet's home screen.
+
+### When Not to Use
+
+* Use [ChoiceGroup](choice-group.md) to pick a value that changes the current view, such as a chart's 1D, 1W, or 1M range.
+* Use [SidebarMenu](sidebar-menu.md) or links to move between pages with their own URLs.
+* Use [Stepper](stepper.md) for steps completed in order.
+* Use [Accordion](accordion.md) to open several sections at once, or to compare them.
+
+### Keep Tabs Few and Short
+
+Use two to five tabs with one-word or two-word labels. Overflowing tabs scroll sideways, and tabs past the edge are easy to miss.
+
+* **Never applies:** Hide the tab.
+* **Temporarily unavailable:** Disable the tab, such as Deliveries before a webhook's first event, and state why in the open panel.
+
+**Do:** Use a few short, parallel labels.
+
+```tsx
+/** Do example for "Keep Tabs Few and Short" on the Tabs page: use a few short, parallel labels. @module */
+import { Tabs } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Tabs.Root defaultValue="overview">
+      <Tabs.List aria-label="Webhook">
+        <Tabs.Tab value="overview">Overview</Tabs.Tab>
+        <Tabs.Tab value="deliveries">Deliveries</Tabs.Tab>
+        <Tabs.Tab value="settings">Settings</Tabs.Tab>
+        <Tabs.Indicator />
+      </Tabs.List>
+    </Tabs.Root>
+  )
+}
+```
+
+**Don't:** Add so many tabs that the row scrolls.
+
+```tsx
+/**
+ * Don't example for "Keep Tabs Few and Short" on the Tabs page.
+ * Don't add so many tabs that the row scrolls.
+ * @module
+ */
+import { style, Tabs } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Tabs.Root defaultValue="overview" {...styles.root()}>
+      <Tabs.List aria-label="Webhook">
+        <Tabs.Tab value="overview">Endpoint overview</Tabs.Tab>
+        <Tabs.Tab value="deliveries">Recent deliveries</Tabs.Tab>
+        <Tabs.Tab value="failed">Failed attempts</Tabs.Tab>
+        <Tabs.Tab value="secrets">Signing secrets</Tabs.Tab>
+        <Tabs.Tab value="settings">Settings</Tabs.Tab>
+        <Tabs.Indicator />
+      </Tabs.List>
+    </Tabs.Root>
+  )
+}
+
+namespace styles {
+  export const root = style({ maxWidth: '100% !custom' })
+}
+```
+
+### Place One Indicator in Every Underline List
+
+Put a `Tabs.Indicator` after the tabs in each underline `Tabs.List`. It slides a bar under the active tab.
+
+**Do:** End every list with a `Tabs.Indicator`.
+
+```tsx
+/** Do example for "Keep Tabs Few and Short" on the Tabs page: use a few short, parallel labels. @module */
+import { Tabs } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Tabs.Root defaultValue="overview">
+      <Tabs.List aria-label="Webhook">
+        <Tabs.Tab value="overview">Overview</Tabs.Tab>
+        <Tabs.Tab value="deliveries">Deliveries</Tabs.Tab>
+        <Tabs.Tab value="settings">Settings</Tabs.Tab>
+        <Tabs.Indicator />
+      </Tabs.List>
+    </Tabs.Root>
+  )
+}
+```
+
+**Don't:** Leave out the indicator, so only the label marks the active tab.
+
+```tsx
+/**
+ * Don't example for "Place One Indicator in Every List" on the Tabs page.
+ * Don't leave out the indicator, so only the label marks the active tab.
+ * @module
+ */
+import { Tabs } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Tabs.Root defaultValue="overview">
+      <Tabs.List aria-label="Webhook">
+        <Tabs.Tab value="overview">Overview</Tabs.Tab>
+        <Tabs.Tab value="deliveries">Deliveries</Tabs.Tab>
+        <Tabs.Tab value="settings">Settings</Tabs.Tab>
+      </Tabs.List>
+    </Tabs.Root>
+  )
+}
+```
+
+### Keep Panels Independent
+
+Make each panel complete on its own. A Save button in one panel can't show errors in another, so use a [Stepper](stepper.md) flow or one longer form.
+
+**Do:** Keep the fields of one form together.
+
+```tsx
+/** Do example for "Keep Panels Independent" on the Tabs page: keep the fields of one form together. @module */
+import { Button, Field, Stack, style, TextInput } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Stack gap="16" {...styles.fill()}>
+      <Field.Root>
+        <Field.Label>Key name</Field.Label>
+        <TextInput.Group>
+          <TextInput.Control defaultValue="Checkout server" />
+        </TextInput.Group>
+      </Field.Root>
+      <Field.Root>
+        <Field.Label>Daily limit</Field.Label>
+        <TextInput.Group>
+          <TextInput.Control defaultValue="5,000.00 USDC" />
+        </TextInput.Group>
+      </Field.Root>
+      <div {...styles.actions()}>
+        <Button size="small">Save key</Button>
+      </div>
+    </Stack>
+  )
+}
+
+namespace styles {
+  export const actions = style({ columnGap: '8', display: 'flex', justifyContent: 'flex-end' })
+
+  export const fill = style({ width: '100% !custom' })
+}
+```
+
+**Don't:** Split a form across tabs.
+
+```tsx
+/** Don't example for "Keep Panels Independent" on the Tabs page. Don't split a form across tabs. @module */
+import { Button, Field, Stack, style, Tabs, TextInput } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Tabs.Root defaultValue="details" {...styles.fill()}>
+      <Tabs.List aria-label="Key" size="small">
+        <Tabs.Tab value="details">Details</Tabs.Tab>
+        <Tabs.Tab value="limits">Limits</Tabs.Tab>
+        <Tabs.Indicator />
+      </Tabs.List>
+      <Tabs.Panel value="details">
+        <Stack gap="16" {...styles.panel()}>
+          <Field.Root>
+            <Field.Label>Key name</Field.Label>
+            <TextInput.Group>
+              <TextInput.Control defaultValue="Checkout server" />
+            </TextInput.Group>
+          </Field.Root>
+          <div {...styles.actions()}>
+            <Button size="small">Save key</Button>
+          </div>
+        </Stack>
+      </Tabs.Panel>
+    </Tabs.Root>
+  )
+}
+
+namespace styles {
+  export const actions = style({ columnGap: '8', display: 'flex', justifyContent: 'flex-end' })
+
+  export const fill = style({ width: '100% !custom' })
+
+  export const panel = style({ marginBlockStart: '16' })
+}
+```
+
+### Keep the Selected Tab on Reload
+
+If a tab marks a significant view, store it in the URL. Control `Tabs.Root` with `value` and `onValueChange`.
+
+**Do:** Store the tab in the URL, such as `?tab=deliveries`, so a reload or a shared link opens it.
+
+```tsx
+/**
+ * Do example for "Keep the Selected Tab on Reload" on the Tabs page.
+ * Store the tab in the URL, such as `?tab=deliveries`, so a reload or a shared link opens it.
+ * @module
+ */
+import { style, Tabs } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.page()}>
+      <span {...styles.address()}>console.tempo.xyz/webhooks/wh_8f3a?tab=deliveries</span>
+      <Tabs.Root defaultValue="deliveries">
+        <Tabs.List aria-label="Webhook" size="small">
+          <Tabs.Tab value="overview">Overview</Tabs.Tab>
+          <Tabs.Tab value="deliveries">Deliveries</Tabs.Tab>
+          <Tabs.Tab value="settings">Settings</Tabs.Tab>
+          <Tabs.Indicator />
+        </Tabs.List>
+      </Tabs.Root>
+    </div>
+  )
+}
+
+namespace styles {
+  export const address = style({
+    backgroundColor: 'container.regular',
+    borderRadius: 'full',
+    color: 'content.secondary',
+    cornerShape: 'round',
+    paddingBlock: '4',
+    paddingInline: '12',
+    typography: 'body.b3',
+  })
+
+  export const page = style({ display: 'flex', flexDirection: 'column', rowGap: '16' })
+}
+```
+
+**Don't:** Reset a reloaded or shared page to the first tab.
+
+```tsx
+/**
+ * Don't example for "Keep the Selected Tab on Reload" on the Tabs page.
+ * Don't reset a reloaded or shared page to the first tab.
+ * @module
+ */
+import { style, Tabs } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.page()}>
+      <span {...styles.address()}>console.tempo.xyz/webhooks/wh_8f3a</span>
+      <Tabs.Root defaultValue="overview">
+        <Tabs.List aria-label="Webhook" size="small">
+          <Tabs.Tab value="overview">Overview</Tabs.Tab>
+          <Tabs.Tab value="deliveries">Deliveries</Tabs.Tab>
+          <Tabs.Tab value="settings">Settings</Tabs.Tab>
+          <Tabs.Indicator />
+        </Tabs.List>
+      </Tabs.Root>
+    </div>
+  )
+}
+
+namespace styles {
+  export const address = style({
+    backgroundColor: 'container.regular',
+    borderRadius: 'full',
+    color: 'content.secondary',
+    cornerShape: 'round',
+    paddingBlock: '4',
+    paddingInline: '12',
+    typography: 'body.b3',
+  })
+
+  export const page = style({ display: 'flex', flexDirection: 'column', rowGap: '16' })
+}
+```
+
+### Expand Tabs in Narrow Containers
+
+Set `expand` in a narrow container, such as a [Surface](surface.md) or a phone-width column. Leave it off across a wide page, where stretched tabs drift apart.
+
+**Do:** Stretch the tabs across a narrow card with `expand`.
+
+```tsx
+/**
+ * Do example for "Expand Tabs in Narrow Containers" on the Tabs page.
+ * Stretch the tabs across a narrow card with `expand`.
+ * @module
+ */
+import { style, Surface, Tabs } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Surface size="small" {...styles.card()}>
+      <Tabs.Root defaultValue="balances">
+        <Tabs.List aria-label="Wallet" expand size="small">
+          <Tabs.Tab value="balances">Balances</Tabs.Tab>
+          <Tabs.Tab value="activity">Activity</Tabs.Tab>
+          <Tabs.Indicator />
+        </Tabs.List>
+      </Tabs.Root>
+    </Surface>
+  )
+}
+
+namespace styles {
+  export const card = style({ width: '16rem !custom' })
+}
+```
+
+**Don't:** Leave a gap at the end of the row in a narrow card.
+
+```tsx
+/**
+ * Don't example for "Expand Tabs in Narrow Containers" on the Tabs page.
+ * Don't leave a gap at the end of the row in a narrow card.
+ * @module
+ */
+import { style, Surface, Tabs } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Surface size="small" {...styles.card()}>
+      <Tabs.Root defaultValue="balances">
+        <Tabs.List aria-label="Wallet" size="small">
+          <Tabs.Tab value="balances">Balances</Tabs.Tab>
+          <Tabs.Tab value="activity">Activity</Tabs.Tab>
+          <Tabs.Indicator />
+        </Tabs.List>
+      </Tabs.Root>
+    </Surface>
+  )
+}
+
+namespace styles {
+  export const card = style({ width: '16rem !custom' })
+}
+```
+
+## Content
+
+* Use nouns that name the panel's content, such as Overview, Activity, or Settings.
+* Keep labels parallel in form and length, such as Send, Receive, and Swap.
+* Add an icon only if every tab in the list has one.
+* Don't repeat the page title in each label, such as Webhook overview and Webhook settings.
+
+## Accessibility
+
+Tabs follow the [WAI-ARIA tabs pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/), with manual activation by default.
+
+### Semantics
+
+* **Tabs.List (tablist):** Holds the tabs, and needs its own name.
+* **Tabs.Tab (tab):** A button. The active tab is selected and points at its panel.
+* **Tabs.Panel (tabpanel):** Named by its tab. Hidden panels unmount unless you set `keepMounted`, which find in page requires.
+* **Disabled Tabs (aria-disabled):** Reachable with the arrow keys, but can't be activated or shown first.
+* **Tabs.Indicator:** Decorative, and ignores pointer events. Under reduced motion, it moves without sliding.
+
+### Keyboard
+
+* **Move into the List (Tab):** Moves focus to the active tab, then to the open panel.
+* **Move to the Next Tab (Right Arrow):** Moves focus to the next tab, and wraps at the end.
+* **Move to the Previous Tab (Left Arrow):** Moves focus to the previous tab, and wraps at the start.
+* **Move to the First Tab (Home):** Moves focus to the first tab.
+* **Move to the Last Tab (End):** Moves focus to the last tab.
+* **Activate the Tab (Enter or Space):** Activates the focused tab and shows its panel.
+
+Set `activateOnFocus` on `Tabs.List` to activate a tab on focus. Use it only if panels render without delay.
+
+### Focus
+
+* **One Tab Stop:** Only the active tab is in the Tab order. Arrow keys move between tabs.
+* **Focusable Panel:** The open panel is focusable, so Tab moves into it even if it holds no controls.
+
+### Your Responsibilities
+
+* **Name the List (SC 4.1.2):** Name the tab list, such as "Sections".
+
+## Related
+
+[ChoiceGroup](choice-group.md)
+
+Use for one value that changes a view.
+
+[SidebarMenu](sidebar-menu.md)
+
+Use for navigating between pages.
+
+[Accordion](accordion.md)
+
+Use for sections you open together.
+
+[Snippet](snippet.md)
+
+Use for a command with a tab per tool.
+
+[Navigation](../patterns/navigation.md)
+
+Covers choosing between navigation components.