@tempoxyz/ds 0.3.10 → 0.3.11

package/dist/docs/patterns/empty-states.md

@@ -0,0 +1,612 @@
+# Empty States
+
+Explain why a region has nothing to show, and offer the next step that fills it.
+
+## Overview
+
+An empty region can mean missing data, a filter with no matches, finished work, or a failed request. Each cause takes different words and actions. [Empty](/docs/components/empty) composes the parts, and every empty state covers three points:
+
+* **What Is This Place? (Empty.Title):** Names the content that would appear.
+* **Why Is It Empty? (Empty.Description):** Explains the cause in one sentence.
+* **What Can I Do? (Empty.Actions):** One action that fills the region, if one exists.
+
+## Variants
+
+The cause decides the text and the action. These are reference layouts built from [Surface](/docs/components/surface), [Empty](/docs/components/empty), and [Button](/docs/components/button), not shipped components.
+
+### First Use
+
+```tsx
+import { Button, Empty, style, Surface } from '@tempoxyz/ds'
+import { History } from '@tempoxyz/ds/icons'
+
+export const fill = true
+export function Demo() {
+  return (
+    <div {...styles.page()}>
+      <Surface {...styles.card()}>
+        <Surface.Header>
+          <Surface.Title>Activity</Surface.Title>
+        </Surface.Header>
+        <Empty.Root>
+          <Empty.Icon>
+            <History />
+          </Empty.Icon>
+          <Empty.Title>No activity yet</Empty.Title>
+          <Empty.Description>
+            Payments you send and receive appear here. Add funds to make your first payment.
+          </Empty.Description>
+          <Empty.Actions>
+            <Button size="small">Add funds</Button>
+          </Empty.Actions>
+        </Empty.Root>
+      </Surface>
+    </div>
+  )
+}
+
+namespace styles {
+  export const card = style({
+    boxSizing: 'border-box',
+    maxWidth: '26rem !custom',
+    width: '100% !custom',
+  })
+
+  export const page = style({
+    backgroundColor: 'background.primary',
+    display: 'grid',
+    justifyItems: 'center',
+    padding: '16',
+  })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Patterns/EmptyFirstUse.tsx)
+
+Nothing exists yet. State what will appear, and offer the action that creates the first item, such as Add funds or Create key.
+
+### No Results
+
+```tsx
+import { Button, Empty, Field, Identicon, ListGroup, style, Surface, TextInput } from '@tempoxyz/ds'
+import { Search } from '@tempoxyz/ds/icons'
+import { useRef, useState } from 'react'
+
+export const fill = true
+const contacts = [
+  ['Ada', '0x71C7656EC7ab88b098defB751B7401B5f6d8976F'],
+  ['Payroll', '0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC'],
+  ['Treasury', '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'],
+] as const
+
+export function Demo() {
+  const input = useRef<HTMLInputElement>(null)
+  const [query, setQuery] = useState('zara')
+  const matches = contacts.filter(([name, address]) =>
+    `${name} ${address}`.toLowerCase().includes(query.trim().toLowerCase()),
+  )
+
+  return (
+    <div {...styles.page()}>
+      <Surface {...styles.card()}>
+        <Surface.Header>
+          <Surface.Title>Contacts</Surface.Title>
+        </Surface.Header>
+        <Field.Root>
+          <TextInput.Group>
+            <TextInput.Prefix>
+              <Search />
+            </TextInput.Prefix>
+            <TextInput.Control
+              aria-label="Search contacts"
+              onValueChange={setQuery}
+              placeholder="Name or address"
+              ref={input}
+              type="search"
+              value={query}
+            />
+            <TextInput.Clear />
+          </TextInput.Group>
+        </Field.Root>
+        {/* Stays mounted, so screen readers hear the count change as you type. */}
+        <p role="status" {...styles.status()}>
+          {matches.length === 1 ? '1 contact' : `${matches.length} contacts`}
+        </p>
+        {matches.length > 0 ? (
+          <div {...styles.rows()}>
+            <ListGroup.Root>
+              {matches.map(([name, address]) => (
+                <ListGroup.Row key={address}>
+                  <Identicon address={address} aria-hidden size="24" />
+                  <ListGroup.Info>
+                    <ListGroup.Title>{name}</ListGroup.Title>
+                    <ListGroup.Description>
+                      {address.slice(0, 6)}…{address.slice(-4)}
+                    </ListGroup.Description>
+                  </ListGroup.Info>
+                </ListGroup.Row>
+              ))}
+            </ListGroup.Root>
+          </div>
+        ) : (
+          <Empty.Root>
+            <Empty.Icon>
+              <Search />
+            </Empty.Icon>
+            <Empty.Title>No contacts match “{query.trim()}”</Empty.Title>
+            <Empty.Description>
+              Check the spelling, or search by the full 0x address.
+            </Empty.Description>
+            <Empty.Actions>
+              <Button
+                onClick={() => {
+                  setQuery('')
+                  input.current?.focus()
+                }}
+                size="small"
+                variant="secondary"
+              >
+                Clear search
+              </Button>
+            </Empty.Actions>
+          </Empty.Root>
+        )}
+      </Surface>
+    </div>
+  )
+}
+
+namespace styles {
+  export const card = style({
+    boxSizing: 'border-box',
+    maxWidth: '26rem !custom',
+    width: '100% !custom',
+  })
+
+  export const page = style({
+    backgroundColor: 'background.primary',
+    display: 'grid',
+    justifyItems: 'center',
+    padding: '16',
+  })
+
+  export const rows = style({ marginBlockStart: '8' })
+
+  export const status = style({
+    clipPath: 'inset(50%) !custom',
+    height: '1px !custom',
+    margin: '0',
+    overflow: 'hidden',
+    position: 'absolute',
+    whiteSpace: 'nowrap',
+    width: '1px !custom',
+  })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Patterns/EmptyNoResults.tsx)
+
+Repeat the query in the title, so the reader can spot a typo. Offer Clear search or Clear filters as a `secondary` button, and keep the search field and filters visible above the empty state.
+
+**Do:** Repeat the query and offer a way to widen the search.
+
+```tsx
+<Empty.Root>
+  <Empty.Icon>
+    <Search />
+  </Empty.Icon>
+  <Empty.Title>No results for "rent"</Empty.Title>
+  <Empty.Description>Check the spelling or search for another payment.</Empty.Description>
+  <Empty.Actions>
+    <Button size="small" variant="secondary">Clear search</Button>
+  </Empty.Actions>
+</Empty.Root>
+```
+
+**Don't:** If a filter hides existing items, don't show the first use state.
+
+```tsx
+<Empty.Root>
+  <Empty.Icon>
+    <Wallet />
+  </Empty.Icon>
+  <Empty.Title>No payments yet</Empty.Title>
+  <Empty.Description>Payments you send or receive appear here.</Empty.Description>
+  <Empty.Actions>
+    <Button size="small">Add funds</Button>
+  </Empty.Actions>
+</Empty.Root>
+```
+
+### Cleared
+
+```tsx
+import { Button, Empty, style, Surface } from '@tempoxyz/ds'
+import { CheckCircle } from '@tempoxyz/ds/icons'
+
+export const fill = true
+export function Demo() {
+  return (
+    <div {...styles.page()}>
+      <Surface {...styles.card()}>
+        <Surface.Header>
+          <Surface.Title>Payment requests</Surface.Title>
+        </Surface.Header>
+        <Empty.Root>
+          <Empty.Icon>
+            <CheckCircle />
+          </Empty.Icon>
+          <Empty.Title>No pending requests</Empty.Title>
+          <Empty.Description>
+            You've paid or declined every request. New requests appear here.
+          </Empty.Description>
+          <Empty.Actions>
+            <Button size="small" variant="secondary">
+              View history
+            </Button>
+          </Empty.Actions>
+        </Empty.Root>
+      </Surface>
+    </div>
+  )
+}
+
+namespace styles {
+  export const card = style({
+    boxSizing: 'border-box',
+    maxWidth: '26rem !custom',
+    width: '100% !custom',
+  })
+
+  export const page = style({
+    backgroundColor: 'background.primary',
+    display: 'grid',
+    justifyItems: 'center',
+    padding: '16',
+  })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Patterns/EmptyCleared.tsx)
+
+If the reader processed everything, such as every payment request, confirm that nothing is left. Leave out the primary action. If a history exists, link to it.
+
+**Do:** Confirm the reader finished, and state what will appear next.
+
+```tsx
+<Empty.Root>
+  <Empty.Icon>
+    <Check />
+  </Empty.Icon>
+  <Empty.Title>All caught up</Empty.Title>
+  <Empty.Description>New requests appear here when someone asks you to pay.</Empty.Description>
+</Empty.Root>
+```
+
+**Don't:** Use playful filler in place of a clear outcome.
+
+```tsx
+<Empty.Root>
+  <Empty.Icon>
+    <Clipboard />
+  </Empty.Icon>
+  <Empty.Title>Nothing here!</Empty.Title>
+  <Empty.Description>Looks like it is pretty quiet. Check back later!</Empty.Description>
+</Empty.Root>
+```
+
+### Error-Empty
+
+```tsx
+import { Button, Empty, ListGroup, style, Surface } from '@tempoxyz/ds'
+import { AlertCircle } from '@tempoxyz/ds/icons'
+import { useState } from 'react'
+
+export const fill = true
+function Failed(props: { onRetry: () => void; retrying: boolean }) {
+  return (
+    <Empty.Root>
+      <Empty.Icon>
+        <AlertCircle />
+      </Empty.Icon>
+      <Empty.Title>Couldn't load activity</Empty.Title>
+      <Empty.Description>
+        Check your connection, then try again. Your balance and payments aren't affected.
+      </Empty.Description>
+      <Empty.Actions>
+        <Button loading={props.retrying} onClick={props.onRetry} size="small">
+          Try again
+        </Button>
+      </Empty.Actions>
+    </Empty.Root>
+  )
+}
+
+export function Demo() {
+  const [loaded, setLoaded] = useState(false)
+  const [retrying, setRetrying] = useState(false)
+
+  return (
+    <div {...styles.page()}>
+      <Surface {...styles.card()}>
+        <Surface.Header>
+          <Surface.Title>Activity</Surface.Title>
+        </Surface.Header>
+        {loaded ? (
+          <div {...styles.rows()}>
+            <ListGroup.Root>
+              <ListGroup.Row>
+                <ListGroup.Label>Received from 0x3C44…93BC</ListGroup.Label>
+                120.00 USDC
+              </ListGroup.Row>
+              <ListGroup.Row>
+                <ListGroup.Label>Sent to 0x71C7…976F</ListGroup.Label>
+                25.00 USDC
+              </ListGroup.Row>
+            </ListGroup.Root>
+          </div>
+        ) : (
+          <Failed
+            onRetry={() => {
+              setRetrying(true)
+              setTimeout(() => {
+                setRetrying(false)
+                setLoaded(true)
+              }, 1000)
+            }}
+            retrying={retrying}
+          />
+        )}
+      </Surface>
+    </div>
+  )
+}
+
+namespace styles {
+  export const card = style({
+    boxSizing: 'border-box',
+    maxWidth: '26rem !custom',
+    width: '100% !custom',
+  })
+
+  export const page = style({
+    backgroundColor: 'background.primary',
+    display: 'grid',
+    justifyItems: 'center',
+    padding: '16',
+  })
+
+  export const rows = style({ marginBlockStart: '8' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Patterns/EmptyError.tsx)
+
+If the request fails, write Couldn't load followed by the content, and offer Try again. Set `loading` on the [Button](/docs/components/button) while the retry runs.
+
+## Guidelines
+
+### Explain the Cause and the Next Step
+
+Write the title as a short statement of what is missing, such as No API keys yet. Use the description for the cause and what the action does.
+
+**Do:** State what is missing and offer the action that adds it.
+
+```tsx
+/**
+ * Do example for "Explain the Cause and the Next Step" on the Empty States page.
+ * State what is missing and offer the action that adds it.
+ * @module
+ */
+import { Button, Empty } from '@tempoxyz/ds'
+import { Key } from '@tempoxyz/ds/icons'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Empty.Root>
+      <Empty.Icon>
+        <Key />
+      </Empty.Icon>
+      <Empty.Title>No API keys yet</Empty.Title>
+      <Empty.Description>Create a key to call the Tempo API from your server.</Empty.Description>
+      <Empty.Actions>
+        <Button size="small">Create key</Button>
+      </Empty.Actions>
+    </Empty.Root>
+  )
+}
+```
+
+**Don't:** Show a bare No data message with nothing to do next.
+
+```tsx
+/**
+ * Don't example for "Explain the Cause and the Next Step" on the Empty States page.
+ * Don't show a bare No data message with nothing to do next.
+ * @module
+ */
+import { Empty } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Empty.Root>
+      <Empty.Title>No data</Empty.Title>
+    </Empty.Root>
+  )
+}
+```
+
+### Never Show a Failed Request as Empty
+
+An empty list after a failed request falsely reports no activity. Keep empty states for successful requests with no content.
+
+**Do:** State that the content couldn't load, and offer Try again.
+
+```tsx
+/**
+ * Do example for "Never Show a Failed Request as Empty" on the Empty States page.
+ * State that the content couldn't load, and offer Try again.
+ * @module
+ */
+import { Button, Empty } from '@tempoxyz/ds'
+import { AlertCircle } from '@tempoxyz/ds/icons'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Empty.Root>
+      <Empty.Icon>
+        <AlertCircle />
+      </Empty.Icon>
+      <Empty.Title>Couldn't load activity</Empty.Title>
+      <Empty.Description>Check your connection, then try again.</Empty.Description>
+      <Empty.Actions>
+        <Button size="small">Try again</Button>
+      </Empty.Actions>
+    </Empty.Root>
+  )
+}
+```
+
+**Don't:** Show No activity yet after the request failed.
+
+```tsx
+/**
+ * Don't example for "Never Show a Failed Request as Empty" on the Empty States page.
+ * Don't show No activity yet after the request failed.
+ * @module
+ */
+import { Empty } from '@tempoxyz/ds'
+import { History } from '@tempoxyz/ds/icons'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Empty.Root>
+      <Empty.Icon>
+        <History />
+      </Empty.Icon>
+      <Empty.Title>No activity yet</Empty.Title>
+      <Empty.Description>Payments you send and receive appear here.</Empty.Description>
+    </Empty.Root>
+  )
+}
+```
+
+### Offer One Primary Action
+
+Make it the task that fills the region. Add a secondary button only for a related step, such as a guide, and use `Button.Link` if the action opens another page.
+
+**Do:** Pair one primary action with an optional secondary one.
+
+```tsx
+/**
+ * Do example for "Offer One Primary Action" on the Empty States page.
+ * Pair one primary action with an optional secondary one.
+ * @module
+ */
+import { Button, Empty } from '@tempoxyz/ds'
+import { Link } from '@tempoxyz/ds/icons'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Empty.Root>
+      <Empty.Icon>
+        <Link />
+      </Empty.Icon>
+      <Empty.Title>No webhooks</Empty.Title>
+      <Empty.Description>Add an endpoint to receive payment events.</Empty.Description>
+      <Empty.Actions>
+        <Button size="small">Add webhook</Button>
+        <Button size="small" variant="secondary">
+          Read the guide
+        </Button>
+      </Empty.Actions>
+    </Empty.Root>
+  )
+}
+```
+
+**Don't:** Offer several primary actions that compete for attention.
+
+```tsx
+/**
+ * Don't example for "Offer One Primary Action" on the Empty States page.
+ * Don't offer several primary actions that compete for attention.
+ * @module
+ */
+import { Button, Empty } from '@tempoxyz/ds'
+import { Link } from '@tempoxyz/ds/icons'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Empty.Root>
+      <Empty.Icon>
+        <Link />
+      </Empty.Icon>
+      <Empty.Title>No webhooks</Empty.Title>
+      <Empty.Description>Add an endpoint to receive payment events.</Empty.Description>
+      <Empty.Actions>
+        <Button size="small">Add webhook</Button>
+        <Button size="small">Import</Button>
+        <Button size="small">Test event</Button>
+      </Empty.Actions>
+    </Empty.Root>
+  )
+}
+```
+
+### Fit the State to the Region
+
+* **Pages and Cards:** Use the full empty state with an icon that hints at the content.
+* **Small Regions:** In a small region, such as a [Popover](/docs/components/popover), use a short line of text and no icon.
+* **Comboboxes (Combobox.Empty):** Render it in a [Combobox](/docs/components/combobox), so an empty result is announced instead of an empty popup.
+* **Keep the Frame:** Keep the heading and filters. In a [Table](/docs/components/table), put the empty state below the header row.
+
+### Don't Show an Empty State While Loading
+
+* **Load First (Skeleton):** Show a [Skeleton](/docs/components/skeleton) until the request settles. An empty state that flashes first reads as a missing balance.
+* **Then Decide:** After the request settles, choose content, an empty state, or an error (see [Loading](/docs/patterns/loading)).
+
+## States
+
+* **Disabled:** If the reader lacks permission for the action, leave it out and state who can act.
+* **Success (Toast):** The new item replaces the empty state, and a [Toast](/docs/components/toast) confirms it.
+
+## Content
+
+* **Title (Sentence case):** Name what is missing, such as "No payments yet".
+* **Description (1 sentence):** Address the reader as "you".
+* **Action (Verb):** Lead with a verb, such as "Add funds".
+
+## Accessibility
+
+* **Heading Level (h3):** Place the state under an `h2`, such as a `Surface.Title`, so heading levels stay in order.
+* **Announce Results (role=status):** The parts render no live region. If results change on input, announce the count in a polite region that stays mounted.
+* **Focus After Clearing:** After Clear search, move focus to the search field.
+
+## Related
+
+[Empty](/docs/components/empty)
+
+Use for the component parts.
+
+[Combobox](/docs/components/combobox)
+
+Use for empty popups.
+
+[Loading](/docs/patterns/loading)
+
+Covers what shows before content.
+
+[Feedback and Status](/docs/patterns/feedback-and-status)
+
+Covers the Couldn't load state.
+
+[Tables and Lists](/docs/patterns/tables-and-lists)
+
+Covers empty tables.