@tempoxyz/ds 0.3.9 → 0.3.11

package/dist/docs/components/loading-dots.md

@@ -0,0 +1,237 @@
+# LoadingDots
+
+Shows three pulsing dots for inline loading.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/LoadingDots.tsx)
+
+## Overview
+
+LoadingDots renders three pulsing dots inline, such as inside a button or beside text.
+
+## Examples
+
+### Basic
+
+```tsx
+import { LoadingDots } from '@tempoxyz/ds'
+
+export function Demo() {
+  return <LoadingDots />
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/LoadingDots/Basic.tsx)
+
+### Size
+
+Set `size` to `small`, `medium` (default), or `large`.
+
+```tsx
+import { LoadingDots, style } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      {(['small', 'medium', 'large'] as const).map((size) => (
+        <LoadingDots key={size} size={size} />
+      ))}
+    </div>
+  )
+}
+
+namespace styles {
+  export const row = style({ alignItems: 'center', display: 'flex', gap: '24' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/LoadingDots/Size.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { LoadingDots } from '@tempoxyz/ds'
+
+<LoadingDots />
+```
+
+## Guidelines
+
+### When to Use
+
+* Show a short wait inside a line of text, such as Estimating network fee.
+* Hold the place of one inline value, such as an exchange rate or a recipient name.
+
+### When Not to Use
+
+* Use `loading` on a [Button](/docs/components/button) while its action runs.
+* Use [Spinner](/docs/components/spinner) for a busy region or control.
+* Use [Skeleton](/docs/components/skeleton) for content with a known shape, such as rows or cards.
+* Use [Progress](/docs/components/progress) for measurable work, or any wait longer than about 10 seconds.
+
+### Keep Them in Line With Text
+
+The dots render as an inline `span`, aligned to the middle of the line in the current text color.
+
+**Do:** Put the dots after the words that describe the wait.
+
+```tsx
+/**
+ * Do example for "Keep Them in Line With Text" on the LoadingDots page.
+ * Put the dots after the words that describe the wait.
+ * @module
+ */
+import { LoadingDots, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.text()}>
+      Estimating network fee <LoadingDots aria-label="Estimating network fee" size="small" />
+    </div>
+  )
+}
+
+namespace styles {
+  export const text = style({ color: 'content.secondary', typography: 'body.b2' })
+}
+```
+
+**Don't:** Fill an empty card with dots in place of its content.
+
+```tsx
+/**
+ * Don't example for "Keep Them in Line With Text" on the LoadingDots page.
+ * Don't fill an empty card with dots in place of its content.
+ * @module
+ */
+import { LoadingDots, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.card()}>
+      <div {...styles.title()}>Activity</div>
+      <div {...styles.body()}>
+        <LoadingDots size="large" />
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const body = style({
+    alignItems: 'center',
+    display: 'flex',
+    height: '100',
+    justifyContent: 'center',
+  })
+
+  export const card = style({
+    borderColor: 'line.secondary',
+    borderRadius: 'xs',
+    borderStyle: 'solid',
+    borderWidth: 'regular',
+    boxSizing: 'border-box',
+    padding: '16',
+    width: '100% !custom',
+  })
+
+  export const title = style({ color: 'content.primary', typography: 'body.b2Strong' })
+}
+```
+
+### Show Them Only After a Delay
+
+* **Fast Responses (Under 300 ms):** Show no dots. Render the value when it arrives.
+* **Longer Waits (Over 300 ms):** Show the dots after the delay, to avoid a flash.
+
+### Replace Them With the Result
+
+Keep the text length stable so the line does not reflow. If loading fails, show an error message in place of the dots.
+
+**Do:** Replace the dots with the value when loading finishes.
+
+```tsx
+/**
+ * Do example for "Replace Them With the Result" on the LoadingDots page.
+ * Replace the dots with the value when loading finishes.
+ * @module
+ */
+import { style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return <div {...styles.text()}>Network fee: $0.01</div>
+}
+
+namespace styles {
+  export const text = style({ color: 'content.secondary', typography: 'body.b2' })
+}
+```
+
+**Don't:** Leave the dots beside the value after it arrives.
+
+```tsx
+/**
+ * Don't example for "Replace Them With the Result" on the LoadingDots page.
+ * Don't leave the dots beside the value after it arrives.
+ * @module
+ */
+import { LoadingDots, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.text()}>
+      Network fee: $0.01 <LoadingDots aria-label="Estimating network fee" size="small" />
+    </div>
+  )
+}
+
+namespace styles {
+  export const text = style({ color: 'content.secondary', typography: 'body.b2' })
+}
+```
+
+### Size Them to the Text
+
+* **Small (small):** Dense text, such as table cells.
+* **Medium (medium):** The default, beside body text.
+* **Large (large):** Beside larger values or headings.
+
+## Accessibility
+
+LoadingDots renders a polite live region named "Loading". The dots carry no text.
+
+### Semantics
+
+* **Root (status):** Announced politely as "Loading" by default, after current speech.
+* **Custom Name (aria-label):** Replaces the default "Loading" name with a more specific one.
+* **Reduced Motion (reduce):** If the reader prefers reduced motion, the dots hold still at reduced opacity.
+
+### Your Responsibilities
+
+* **Say What Is Loading (aria-label):** Name it, such as "Estimating network fee", when "Loading" is too vague.
+* **Keep Visible Text:** The dots are not focusable, and the accessible name is not visible. Keep text beside them.
+* **Show One per Region:** Many status regions at once, such as one per table row, repeat the announcement.
+* **Announce the Outcome (SC 4.1.3):** Announce the result or error in a live region when loading finishes.
+
+## Related
+
+[Spinner](/docs/components/spinner)
+
+Use for a busy region or control.
+
+[Skeleton](/docs/components/skeleton)
+
+Use for content with a known shape.
+
+[Button](/docs/components/button)
+
+Use for an action's loading state.
+
+[Loading](/docs/patterns/loading)
+
+Covers choosing a loading indicator.