@tempoxyz/ds 0.3.9 → 0.3.11

package/dist/docs/components/field.md

@@ -0,0 +1,570 @@
+# Field
+
+Links a label, description, and error message to a control.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Field.tsx)
+
+## Overview
+
+A field links a label, description, and error message to the control inside it.
+
+## Examples
+
+### Basic
+
+```tsx
+import { Field, TextInput } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <Field.Root>
+      <Field.Label>Email</Field.Label>
+      <TextInput.Group>
+        <TextInput.Control placeholder="alice@example.com" type="email" />
+      </TextInput.Group>
+      <Field.Description>Used for receipts.</Field.Description>
+    </Field.Root>
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Field/Basic.tsx)
+
+### Invalid
+
+Set `invalid` to fill the control red and show a matching `Field.Error` in place of the description.
+
+```tsx
+import { Field, TextInput } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <Field.Root invalid>
+      <Field.Label>Invalid</Field.Label>
+      <TextInput.Group>
+        <TextInput.Control defaultValue="alice" type="email" />
+      </TextInput.Group>
+      <Field.Description>Used for receipts.</Field.Description>
+      <Field.Error match>Enter a valid email.</Field.Error>
+    </Field.Root>
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Field/Invalid.tsx)
+
+### Success
+
+Set `success` to end a text field with a check, and to set the description in the positive color.
+
+```tsx
+import { Field, TextInput } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <Field.Root success>
+      <Field.Label>Success</Field.Label>
+      <TextInput.Group>
+        <TextInput.Control defaultValue="alice@example.com" type="email" />
+      </TextInput.Group>
+    </Field.Root>
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Field/Success.tsx)
+
+### Secondary Label
+
+Put a `Field.SecondaryLabel` inside `Field.Label` for a qualifier at the end of the label row, such as Optional. It joins the control's accessible name.
+
+```tsx
+import { Field, style, TextInput } from '@tempoxyz/ds'
+
+export const fill = true
+export function Demo() {
+  return (
+    <Field.Root {...styles.field()}>
+      <Field.Label>
+        Memo <Field.SecondaryLabel>Optional</Field.SecondaryLabel>
+      </Field.Label>
+      <TextInput.Group>
+        <TextInput.Control placeholder="What is it for?" />
+      </TextInput.Group>
+      <Field.Description>Only you and Maya can see this</Field.Description>
+    </Field.Root>
+  )
+}
+
+namespace styles {
+  export const field = style({ maxWidth: '24rem !custom' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Field/SecondaryLabel.tsx)
+
+### Size
+
+Set `size` to `medium` (default) or `large`. A large field sets the label in the regular weight with its secondary label beside it, sets the description at 14px, and insets a text field or textarea 20px.
+
+```tsx
+import { Field, style, Textarea, TextInput } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <div {...styles.grid()}>
+      <Field.Root size="large">
+        <Field.Label>
+          Display name<Field.SecondaryLabel>Optional</Field.SecondaryLabel>
+        </Field.Label>
+        <TextInput.Group>
+          <TextInput.Control placeholder="Maya Chen" />
+        </TextInput.Group>
+        <Field.Description>Shown to people you pay</Field.Description>
+      </Field.Root>
+      <Field.Root size="large">
+        <Field.Label>
+          Bio<Field.SecondaryLabel>Optional</Field.SecondaryLabel>
+        </Field.Label>
+        <Textarea placeholder="A few words about you" rows={2} />
+        <Field.Description>Up to 160 characters</Field.Description>
+      </Field.Root>
+    </div>
+  )
+}
+
+namespace styles {
+  export const grid = style({
+    alignItems: 'start',
+    display: 'grid',
+    gap: '24',
+    gridTemplateColumns: 'repeat(auto-fill, minmax(min(280px, 100%), 1fr)) !custom',
+  })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Field/Size.tsx)
+
+### Disabled
+
+```tsx
+import { Field, TextInput } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <Field.Root disabled>
+      <Field.Label>Disabled</Field.Label>
+      <TextInput.Group>
+        <TextInput.Control defaultValue="Locked" />
+      </TextInput.Group>
+    </Field.Root>
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Field/Disabled.tsx)
+
+### Item
+
+Wrap a checkbox or radio and its `Field.Label` in `Field.Item` to put them on one row.
+
+```tsx
+import { Checkbox, Field } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <Field.Root>
+      <Field.Item>
+        <Checkbox defaultChecked />
+        <Field.Label>Item with a checkbox</Field.Label>
+      </Field.Item>
+    </Field.Root>
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Field/Item.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { Field } from '@tempoxyz/ds'
+
+<Field.Root>
+  <Field.Label>
+    <Field.SecondaryLabel />
+  </Field.Label>
+  <Field.Item />
+  <Field.Description />
+  <Field.Error />
+</Field.Root>
+```
+
+## Guidelines
+
+### When to Use
+
+* Label an input control, such as [TextInput](/docs/components/text-input), [AmountInput](/docs/components/amount-input), [Textarea](/docs/components/textarea), [Select](/docs/components/select), or [Combobox](/docs/components/combobox).
+* Attach a hint or an error to that control.
+* Put a [Checkbox](/docs/components/checkbox) or radio on one row with its label through `Field.Item`.
+* Label a [Switch](/docs/components/switch) above it, with its description below.
+
+### When Not to Use
+
+* Use [Fieldset](/docs/components/fieldset) to name a group of related fields, such as a billing address.
+* Use [ListGroup](/docs/components/list-group) for read-only details.
+* Use an [Alert](/docs/components/alert) above the form to summarize a failed submission.
+
+### Give Every Control a Visible Label
+
+**Do:** Name the control with a `Field.Label` and put the format in the description.
+
+```tsx
+/**
+ * Do example for "Give Every Control a Visible Label" on the Field page.
+ * Name the control with a `Field.Label` and put the format in the description.
+ * @module
+ */
+import { Field, style, TextInput } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Field.Root {...styles.field()}>
+      <Field.Label>Recipient</Field.Label>
+      <TextInput.Group>
+        <TextInput.Control placeholder="0x…" />
+      </TextInput.Group>
+      <Field.Description>A Tempo address that starts with 0x.</Field.Description>
+    </Field.Root>
+  )
+}
+
+namespace styles {
+  export const field = style({ width: '100% !custom' })
+}
+```
+
+**Don't:** Use the placeholder as the only label.
+
+```tsx
+/**
+ * Don't example for "Give Every Control a Visible Label" on the Field page.
+ * Don't use the placeholder as the only label.
+ * @module
+ */
+import { style, TextInput } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <TextInput.Group {...styles.group()}>
+      <TextInput.Control aria-label="Recipient" placeholder="Recipient address" />
+    </TextInput.Group>
+  )
+}
+
+namespace styles {
+  export const group = style({ width: '100% !custom' })
+}
+```
+
+### Keep Hints in the Description
+
+Use `Field.Description` for one fact about the value, such as a format or a limit. Keep the label to the name of the value.
+
+**Do:** Put the limit in `Field.Description` below the control.
+
+```tsx
+/**
+ * Do example for "Keep Hints in the Description" on the Field page.
+ * Put the limit in `Field.Description` below the control.
+ * @module
+ */
+import { Field, style, TextInput } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Field.Root {...styles.field()}>
+      <Field.Label>Key name</Field.Label>
+      <TextInput.Group>
+        <TextInput.Control defaultValue="Payroll server" />
+      </TextInput.Group>
+      <Field.Description>Up to 32 letters, numbers, or spaces.</Field.Description>
+    </Field.Root>
+  )
+}
+
+namespace styles {
+  export const field = style({ width: '100% !custom' })
+}
+```
+
+**Don't:** Pack formats and limits into the label.
+
+```tsx
+/**
+ * Don't example for "Keep Hints in the Description" on the Field page.
+ * Don't pack formats and limits into the label.
+ * @module
+ */
+import { Field, style, TextInput } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Field.Root {...styles.field()}>
+      <Field.Label>Key name (up to 32 letters, numbers, or spaces)</Field.Label>
+      <TextInput.Group>
+        <TextInput.Control defaultValue="Payroll server" />
+      </TextInput.Group>
+    </Field.Root>
+  )
+}
+
+namespace styles {
+  export const field = style({ width: '100% !custom' })
+}
+```
+
+### Write Errors That Say How to Fix the Value
+
+Start the `Field.Error` with a verb, such as Enter or Choose, and include the limit, such as Enter an amount up to 250.00 USDC. A shown error replaces the description, so repeat any limit the error depends on.
+
+**Do:** Say what the value needs, such as the https\:// scheme.
+
+```tsx
+/**
+ * Do example for "Write Errors That Say How to Fix the Value" on the Field page.
+ * Say what the value needs, such as the https:// scheme.
+ * @module
+ */
+import { Field, style, TextInput } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Field.Root invalid {...styles.field()}>
+      <Field.Label>Webhook URL</Field.Label>
+      <TextInput.Group>
+        <TextInput.Control defaultValue="http://api.example.com/hooks" type="url" />
+      </TextInput.Group>
+      <Field.Error match>Enter a URL that starts with https://.</Field.Error>
+    </Field.Root>
+  )
+}
+
+namespace styles {
+  export const field = style({ width: '100% !custom' })
+}
+```
+
+**Don't:** Show a generic message such as Invalid input.
+
+```tsx
+/**
+ * Don't example for "Write Errors That Say How to Fix the Value" on the Field page.
+ * Don't show a generic message such as Invalid input.
+ * @module
+ */
+import { Field, style, TextInput } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Field.Root invalid {...styles.field()}>
+      <Field.Label>Webhook URL</Field.Label>
+      <TextInput.Group>
+        <TextInput.Control defaultValue="http://api.example.com/hooks" type="url" />
+      </TextInput.Group>
+      <Field.Error match>Invalid input.</Field.Error>
+    </Field.Root>
+  )
+}
+
+namespace styles {
+  export const field = style({ width: '100% !custom' })
+}
+```
+
+### Validate When the Value Is Complete
+
+`Field.Root` validates on submit, then on each change after a failed submit. For format checks, such as a URL, set `validationMode="onBlur"`. Pass `validate` for custom rules. If another library owns validation, set `invalid`. See [Errors and Validation](/docs/patterns/errors-and-validation).
+
+**Do:** Leave a partial value unmarked until focus leaves the field.
+
+```tsx
+/**
+ * Do example for "Validate When the Value Is Complete" on the Field page.
+ * Leave a partial value unmarked until focus leaves the field.
+ * @module
+ */
+import { Field, style, TextInput } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Field.Root validationMode="onBlur" {...styles.field()}>
+      <Field.Label>Webhook URL</Field.Label>
+      <TextInput.Group>
+        <TextInput.Control defaultValue="https://api.exa" type="url" />
+      </TextInput.Group>
+      <Field.Description>Starts with https://.</Field.Description>
+    </Field.Root>
+  )
+}
+
+namespace styles {
+  export const field = style({ width: '100% !custom' })
+}
+```
+
+**Don't:** Flag a format error before the value is complete.
+
+```tsx
+/**
+ * Don't example for "Validate When the Value Is Complete" on the Field page.
+ * Don't flag a format error before the value is complete.
+ * @module
+ */
+import { Field, style, TextInput } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Field.Root invalid {...styles.field()}>
+      <Field.Label>Webhook URL</Field.Label>
+      <TextInput.Group>
+        <TextInput.Control defaultValue="https://api.exa" type="url" />
+      </TextInput.Group>
+      <Field.Error match>Enter a URL that starts with https://.</Field.Error>
+    </Field.Root>
+  )
+}
+
+namespace styles {
+  export const field = style({ width: '100% !custom' })
+}
+```
+
+### Reserve Success for Verified Values
+
+Set `success` only after the app checks the value, such as an address that resolves to a contact. It sets no ARIA state, so state the result in the description too.
+
+**Do:** Mark only the checked value, and state the result in the description.
+
+```tsx
+/**
+ * Do example for "Reserve Success for Verified Values" on the Field page.
+ * Mark only the checked value, and state the result in the description.
+ * @module
+ */
+import { Field, style, TextInput } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.form()}>
+      <Field.Root success>
+        <Field.Label>Recipient address</Field.Label>
+        <TextInput.Group>
+          <TextInput.Control defaultValue="0x8f3a…12c4" />
+        </TextInput.Group>
+        <Field.Description>Matches your contact Alice Chen.</Field.Description>
+      </Field.Root>
+      <Field.Root>
+        <Field.Label>Memo</Field.Label>
+        <TextInput.Group>
+          <TextInput.Control defaultValue="Rent for May" />
+        </TextInput.Group>
+      </Field.Root>
+    </div>
+  )
+}
+
+namespace styles {
+  export const form = style({ display: 'grid', gap: '16', width: '100% !custom' })
+}
+```
+
+**Don't:** Mark every filled field successful.
+
+```tsx
+/**
+ * Don't example for "Reserve Success for Verified Values" on the Field page.
+ * Don't turn every filled field green.
+ * @module
+ */
+import { Field, style, TextInput } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.form()}>
+      <Field.Root success>
+        <Field.Label>Recipient address</Field.Label>
+        <TextInput.Group>
+          <TextInput.Control defaultValue="0x8f3a…12c4" />
+        </TextInput.Group>
+      </Field.Root>
+      <Field.Root success>
+        <Field.Label>Memo</Field.Label>
+        <TextInput.Group>
+          <TextInput.Control defaultValue="Rent for May" />
+        </TextInput.Group>
+      </Field.Root>
+    </div>
+  )
+}
+
+namespace styles {
+  export const form = style({ display: 'grid', gap: '16', width: '100% !custom' })
+}
+```
+
+## Accessibility
+
+A field connects a control to its label, description, and error. See [Accessibility](/docs/foundations/accessibility) for the baseline.
+
+### Semantics
+
+* **Field.Label (label):** Names the control. A click focuses or toggles it.
+* **Field.Description (aria-describedby):** Read after the control's name.
+* **Field.Error (aria-describedby):** Once shown, read after the description.
+* **Invalid State (aria-invalid):** Set on failed validation or `invalid`.
+* **Disabled (disabled):** Disables the control and dims the label and description.
+* **Field.Item:** Labels one checkbox or radio inside a group.
+
+### Your Responsibilities
+
+* **Label Every Control (Field.Label):** A placeholder disappears once the reader types, so it can't replace a label.
+* **Explain the Fix:** State the fix in the error, not only the problem, such as "Enter an email address."
+* **Focus the First Error:** The error is not a live region. If a submit fails, focus the first invalid field.
+* **Confirm Success in Text (success):** The `success` check sets no ARIA state and isn't announced. Confirm a verified value in text.
+* **State Requirements:** State requirements and formats in text, such as "(required)" in the label, not only with a symbol.
+* **Label a Date Picker Trigger (aria-labelledby):** `Field.Label` doesn't name a [DatePicker](/docs/components/date-picker) trigger. Point `aria-labelledby` at a visible label.
+
+## Related
+
+[TextInput](/docs/components/text-input)
+
+Use for single-line text.
+
+[Fieldset](/docs/components/fieldset)
+
+Use for grouping fields under a legend.
+
+[Textarea](/docs/components/textarea)
+
+Use for multi-line text.
+
+[Forms](/docs/patterns/forms)
+
+Covers laying out and submitting forms.
+
+[Errors and Validation](/docs/patterns/errors-and-validation)
+
+Covers when and how to show errors.