@tempoxyz/ds 0.3.9 → 0.3.11

package/dist/docs/components/skeleton.md

@@ -0,0 +1,517 @@
+# Skeleton
+
+Holds the place of content while it loads.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Skeleton.tsx)
+
+## Overview
+
+Skeleton renders a loading placeholder at the size of the content it wraps.
+
+## Examples
+
+### Basic
+
+```tsx
+import { Skeleton, style } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      <div {...styles.column()}>
+        <Skeleton style={{ height: 14, width: 160 }} />
+        <Skeleton style={{ height: 14, width: 96 }} />
+      </div>
+      <Skeleton>
+        <p {...styles.text()}>Keeps the size of its content</p>
+      </Skeleton>
+    </div>
+  )
+}
+
+namespace styles {
+  export const column = style({ display: 'flex', flexDirection: 'column', gap: '8' })
+
+  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '16' })
+
+  export const text = style({ margin: '0', typography: 'body.b2' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Skeleton/Basic.tsx)
+
+### Shape
+
+Set `shape` to `default` (default), `pill`, or `circle`.
+
+```tsx
+import { Skeleton, style } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      <Skeleton shape="circle" style={{ height: 40, width: 40 }} />
+      <Skeleton shape="default" style={{ height: 14, width: 160 }} />
+      <Skeleton shape="pill" style={{ height: 32, width: 96 }} />
+    </div>
+  )
+}
+
+namespace styles {
+  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '16' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Skeleton/Shape.tsx)
+
+### Show
+
+Set `show={false}` when data arrives to reveal the content. `show` defaults to `true`.
+
+```tsx
+import { Skeleton, style } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      <Skeleton>
+        <p {...styles.text()}>Loading content</p>
+      </Skeleton>
+      <Skeleton show={false}>
+        <p {...styles.text()}>Loaded content</p>
+      </Skeleton>
+    </div>
+  )
+}
+
+namespace styles {
+  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '16' })
+
+  export const text = style({ margin: '0', typography: 'body.b2' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Skeleton/Show.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { Skeleton } from '@tempoxyz/ds'
+
+<Skeleton />
+```
+
+## Guidelines
+
+### When to Use
+
+* Hold the place of content with a known layout, such as balances, activity rows, or metric tiles.
+* Fill table rows, cards, and lists on first load, with the expected or a typical item count.
+
+### When Not to Use
+
+* Use [Spinner](/docs/components/spinner) when the shape of the result is unknown, or for a busy control.
+* Use [Progress](/docs/components/progress) for a long task with measurable work.
+* Use `loading` on a [Button](/docs/components/button) while its action runs.
+* Use [Empty](/docs/components/empty) when the request returns no records.
+
+### Match the Final Content's Shape
+
+* **`circle`:** Avatars, identicons, and token icons.
+* **`pill`:** Pill-shaped controls, such as an extra-small button.
+* **`default`:** Text, blocks, badges, and buttons.
+
+For a list, repeat each row's structure instead of one block.
+
+**Do:** Mirror each row's icon, text lines, and amount.
+
+```tsx
+/**
+ * Do example for "Match the Final Content's Shape" on the Skeleton page.
+ * Mirror each row's icon, text lines, and amount.
+ * @module
+ */
+import { Skeleton, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.list()}>
+      {['0x8f3c…a21b', '0x41d2…9c07', '0xb7e0…3f5a'].map((address) => (
+        <div {...styles.row()} key={address}>
+          <Skeleton shape="circle" style={{ height: 32, width: 32 }} />
+          <div {...styles.text()}>
+            <Skeleton>
+              <div {...styles.title()}>{address}</div>
+            </Skeleton>
+            <Skeleton>
+              <div {...styles.meta()}>Oct 18, 14:02</div>
+            </Skeleton>
+          </div>
+          <Skeleton>
+            <div {...styles.title()}>+50.00 USDC</div>
+          </Skeleton>
+        </div>
+      ))}
+    </div>
+  )
+}
+
+namespace styles {
+  export const list = style({ display: 'flex', flexDirection: 'column', gap: '16' })
+
+  export const meta = style({ typography: 'body.b3' })
+
+  export const row = style({ alignItems: 'center', display: 'flex', gap: '12' })
+
+  export const text = style({
+    alignItems: 'flex-start',
+    display: 'flex',
+    flex: '1 !custom',
+    flexDirection: 'column',
+    gap: '4',
+  })
+
+  export const title = style({ typography: 'body.b2' })
+}
+```
+
+**Don't:** Cover a list with one block that hides its structure.
+
+```tsx
+/**
+ * Don't example for "Match the Final Content's Shape" on the Skeleton page.
+ * Don't cover a list with one block that hides its structure.
+ * @module
+ */
+import { Skeleton } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return <Skeleton style={{ height: 144, width: 256 }} />
+}
+```
+
+### Wrap the Real Content
+
+Skeleton takes the size of its children and hides them with `visibility: hidden`. Set `show={false}` when the data arrives, so the content keeps its place in reading order.
+
+```tsx
+<Skeleton show={loading}>
+  <Amount currency="USD" value={balance} />
+</Skeleton>
+```
+
+Size an empty skeleton with `style` only when there is nothing to wrap.
+
+**Do:** Wrap the element that holds the data, with a placeholder of typical length.
+
+```tsx
+/**
+ * Do example for "Wrap the Real Content" on the Skeleton page.
+ * Wrap the element that holds the data, with a placeholder of typical length.
+ * @module
+ */
+import { Skeleton, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.card()}>
+      <div {...styles.label()}>Balance</div>
+      <Skeleton>
+        <div {...styles.value()}>1,250.00 USDC</div>
+      </Skeleton>
+    </div>
+  )
+}
+
+namespace styles {
+  export const card = style({
+    alignItems: 'flex-start',
+    display: 'flex',
+    flexDirection: 'column',
+    gap: '4',
+  })
+
+  export const label = style({ color: 'content.secondary', typography: 'body.b3' })
+
+  export const value = style({ color: 'content.primary', typography: 'heading.h1' })
+}
+```
+
+**Don't:** Swap in a separately sized block that doesn't match the content.
+
+```tsx
+/**
+ * Don't example for "Wrap the Real Content" on the Skeleton page.
+ * Don't swap in a separately sized block that doesn't match the content.
+ * @module
+ */
+import { Skeleton, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.card()}>
+      <div {...styles.label()}>Balance</div>
+      <Skeleton style={{ height: 12, width: 80 }} />
+    </div>
+  )
+}
+
+namespace styles {
+  export const card = style({
+    alignItems: 'flex-start',
+    display: 'flex',
+    flexDirection: 'column',
+    gap: '4',
+  })
+
+  export const label = style({ color: 'content.secondary', typography: 'body.b3' })
+}
+```
+
+### Keep Labels and Controls Visible
+
+Keep headings, labels, tabs, filters, and buttons that do not depend on the data on screen.
+
+**Do:** Keep the label and actions, and hold the place of the amount.
+
+```tsx
+/**
+ * Do example for "Keep Labels and Controls Visible" on the Skeleton page.
+ * Keep the label and actions, and hold the place of the amount.
+ * @module
+ */
+import { Button, Skeleton, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.card()}>
+      <div {...styles.label()}>Balance</div>
+      <Skeleton>
+        <div {...styles.value()}>$1,250.00</div>
+      </Skeleton>
+      <div {...styles.actions()}>
+        <Button size="small">Send</Button>
+        <Button size="small" variant="secondary">
+          Receive
+        </Button>
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const actions = style({ display: 'flex', gap: '8', marginBlockStart: '12' })
+
+  export const card = style({
+    alignItems: 'flex-start',
+    display: 'flex',
+    flexDirection: 'column',
+    gap: '4',
+  })
+
+  export const label = style({ color: 'content.secondary', typography: 'body.b3' })
+
+  export const value = style({ color: 'content.primary', typography: 'heading.h1' })
+}
+```
+
+**Don't:** Turn static labels and buttons into skeletons.
+
+```tsx
+/**
+ * Don't example for "Keep Labels and Controls Visible" on the Skeleton page.
+ * Don't turn static labels and buttons into skeletons.
+ * @module
+ */
+import { Button, Skeleton, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.card()}>
+      <Skeleton>
+        <div {...styles.label()}>Balance</div>
+      </Skeleton>
+      <Skeleton>
+        <div {...styles.value()}>$1,250.00</div>
+      </Skeleton>
+      <div {...styles.actions()}>
+        <Skeleton shape="pill">
+          <Button size="small">Send</Button>
+        </Skeleton>
+        <Skeleton shape="pill">
+          <Button size="small" variant="secondary">
+            Receive
+          </Button>
+        </Skeleton>
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const actions = style({ display: 'flex', gap: '8', marginBlockStart: '12' })
+
+  export const card = style({
+    alignItems: 'flex-start',
+    display: 'flex',
+    flexDirection: 'column',
+    gap: '4',
+  })
+
+  export const label = style({ color: 'content.secondary', typography: 'body.b3' })
+
+  export const value = style({ color: 'content.primary', typography: 'heading.h1' })
+}
+```
+
+### Keep Current Data During a Refresh
+
+**Do:** Keep values on screen, such as a polled balance, until the new ones arrive.
+
+```tsx
+/**
+ * Do example for "Keep Current Data During a Refresh" on the Skeleton page.
+ * Keep values on screen, such as a polled balance, until the new ones arrive.
+ * @module
+ */
+import { style } from '@tempoxyz/ds'
+
+const payments = [
+  { address: '0x8f3c…a21b', amount: '+50.00 USDC' },
+  { address: '0x41d2…9c07', amount: '-25.00 USDC' },
+]
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.list()}>
+      <div {...styles.heading()}>Activity</div>
+      {payments.map((payment) => (
+        <div {...styles.row()} key={payment.address}>
+          <div>{payment.address}</div>
+          <div>{payment.amount}</div>
+        </div>
+      ))}
+    </div>
+  )
+}
+
+namespace styles {
+  export const heading = style({ color: 'content.primary', typography: 'body.b2Strong' })
+
+  export const list = style({
+    display: 'flex',
+    flexDirection: 'column',
+    gap: '12',
+    width: '100% !custom',
+  })
+
+  export const row = style({
+    alignItems: 'center',
+    display: 'flex',
+    justifyContent: 'space-between',
+    typography: 'body.b2',
+  })
+}
+```
+
+**Don't:** Return to skeletons on every refresh.
+
+```tsx
+/**
+ * Don't example for "Keep Current Data During a Refresh" on the Skeleton page.
+ * Don't return to skeletons on every refresh.
+ * @module
+ */
+import { Skeleton, style } from '@tempoxyz/ds'
+
+const payments = [
+  { address: '0x8f3c…a21b', amount: '+50.00 USDC' },
+  { address: '0x41d2…9c07', amount: '-25.00 USDC' },
+]
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.list()}>
+      <div {...styles.heading()}>Activity</div>
+      {payments.map((payment) => (
+        <div {...styles.row()} key={payment.address}>
+          <Skeleton>
+            <div>{payment.address}</div>
+          </Skeleton>
+          <Skeleton>
+            <div>{payment.amount}</div>
+          </Skeleton>
+        </div>
+      ))}
+    </div>
+  )
+}
+
+namespace styles {
+  export const heading = style({ color: 'content.primary', typography: 'body.b2Strong' })
+
+  export const list = style({
+    display: 'flex',
+    flexDirection: 'column',
+    gap: '12',
+    width: '100% !custom',
+  })
+
+  export const row = style({
+    alignItems: 'center',
+    display: 'flex',
+    justifyContent: 'space-between',
+    typography: 'body.b2',
+  })
+}
+```
+
+### Skip It for Fast Responses
+
+* **Fast Responses (Under 300 ms):** Delay the skeleton, so the content renders without a flash.
+* **Typical Waits (300 ms to 10 s):** Show the skeleton.
+* **Long Waits (Over 10 s):** Show [Progress](/docs/components/progress). See [Loading](/docs/patterns/loading).
+
+## Accessibility
+
+Skeleton renders a `div` that marks its content busy and hides it until `show={false}`. It has no live region, and most screen readers ignore `aria-busy` on a plain `div`.
+
+### Semantics
+
+* **Busy State (aria-busy):** Marks the region busy while `show` is true.
+* **Hidden Content (visibility: hidden):** Screen readers skip the placeholder text, and focus cannot reach hidden controls.
+* **Pointer Events:** The root blocks pointer events while it shows, so placeholder buttons are inert.
+* **Reduced Motion (prefers-reduced-motion):** The sweep stops, and the placeholder stays a static tint.
+
+### Your Responsibilities
+
+* **Announce Long Loads (status):** For main content, state what loads in a status message, such as "Loading activity".
+* **Handle Failures:** If loading fails, show an error message. Never leave a skeleton that does not resolve.
+
+## Related
+
+[Spinner](/docs/components/spinner)
+
+Use for loading with an unknown shape.
+
+[Progress](/docs/components/progress)
+
+Use for measurable work.
+
+[Empty](/docs/components/empty)
+
+Use for a region with nothing to show.
+
+[Loading](/docs/patterns/loading)
+
+Covers choosing a loading indicator.