@tempoxyz/ds 0.3.10 → 0.3.13

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

@@ -0,0 +1,434 @@
+# Frame
+
+Lays out a header, body, and footer in a column.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Frame.tsx)
+
+## Overview
+
+A frame lays out a header, body, and footer in a column with no fill. Wrap it in a [Surface](surface.md) for a card, or put it in a [Dialog](dialog.md) or [Drawer](drawer.md) popup.
+
+The actions share the width of the footer equally.
+
+## Examples
+
+### Basic
+
+```tsx
+import { Button, Frame, ListGroup, Surface } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <Surface>
+      <Frame.Root onDismiss={() => {}}>
+        <Frame.Header>
+          <Frame.Title>Review request</Frame.Title>
+          <Frame.Description>Review the details before continuing.</Frame.Description>
+          <Frame.Close />
+        </Frame.Header>
+        <Frame.Body>
+          <ListGroup>
+            <ListGroup.Row>
+              <ListGroup.Label>Network</ListGroup.Label>
+              Tempo
+            </ListGroup.Row>
+            <ListGroup.Row>
+              <ListGroup.Label>Amount</ListGroup.Label>
+              $50.00
+            </ListGroup.Row>
+          </ListGroup>
+        </Frame.Body>
+        <Frame.Footer>
+          <Frame.Actions>
+            <Button variant="secondary">Cancel</Button>
+            <Button>Approve</Button>
+          </Frame.Actions>
+        </Frame.Footer>
+      </Frame.Root>
+    </Surface>
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Frame/Basic.tsx)
+
+### OnDismiss
+
+Set `onDismiss` on the frame or a surrounding `Frame.Provider` to show `Frame.Close`.
+
+```tsx
+import { Button, Frame, ListGroup, style, Surface } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <Frame.Provider onDismiss={() => {}}>
+      <div {...styles.grid()}>
+        <Surface>
+          <Review />
+        </Surface>
+        <Review />
+        <Surface>
+          <Review onDismiss={null} />
+        </Surface>
+      </div>
+    </Frame.Provider>
+  )
+}
+
+function Review(props: Frame.Root.Props) {
+  return (
+    <Frame.Root {...props}>
+      <Frame.Header>
+        <Frame.Title>Review request</Frame.Title>
+        <Frame.Description>Review the details before continuing.</Frame.Description>
+        <Frame.Close />
+      </Frame.Header>
+      <Frame.Body>
+        <ListGroup>
+          <ListGroup.Row>
+            <ListGroup.Label>Network</ListGroup.Label>
+            Tempo
+          </ListGroup.Row>
+          <ListGroup.Row>
+            <ListGroup.Label>Amount</ListGroup.Label>
+            $50.00
+          </ListGroup.Row>
+        </ListGroup>
+      </Frame.Body>
+      <Frame.Footer>
+        <Frame.Actions>
+          <Button variant="secondary">Cancel</Button>
+          <Button>Approve</Button>
+        </Frame.Actions>
+      </Frame.Footer>
+    </Frame.Root>
+  )
+}
+
+namespace styles {
+  export const grid = style({
+    backgroundColor: 'background.primary',
+    display: 'grid',
+    gap: '16',
+    padding: '16',
+    gridTemplateColumns: 'repeat(auto-fill, minmax(20rem, 1fr)) !custom',
+  })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Frame/OnDismiss.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { Frame } from '@tempoxyz/ds'
+
+<Frame />
+
+<Frame.Provider>
+  <Frame.Root>
+    <Frame.Header>
+      <Frame.Title />
+      <Frame.Description />
+      <Frame.Close />
+    </Frame.Header>
+    <Frame.Body />
+    <Frame.Footer>
+      <Frame.Actions />
+    </Frame.Footer>
+  </Frame.Root>
+</Frame.Provider>
+```
+
+## Guidelines
+
+### When to Use
+
+* Give a card, dialog, or drawer a title, content, and a row of actions.
+* Share one dismiss handler across nested panels with `Frame.Provider`, such as the steps of a dialog.
+
+### When Not to Use
+
+* Use [Surface](surface.md) with `Surface.Header` and `Surface.Title` for a card with only a heading and content.
+* Use [AppShell](app-shell.md) for the frame of a whole page.
+* Use [Stack](stack.md) for a plain column without a header or footer.
+
+### Put Actions in the Footer
+
+Put `Frame.Actions` inside `Frame.Footer`, in the [Button](button.md) order. `Frame.Body` grows to fill the frame, so the footer stays at the bottom of a tall container, such as a dialog popup. The body never scrolls, so let the container handle overflow.
+
+**Do:** Keep the actions in `Frame.Footer`, at the bottom of the frame.
+
+```tsx
+/**
+ * Do example for "Put Actions in the Footer" on the Frame page.
+ * Keep the actions in `Frame.Footer`, at the bottom of the frame.
+ * @module
+ */
+import { Amount, Button, Frame, ListGroup, style, Surface } from '@tempoxyz/ds'
+
+const payments = [
+  ['Alice', '25.00'],
+  ['Bob', '120.00'],
+] as const
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.canvas()}>
+      <Surface size="medium" {...styles.card()}>
+        <Frame {...styles.frame()}>
+          <Frame.Header>
+            <Frame.Title>Review batch</Frame.Title>
+          </Frame.Header>
+          <Frame.Body>
+            <ListGroup>
+              {payments.map(([name, amount]) => (
+                <ListGroup.Row key={name}>
+                  <ListGroup.Label>{name}</ListGroup.Label>
+                  <Amount symbol="USDC" value={amount} />
+                </ListGroup.Row>
+              ))}
+            </ListGroup>
+          </Frame.Body>
+          <Frame.Footer>
+            <Frame.Actions>
+              <Button size="small" variant="secondary">
+                Cancel
+              </Button>
+              <Button size="small">Send 2 payments</Button>
+            </Frame.Actions>
+          </Frame.Footer>
+        </Frame>
+      </Surface>
+    </div>
+  )
+}
+
+namespace styles {
+  export const canvas = style({
+    backgroundColor: 'background.primary',
+    borderRadius: 'sm',
+    boxSizing: 'border-box',
+    padding: '12',
+    width: '100% !custom',
+  })
+
+  export const card = style({ height: '240' })
+
+  export const frame = style({ height: '100% !custom', rowGap: '16' })
+}
+```
+
+**Don't:** Put the actions at the end of `Frame.Body`, directly against the content.
+
+```tsx
+/**
+ * Don't example for "Put Actions in the Footer" on the Frame page.
+ * Don't put the actions at the end of `Frame.Body`, directly against the content.
+ * @module
+ */
+import { Amount, Button, Frame, ListGroup, style, Surface } from '@tempoxyz/ds'
+
+const payments = [
+  ['Alice', '25.00'],
+  ['Bob', '120.00'],
+] as const
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.canvas()}>
+      <Surface size="medium" {...styles.card()}>
+        <Frame {...styles.frame()}>
+          <Frame.Header>
+            <Frame.Title>Review batch</Frame.Title>
+          </Frame.Header>
+          <Frame.Body>
+            <ListGroup>
+              {payments.map(([name, amount]) => (
+                <ListGroup.Row key={name}>
+                  <ListGroup.Label>{name}</ListGroup.Label>
+                  <Amount symbol="USDC" value={amount} />
+                </ListGroup.Row>
+              ))}
+            </ListGroup>
+            <Frame.Actions>
+              <Button size="small" variant="secondary">
+                Cancel
+              </Button>
+              <Button size="small">Send 2 payments</Button>
+            </Frame.Actions>
+          </Frame.Body>
+        </Frame>
+      </Surface>
+    </div>
+  )
+}
+
+namespace styles {
+  export const canvas = style({
+    backgroundColor: 'background.primary',
+    borderRadius: 'sm',
+    boxSizing: 'border-box',
+    padding: '12',
+    width: '100% !custom',
+  })
+
+  export const card = style({ height: '240' })
+
+  export const frame = style({ height: '100% !custom', rowGap: '16' })
+}
+```
+
+### Show Close Only When It Dismisses
+
+If a nested frame can't be dismissed, such as a confirmation step, pass `onDismiss={null}` to drop the inherited handler and hide `Frame.Close`.
+
+**Do:** Pass `onDismiss={null}` on a step that must finish.
+
+```tsx
+/**
+ * Do example for "Show Close Only When It Dismisses" on the Frame page.
+ * Pass `onDismiss={null}` on a step that must finish.
+ * @module
+ */
+import { Button, Frame, style, Surface } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Frame.Provider onDismiss={() => {}}>
+      <div {...styles.canvas()}>
+        <Surface size="medium">
+          <Frame onDismiss={null}>
+            <Frame.Header>
+              <Frame.Title>Sending payment</Frame.Title>
+              <Frame.Description>Keep this window open until 25.00 USDC settles.</Frame.Description>
+              <Frame.Close />
+            </Frame.Header>
+            <Frame.Footer>
+              <Frame.Actions>
+                <Button loading size="small">
+                  Send
+                </Button>
+              </Frame.Actions>
+            </Frame.Footer>
+          </Frame>
+        </Surface>
+      </div>
+    </Frame.Provider>
+  )
+}
+
+namespace styles {
+  export const canvas = style({
+    backgroundColor: 'background.primary',
+    borderRadius: 'sm',
+    boxSizing: 'border-box',
+    padding: '12',
+    width: '100% !custom',
+  })
+}
+```
+
+**Don't:** Leave an inherited close button on a step that can't be dismissed.
+
+```tsx
+/**
+ * Don't example for "Show Close Only When It Dismisses" on the Frame page.
+ * Don't leave an inherited close button on a step that can't be dismissed.
+ * @module
+ */
+import { Button, Frame, style, Surface } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Frame.Provider onDismiss={() => {}}>
+      <div {...styles.canvas()}>
+        <Surface size="medium">
+          <Frame>
+            <Frame.Header>
+              <Frame.Title>Sending payment</Frame.Title>
+              <Frame.Description>Keep this window open until 25.00 USDC settles.</Frame.Description>
+              <Frame.Close />
+            </Frame.Header>
+            <Frame.Footer>
+              <Frame.Actions>
+                <Button loading size="small">
+                  Send
+                </Button>
+              </Frame.Actions>
+            </Frame.Footer>
+          </Frame>
+        </Surface>
+      </div>
+    </Frame.Provider>
+  )
+}
+
+namespace styles {
+  export const canvas = style({
+    backgroundColor: 'background.primary',
+    borderRadius: 'sm',
+    boxSizing: 'border-box',
+    padding: '12',
+    width: '100% !custom',
+  })
+}
+```
+
+### Check the Heading Level
+
+`Frame.Title` always renders an `h2`.
+
+* **Dialog or Card (h2):** Use `Frame.Title` in a dialog, or in a card below the page `h1`.
+* **Inside an h2 Section (h3):** Render your own `h3` in the header in place of `Frame.Title`.
+
+## Content
+
+* **Title:** Name the task, such as Review request or Send USDC.
+* **Description:** In one sentence, state what happens next.
+* **Primary action:** Repeat the title's verb, such as Approve request.
+
+## Accessibility
+
+A frame adds headings and an optional close button. It doesn't move or trap focus, so other semantics and focus management come from its container.
+
+### Semantics
+
+* **Frame.Title (h2):** The frame's heading, rendered at the top of its header.
+* **Frame.Description (p):** Supporting text below the title, which describes the frame's content.
+* **Frame.Close (button):** Announced as "Close", with its icon hidden. Its target exceeds the WCAG 2.2 minimum.
+* **No Inert Close Button:** The close button renders nothing without a dismiss handler or `onClick`.
+
+### Keyboard
+
+* **Move Through the Frame (Tab):** Moves focus to the close button and the controls, in source order.
+* **Activate Close (Enter or Space):** Calls the close button's `onClick`, then the dismiss handler.
+
+### Your Responsibilities
+
+* **Name the Close Button (aria-label):** If ambiguous, name what it closes: "Close send payment".
+* **Label the Dialog (aria-labelledby):** Point a dialog's `aria-labelledby` at the title.
+
+## Related
+
+[Surface](surface.md)
+
+Use for the card around a frame.
+
+[Dialog](dialog.md)
+
+Use for frames that open over the page.
+
+[Drawer](drawer.md)
+
+Use for side panels.
+
+[Button](button.md)
+
+Use for ordering actions.