@tempoxyz/ds 0.3.10 → 0.3.11

package/dist/docs/components/slider.md

@@ -0,0 +1,539 @@
+# Slider
+
+Picks a single value or a range by dragging.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Slider.tsx)
+
+## Overview
+
+Slider renders a horizontal control for a single value or a range, with one `Slider.Thumb` per value.
+
+## Examples
+
+### Basic
+
+```tsx
+import { Slider, style } from '@tempoxyz/ds'
+import { useState } from 'react'
+
+export const fill = true
+export function Demo() {
+  const [amount, setAmount] = useState(40)
+
+  return (
+    <Slider.Root aria-label="Amount" onValueChange={setAmount} value={amount} {...styles.root()}>
+      <div {...styles.header()}>
+        <span>Amount</span>
+        <Slider.Value />
+      </div>
+      <Slider.Control>
+        <Slider.Track>
+          <Slider.Indicator />
+          <Slider.Thumb aria-label="Amount" />
+        </Slider.Track>
+      </Slider.Control>
+    </Slider.Root>
+  )
+}
+
+namespace styles {
+  export const header = style({
+    display: 'flex',
+    justifyContent: 'space-between',
+    marginBottom: '8',
+  })
+
+  export const root = style({ maxWidth: '360px !custom' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Slider/Basic.tsx)
+
+### Range
+
+Pass an array to `defaultValue` or `value` and add one `Slider.Thumb` per value, each with its `index`.
+
+```tsx
+import { Slider, style } from '@tempoxyz/ds'
+
+export const fill = true
+export function Demo() {
+  return (
+    <Slider.Root aria-label="Range" defaultValue={[20, 70]} {...styles.root()}>
+      <Slider.Control>
+        <Slider.Track>
+          <Slider.Indicator />
+          <Slider.Thumb aria-label="Minimum" index={0} />
+          <Slider.Thumb aria-label="Maximum" index={1} />
+        </Slider.Track>
+      </Slider.Control>
+    </Slider.Root>
+  )
+}
+
+namespace styles {
+  export const root = style({ maxWidth: '360px !custom' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Slider/Range.tsx)
+
+### Disabled
+
+Set `disabled` to lock the slider at its current value.
+
+```tsx
+import { Slider, style } from '@tempoxyz/ds'
+
+export const fill = true
+export function Demo() {
+  return (
+    <Slider.Root aria-label="Locked" defaultValue={60} disabled {...styles.root()}>
+      <Slider.Control>
+        <Slider.Track>
+          <Slider.Indicator />
+          <Slider.Thumb aria-label="Locked" />
+        </Slider.Track>
+      </Slider.Control>
+    </Slider.Root>
+  )
+}
+
+namespace styles {
+  export const root = style({ maxWidth: '360px !custom' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Slider/Disabled.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { Slider } from '@tempoxyz/ds'
+
+<Slider.Root>
+  <Slider.Value />
+  <Slider.Control>
+    <Slider.Track>
+      <Slider.Indicator />
+      <Slider.Thumb />
+    </Slider.Track>
+  </Slider.Control>
+</Slider.Root>
+```
+
+## Guidelines
+
+### When to Use
+
+* Set a value where position matters more than the exact number, such as a benchmark's target load.
+* Pick a range with two thumbs, such as the block heights on a chart.
+* Preview a setting live, such as a chart's moving-average window.
+
+### When Not to Use
+
+* Use [AmountInput](/docs/components/amount-input) for amounts and [NumberField](/docs/components/number-field) for exact counts.
+* Use [ChoiceGroup](/docs/components/choice-group) for a few presets, such as 25%, 50%, and Max.
+* Use [Progress](/docs/components/progress) or [Gauge](/docs/components/gauge) for a value that people cannot change.
+
+### Always Show the Value
+
+**Do:** Show the current value and its unit beside the label.
+
+```tsx
+/**
+ * Do example for "Always Show the Value" on the Slider page.
+ * Show the current value and its unit beside the label.
+ * @module
+ */
+import { Slider, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Slider.Root
+      aria-labelledby="guideline-target-load"
+      defaultValue={4000}
+      max={10000}
+      step={500}
+      {...styles.root()}
+    >
+      <div {...styles.header()}>
+        <span id="guideline-target-load">Target load</span>
+        <span>
+          <Slider.Value /> TPS
+        </span>
+      </div>
+      <Slider.Control>
+        <Slider.Track>
+          <Slider.Indicator />
+          <Slider.Thumb />
+        </Slider.Track>
+      </Slider.Control>
+    </Slider.Root>
+  )
+}
+
+namespace styles {
+  export const header = style({
+    display: 'flex',
+    justifyContent: 'space-between',
+    marginBottom: '8',
+    typography: 'body.b2',
+  })
+
+  export const root = style({ maxWidth: '18rem !custom', width: '100% !custom' })
+}
+```
+
+**Don't:** Show a slider without its value.
+
+```tsx
+/** Don't example for "Always Show the Value" on the Slider page. Don't show a slider without its value. @module */
+import { Slider, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Slider.Root
+      aria-labelledby="guideline-target-load-hidden"
+      defaultValue={4000}
+      max={10000}
+      step={500}
+      {...styles.root()}
+    >
+      <div {...styles.header()}>
+        <span id="guideline-target-load-hidden">Target load</span>
+      </div>
+      <Slider.Control>
+        <Slider.Track>
+          <Slider.Indicator />
+          <Slider.Thumb />
+        </Slider.Track>
+      </Slider.Control>
+    </Slider.Root>
+  )
+}
+
+namespace styles {
+  export const header = style({ marginBottom: '8', typography: 'body.b2' })
+
+  export const root = style({ maxWidth: '18rem !custom', width: '100% !custom' })
+}
+```
+
+`Slider.Value` renders an `<output>` with tabular figures, so the label does not shift. Format it with `format` and `locale` on `Slider.Root`, or pass a function as `children`.
+
+### Pair With an Input for Exact Values
+
+Some people cannot drag. Where precision matters, add a [NumberField](/docs/components/number-field) beside the slider.
+
+**Do:** Share one value between the slider and the input.
+
+```tsx
+/**
+ * Do example for "Pair With an Input for Exact Values" on the Slider page.
+ * Share one value between the slider and the input.
+ * @module
+ */
+import { NumberField, Slider, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.root()}>
+      <span {...styles.label()}>Target load (TPS)</span>
+      <div {...styles.row()}>
+        <Slider.Root
+          aria-label="Target load"
+          defaultValue={4000}
+          max={10000}
+          step={500}
+          {...styles.slider()}
+        >
+          <Slider.Control>
+            <Slider.Track>
+              <Slider.Indicator />
+              <Slider.Thumb />
+            </Slider.Track>
+          </Slider.Control>
+        </Slider.Root>
+        <NumberField.Root defaultValue={4000} max={10000} min={0} step={500} {...styles.number()}>
+          <NumberField.Group>
+            <NumberField.Input aria-label="Target load" />
+          </NumberField.Group>
+        </NumberField.Root>
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const label = style({ typography: 'body.b2' })
+
+  // The root keeps its full width, so a maximum narrows it.
+  export const number = style({ maxWidth: '6rem !custom' })
+
+  export const root = style({
+    display: 'flex',
+    flexDirection: 'column',
+    gap: '8',
+    maxWidth: '20rem !custom',
+    width: '100% !custom',
+  })
+
+  export const row = style({ alignItems: 'center', display: 'flex', gap: '16' })
+
+  export const slider = style({ flexGrow: '1 !custom' })
+}
+```
+
+**Don't:** Let the slider and the input hold different values.
+
+```tsx
+/**
+ * Don't example for "Pair With an Input for Exact Values" on the Slider page.
+ * Don't let the slider and the input hold different values.
+ * @module
+ */
+import { NumberField, Slider, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.root()}>
+      <span {...styles.label()}>Target load (TPS)</span>
+      <div {...styles.row()}>
+        <Slider.Root
+          aria-label="Target load"
+          defaultValue={4000}
+          max={10000}
+          step={500}
+          {...styles.slider()}
+        >
+          <Slider.Control>
+            <Slider.Track>
+              <Slider.Indicator />
+              <Slider.Thumb />
+            </Slider.Track>
+          </Slider.Control>
+        </Slider.Root>
+        <NumberField.Root defaultValue={2500} max={10000} min={0} step={500} {...styles.number()}>
+          <NumberField.Group>
+            <NumberField.Input aria-label="Target load" />
+          </NumberField.Group>
+        </NumberField.Root>
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const label = style({ typography: 'body.b2' })
+
+  // The root keeps its full width, so a maximum narrows it.
+  export const number = style({ maxWidth: '6rem !custom' })
+
+  export const root = style({
+    display: 'flex',
+    flexDirection: 'column',
+    gap: '8',
+    maxWidth: '20rem !custom',
+    width: '100% !custom',
+  })
+
+  export const row = style({ alignItems: 'center', display: 'flex', gap: '16' })
+
+  export const slider = style({ flexGrow: '1 !custom' })
+}
+```
+
+### Choose a Range and Steps That Fit the Data
+
+* **`largeStep`:** Applies to Page Up and Page Down. Size it to cross the range in a few presses.
+* **Bounds:** If the label does not make them obvious, show them below the track.
+* **`minStepsBetweenValues`:** If an empty range is not valid, set it to keep the thumbs apart.
+
+**Do:** Set `min`, `max`, and `step` to values people think in, such as 500 TPS steps.
+
+```tsx
+/**
+ * Do example for "Choose a Range and Steps That Fit the Data" on the Slider page.
+ * Set `min`, `max`, and `step` to values people think in, such as 500 TPS steps.
+ * @module
+ */
+import { Slider, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Slider.Root
+      aria-label="Target load"
+      defaultValue={4000}
+      max={10000}
+      step={500}
+      {...styles.root()}
+    >
+      <div {...styles.header()}>
+        <span>Target load</span>
+        <span>
+          <Slider.Value /> TPS
+        </span>
+      </div>
+      <Slider.Control>
+        <Slider.Track>
+          <Slider.Indicator />
+          <Slider.Thumb />
+        </Slider.Track>
+      </Slider.Control>
+      <div {...styles.bounds()}>
+        <span>0</span>
+        <span>10,000</span>
+      </div>
+    </Slider.Root>
+  )
+}
+
+namespace styles {
+  export const bounds = style({
+    color: 'content.secondary',
+    display: 'flex',
+    justifyContent: 'space-between',
+    marginTop: '8',
+    typography: 'body.b3',
+  })
+
+  export const header = style({
+    display: 'flex',
+    justifyContent: 'space-between',
+    marginBottom: '8',
+    typography: 'body.b2',
+  })
+
+  export const root = style({ maxWidth: '18rem !custom', width: '100% !custom' })
+}
+```
+
+**Don't:** Use a step or bounds that produce values such as 4,137.
+
+```tsx
+/**
+ * Don't example for "Choose a Range and Steps That Fit the Data" on the Slider page.
+ * Don't use a step or bounds that produce values such as 4,137.
+ * @module
+ */
+import { Slider, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Slider.Root
+      aria-label="Target load"
+      defaultValue={4137}
+      max={10240}
+      step={1}
+      {...styles.root()}
+    >
+      <div {...styles.header()}>
+        <span>Target load</span>
+        <span>
+          <Slider.Value /> TPS
+        </span>
+      </div>
+      <Slider.Control>
+        <Slider.Track>
+          <Slider.Indicator />
+          <Slider.Thumb />
+        </Slider.Track>
+      </Slider.Control>
+      <div {...styles.bounds()}>
+        <span>0</span>
+        <span>10,240</span>
+      </div>
+    </Slider.Root>
+  )
+}
+
+namespace styles {
+  export const bounds = style({
+    color: 'content.secondary',
+    display: 'flex',
+    justifyContent: 'space-between',
+    marginTop: '8',
+    typography: 'body.b3',
+  })
+
+  export const header = style({
+    display: 'flex',
+    justifyContent: 'space-between',
+    marginBottom: '8',
+    typography: 'body.b2',
+  })
+
+  export const root = style({ maxWidth: '18rem !custom', width: '100% !custom' })
+}
+```
+
+### Commit Expensive Work on Release
+
+* **Every Movement (onValueChange):** Fires on every movement. Use it to update the visible value.
+* **Release (onValueCommitted):** Fires once when the drag, track press, or key press ends. Use it to refetch data or save.
+
+## Content
+
+* **Label:** Name the quantity, such as Target load. Show the unit with the value, such as 4,000 TPS.
+
+## Accessibility
+
+Slider accepts keyboard, pointer, and touch input. It follows the [WAI-ARIA Authoring Practices slider pattern](https://www.w3.org/WAI/ARIA/apg/patterns/slider/), and the [multi-thumb slider pattern](https://www.w3.org/WAI/ARIA/apg/patterns/slider-multithumb/) for a range.
+
+### Semantics
+
+* **Slider.Root (group):** Holds the thumbs as one named group.
+* **Slider.Thumb (input type=range):** Wraps a native range input, which holds the name and keyboard focus.
+* **Range Values (aria-valuetext):** Each range thumb reads as "20 start range" or "70 end range". `getAriaValueText` replaces it.
+* **Slider.Value (output):** Linked to its thumb, and silent during a drag.
+* **Disabled (disabled):** Locks every thumb and dims the slider. Explain why nearby.
+* **Size and Motion (24px):** The thumb grows slightly during a drag, except under reduced motion.
+
+### Keyboard
+
+* **Move to a Thumb (Tab):** Moves focus to each thumb in order.
+* **Increase by Step (Right Arrow or Up Arrow):** Increases the value by `step`.
+* **Decrease by Step (Left Arrow or Down Arrow):** Decreases the value by `step`.
+* **Increase by Large Step (Page Up or Shift+Right Arrow):** Increases the value by `largeStep`.
+* **Decrease by Large Step (Page Down or Shift+Left Arrow):** Decreases the value by `largeStep`.
+* **Set to Minimum (Home):** Sets the value to `min`.
+* **Set to Maximum (End):** Sets the value to `max`.
+
+In a range, a thumb stops at the other thumb's value.
+
+### Dragging
+
+Every drag has a single-press alternative ([SC 2.5.7](https://www.w3.org/WAI/WCAG22/Understanding/dragging-movements.html)). A press on `Slider.Control` moves the nearest thumb, and the keys above set any value.
+
+### Your Responsibilities
+
+* **Name Every Thumb (aria-label):** Label each thumb with `getAriaLabel` or a field label. A root `aria-label` names only the group.
+* **Name Range Thumbs by Role:** Label the thumbs by role, such as "Minimum" and "Maximum".
+* **Announce Units (getAriaValueText):** Announce the unit with each value, such as "20 percent".
+
+## Related
+
+[NumberField](/docs/components/number-field)
+
+Use for exact numbers.
+
+[ChoiceGroup](/docs/components/choice-group)
+
+Use for a few preset values.
+
+[Progress](/docs/components/progress)
+
+Use for showing progress you can't change.
+
+[Dashboards](/docs/patterns/dashboards)
+
+Covers chart controls and filters.