@tempoxyz/ds 0.3.9 → 0.3.11

package/dist/docs/components/app-shell.md

@@ -0,0 +1,559 @@
+# AppShell
+
+Places a sticky sidebar beside the main content column.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/AppShell.tsx)
+
+Figma: [Layout/App Shell](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=5227-5593) (`AppShell.Root`), [Layout/Page Header](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=5227-5633) (`AppShell.Header`), [Navigation/Tab Bar](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=5265-2292) (`AppShell.Root`)
+
+## Overview
+
+The outer frame of an application. Below 1024px, the sidebar moves into a drawer, which a menu button in a bottom bar opens. With `collapse`, the sidebar collapses to its icons until 768px instead. The bottom bar also repeats the items you choose.
+
+## Examples
+
+### Basic
+
+```tsx
+/** Composes the Tempo Wallet shell: the account row, the wallet pages, the theme item and a page header. @module */
+import { AppShell, Avatar, Hex, Kbd, Menu, SidebarMenu, StatusChip, style, Surface } from '@tempoxyz/ds'
+import { Clock, DarkMode, Home, Link, LogOut, Plus, Wallet } from '@tempoxyz/ds/icons'
+
+export const fill = true
+const address = '0x7a3f2c19b0e4d85a6f1c3e9b2d7a40c58e6f91c2'
+
+const balances = ['pathUSD', 'USDC.e', 'AlphaUSD']
+
+export function Demo() {
+  return (
+    <div {...styles.frame()}>
+      <AppShell.Root
+        align="start"
+        collapse
+        style={{ height: '100%', minHeight: 0, overflowY: 'auto' }}
+      >
+        <AppShell.Sidebar aria-label="Wallet" style={{ height: '100%' }}>
+          <AppShell.SidebarHeader>
+            <Menu.Root>
+              <Menu.Trigger
+                render={<SidebarMenu.AccountRow description="Tempo Wallet" label="Piril Akay" />}
+              >
+                <Avatar size="32">
+                  <Avatar.Fallback>PA</Avatar.Fallback>
+                </Avatar>
+              </Menu.Trigger>
+              <Menu.Popup>
+                <Menu.Item>
+                  <Plus />
+                  Add account
+                </Menu.Item>
+                <Menu.Separator />
+                <Menu.Item intent="negative">
+                  <LogOut />
+                  Sign out
+                </Menu.Item>
+              </Menu.Popup>
+            </Menu.Root>
+          </AppShell.SidebarHeader>
+          <AppShell.SidebarBody>
+            <SidebarMenu.Root>
+              <SidebarMenu.Group aria-label="Wallet">
+                <SidebarMenu.Item active href="#" tabBar="tab">
+                  <Home />
+                  Home
+                </SidebarMenu.Item>
+                <SidebarMenu.Item href="#" tabBar="tab">
+                  <Clock />
+                  Activity
+                </SidebarMenu.Item>
+                <SidebarMenu.Item href="#" tabBar="tab">
+                  <Wallet />
+                  Assets
+                </SidebarMenu.Item>
+                <SidebarMenu.Item href="#">
+                  <Link />
+                  Connections
+                </SidebarMenu.Item>
+              </SidebarMenu.Group>
+            </SidebarMenu.Root>
+          </AppShell.SidebarBody>
+          <AppShell.SidebarFooter>
+            <SidebarMenu.Root aria-label="Preferences">
+              <SidebarMenu.Item render={<button type="button" />}>
+                <DarkMode />
+                <span {...styles.grow()}>Dark mode</span>
+                <Kbd alt size="small">
+                  M
+                </Kbd>
+              </SidebarMenu.Item>
+            </SidebarMenu.Root>
+          </AppShell.SidebarFooter>
+        </AppShell.Sidebar>
+        <AppShell.Main>
+          <AppShell.Header>
+            <AppShell.Title>Home</AppShell.Title>
+            <div {...styles.actions()}>
+              <StatusChip intent="positive" network>
+                Mainnet
+              </StatusChip>
+              <Hex.Root size="small" value={address} variant="filled" {...styles.address()}>
+                <Hex.Text />
+                <Hex.Copy aria-label="Copy wallet address" />
+              </Hex.Root>
+            </div>
+            <AppShell.Trigger />
+          </AppShell.Header>
+          <div {...styles.list()}>
+            {balances.map((balance) => (
+              <Surface key={balance}>
+                <p {...styles.name()}>{balance}</p>
+                <p {...styles.caption()}>Available to send</p>
+              </Surface>
+            ))}
+          </div>
+        </AppShell.Main>
+      </AppShell.Root>
+    </div>
+  )
+}
+
+namespace styles {
+  // The bottom bar takes over below 768px, so the header keeps only its title.
+  export const actions = style({
+    alignItems: 'center',
+    columnGap: '8',
+    display: 'flex',
+    '@media (max-width: 767px)': { display: 'none' },
+  })
+
+  export const address = style({ maxWidth: '10rem !custom' })
+
+  export const caption = style({ color: 'content.secondary', margin: '0', typography: 'body.b3' })
+
+  // The transform makes the frame the containing block for the mobile drawer.
+  export const frame = style({
+    borderRadius: 'sm',
+    height: '32rem !custom',
+    overflow: 'hidden',
+    transform: 'translateZ(0) !custom',
+    selectors: {
+      // The maximized gallery preview shows the shell at full window height.
+      ':root[data-maximized] &': { borderRadius: '0px !custom', height: '100vh !custom' },
+    },
+  })
+
+  export const grow = style({ flex: '1 !custom', minWidth: '0 !custom' })
+
+  export const list = style({ display: 'flex', flexDirection: 'column', rowGap: '12' })
+
+  export const name = style({ margin: '0', typography: 'body.b2' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/AppShell/Basic.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { AppShell } from '@tempoxyz/ds'
+
+<AppShell.Root>
+  <AppShell.Sidebar>
+    <AppShell.SidebarHeader />
+    <AppShell.SidebarBody />
+    <AppShell.SidebarFooter />
+  </AppShell.Sidebar>
+  <AppShell.Main>
+    <AppShell.Header>
+      <AppShell.Title />
+    </AppShell.Header>
+  </AppShell.Main>
+  <AppShell.Trigger />
+</AppShell.Root>
+```
+
+## Guidelines
+
+### When to Use
+
+* Frame a product with persistent navigation, such as Tempo Console or the web wallet. Render it once, in the root layout.
+* Pair a [SidebarMenu](/docs/components/sidebar-menu) with a content column of tables, cards, or settings.
+
+### When Not to Use
+
+* Use [Container](/docs/components/container) for pages without persistent navigation, such as sign-in, onboarding, or a public receipt.
+* Use [Dialog](/docs/components/dialog), or a full-screen flow in a [Container](/docs/components/container), for focused tasks such as Send payment.
+* Use [Drawer](/docs/components/drawer) for a details or filter panel that opens on demand. The shell's drawer holds only primary navigation.
+* Use [Frame](/docs/components/frame) for a header, body, and footer inside a card or popup.
+
+### Plan for Each Layout
+
+The shell switches layouts at 768px and 1024px (the `'768'` and `'1024'` breakpoints). Design and test each.
+
+* **Below 768px (Bottom bar):** The sidebar becomes a drawer from the right edge, and a bottom bar holds the chosen items and the menu button.
+* **768px to 1023px (collapse):** The drawer and bottom bar by default. With `collapse`, a 64px column of icons that keep their labels as names.
+* **1024px and Up (28px padding):** The sidebar sticks beside the content with its own scroll, and the bottom bar hides.
+
+The drawer is `min(18rem, 85vw)` wide. Server rendering emits the inline sidebar, and CSS hides it below 1024px, or collapses it until 768px with `collapse`.
+
+### Always Render the Trigger
+
+Render `AppShell.Trigger` once inside `AppShell.Root`. It adds the menu button to the end of the bottom bar, so the header keeps its full width for the title and actions.
+
+**Do:** Render the trigger once in the shell.
+
+```tsx
+/**
+ * Do example for "Always Render the Trigger" on the AppShell page.
+ * Render the trigger once in the shell.
+ * @module
+ */
+import { Button, style, Surface } from '@tempoxyz/ds'
+import { Menu } from '@tempoxyz/ds/icons'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Surface size="small" {...styles.frame()}>
+      <span {...styles.title()}>Balances</span>
+      <div {...styles.bar()}>
+        <Button aria-label="Open menu" shape="icon" size="small">
+          <Menu />
+        </Button>
+      </div>
+    </Surface>
+  )
+}
+
+namespace styles {
+  export const bar = style({ display: 'flex', justifyContent: 'flex-end' })
+
+  export const frame = style({
+    display: 'flex',
+    flexDirection: 'column',
+    gap: '24',
+    width: '18rem !custom',
+  })
+
+  export const title = style({ color: 'content.primary', typography: 'heading.h3' })
+}
+```
+
+**Don't:** Leave it out. Below 1024px, or 768px with `collapse`, it is the only way to reach every
+destination.
+
+```tsx
+/**
+ * Don't example for "Always Render the Trigger" on the AppShell page.
+ * Don't leave it out. Below 1024px, it is the only way to reach navigation.
+ * @module
+ */
+import { style, Surface } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Surface size="small" {...styles.frame()}>
+      <span {...styles.title()}>Balances</span>
+      <div {...styles.bar()} />
+    </Surface>
+  )
+}
+
+namespace styles {
+  // Matches the height of the bottom bar in the Do example, so only the missing button differs.
+  export const bar = style({ minHeight: '32' })
+
+  export const frame = style({
+    display: 'flex',
+    flexDirection: 'column',
+    gap: '24',
+    width: '18rem !custom',
+  })
+
+  export const title = style({ color: 'content.primary', typography: 'heading.h3' })
+}
+```
+
+### Choose an Alignment
+
+* **Centered (center):** The default. Centers the sidebar beside a content column up to 1024px wide.
+* **Start (start):** Pins the sidebar left, and the content fills the row. Use it for wide data views.
+
+### Structure the Sidebar
+
+* **AppShell.SidebarHeader:** Holds the product or project switcher at the top of the sidebar.
+* **AppShell.SidebarBody:** Holds the sidebar menu. It scrolls on its own and fades the edge with more content.
+* **AppShell.SidebarFooter:** Holds the account row and other controls, pinned to the bottom edge.
+
+Keep the header and footer short so the menu keeps most of the height. Set `--sidebar-width` to change the width of the wide sidebar.
+
+### Choose the Bottom Bar Items
+
+Wherever the drawer replaces the sidebar, a bottom bar repeats the [SidebarMenu](/docs/components/sidebar-menu) items that set `tabBar`, in sidebar order, and ends with the menu button. Keep the rest in the drawer.
+
+* **Tab (tabBar="tab"):** Shows the icon in the tab bar pill. Choose up to three top destinations.
+* **Action (tabBar="action"):** Shows the icon in a floating button beside the pill. Choose one main action.
+
+```tsx
+<SidebarMenu.Item active href="/" tabBar="tab">
+  <Home />
+  Home
+</SidebarMenu.Item>
+```
+
+### Use One Title per Page
+
+`AppShell.Title` renders the page's `h1` in the header bar across the top of the content column. Keep one primary action in the header.
+
+**Do:** Put the title first, then page actions, such as a `small` [Button](/docs/components/button).
+
+```tsx
+/**
+ * Do example for "Use One Title per Page" on the AppShell page.
+ * Put the title first, then page actions, such as a `small` Button.
+ * @module
+ */
+import { Button, style, Surface } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Surface size="small" {...styles.frame()}>
+      <div {...styles.header()}>
+        <span {...styles.title()}>API keys</span>
+        <Button size="small">New key</Button>
+      </div>
+    </Surface>
+  )
+}
+
+namespace styles {
+  export const frame = style({ width: '18rem !custom' })
+
+  export const header = style({ alignItems: 'center', display: 'flex', gap: '12' })
+
+  export const title = style({
+    color: 'content.primary',
+    flex: '1 !custom',
+    typography: 'heading.h3',
+  })
+}
+```
+
+**Don't:** Place actions before the title.
+
+```tsx
+/** Don't example for "Use One Title per Page" on the AppShell page. Don't place actions before the title. @module */
+import { Button, style, Surface } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Surface size="small" {...styles.frame()}>
+      <div {...styles.header()}>
+        <Button size="small">New key</Button>
+        <span {...styles.title()}>API keys</span>
+      </div>
+    </Surface>
+  )
+}
+
+namespace styles {
+  export const frame = style({ width: '18rem !custom' })
+
+  export const header = style({ alignItems: 'center', display: 'flex', gap: '12' })
+
+  export const title = style({
+    color: 'content.primary',
+    flex: '1 !custom',
+    typography: 'heading.h3',
+  })
+}
+```
+
+### Close the Drawer After Navigating
+
+With a client-side router, the drawer stays open when the route changes. Control `AppShell.Root` with `open` and `onOpenChange`, and set `open` to `false` when the location changes.
+
+**Do:** Close the drawer, so the new page shows.
+
+```tsx
+/**
+ * Do example for "Close the Drawer After Navigating" on the AppShell page.
+ * Close the drawer, so the new page shows.
+ * @module
+ */
+import { Button, style } from '@tempoxyz/ds'
+import { Menu } from '@tempoxyz/ds/icons'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.screen()}>
+      <div {...styles.header()}>
+        <span {...styles.title()}>API keys</span>
+        <Button aria-label="Open menu" shape="icon" size="small" variant="secondary">
+          <Menu />
+        </Button>
+      </div>
+      <span {...styles.meta()}>2 active keys</span>
+    </div>
+  )
+}
+
+namespace styles {
+  export const header = style({
+    alignItems: 'center',
+    display: 'flex',
+    gap: '12',
+    justifyContent: 'space-between',
+  })
+
+  export const meta = style({ color: 'content.secondary', typography: 'body.b2' })
+
+  export const screen = style({
+    display: 'flex',
+    flexDirection: 'column',
+    height: '9rem !custom',
+    position: 'relative',
+    rowGap: '8',
+    width: '18rem !custom',
+  })
+
+  export const title = style({ color: 'content.primary', typography: 'heading.h3' })
+}
+```
+
+**Don't:** Leave the drawer over the new page.
+
+```tsx
+/**
+ * Don't example for "Close the Drawer After Navigating" on the AppShell page.
+ * Don't leave the drawer over the new page.
+ * @module
+ */
+import { Button, SidebarMenu, style, Surface } from '@tempoxyz/ds'
+import { Home, Key, Menu } from '@tempoxyz/ds/icons'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.screen()}>
+      <div {...styles.header()}>
+        <span {...styles.title()}>API keys</span>
+        <Button aria-label="Open menu" shape="icon" size="small" variant="secondary">
+          <Menu />
+        </Button>
+      </div>
+      <span {...styles.meta()}>2 active keys</span>
+      <Surface size="small" {...styles.drawer()}>
+        <SidebarMenu.Root aria-label="Primary" size="small">
+          <SidebarMenu.Item href="#">
+            <Home />
+            Home
+          </SidebarMenu.Item>
+          <SidebarMenu.Item active href="#">
+            <Key />
+            API keys
+          </SidebarMenu.Item>
+        </SidebarMenu.Root>
+      </Surface>
+    </div>
+  )
+}
+
+namespace styles {
+  export const drawer = style({
+    insetBlock: '0 !custom',
+    insetInlineEnd: '0 !custom',
+    position: 'absolute',
+    width: '11rem !custom',
+  })
+
+  export const header = style({
+    alignItems: 'center',
+    display: 'flex',
+    gap: '12',
+    justifyContent: 'space-between',
+  })
+
+  export const meta = style({ color: 'content.secondary', typography: 'body.b2' })
+
+  export const screen = style({
+    display: 'flex',
+    flexDirection: 'column',
+    height: '9rem !custom',
+    position: 'relative',
+    rowGap: '8',
+    width: '18rem !custom',
+  })
+
+  export const title = style({ color: 'content.primary', typography: 'heading.h3' })
+}
+```
+
+## Content
+
+* Match `AppShell.Title` to the label of the active [SidebarMenu](/docs/components/sidebar-menu) item, such as API keys.
+* Keep titles short enough to share the header row with its actions at 360px.
+
+## Accessibility
+
+Provides the page landmarks and the `h1`. Below 1024px, the sidebar drawer follows the [WAI-ARIA Dialog (Modal) pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/).
+
+### Semantics
+
+* **AppShell.Main (main):** The page's main landmark.
+* **AppShell.Header (header):** Holds the menu trigger and the page title.
+* **AppShell.Title (h1):** The page's top-level heading.
+* **Wide AppShell.Sidebar (complementary):** From 1024px, a landmark named by `aria-label`.
+* **Narrow AppShell.Sidebar (dialog):** Below 1024px, a dialog with the same name.
+* **AppShell.Trigger (button):** Named "Open menu" or "Close menu" by state.
+
+### Keyboard
+
+* **Move Through the Shell (Tab):** Moves to the trigger, or cycles the open drawer.
+* **Open the Drawer (Enter or Space):** Opens the drawer from the trigger.
+* **Close the Drawer (Escape):** Closes the drawer.
+
+### Focus
+
+* **Opening (Tab or Shift+Tab):** The drawer is modal. Opening it moves focus inside and traps it.
+* **While Open (aria-hidden):** Hides the rest of the page, including the trigger, from assistive technology.
+* **Closing:** Escape, the backdrop, or a swipe right closes the drawer and returns focus to the trigger.
+
+### Motion and Size
+
+* **Reduced Motion (prefers-reduced-motion):** The drawer fades, and the trigger switches instantly.
+* **Minimum Width (360px):** The shell never shrinks below this width.
+
+### Your Responsibilities
+
+* **Name the Sidebar (aria-label):** Name the sidebar, such as "Primary". The name labels the landmark and the drawer.
+* **Use One Title (h1):** Use one page title. Start the headings of the content at `h2`.
+* **Add a Skip Link (SC 2.4.1):** If the sidebar holds many links, add a [skip link](https://www.w3.org/WAI/WCAG22/Understanding/bypass-blocks.html). The shell adds none.
+
+## Related
+
+[SidebarMenu](/docs/components/sidebar-menu)
+
+Use for the navigation inside the sidebar.
+
+[Container](/docs/components/container)
+
+Use for pages without a sidebar.
+
+[Drawer](/docs/components/drawer)
+
+Use for panels that open on demand.
+
+[Responsive Layout](/docs/patterns/responsive-layout)
+
+Covers adapting pages across breakpoints.
+
+[Navigation](/docs/patterns/navigation)
+
+Covers choosing between navigation components.