@tempoxyz/ds 0.3.10 → 0.3.13

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

@@ -0,0 +1,380 @@
+# Breadcrumbs
+
+Shows where the current page sits in the site hierarchy.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Breadcrumbs.tsx)
+
+## Overview
+
+A trail of links from the current page back to its ancestors.
+
+## Examples
+
+### Basic
+
+```tsx
+import { Breadcrumbs } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <Breadcrumbs>
+      <Breadcrumbs.Item href="#">Home</Breadcrumbs.Item>
+      <Breadcrumbs.Item href="#">Payments</Breadcrumbs.Item>
+      <Breadcrumbs.Item current>Invoices</Breadcrumbs.Item>
+    </Breadcrumbs>
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Breadcrumbs/Basic.tsx)
+
+### Separator
+
+Set `separator` to any node to place between items. It defaults to a right chevron.
+
+```tsx
+import { Breadcrumbs } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <Breadcrumbs separator="/">
+      <Breadcrumbs.Item href="#">Docs</Breadcrumbs.Item>
+      <Breadcrumbs.Item current>Guides</Breadcrumbs.Item>
+    </Breadcrumbs>
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Breadcrumbs/Separator.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { Breadcrumbs } from '@tempoxyz/ds'
+
+<Breadcrumbs>
+  <Breadcrumbs.Item />
+</Breadcrumbs>
+```
+
+## Guidelines
+
+### When to Use
+
+* Mark pages three or more levels deep, such as a webhook endpoint inside a project in Tempo Console.
+* Mark detail pages that people reach from a list and return to often, such as one API key under Checkout › API keys.
+
+### When Not to Use
+
+* Use [SidebarMenu](sidebar-menu.md) to move between top-level sections.
+* Use [Stepper](stepper.md) to show progress through a flow, such as Send payment.
+* Use [Tabs](tabs.md) to switch between views of the same page.
+* Use `Button.Link` from [Button](button.md) with `variant="tertiary"` for a single Back link in a two-level product.
+
+### Reserve Breadcrumbs for Deep Hierarchies
+
+Add a trail only at three or more levels deep. On shallower pages, a trail repeats the sidebar and the page title.
+
+**Do:** Show a trail on a page nested under a project and a section.
+
+```tsx
+/**
+ * Do example for "Reserve Breadcrumbs for Deep Hierarchies" on the Breadcrumbs page.
+ * Show a trail on a page nested under a project and a section.
+ * @module
+ */
+import { Breadcrumbs, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.page()}>
+      <Breadcrumbs>
+        <Breadcrumbs.Item href="#">Checkout</Breadcrumbs.Item>
+        <Breadcrumbs.Item href="#">API keys</Breadcrumbs.Item>
+        <Breadcrumbs.Item current>Production</Breadcrumbs.Item>
+      </Breadcrumbs>
+      <span {...styles.title()}>Production</span>
+    </div>
+  )
+}
+
+namespace styles {
+  export const page = style({ display: 'flex', flexDirection: 'column', rowGap: '8' })
+
+  export const title = style({ color: 'content.primary', typography: 'heading.h2' })
+}
+```
+
+**Don't:** Add a trail to a top-level page, where it repeats the sidebar.
+
+```tsx
+/**
+ * Don't example for "Reserve Breadcrumbs for Deep Hierarchies" on the Breadcrumbs page.
+ * Don't add a trail to a top-level page, where it repeats the sidebar.
+ * @module
+ */
+import { Breadcrumbs, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.page()}>
+      <Breadcrumbs>
+        <Breadcrumbs.Item href="#">Home</Breadcrumbs.Item>
+        <Breadcrumbs.Item current>Activity</Breadcrumbs.Item>
+      </Breadcrumbs>
+      <span {...styles.title()}>Activity</span>
+    </div>
+  )
+}
+
+namespace styles {
+  export const page = style({ display: 'flex', flexDirection: 'column', rowGap: '8' })
+
+  export const title = style({ color: 'content.primary', typography: 'heading.h2' })
+}
+```
+
+### Reflect the Hierarchy, Not History
+
+Build the trail from the product's structure. A transaction page shows the same trail from Activity, a search result, or a shared link. The browser's Back button covers history.
+
+**Do:** Show the pages that contain the current page.
+
+```tsx
+/**
+ * Do example for "Reflect the Hierarchy, Not History" on the Breadcrumbs page.
+ * Show the pages that contain the current page.
+ * @module
+ */
+import { Breadcrumbs, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.page()}>
+      <Breadcrumbs>
+        <Breadcrumbs.Item href="#">Checkout</Breadcrumbs.Item>
+        <Breadcrumbs.Item href="#">Activity</Breadcrumbs.Item>
+        <Breadcrumbs.Item current>0x8f3a…c21d</Breadcrumbs.Item>
+      </Breadcrumbs>
+      <span {...styles.title()}>0x8f3a…c21d</span>
+    </div>
+  )
+}
+
+namespace styles {
+  export const page = style({ display: 'flex', flexDirection: 'column', rowGap: '8' })
+
+  export const title = style({ color: 'content.primary', typography: 'heading.h2' })
+}
+```
+
+**Don't:** List the pages someone visited on the way.
+
+```tsx
+/**
+ * Don't example for "Reflect the Hierarchy, Not History" on the Breadcrumbs page.
+ * Don't list the pages someone visited on the way.
+ * @module
+ */
+import { Breadcrumbs, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.page()}>
+      <Breadcrumbs>
+        <Breadcrumbs.Item href="#">Search</Breadcrumbs.Item>
+        <Breadcrumbs.Item href="#">Wallets</Breadcrumbs.Item>
+        <Breadcrumbs.Item current>0x8f3a…c21d</Breadcrumbs.Item>
+      </Breadcrumbs>
+      <span {...styles.title()}>0x8f3a…c21d</span>
+    </div>
+  )
+}
+
+namespace styles {
+  export const page = style({ display: 'flex', flexDirection: 'column', rowGap: '8' })
+
+  export const title = style({ color: 'content.primary', typography: 'heading.h2' })
+}
+```
+
+### Place the Trail Above the Title
+
+Put breadcrumbs at the start of the content column, in the same position on every page.
+
+**Do:** Place the trail directly above the page title.
+
+```tsx
+/**
+ * Do example for "Reserve Breadcrumbs for Deep Hierarchies" on the Breadcrumbs page.
+ * Show a trail on a page nested under a project and a section.
+ * @module
+ */
+import { Breadcrumbs, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.page()}>
+      <Breadcrumbs>
+        <Breadcrumbs.Item href="#">Checkout</Breadcrumbs.Item>
+        <Breadcrumbs.Item href="#">API keys</Breadcrumbs.Item>
+        <Breadcrumbs.Item current>Production</Breadcrumbs.Item>
+      </Breadcrumbs>
+      <span {...styles.title()}>Production</span>
+    </div>
+  )
+}
+
+namespace styles {
+  export const page = style({ display: 'flex', flexDirection: 'column', rowGap: '8' })
+
+  export const title = style({ color: 'content.primary', typography: 'heading.h2' })
+}
+```
+
+**Don't:** Place the trail below the title.
+
+```tsx
+/**
+ * Don't example for "Place the Trail Above the Title" on the Breadcrumbs page.
+ * Don't place the trail below the title.
+ * @module
+ */
+import { Breadcrumbs, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.page()}>
+      <span {...styles.title()}>Production</span>
+      <Breadcrumbs>
+        <Breadcrumbs.Item href="#">Checkout</Breadcrumbs.Item>
+        <Breadcrumbs.Item href="#">API keys</Breadcrumbs.Item>
+        <Breadcrumbs.Item current>Production</Breadcrumbs.Item>
+      </Breadcrumbs>
+    </div>
+  )
+}
+
+namespace styles {
+  export const page = style({ display: 'flex', flexDirection: 'column', rowGap: '8' })
+
+  export const title = style({ color: 'content.primary', typography: 'heading.h2' })
+}
+```
+
+### Keep the Default Separator
+
+The default right chevron reads as one step down the hierarchy. Set `separator` only if the product already uses another convention, such as `/` for documentation paths, and use one separator across the product.
+
+**Do:** Keep the default chevron.
+
+```tsx
+/** Do example for "Keep the Default Separator" on the Breadcrumbs page: keep the default chevron. @module */
+import { Breadcrumbs, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.page()}>
+      <Breadcrumbs>
+        <Breadcrumbs.Item href="#">Checkout</Breadcrumbs.Item>
+        <Breadcrumbs.Item href="#">Webhooks</Breadcrumbs.Item>
+        <Breadcrumbs.Item current>Deliveries</Breadcrumbs.Item>
+      </Breadcrumbs>
+      <span {...styles.title()}>Deliveries</span>
+    </div>
+  )
+}
+
+namespace styles {
+  export const page = style({ display: 'flex', flexDirection: 'column', rowGap: '8' })
+
+  export const title = style({ color: 'content.primary', typography: 'heading.h2' })
+}
+```
+
+**Don't:** Swap in another separator, such as an arrow, without a product convention.
+
+```tsx
+/**
+ * Don't example for "Keep the Default Separator" on the Breadcrumbs page.
+ * Don't swap in another separator, such as an arrow, without a product convention.
+ * @module
+ */
+import { Breadcrumbs, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.page()}>
+      <Breadcrumbs separator="→">
+        <Breadcrumbs.Item href="#">Checkout</Breadcrumbs.Item>
+        <Breadcrumbs.Item href="#">Webhooks</Breadcrumbs.Item>
+        <Breadcrumbs.Item current>Deliveries</Breadcrumbs.Item>
+      </Breadcrumbs>
+      <span {...styles.title()}>Deliveries</span>
+    </div>
+  )
+}
+
+namespace styles {
+  export const page = style({ display: 'flex', flexDirection: 'column', rowGap: '8' })
+
+  export const title = style({ color: 'content.primary', typography: 'heading.h2' })
+}
+```
+
+## Content
+
+* **Labels:** Use each page's title, such as API keys.
+* **Addresses and hashes:** Shorten to the first and last characters, such as 0x71C7…976F. Show the full value on the page.
+* **Length:** The list wraps instead of truncating, so keep labels short.
+
+## Accessibility
+
+Renders a navigation landmark with an ordered list of links, following the [WAI-ARIA breadcrumb pattern](https://www.w3.org/WAI/ARIA/apg/patterns/breadcrumb/).
+
+### Semantics
+
+* **Root (nav):** A navigation landmark named "Breadcrumb".
+* **List (ol):** Screen readers announce the number of levels.
+* **Breadcrumbs.Item (li):** Wraps a link. The current item is plain text marked as the current page.
+* **Separators (aria-hidden):** Hidden. Screen readers announce only the pages.
+
+### Keyboard
+
+* **Move Between Links (Tab):** Moves focus to each link in order, skipping the current item.
+* **Follow a Link (Enter):** Follows the focused link.
+
+### Your Responsibilities
+
+* **Mark the Current Page (current):** Set it on the last item. It is announced as the current page and takes no focus.
+* **Keep the Landmark Distinct (SC 2.4.1):** Keep the "Breadcrumb" name, or pass a distinct `aria-label`.
+* **Use Real Links (render):** Pass your router's link so each item stays a real link with the same styles.
+* **Keep the Default Gaps (20px):** Links are under the 24px minimum, which WCAG 2.2 accepts if targets are spaced apart.
+
+## Related
+
+[SidebarMenu](sidebar-menu.md)
+
+Use for top-level navigation.
+
+[AppShell](app-shell.md)
+
+Use for the page frame that holds the trail.
+
+[Tabs](tabs.md)
+
+Use for switching views within a page.
+
+[Navigation](../patterns/navigation.md)
+
+Covers choosing between navigation components.

package/dist/docs/product/components/button-group.md

@@ -0,0 +1,286 @@
+# ButtonGroup
+
+Lays out the actions at the foot of a dialog or focused flow.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/ButtonGroup.tsx)
+
+Figma: [Button Group](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=1269-1089)
+
+## Overview
+
+A button group places [Buttons](button.md) side by side at equal widths, or stacks them at full width.
+
+## Examples
+
+### Basic
+
+```tsx
+import { Button, ButtonGroup, style } from '@tempoxyz/ds'
+
+export const fill = true
+export function Demo() {
+  return (
+    <ButtonGroup {...styles.group()}>
+      <Button size="large" variant="secondary">
+        Cancel
+      </Button>
+      <Button size="large">Confirm</Button>
+    </ButtonGroup>
+  )
+}
+
+namespace styles {
+  export const group = style({ maxWidth: '360', width: '100% !custom' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/ButtonGroup/Basic.tsx)
+
+### Orientation
+
+Set `orientation` to `horizontal` (default) or `vertical`. Both place the buttons 8px apart.
+
+```tsx
+import { Button, ButtonGroup, style } from '@tempoxyz/ds'
+
+export const fill = true
+export function Demo() {
+  return (
+    <ButtonGroup orientation="vertical" {...styles.group()}>
+      <Button size="large">Get started</Button>
+      <Button size="large" variant="tertiary">
+        Not now
+      </Button>
+    </ButtonGroup>
+  )
+}
+
+namespace styles {
+  export const group = style({ maxWidth: '360', width: '100% !custom' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/ButtonGroup/Orientation.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { Button, ButtonGroup } from '@tempoxyz/ds'
+
+<ButtonGroup>
+  <Button />
+</ButtonGroup>
+```
+
+## Guidelines
+
+### When to Use
+
+* Close a dialog with two actions of equal weight, such as Cancel and Confirm.
+* Stack a main action above a dismiss action in an intro or announcement, such as Get started and Not now.
+
+### When Not to Use
+
+* Use a [SplitButton](split-button.md) for a main action with related alternatives.
+* Use an [Inline](inline.md) row for actions at their natural width, such as a toolbar.
+* Use a [Menu](menu.md) for more than three actions.
+
+### Put the Primary Action Last
+
+Place the `primary` action on the right of a pair. Keep the source order the same as the visual order, so focus reaches the main action last.
+
+**Do:** Put the `secondary` action first and the `primary` action last.
+
+```tsx
+/**
+ * Do example for "Put the Primary Action Last" on the ButtonGroup page.
+ * Put the `secondary` action first and the `primary` action last.
+ * @module
+ */
+import { Button, ButtonGroup, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <ButtonGroup {...styles.group()}>
+      <Button size="large" variant="secondary">
+        Cancel
+      </Button>
+      <Button size="large">Confirm</Button>
+    </ButtonGroup>
+  )
+}
+
+namespace styles {
+  export const group = style({ maxWidth: '320', width: '100% !custom' })
+}
+```
+
+**Don't:** Put the `primary` action on the left of a pair.
+
+```tsx
+/**
+ * Don't example for "Put the Primary Action Last" on the ButtonGroup page.
+ * Don't put the `primary` action on the left of a pair.
+ * @module
+ */
+import { Button, ButtonGroup, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <ButtonGroup {...styles.group()}>
+      <Button size="large">Confirm</Button>
+      <Button size="large" variant="secondary">
+        Cancel
+      </Button>
+    </ButtonGroup>
+  )
+}
+
+namespace styles {
+  export const group = style({ maxWidth: '320', width: '100% !custom' })
+}
+```
+
+### Keep Every Button the Same Size
+
+Give every button in a dialog footer the `large` size. In a stack, the `tertiary` dismiss action keeps that size.
+
+**Do:** Give the dismiss action the same `large` size as the `primary` action.
+
+```tsx
+/**
+ * Do example for "Keep Every Button the Same Size" on the ButtonGroup page.
+ * Give the dismiss action the same `large` size as the `primary` action.
+ * @module
+ */
+import { Button, ButtonGroup, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <ButtonGroup orientation="vertical" {...styles.group()}>
+      <Button size="large">Get started</Button>
+      <Button size="large" variant="tertiary">
+        Not now
+      </Button>
+    </ButtonGroup>
+  )
+}
+
+namespace styles {
+  export const group = style({ maxWidth: '320', width: '100% !custom' })
+}
+```
+
+**Don't:** Shrink the dismiss action below the `primary` action.
+
+```tsx
+/**
+ * Don't example for "Keep Every Button the Same Size" on the ButtonGroup page.
+ * Don't shrink the dismiss action below the `primary` action.
+ * @module
+ */
+import { Button, ButtonGroup, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <ButtonGroup orientation="vertical" {...styles.group()}>
+      <Button size="large">Get started</Button>
+      <Button size="small" variant="tertiary">
+        Not now
+      </Button>
+    </ButtonGroup>
+  )
+}
+
+namespace styles {
+  export const group = style({ maxWidth: '320', width: '100% !custom' })
+}
+```
+
+## Content
+
+### Name the Destructive Action
+
+If the action destroys data or removes access, name what it does on the `primary` button, such as Revoke all.
+
+**Do:** Name both outcomes, such as Keep keys and Revoke all.
+
+```tsx
+/**
+ * Do example for "Name the Destructive Action" on the ButtonGroup page.
+ * Name both outcomes, such as Keep keys and Revoke all.
+ * @module
+ */
+import { Button, ButtonGroup, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <ButtonGroup {...styles.group()}>
+      <Button size="large" variant="secondary">
+        Keep keys
+      </Button>
+      <Button size="large">Revoke all</Button>
+    </ButtonGroup>
+  )
+}
+
+namespace styles {
+  export const group = style({ maxWidth: '320', width: '100% !custom' })
+}
+```
+
+**Don't:** Label a destructive action OK.
+
+```tsx
+/**
+ * Don't example for "Name the Destructive Action" on the ButtonGroup page.
+ * Don't label a destructive action OK.
+ * @module
+ */
+import { Button, ButtonGroup, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <ButtonGroup {...styles.group()}>
+      <Button size="large" variant="secondary">
+        Cancel
+      </Button>
+      <Button size="large">OK</Button>
+    </ButtonGroup>
+  )
+}
+
+namespace styles {
+  export const group = style({ maxWidth: '320', width: '100% !custom' })
+}
+```
+
+## Accessibility
+
+`ButtonGroup` renders a `div` with `role="group"` around native buttons. See [Accessibility](../foundations/accessibility.md) for the baseline.
+
+* **Group (group):** Groups the actions. Name it with `aria-label` when the dialog title does not.
+* **Focus Order (Tab):** Follows the source order, which matches the visual order in both orientations.
+* **Target Size (48px):** Large buttons stretch to the full width, which leaves a wide target on touch screens.
+
+## Related
+
+[Button](button.md)
+
+Use for each action in the group.
+
+[Dialog](dialog.md)
+
+Use for the focused task that the group closes.
+
+[AlertDialog](alert-dialog.md)
+
+Use for confirming a destructive action.