@tempoxyz/ds 0.3.10 → 0.3.11

package/dist/docs/components/empty.md

@@ -0,0 +1,340 @@
+# Empty
+
+Fills a region that has nothing to show yet.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Empty.tsx)
+
+Figma: [Messaging/Progress Panel](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=5227-3967) (`Empty.Root`)
+
+## Overview
+
+A centered placeholder with a title, a description, an optional icon, and actions.
+
+## Examples
+
+### Basic
+
+```tsx
+import { Button, Empty } from '@tempoxyz/ds'
+import { Clipboard } from '@tempoxyz/ds/icons'
+
+export function Demo() {
+  return (
+    <Empty.Root>
+      <Empty.Icon>
+        <Clipboard />
+      </Empty.Icon>
+      <Empty.Title>No activity yet</Empty.Title>
+      <Empty.Description>Transactions will appear here once you send or receive.</Empty.Description>
+      <Empty.Actions>
+        <Button size="small">Refresh</Button>
+        <Button size="small" variant="secondary">
+          Learn more
+        </Button>
+      </Empty.Actions>
+    </Empty.Root>
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Empty/Basic.tsx)
+
+### Progress
+
+Use a [Spinner](/docs/components/spinner) instead of the icon while the region waits on another task, such as a checkout in another window. Frame it in a `medium` [Surface](/docs/components/surface) for a panel.
+
+```tsx
+/** An empty state in a medium surface that waits on a checkout in another window. @module */
+import { Empty, Spinner, Surface } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <Surface size="medium">
+      <Empty.Root>
+        <Spinner aria-label="Waiting for checkout" />
+        <Empty.Title>Finish checkout in the window that opened</Empty.Title>
+        <Empty.Description>Buying $10.00 of MACH. This updates when it lands.</Empty.Description>
+      </Empty.Root>
+    </Surface>
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Empty/Progress.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { Empty } from '@tempoxyz/ds'
+
+<Empty.Root>
+  <Empty.Icon />
+  <Empty.Title />
+  <Empty.Description />
+  <Empty.Actions />
+</Empty.Root>
+```
+
+## Guidelines
+
+### When to Use
+
+* Fill a list or table with no records yet.
+* Replace results when a search or filter matches nothing.
+* Confirm that a list is clear on purpose, such as a retry queue with nothing left.
+
+### When Not to Use
+
+* Use [Skeleton](/docs/components/skeleton) while the request runs. Show the empty state only after it returns no records.
+* Use a `negative` [Alert](/docs/components/alert) with a Retry action if the data fails to load.
+* Use `Combobox.Empty` of [Combobox](/docs/components/combobox) or `Autocomplete.Empty` of [Autocomplete](/docs/components/autocomplete) for a popup list with no matches.
+
+### Explain Why, Then Offer a Next Step
+
+* **`Empty.Title`:** States what belongs here.
+* **`Empty.Description`:** States why there is nothing.
+* **`Empty.Actions`:** Holds a [Button](/docs/components/button) for the next step.
+
+**Do:** Say what will appear and offer the action that adds it.
+
+```tsx
+/**
+ * Do example for "Explain Why, Then Offer a Next Step" on the Empty page.
+ * Say what will appear 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 with no reason or next step.
+
+```tsx
+/**
+ * Don't example for "Explain Why, Then Offer a Next Step" on the Empty page.
+ * Don't show a bare No data with no reason or next step.
+ * @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>
+  )
+}
+```
+
+### Match the Message to the Cause
+
+* **Nothing Created Yet:** Offer the action that adds the first item.
+* **No Search Results:** Repeat the query and offer to clear it.
+* **Filters Exclude All:** Offer to clear the filters.
+* **Cleared on Purpose:** Offer no action, or a link to the logs.
+
+### Offer One Primary Action
+
+Add a `secondary` button only for a real alternative, such as View docs. Use `size="small"` to match the centered text.
+
+**Do:** Give `Empty.Actions` one `primary` button that resolves the empty state.
+
+```tsx
+/**
+ * Do example for "Offer One Primary Action" on the Empty page.
+ * Give `Empty.Actions` one `primary` button that resolves the empty state.
+ * @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" variant="secondary">
+          View docs
+        </Button>
+        <Button size="small">Create key</Button>
+      </Empty.Actions>
+    </Empty.Root>
+  )
+}
+```
+
+**Don't:** Offer several `primary` buttons.
+
+```tsx
+/** Don't example for "Offer One Primary Action" on the Empty page. Don't offer several `primary` buttons. @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">View docs</Button>
+        <Button size="small">Import key</Button>
+        <Button size="small">Create key</Button>
+      </Empty.Actions>
+    </Empty.Root>
+  )
+}
+```
+
+### Keep It Inside the Region It Replaces
+
+**Do:** Render `Empty.Root` in place of the list or table body. Keep the heading and filters around it.
+
+```tsx
+/**
+ * Do example for "Keep It Inside the Region It Replaces" on the Empty page.
+ * Render `Empty.Root` in place of the list or table body. Keep the heading and filters around it.
+ * @module
+ */
+import { Empty, style, Surface, TextInput } from '@tempoxyz/ds'
+import { Search } from '@tempoxyz/ds/icons'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Surface size="medium" {...styles.card()}>
+      <div {...styles.heading()}>Payments</div>
+      <TextInput.Group>
+        <TextInput.Prefix>
+          <Search />
+        </TextInput.Prefix>
+        <TextInput.Control aria-label="Search payments" defaultValue="0x8f3c" />
+      </TextInput.Group>
+      <Empty.Root>
+        <Empty.Title>No results for "0x8f3c"</Empty.Title>
+        <Empty.Description>Check the address, or search by amount.</Empty.Description>
+      </Empty.Root>
+    </Surface>
+  )
+}
+
+namespace styles {
+  export const card = style({
+    boxSizing: 'border-box',
+    display: 'flex',
+    flexDirection: 'column',
+    gap: '16',
+    width: '100% !custom',
+  })
+
+  export const heading = style({ color: 'content.primary', typography: 'body.b1Strong' })
+}
+```
+
+**Don't:** Replace the heading and filters with the empty state.
+
+```tsx
+/**
+ * Don't example for "Keep It Inside the Region It Replaces" on the Empty page.
+ * Don't replace the heading and filters with the empty state.
+ * @module
+ */
+import { Empty, style, Surface } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Surface size="medium" {...styles.card()}>
+      <Empty.Root>
+        <Empty.Title>No results for "0x8f3c"</Empty.Title>
+        <Empty.Description>Check the address, or search by amount.</Empty.Description>
+      </Empty.Root>
+    </Surface>
+  )
+}
+
+namespace styles {
+  export const card = style({
+    boxSizing: 'border-box',
+    display: 'flex',
+    flexDirection: 'column',
+    gap: '16',
+    width: '100% !custom',
+  })
+}
+```
+
+Use `Empty.Icon` for an icon that names the content type, such as `Key` for API keys. Leave out status icons such as `AlertTriangle`.
+
+## Content
+
+* **Title:** State what is missing, such as No activity yet, without a period.
+* **Description:** In one sentence, state when content appears or why it is hidden, such as Transactions appear here once you send or receive. It wraps at 22.5rem.
+* **Tone:** Avoid blame and jokes. Write No payments match these filters, not You haven't made any payments.
+* **Action:** Start with a verb and name the object, such as Create key. Avoid Get started.
+
+## Accessibility
+
+An empty state renders plain elements with no ARIA wiring, in the order you compose them.
+
+### Semantics
+
+* **Empty.Title (h3):** Titles the empty state below a section heading.
+* **Empty.Description (p):** Explains why the area is empty or what to do.
+* **Empty.Icon (aria-hidden):** A decorative badge that screen readers skip.
+* **Empty.Actions:** Holds the buttons or links you pass.
+
+### Keyboard
+
+* **Move Through the Actions (Tab):** Moves focus to each action, in order.
+* **Activate an Action (Enter or Space):** Actions keep native keys and focus outlines.
+
+### Your Responsibilities
+
+* **Keep the Heading Order (h2 then h3):** Put the empty state under a section heading to keep the outline in order (SC 1.3.1).
+* **Announce New Results (role="status"):** Not a live region. If it replaces results after a search, announce it in a status element.
+
+## Related
+
+[Skeleton](/docs/components/skeleton)
+
+Use for content that is still loading.
+
+[Alert](/docs/components/alert)
+
+Use for a failed load with a retry.
+
+[Button](/docs/components/button)
+
+Use for the action that fills the state.
+
+[Empty States](/docs/patterns/empty-states)
+
+Covers first-use, no-results, and cleared states.