@tempoxyz/ds 0.3.9 → 0.3.11

package/dist/docs/patterns/navigation.md

@@ -0,0 +1,397 @@
+# Navigation
+
+Move between product areas, page views, and nested pages in one shared frame.
+
+## Overview
+
+Navigation shows the current location, the possible destinations, and the way back. Tempo products share one navigation model with four levels. Each level has its own component, so a control always leads to another area, another view, or one level up.
+
+* **Product Area (SidebarMenu):** [AppShell](/docs/components/app-shell) with [SidebarMenu](/docs/components/sidebar-menu) lists the main areas and marks the current one.
+* **Page (AppShell.Title):** The page title names the current page and serves as its main heading.
+* **Depth (Breadcrumbs):** [Breadcrumbs](/docs/components/breadcrumbs) show the position of a nested page and lead back up.
+* **View (Tabs):** [Tabs](/docs/components/tabs) switch between views of the same content without leaving the page.
+
+[Pagination](/docs/components/pagination) moves through a long list, and [Stepper](/docs/components/stepper) marks the position in a fixed sequence of steps, such as account setup.
+
+## Structure
+
+A page renders the sidebar, then breadcrumbs on nested pages, one page title in `AppShell.Header` with the page actions, tabs if the page has several views of one object, and the content.
+
+```tsx
+import { AppShell, Breadcrumbs, Field, ListGroup, SidebarMenu, style, Surface, Switch, Tabs } from '@tempoxyz/ds'
+import { Grid, Key, Link, Settings, Users } from '@tempoxyz/ds/icons'
+
+export const fill = true
+const pages = [
+  ['Home', Grid],
+  ['API Keys', Key],
+  ['Webhooks', Link],
+  ['Team', Users],
+  ['Settings', Settings],
+] as const
+
+export function Demo() {
+  return (
+    <div {...styles.frame()}>
+      <AppShell.Root style={{ height: '100%', minHeight: 0, overflowY: 'auto' }}>
+        <AppShell.Sidebar aria-label="Console" style={{ height: '100%' }}>
+          <AppShell.SidebarHeader>
+            <span {...styles.product()}>Tempo Console</span>
+          </AppShell.SidebarHeader>
+          <AppShell.SidebarBody>
+            <SidebarMenu.Root>
+              {pages.map(([label, Icon]) => (
+                <SidebarMenu.Item active={label === 'API Keys'} href="#" key={label}>
+                  <Icon />
+                  {label}
+                </SidebarMenu.Item>
+              ))}
+            </SidebarMenu.Root>
+          </AppShell.SidebarBody>
+        </AppShell.Sidebar>
+        <AppShell.Main>
+          <Breadcrumbs>
+            <Breadcrumbs.Item href="#">API Keys</Breadcrumbs.Item>
+            <Breadcrumbs.Item current>Production</Breadcrumbs.Item>
+          </Breadcrumbs>
+          <AppShell.Header>
+            <AppShell.Title>Production</AppShell.Title>
+            <AppShell.Trigger />
+          </AppShell.Header>
+          <Tabs.Root defaultValue="overview">
+            <Tabs.List aria-label="Key details">
+              <Tabs.Tab value="overview">Overview</Tabs.Tab>
+              <Tabs.Tab value="usage">Usage</Tabs.Tab>
+              <Tabs.Tab value="settings">Settings</Tabs.Tab>
+              <Tabs.Indicator />
+            </Tabs.List>
+            <Tabs.Panel value="overview" {...styles.panel()}>
+              <Surface size="medium">
+                <ListGroup.Root>
+                  <ListGroup.Row>
+                    <ListGroup.Label>Created</ListGroup.Label>
+                    March 3, 2026
+                  </ListGroup.Row>
+                  <ListGroup.Row>
+                    <ListGroup.Label>Last used</ListGroup.Label>2 minutes ago
+                  </ListGroup.Row>
+                  <ListGroup.Row>
+                    <ListGroup.Label>Network</ListGroup.Label>
+                    Mainnet
+                  </ListGroup.Row>
+                </ListGroup.Root>
+              </Surface>
+            </Tabs.Panel>
+            <Tabs.Panel value="usage" {...styles.panel()}>
+              <Surface size="medium">
+                <ListGroup.Root>
+                  <ListGroup.Row>
+                    <ListGroup.Label>Requests, last 24 hours</ListGroup.Label>
+                    12,480
+                  </ListGroup.Row>
+                  <ListGroup.Row>
+                    <ListGroup.Label>Errors</ListGroup.Label>3
+                  </ListGroup.Row>
+                </ListGroup.Root>
+              </Surface>
+            </Tabs.Panel>
+            <Tabs.Panel value="settings" {...styles.panel()}>
+              <Surface size="medium">
+                <Field.Root>
+                  <Field.Label>Allow testnet requests</Field.Label>
+                  <Switch />
+                  <Field.Description>
+                    Use this key against testnet as well as mainnet.
+                  </Field.Description>
+                </Field.Root>
+              </Surface>
+            </Tabs.Panel>
+          </Tabs.Root>
+        </AppShell.Main>
+      </AppShell.Root>
+    </div>
+  )
+}
+
+namespace styles {
+  // The transform makes the frame the containing block for the drawer below 1024px.
+  export const frame = style({
+    borderRadius: 'sm',
+    height: '32rem !custom',
+    overflow: 'hidden',
+    transform: 'translateZ(0) !custom',
+    selectors: {
+      ':root[data-maximized] &': { borderRadius: '0px !custom', height: '100vh !custom' },
+    },
+  })
+
+  export const panel = style({ marginBlockStart: '16' })
+
+  export const product = style({ paddingInline: '12', typography: 'body.b2Strong' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Patterns/ConsoleNavigation.tsx)
+
+This reference layout uses [AppShell](/docs/components/app-shell), [SidebarMenu](/docs/components/sidebar-menu), [Breadcrumbs](/docs/components/breadcrumbs), and [Tabs](/docs/components/tabs). On a wide display, open the preview full screen for the sticky sidebar.
+
+## Product Navigation
+
+Put every product area in the [SidebarMenu](/docs/components/sidebar-menu) inside `AppShell.Sidebar`, in the same order on every page.
+
+* **One Active Item (active):** Mark only the area of the current page. It sets `aria-current="page"`.
+* **Consistent Icons:** Items do not wrap. Give each one a short label and an icon, never a mix with and without.
+* **Grouped Sections (SidebarMenu.Group):** Past about seven items, group them under specific labels, such as Project and Organization.
+
+**Do:** Mark the current area `active`, with short labels and icons.
+
+```tsx
+/**
+ * Do example for "Navigation" on the Navigation page.
+ * Mark the current area `active`, with short labels and icons.
+ * @module
+ */
+import { SidebarMenu, style } from '@tempoxyz/ds'
+import { Grid, Key, Link, Users } from '@tempoxyz/ds/icons'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <SidebarMenu.Root aria-label="Console" {...styles.column()}>
+      <SidebarMenu.Item href="#">
+        <Grid />
+        Home
+      </SidebarMenu.Item>
+      <SidebarMenu.Item active href="#">
+        <Key />
+        API Keys
+      </SidebarMenu.Item>
+      <SidebarMenu.Item href="#">
+        <Link />
+        Webhooks
+      </SidebarMenu.Item>
+      <SidebarMenu.Item href="#">
+        <Users />
+        Team
+      </SidebarMenu.Item>
+    </SidebarMenu.Root>
+  )
+}
+
+namespace styles {
+  export const column = style({ width: '15rem !custom' })
+}
+```
+
+**Don't:** Leave the current area unmarked.
+
+```tsx
+/** Don't example for "Navigation" on the Navigation page. Don't leave the current area unmarked. @module */
+import { SidebarMenu, style } from '@tempoxyz/ds'
+import { Grid, Key, Link, Users } from '@tempoxyz/ds/icons'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <SidebarMenu.Root aria-label="Console" {...styles.column()}>
+      <SidebarMenu.Item href="#">
+        <Grid />
+        Home
+      </SidebarMenu.Item>
+      <SidebarMenu.Item href="#">
+        <Key />
+        API Keys
+      </SidebarMenu.Item>
+      <SidebarMenu.Item href="#">
+        <Link />
+        Webhooks
+      </SidebarMenu.Item>
+      <SidebarMenu.Item href="#">
+        <Users />
+        Team
+      </SidebarMenu.Item>
+    </SidebarMenu.Root>
+  )
+}
+
+namespace styles {
+  export const column = style({ width: '15rem !custom' })
+}
+```
+
+### Move the Sidebar Into a Drawer Below 1024px
+
+Below 1024px, `AppShell.Sidebar` renders as a modal drawer from the right edge, with the same items in the same order. `AppShell.Trigger` toggles it from a menu button at the end of the bottom bar, which hides from 1024px.
+
+* **Main Action in the Header (AppShell.Header):** Keep the main action in the header, not the drawer.
+* **Server Rendering (Hydration):** The server emits the wide layout. Narrow screens switch to the drawer after hydration.
+
+## Tabs
+
+Use [Tabs](/docs/components/tabs) when a page shows several views of one object, such as the Overview, Usage, and Settings of an API key.
+
+* **Another page:** Use [SidebarMenu](/docs/components/sidebar-menu) or links.
+* **A mode of the same content:** Use [ChoiceGroup](/docs/components/choice-group), such as for the time range of a chart.
+* **Tabs inside tabs:** Never nest them. Split the view, or move the inner level to its own page.
+
+If tabs overflow one line, the list scrolls horizontally. Set `expand` on `Tabs.List` to stretch tabs across a narrow column.
+
+**Do:** Use one or two words per tab, in parallel form.
+
+```tsx
+/**
+ * Do example for "Move the Sidebar Into a Drawer Below 1024px" on the Navigation page.
+ * Use one or two words per tab, in parallel form.
+ * @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="Key details">
+        <Tabs.Tab value="overview">Overview</Tabs.Tab>
+        <Tabs.Tab value="usage">Usage</Tabs.Tab>
+        <Tabs.Tab value="settings">Settings</Tabs.Tab>
+        <Tabs.Indicator />
+      </Tabs.List>
+    </Tabs.Root>
+  )
+}
+```
+
+**Don't:** Write long or mismatched tab labels.
+
+```tsx
+/**
+ * Don't example for "Move the Sidebar Into a Drawer Below 1024px" on the Navigation page.
+ * Don't write long or mismatched tab 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="Key details">
+        <Tabs.Tab value="overview">About this key</Tabs.Tab>
+        <Tabs.Tab value="usage">Requests in the last 30 days</Tabs.Tab>
+        <Tabs.Tab value="settings">Configure</Tabs.Tab>
+        <Tabs.Indicator />
+      </Tabs.List>
+    </Tabs.Root>
+  )
+}
+```
+
+## Breadcrumbs
+
+Use [Breadcrumbs](/docs/components/breadcrumbs) on pages below a product area, such as a key under API Keys or an invoice inside Payments. Start with the product area, follow the hierarchy rather than the visit history, and mark the last item `current`.
+
+**Do:** Show the path from the product area down to the current page.
+
+```tsx
+/**
+ * Do example for "Move the Sidebar Into a Drawer Below 1024px" on the Navigation page.
+ * Show the path from the product area down to the current page.
+ * @module
+ */
+import { Breadcrumbs } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Breadcrumbs>
+      <Breadcrumbs.Item href="#">Settings</Breadcrumbs.Item>
+      <Breadcrumbs.Item href="#">Webhooks</Breadcrumbs.Item>
+      <Breadcrumbs.Item current>Order events</Breadcrumbs.Item>
+    </Breadcrumbs>
+  )
+}
+```
+
+**Don't:** Show breadcrumbs on a top-level page, where they hold only the current page.
+
+```tsx
+/**
+ * Don't example for "Move the Sidebar Into a Drawer Below 1024px" on the Navigation page.
+ * Don't show breadcrumbs on a top-level page, where they hold only the current page.
+ * @module
+ */
+import { Breadcrumbs } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Breadcrumbs>
+      <Breadcrumbs.Item current>API Keys</Breadcrumbs.Item>
+    </Breadcrumbs>
+  )
+}
+```
+
+If the full path would wrap on a narrow screen, show only the parent page as a back link, such as a secondary `Button.Link` from [Button](/docs/components/button) with an arrow icon and the parent's name.
+
+## Pagination
+
+Use [Pagination](/docs/components/pagination) for long lists that load page by page and need a stable position, such as transaction history. [Tables and Lists](/docs/patterns/tables-and-lists#paginate-or-load-more) covers when to page and when to load more.
+
+## Best Practices
+
+* **Location in the URL:** Reflect the selected tab and page in the URL, so links and the back button work.
+* **Links for Navigation (Button.Link):** Use a link to change pages. Put commands, such as Log out, in a [Menu](/docs/components/menu) in the sidebar footer.
+
+## States
+
+* **Loading and Error:** Navigation renders at once and works. Only the main column shows placeholders and errors.
+* **Empty:** A product area with no content still appears in the sidebar. Its page shows an [empty state](/docs/patterns/empty-states).
+* **Disabled:** Leave out unavailable areas. Disable a tab only if its view does not apply yet, and state the reason.
+* **Success:** After a flow such as key creation, open the page of the new item with its area marked active.
+
+## Content
+
+Name destinations with nouns, such as Activity, not verbs, such as View activity. Use the same name in the sidebar, the page title, and the breadcrumb. [Writing Style](/docs/foundations/content/writing-style) covers capitalization.
+
+## Accessibility
+
+* **Landmarks (aria-label):** Sidebar, breadcrumbs, and pagination are named landmarks. Rename one if two share a kind.
+* **Sidebar Drawer (Escape):** The drawer takes focus, also closes on the backdrop or a swipe, and returns focus to the menu button.
+* **One Page Title (h1):** The page title is the page's heading. Render exactly one title per page.
+* **Named Tab Lists (aria-label):** Give every tab list a name that states its content, such as Key details.
+* **Skip Links (AppShell.Main):** If the sidebar holds many links, add a skip link to the main column.
+
+## Related
+
+[AppShell](/docs/components/app-shell)
+
+Use for the application frame.
+
+[SidebarMenu](/docs/components/sidebar-menu)
+
+Use for links to product areas.
+
+[Tabs](/docs/components/tabs)
+
+Use for views of a page.
+
+[Breadcrumbs](/docs/components/breadcrumbs)
+
+Use for nested pages.
+
+[Pagination](/docs/components/pagination)
+
+Use for long lists.
+
+[Stepper](/docs/components/stepper)
+
+Use for fixed sequences of steps.
+
+[Responsive Layout](/docs/patterns/responsive-layout)
+
+Covers breakpoints.
+
+[Tempo Console](/docs/products/tempo-console)
+
+Covers the console's pages.