@tempoxyz/ds 0.3.10 → 0.3.13

package/dist/docs/product/components/fieldset.md

@@ -0,0 +1,398 @@
+# Fieldset
+
+Groups related fields under a shared legend.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Fieldset.tsx)
+
+## Overview
+
+A fieldset groups related fields under a legend in a native `<fieldset>`.
+
+## Examples
+
+### Basic
+
+```tsx
+import { Field, Fieldset, style, TextInput } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <Fieldset.Root {...styles.group()}>
+      <Fieldset.Legend>Legal name</Fieldset.Legend>
+      <Name label="First name" />
+      <Name label="Last name" />
+    </Fieldset.Root>
+  )
+}
+
+function Name(props: { label: string }) {
+  return (
+    <Field.Root>
+      <Field.Label>{props.label}</Field.Label>
+      <TextInput.Group>
+        <TextInput.Control />
+      </TextInput.Group>
+    </Field.Root>
+  )
+}
+
+namespace styles {
+  export const group = style({ maxWidth: '100% !custom', width: '320px !custom' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Fieldset/Basic.tsx)
+
+### Disabled
+
+Set `disabled` to disable every control in the group.
+
+```tsx
+import { Field, Fieldset, style, TextInput } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <Fieldset.Root disabled {...styles.group()}>
+      <Fieldset.Legend>Legal name</Fieldset.Legend>
+      <Field.Root>
+        <Field.Label>First name</Field.Label>
+        <TextInput.Group>
+          <TextInput.Control />
+        </TextInput.Group>
+      </Field.Root>
+      <Field.Root>
+        <Field.Label>Last name</Field.Label>
+        <TextInput.Group>
+          <TextInput.Control />
+        </TextInput.Group>
+      </Field.Root>
+    </Fieldset.Root>
+  )
+}
+
+namespace styles {
+  export const group = style({ maxWidth: '100% !custom', width: '320px !custom' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Fieldset/Disabled.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { Field, Fieldset } from '@tempoxyz/ds'
+
+<Fieldset.Root>
+  <Fieldset.Legend />
+  <Field.Root />
+</Fieldset.Root>
+```
+
+## Guidelines
+
+### When to Use
+
+* Group fields that describe one thing, such as an address.
+* Name a set of radios or checkboxes with one question.
+
+### When Not to Use
+
+* Use [Field](field.md) alone for a single control. A fieldset around one field repeats its label.
+* Use a heading for a page section with no form controls.
+* Use [Stepper](stepper.md) to split a long form into steps, not many fieldsets on one screen.
+
+### Write the Legend as the Group's Topic
+
+* **Radio group:** Write a question that ends with a question mark, such as How often should we pay you?
+* **Set of fields:** Write a noun without a colon, such as Billing address.
+
+Keep each field's own `Field.Label`, and don't repeat the legend in it.
+
+**Do:** Name the group in the legend and each value in its label.
+
+```tsx
+/**
+ * Do example for "Write the Legend as the Group's Topic" on the Fieldset page.
+ * Name the group in the legend and each value in its label.
+ * @module
+ */
+import { Field, Fieldset, style, TextInput } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Fieldset.Root {...styles.group()}>
+      <Fieldset.Legend>Billing address</Fieldset.Legend>
+      <Field.Root>
+        <Field.Label>Street</Field.Label>
+        <TextInput.Group>
+          <TextInput.Control defaultValue="350 Mission St" />
+        </TextInput.Group>
+      </Field.Root>
+      <Field.Root>
+        <Field.Label>City</Field.Label>
+        <TextInput.Group>
+          <TextInput.Control defaultValue="San Francisco" />
+        </TextInput.Group>
+      </Field.Root>
+    </Fieldset.Root>
+  )
+}
+
+namespace styles {
+  export const group = style({ maxWidth: '320px !custom', rowGap: '12', width: '100% !custom' })
+}
+```
+
+**Don't:** Repeat the legend in every field label.
+
+```tsx
+/**
+ * Don't example for "Write the Legend as the Group's Topic" on the Fieldset page.
+ * Don't repeat the legend in every field label.
+ * @module
+ */
+import { Field, Fieldset, style, TextInput } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Fieldset.Root {...styles.group()}>
+      <Fieldset.Legend>Billing address</Fieldset.Legend>
+      <Field.Root>
+        <Field.Label>Billing address street</Field.Label>
+        <TextInput.Group>
+          <TextInput.Control defaultValue="350 Mission St" />
+        </TextInput.Group>
+      </Field.Root>
+      <Field.Root>
+        <Field.Label>Billing address city</Field.Label>
+        <TextInput.Group>
+          <TextInput.Control defaultValue="San Francisco" />
+        </TextInput.Group>
+      </Field.Root>
+    </Fieldset.Root>
+  )
+}
+
+namespace styles {
+  export const group = style({ maxWidth: '320px !custom', rowGap: '12', width: '100% !custom' })
+}
+```
+
+### Disable the Group, Not Each Field
+
+Set `disabled` on `Fieldset.Root` to disable every control inside. State the reason above the group, such as Billing details are locked while a payment is pending.
+
+**Do:** Disable the fieldset and say why above it.
+
+```tsx
+/**
+ * Do example for "Disable the Group, Not Each Field" on the Fieldset page.
+ * Disable the fieldset and say why above it.
+ * @module
+ */
+import { Field, Fieldset, style, TextInput } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.stack()}>
+      <p {...styles.reason()}>Billing details are locked while a payment is pending.</p>
+      <Fieldset.Root disabled {...styles.group()}>
+        <Fieldset.Legend>Billing address</Fieldset.Legend>
+        <Field.Root>
+          <Field.Label>Street</Field.Label>
+          <TextInput.Group>
+            <TextInput.Control defaultValue="350 Mission St" />
+          </TextInput.Group>
+        </Field.Root>
+        <Field.Root>
+          <Field.Label>City</Field.Label>
+          <TextInput.Group>
+            <TextInput.Control defaultValue="San Francisco" />
+          </TextInput.Group>
+        </Field.Root>
+      </Fieldset.Root>
+    </div>
+  )
+}
+
+namespace styles {
+  export const group = style({ rowGap: '12', width: '100% !custom' })
+
+  export const reason = style({ color: 'content.secondary', margin: '0', typography: 'body.b2' })
+
+  export const stack = style({
+    display: 'grid',
+    gap: '16',
+    maxWidth: '320px !custom',
+    width: '100% !custom',
+  })
+}
+```
+
+**Don't:** Disable a group without a reason.
+
+```tsx
+/**
+ * Don't example for "Disable the Group, Not Each Field" on the Fieldset page.
+ * Don't disable a group without a reason.
+ * @module
+ */
+import { Field, Fieldset, style, TextInput } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Fieldset.Root disabled {...styles.group()}>
+      <Fieldset.Legend>Billing address</Fieldset.Legend>
+      <Field.Root>
+        <Field.Label>Street</Field.Label>
+        <TextInput.Group>
+          <TextInput.Control defaultValue="350 Mission St" />
+        </TextInput.Group>
+      </Field.Root>
+      <Field.Root>
+        <Field.Label>City</Field.Label>
+        <TextInput.Group>
+          <TextInput.Control defaultValue="San Francisco" />
+        </TextInput.Group>
+      </Field.Root>
+    </Fieldset.Root>
+  )
+}
+
+namespace styles {
+  export const group = style({ maxWidth: '320px !custom', rowGap: '12', width: '100% !custom' })
+}
+```
+
+### Keep Groups Flat and Short
+
+Screen readers announce every legend of nested fieldsets as focus moves in. Put groups one after another, each with its own legend. If a group grows past five or six fields, split it under a second legend.
+
+**Do:** Place short groups one after another.
+
+```tsx
+/**
+ * Do example for "Keep Groups Flat and Short" on the Fieldset page.
+ * Place short groups one after another.
+ * @module
+ */
+import { Field, Fieldset, style, TextInput } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.form()}>
+      <Fieldset.Root {...styles.group()}>
+        <Fieldset.Legend>Destination</Fieldset.Legend>
+        <Field.Root>
+          <Field.Label>Address</Field.Label>
+          <TextInput.Group>
+            <TextInput.Control defaultValue="0x8f3a…12c4" />
+          </TextInput.Group>
+        </Field.Root>
+      </Fieldset.Root>
+      <Fieldset.Root {...styles.group()}>
+        <Fieldset.Legend>Payment</Fieldset.Legend>
+        <Field.Root>
+          <Field.Label>Memo</Field.Label>
+          <TextInput.Group>
+            <TextInput.Control defaultValue="Rent for May" />
+          </TextInput.Group>
+        </Field.Root>
+      </Fieldset.Root>
+    </div>
+  )
+}
+
+namespace styles {
+  export const form = style({
+    display: 'grid',
+    gap: '24',
+    maxWidth: '320px !custom',
+    width: '100% !custom',
+  })
+
+  export const group = style({ rowGap: '12' })
+}
+```
+
+**Don't:** Nest one fieldset inside another.
+
+```tsx
+/**
+ * Don't example for "Keep Groups Flat and Short" on the Fieldset page.
+ * Don't nest one fieldset inside another.
+ * @module
+ */
+import { Field, Fieldset, style, TextInput } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Fieldset.Root {...styles.outer()}>
+      <Fieldset.Legend>Destination</Fieldset.Legend>
+      <Field.Root>
+        <Field.Label>Address</Field.Label>
+        <TextInput.Group>
+          <TextInput.Control defaultValue="0x8f3a…12c4" />
+        </TextInput.Group>
+      </Field.Root>
+      <Fieldset.Root {...styles.group()}>
+        <Fieldset.Legend>Payment</Fieldset.Legend>
+        <Field.Root>
+          <Field.Label>Memo</Field.Label>
+          <TextInput.Group>
+            <TextInput.Control defaultValue="Rent for May" />
+          </TextInput.Group>
+        </Field.Root>
+      </Fieldset.Root>
+    </Fieldset.Root>
+  )
+}
+
+namespace styles {
+  export const group = style({ rowGap: '12' })
+
+  export const outer = style({ maxWidth: '320px !custom', rowGap: '12', width: '100% !custom' })
+}
+```
+
+## Accessibility
+
+A fieldset renders a native `<fieldset>` named by its legend. Screen readers read the legend before the controls.
+
+### Semantics
+
+* **Fieldset.Root (group):** A native fieldset with one name for related controls.
+* **Fieldset.Legend (aria-labelledby):** Names the fieldset, as a div, not a native legend.
+* **Disabled (disabled):** Disables every control inside and dims the labels.
+
+### Your Responsibilities
+
+* **Include a Legend (Fieldset.Legend):** Include a legend. Without one, the group has no accessible name.
+* **Group Related Controls:** Group only related controls, such as radios or an address.
+* **Render a Heading When Needed (render):** The legend is not a heading. If the group starts a section, render an `h2`.
+
+## Related
+
+[Field](field.md)
+
+Use for labelling a single control.
+
+[RadioGroup](radio-group.md)
+
+Use for one choice from a group.
+
+[CheckboxGroup](checkbox-group.md)
+
+Use for several choices from a group.
+
+[Forms](../patterns/forms.md)
+
+Covers laying out groups of fields.