@tempoxyz/ds 0.3.9 → 0.3.11

package/dist/docs/components/number-field.md

@@ -0,0 +1,543 @@
+# NumberField
+
+A numeric input with increment and decrement buttons.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/NumberField.tsx)
+
+## Overview
+
+NumberField renders a numeric text input with decrement and increment buttons, for quantities adjusted in small steps.
+
+## Examples
+
+### Basic
+
+```tsx
+import { NumberField } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <NumberField.Root defaultValue={3}>
+      <NumberField.Group>
+        <NumberField.Decrement />
+        <NumberField.Input aria-label="Quantity" />
+        <NumberField.Increment />
+      </NumberField.Group>
+    </NumberField.Root>
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/NumberField/Basic.tsx)
+
+### Min
+
+Set `min` and `max` on `NumberField.Root` to bound the value.
+
+```tsx
+import { NumberField, style } from '@tempoxyz/ds'
+
+export const fill = true
+function Example(
+  props: Pick<NumberField.Root.Props, 'defaultValue' | 'disabled' | 'max' | 'min' | 'step'> &
+    Pick<NumberField.Group.Props, 'invalid'>,
+) {
+  const { invalid, ...root } = props
+
+  return (
+    <NumberField.Root {...root}>
+      <NumberField.Group invalid={invalid}>
+        <NumberField.Decrement />
+        <NumberField.Input aria-label="Quantity" />
+        <NumberField.Increment />
+      </NumberField.Group>
+    </NumberField.Root>
+  )
+}
+
+export function Demo() {
+  return (
+    <div {...styles.grid()}>
+      <Example defaultValue={0} min={0} />
+      <Example defaultValue={10} max={10} />
+    </div>
+  )
+}
+
+namespace styles {
+  export const grid = style({
+    alignItems: 'start',
+    display: 'grid',
+    gap: '12',
+    gridTemplateColumns: 'repeat(auto-fill, minmax(240px, 1fr)) !custom',
+    maxWidth: '520px !custom',
+  })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/NumberField/Min.tsx)
+
+### Invalid
+
+Set `invalid` on `NumberField.Group` to mark the value as rejected.
+
+```tsx
+import { NumberField, style } from '@tempoxyz/ds'
+
+export const fill = true
+function Example(
+  props: Pick<NumberField.Root.Props, 'defaultValue' | 'disabled' | 'max' | 'min' | 'step'> &
+    Pick<NumberField.Group.Props, 'invalid'>,
+) {
+  const { invalid, ...root } = props
+
+  return (
+    <NumberField.Root {...root}>
+      <NumberField.Group invalid={invalid}>
+        <NumberField.Decrement />
+        <NumberField.Input aria-label="Quantity" />
+        <NumberField.Increment />
+      </NumberField.Group>
+    </NumberField.Root>
+  )
+}
+
+export function Demo() {
+  return (
+    <div {...styles.grid()}>
+      <Example defaultValue={5} invalid />
+    </div>
+  )
+}
+
+namespace styles {
+  export const grid = style({
+    alignItems: 'start',
+    display: 'grid',
+    gap: '12',
+    gridTemplateColumns: 'repeat(auto-fill, minmax(240px, 1fr)) !custom',
+    maxWidth: '520px !custom',
+  })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/NumberField/Invalid.tsx)
+
+### Disabled
+
+Set `disabled` on `NumberField.Root` to make the field unavailable.
+
+```tsx
+import { NumberField, style } from '@tempoxyz/ds'
+
+export const fill = true
+function Example(
+  props: Pick<NumberField.Root.Props, 'defaultValue' | 'disabled' | 'max' | 'min' | 'step'> &
+    Pick<NumberField.Group.Props, 'invalid'>,
+) {
+  const { invalid, ...root } = props
+
+  return (
+    <NumberField.Root {...root}>
+      <NumberField.Group invalid={invalid}>
+        <NumberField.Decrement />
+        <NumberField.Input aria-label="Quantity" />
+        <NumberField.Increment />
+      </NumberField.Group>
+    </NumberField.Root>
+  )
+}
+
+export function Demo() {
+  return (
+    <div {...styles.grid()}>
+      <Example defaultValue={5} disabled />
+    </div>
+  )
+}
+
+namespace styles {
+  export const grid = style({
+    alignItems: 'start',
+    display: 'grid',
+    gap: '12',
+    gridTemplateColumns: 'repeat(auto-fill, minmax(240px, 1fr)) !custom',
+    maxWidth: '520px !custom',
+  })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/NumberField/Disabled.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { NumberField } from '@tempoxyz/ds'
+
+<NumberField.Root>
+  <NumberField.Group>
+    <NumberField.Decrement />
+    <NumberField.Input />
+    <NumberField.Increment />
+  </NumberField.Group>
+</NumberField.Root>
+```
+
+## Guidelines
+
+### When to Use
+
+* Enter a whole number that people nudge up or down, such as webhook retry attempts or block confirmations.
+* Set a bounded count, such as seats on a team plan or API keys per project.
+
+### When Not to Use
+
+* Use [AmountInput](/docs/components/amount-input) for token and fiat amounts.
+* Use [TextInput](/docs/components/text-input) for codes and identifiers that look numeric, such as a chain ID or a postal code.
+* Use [Slider](/docs/components/slider) when an approximate position matters more than the exact number.
+* Use [ChoiceGroup](/docs/components/choice-group) or [Select](/docs/components/select) when only a few values are valid, such as 1, 5, or 10 minutes.
+
+### State the Bounds and the Unit
+
+Set `min` and `max`, and state them in `Field.Description`, such as Between 0 and 10. Typed input does not show the range.
+
+Name the unit in the label, such as Timeout (seconds), or add it to the value with `format`. Format large numbers with `format` and `locale`, not hand-written separators.
+
+**Do:** Name the unit in the label and the range in the description.
+
+```tsx
+/**
+ * Do example for "State the Bounds and the Unit" on the NumberField page.
+ * Name the unit in the label and the range in the description.
+ * @module
+ */
+import { Field, NumberField, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Field.Root {...styles.field()}>
+      <Field.Label>Block confirmations</Field.Label>
+      <NumberField.Root defaultValue={2} max={12} min={1} {...styles.number()}>
+        <NumberField.Group>
+          <NumberField.Decrement />
+          <NumberField.Input />
+          <NumberField.Increment />
+        </NumberField.Group>
+      </NumberField.Root>
+      <Field.Description>Between 1 and 12.</Field.Description>
+    </Field.Root>
+  )
+}
+
+namespace styles {
+  export const field = style({ maxWidth: '18rem !custom', width: '100% !custom' })
+
+  // The root keeps its full width, so a maximum narrows it.
+  export const number = style({ maxWidth: '8rem !custom' })
+}
+```
+
+**Don't:** Leave people to find the bounds by stepping.
+
+```tsx
+/**
+ * Don't example for "State the Bounds and the Unit" on the NumberField page.
+ * Don't leave people to find the bounds by stepping.
+ * @module
+ */
+import { Field, NumberField, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Field.Root {...styles.field()}>
+      <Field.Label>Block confirmations</Field.Label>
+      <NumberField.Root defaultValue={2} max={12} min={1} {...styles.number()}>
+        <NumberField.Group>
+          <NumberField.Decrement />
+          <NumberField.Input />
+          <NumberField.Increment />
+        </NumberField.Group>
+      </NumberField.Root>
+    </Field.Root>
+  )
+}
+
+namespace styles {
+  export const field = style({ maxWidth: '18rem !custom', width: '100% !custom' })
+
+  // The root keeps its full width, so a maximum narrows it.
+  export const number = style({ maxWidth: '8rem !custom' })
+}
+```
+
+### Size the Field to the Number
+
+`NumberField.Root` fills its container. Set a `maxWidth` that fits the longest value, so the steppers stay close to the digits.
+
+**Do:** Size the field for a few digits and state the range below it.
+
+```tsx
+/**
+ * Do example for "Size the Field to the Number" on the NumberField page.
+ * Size the field for a few digits and state the range below it.
+ * @module
+ */
+import { Field, NumberField, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Field.Root {...styles.field()}>
+      <Field.Label>Retry attempts</Field.Label>
+      <NumberField.Root defaultValue={3} max={10} min={0} {...styles.number()}>
+        <NumberField.Group>
+          <NumberField.Decrement />
+          <NumberField.Input />
+          <NumberField.Increment />
+        </NumberField.Group>
+      </NumberField.Root>
+      <Field.Description>Between 0 and 10.</Field.Description>
+    </Field.Root>
+  )
+}
+
+namespace styles {
+  export const field = style({ maxWidth: '18rem !custom', width: '100% !custom' })
+
+  // The root keeps its full width, so a maximum narrows it.
+  export const number = style({ maxWidth: '8rem !custom' })
+}
+```
+
+**Don't:** Stretch a one-digit count across the form.
+
+```tsx
+/**
+ * Don't example for "Size the Field to the Number" on the NumberField page.
+ * Don't stretch a one-digit count across the form.
+ * @module
+ */
+import { Field, NumberField, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Field.Root {...styles.field()}>
+      <Field.Label>Retry attempts</Field.Label>
+      <NumberField.Root defaultValue={3} max={10} min={0}>
+        <NumberField.Group>
+          <NumberField.Decrement />
+          <NumberField.Input />
+          <NumberField.Increment />
+        </NumberField.Group>
+      </NumberField.Root>
+    </Field.Root>
+  )
+}
+
+namespace styles {
+  export const field = style({ maxWidth: '18rem !custom', width: '100% !custom' })
+}
+```
+
+### Pick Steps People Expect
+
+Set `step` to the increment the value moves in, such as 5 seconds for a timeout. Add `snapOnStep` to snap typed values to a multiple of the step. If a value has no natural step and spans a wide range, typing is faster than stepping.
+
+**Do:** Step a timeout in fives and say so in the description.
+
+```tsx
+/**
+ * Do example for "Pick Steps People Expect" on the NumberField page.
+ * Step a timeout in fives and say so in the description.
+ * @module
+ */
+import { Field, NumberField, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Field.Root {...styles.field()}>
+      <Field.Label>Timeout (seconds)</Field.Label>
+      <NumberField.Root defaultValue={30} max={60} min={5} step={5} {...styles.number()}>
+        <NumberField.Group>
+          <NumberField.Decrement />
+          <NumberField.Input />
+          <NumberField.Increment />
+        </NumberField.Group>
+      </NumberField.Root>
+      <Field.Description>Between 5 and 60, in steps of 5.</Field.Description>
+    </Field.Root>
+  )
+}
+
+namespace styles {
+  export const field = style({ maxWidth: '18rem !custom', width: '100% !custom' })
+
+  // The root keeps its full width, so a maximum narrows it.
+  export const number = style({ maxWidth: '8rem !custom' })
+}
+```
+
+**Don't:** Step by 1 through a range that people set in fives.
+
+```tsx
+/**
+ * Don't example for "Pick Steps People Expect" on the NumberField page.
+ * Don't step by 1 through a range that people set in fives.
+ * @module
+ */
+import { Field, NumberField, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Field.Root {...styles.field()}>
+      <Field.Label>Timeout (seconds)</Field.Label>
+      <NumberField.Root defaultValue={31} max={60} min={5} {...styles.number()}>
+        <NumberField.Group>
+          <NumberField.Decrement />
+          <NumberField.Input />
+          <NumberField.Increment />
+        </NumberField.Group>
+      </NumberField.Root>
+      <Field.Description>Between 5 and 60.</Field.Description>
+    </Field.Root>
+  )
+}
+
+namespace styles {
+  export const field = style({ maxWidth: '18rem !custom', width: '100% !custom' })
+
+  // The root keeps its full width, so a maximum narrows it.
+  export const number = style({ maxWidth: '8rem !custom' })
+}
+```
+
+### Avoid Silent Clamping
+
+A typed value outside `min` and `max` is clamped by default, so a typo such as 100 becomes 10.
+
+If a silent change would surprise people, set `allowOutOfRange` and explain the limit in `Field.Error`. Arrow keys and the steppers still clamp.
+
+**Do:** Keep the typed value and explain the limit.
+
+```tsx
+/**
+ * Do example for "Avoid Silent Clamping" on the NumberField page.
+ * Keep the typed value and explain the limit.
+ * @module
+ */
+import { Field, NumberField, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Field.Root invalid {...styles.field()}>
+      <Field.Label>Seats</Field.Label>
+      <NumberField.Root allowOutOfRange defaultValue={100} max={10} min={1} {...styles.number()}>
+        <NumberField.Group invalid>
+          <NumberField.Decrement />
+          <NumberField.Input />
+          <NumberField.Increment />
+        </NumberField.Group>
+      </NumberField.Root>
+      <Field.Error match>Choose up to 10 seats.</Field.Error>
+    </Field.Root>
+  )
+}
+
+namespace styles {
+  export const field = style({ maxWidth: '18rem !custom', width: '100% !custom' })
+
+  // The root keeps its full width, so a maximum narrows it.
+  export const number = style({ maxWidth: '8rem !custom' })
+}
+```
+
+**Don't:** Silently replace a typed 100 with the maximum of 10.
+
+```tsx
+/**
+ * Don't example for "Avoid Silent Clamping" on the NumberField page.
+ * Don't silently replace a typed 100 with the maximum of 10.
+ * @module
+ */
+import { Field, NumberField, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Field.Root {...styles.field()}>
+      <Field.Label>Seats</Field.Label>
+      <NumberField.Root defaultValue={10} max={10} min={1} {...styles.number()}>
+        <NumberField.Group>
+          <NumberField.Decrement />
+          <NumberField.Input />
+          <NumberField.Increment />
+        </NumberField.Group>
+      </NumberField.Root>
+    </Field.Root>
+  )
+}
+
+namespace styles {
+  export const field = style({ maxWidth: '18rem !custom', width: '100% !custom' })
+
+  // The root keeps its full width, so a maximum narrows it.
+  export const number = style({ maxWidth: '8rem !custom' })
+}
+```
+
+## Accessibility
+
+The keyboard follows the [WAI-ARIA Authoring Practices spinbutton pattern](https://www.w3.org/WAI/ARIA/apg/patterns/spinbutton/).
+
+### Semantics
+
+* **NumberField.Group (group):** Groups the input and its steppers.
+* **NumberField.Input (textbox):** A text input with a numeric keyboard, announced as a number field.
+* **Animated Digits (aria-hidden):** Screen readers skip them and read only the input's value.
+* **NumberField.Decrement and NumberField.Increment (button):** Labelled "Decrease" and "Increase". They stay out of the tab order, since arrow keys do the same.
+* **Limits (min and max):** A stepper is disabled once the value reaches its limit.
+* **Invalid (data-invalid):** `invalid` on the group only fills it red. It sets no ARIA state.
+
+### Keyboard
+
+* **Move Focus to the TextInput (Tab):** Focuses the input but skips the stepper buttons.
+* **Step the Value (Up or Down Arrow):** Increases or decreases the value by `step`.
+* **Take a Large Step (Shift+Arrow):** Steps by `largeStep`, which defaults to 10.
+* **Take a Small Step (Alt+Arrow):** Steps by `smallStep`, which defaults to 0.1.
+* **Jump to a Limit (Home or End):** Sets the value to `min` or `max`, when defined.
+
+### Size and Motion
+
+* **Stepper Size (40px):** Steppers sit 4px inside the 48px field, above the 24px WCAG minimum.
+* **Reduced Motion (reduce):** If the reader prefers reduced motion, the value morph turns off.
+
+### Your Responsibilities
+
+* **Name the TextInput (aria-label):** Use a field label. Without a visible label, set an `aria-label` such as "Quantity".
+* **Mark Invalid Values (aria-invalid):** Set `invalid` on the field, not the group, and explain the problem in an error message.
+
+## Related
+
+[AmountInput](/docs/components/amount-input)
+
+Use for token and fiat amounts.
+
+[TextInput](/docs/components/text-input)
+
+Use for codes and identifiers.
+
+[Slider](/docs/components/slider)
+
+Use for approximate values in a range.
+
+[Field](/docs/components/field)
+
+Use for labels, descriptions, and errors.