@slotted/react 0.0.0-stage → 0.1.0-beta.0

package/dist/docs/field.examples.md

@@ -0,0 +1,557 @@
+<!-- index: ./index.md -->
+# field
+
+`data-ui="field"` · Label, control, help and error for one input.
+
+## Examples
+
+### Playground
+
+One field with every axis on it, driven by the controls below the canvas. Switch labelPlacement to side and narrow the window: below 320 pixels of its own width the field stacks again.
+
+Excerpt — not a complete module
+
+```tsx
+<Field required>
+  <FieldLabel>Email</FieldLabel>
+  <FieldControl type="email" />
+  <FieldDescription>We will use this address for billing.</FieldDescription>
+</Field>;
+```
+
+### Saying which answers are required
+
+The asterisk is the convention. A form where most fields are required marks the exception instead — optional writes (optional) on the fields a reader may skip and nothing on the rest — and words names both sides. All four answers come from one axis an application sets once.
+
+Example
+
+```tsx
+import { Field, FieldLabel } from '@slotted/react/field';
+import { Stack } from '@slotted/react/stack';
+import { TextField } from '@slotted/react/text-field';
+
+export default function FieldNecessity() {
+  return (
+    <Stack gap={5}>
+      <Field required>
+        <FieldLabel>Company name</FieldLabel>
+        <TextField />
+      </Field>
+      <Field necessity="optional">
+        <FieldLabel>Purchase order</FieldLabel>
+        <TextField />
+      </Field>
+      <Field necessity="words" required>
+        <FieldLabel>Tax ID</FieldLabel>
+        <TextField />
+      </Field>
+    </Stack>
+  );
+}
+```
+
+### The label above the control, or beside it
+
+Drag the narrow column’s edge, or read it at 360 pixels: the side label stacks below 320 pixels of the field’s own width, so the same field reflows in a drawer and stays beside its control in a page grid.
+
+Example
+
+```tsx
+import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';
+import { Stack } from '@slotted/react/stack';
+import { TextField } from '@slotted/react/text-field';
+
+export default function FieldPlacement() {
+  return (
+    <Stack gap={4}>
+      <Field labelPlacement="side" required>
+        <FieldLabel>Legal name</FieldLabel>
+        <TextField defaultValue="Northwind Traders Ltd." />
+      </Field>
+      <Field labelPlacement="side" required>
+        <FieldLabel>Billing email</FieldLabel>
+        <TextField type="email" defaultValue="billing@northwind.example" />
+        <FieldDescription>Invoices and payment receipts are sent here.</FieldDescription>
+      </Field>
+      <Field labelPlacement="side">
+        <FieldLabel>VAT number</FieldLabel>
+        <TextField defaultValue="GB 284 9113 07" />
+      </Field>
+    </Stack>
+  );
+}
+```
+
+### The step the field sits at
+
+Three steps matching the control the field wraps, and every one of them reads the control type scale — set the toolbar to dense and the label, the message and the counter step down together.
+
+Example
+
+```tsx
+import { Field, FieldLabel } from '@slotted/react/field';
+import { Stack } from '@slotted/react/stack';
+import { TextField } from '@slotted/react/text-field';
+
+export default function FieldSizes() {
+  return (
+    <Stack gap={5}>
+      <Field size="sm">
+        <FieldLabel>SKU</FieldLabel>
+        <TextField defaultValue="NW-CHAI-24" />
+      </Field>
+      <Field size="md">
+        <FieldLabel>Product name</FieldLabel>
+        <TextField defaultValue="Chai tea, 24 bags" />
+      </Field>
+      <Field size="lg">
+        <FieldLabel>Shelf label</FieldLabel>
+        <TextField defaultValue="Chai — spiced black tea" />
+      </Field>
+    </Stack>
+  );
+}
+```
+
+### The four states a field can be in
+
+The label never turns red when the field is invalid: the error already says so in words and in colour, and a red marker on a red label is a marker nobody can see. Read-only stays legible and focusable; disabled is muted to a measured colour rather than faded.
+
+Example
+
+```tsx
+import { Field, FieldDescription, FieldError, FieldLabel } from '@slotted/react/field';
+import { Stack } from '@slotted/react/stack';
+import { TextField } from '@slotted/react/text-field';
+
+export default function FieldStates() {
+  return (
+    <Stack gap={5}>
+      <Field invalid required>
+        <FieldLabel>Card number</FieldLabel>
+        <TextField inputMode="numeric" defaultValue="4242 4242 42" />
+        <FieldError>Six digits are missing.</FieldError>
+      </Field>
+      <Field readOnly>
+        <FieldLabel>Account ID</FieldLabel>
+        <TextField defaultValue="acct_9f2c41" />
+        <FieldDescription>Quote this ID when you contact support.</FieldDescription>
+      </Field>
+      <Field disabled>
+        <FieldLabel>Workspace URL</FieldLabel>
+        <TextField defaultValue="northwind.slotted.app" />
+        <FieldDescription>Only the workspace owner can change the URL.</FieldDescription>
+      </Field>
+    </Stack>
+  );
+}
+```
+
+### Help, errors, and the line held open for one
+
+Both messages are inline-message roots, so the error carries a clipped “Error:” a screen reader reads first. The right-hand column renders its error unconditionally with reserve, so the button below it does not move when the error arrives.
+
+Example
+
+```tsx
+import { Field, FieldDescription, FieldError, FieldLabel } from '@slotted/react/field';
+import { Stack } from '@slotted/react/stack';
+import { TextField } from '@slotted/react/text-field';
+
+export default function FieldMessages() {
+  return (
+    <Stack gap={5}>
+      <Field>
+        <FieldLabel>Purchase order</FieldLabel>
+        <TextField defaultValue="PO-20418" />
+        <FieldDescription>
+          Printed on the invoice so your accounts team can match it.
+        </FieldDescription>
+      </Field>
+      <Field invalid>
+        <FieldLabel>Postal code</FieldLabel>
+        <TextField defaultValue="981" />
+        <FieldDescription>Five digits, as on the shipping label.</FieldDescription>
+        <FieldError>Enter all five digits.</FieldError>
+      </Field>
+      <Field>
+        <FieldLabel>Discount</FieldLabel>
+        <TextField defaultValue="45%" />
+        <FieldError tone="warning">Above 40% the order waits for a manager's approval.</FieldError>
+      </Field>
+    </Stack>
+  );
+}
+```
+
+### Counting what the page is counting
+
+The count sits in the label row’s spare column, so it never shares a row with the error and never adds one. It turns at its own limit rather than at the field’s, because a count passes its maximum before validation runs.
+
+Example
+
+```tsx
+import { useState } from 'react';
+import {
+  Field,
+  FieldCounter,
+  FieldDescription,
+  FieldHeader,
+  FieldLabel,
+} from '@slotted/react/field';
+import { Stack } from '@slotted/react/stack';
+import { TextField } from '@slotted/react/text-field';
+import { Textarea } from '@slotted/react/textarea';
+
+const MAX_TAGS = 5;
+
+export default function FieldCounterExample() {
+  const [tags, setTags] = useState('tea, organic, fair trade');
+  const count = tags.split(',').filter((tag) => tag.trim() !== '').length;
+  const over = count > MAX_TAGS;
+
+  return (
+    <Stack gap={5}>
+      <Field>
+        <FieldLabel>Public description</FieldLabel>
+        <Textarea
+          autoSize
+          countMax={140}
+          showCount
+          defaultValue="Ships within two business days. Returns are free for thirty days."
+        />
+      </Field>
+      <Field invalid={over ? true : undefined}>
+        <FieldHeader>
+          <FieldLabel>Search tags</FieldLabel>
+          <FieldCounter invalid={over}>{`${count}/${MAX_TAGS} tags`}</FieldCounter>
+        </FieldHeader>
+        <TextField value={tags} onValueChange={setTags} />
+        <FieldDescription>Separate tags with commas.</FieldDescription>
+      </Field>
+    </Stack>
+  );
+}
+```
+
+### The label row: help, indicator, action and count
+
+Hover the circle, or tab to it: the hint opens. Press it and it stays until a second press, which is what a finger needs. The row is as tall as the label with or without them, aligns on the label’s baseline, and in a narrow field sends the action and the count to a line of their own.
+
+Example
+
+```tsx
+import { Badge } from '@slotted/react/badge';
+import { Field, FieldAction, FieldHeader, FieldIndicator, FieldLabel } from '@slotted/react/field';
+import { Stack } from '@slotted/react/stack';
+import { TextField } from '@slotted/react/text-field';
+
+export default function FieldHeaderExample() {
+  return (
+    <Stack gap={5}>
+      <Field required>
+        <FieldHeader>
+          <FieldLabel>Password</FieldLabel>
+          <FieldAction render={(props) => <a {...props} href="#reset-password" />}>
+            Forgot password?
+          </FieldAction>
+        </FieldHeader>
+        <TextField type="password" autoComplete="current-password" />
+      </Field>
+      <Field>
+        <FieldHeader>
+          <FieldLabel>Webhook URL</FieldLabel>
+          <FieldIndicator>
+            <Badge size="sm" tone="accent" variant="soft">
+              Beta
+            </Badge>
+          </FieldIndicator>
+          <FieldAction>Send test event</FieldAction>
+        </FieldHeader>
+        <TextField type="url" defaultValue="https://hooks.northwind.example/orders" />
+      </Field>
+    </Stack>
+  );
+}
+```
+
+### Content the field did not choose
+
+A German compound with no break opportunity, a container digest in the description, and an Arabic field in a right-to-left document — the label breaks rather than sliding under the control, and the necessity word never breaks.
+
+Excerpt — not a complete module
+
+```tsx
+<Field dir="rtl" labelPlacement="side" lang="ar">
+  <FieldLabel>رقم التعريف الضريبي</FieldLabel>
+  <FieldControl />
+</Field>;
+```
+
+### Composition and escape hatches
+
+The provider sets the whole application’s fields once, render substitutes any part’s element, and useField lets a control this library does not own take the wiring without a wrapper around it.
+
+Excerpt — not a complete module
+
+```tsx
+<FieldDefaultsProvider necessity="words" size="sm">
+  <App />
+</FieldDefaultsProvider>;
+
+// A control the library does not own, wired without a wrapper.
+function MoneyInput() {
+  const field = useField();
+  return <input id={field?.ids.control} aria-describedby={field?.describedBy} />;
+}
+```
+
+### What a reader hears, in order
+
+Turn a screen reader on and enter the control: the label, then “required”, then the indicator, the help behind the icon, the description, the count and the error — one name, one description in a fixed order, and no asterisk read aloud.
+
+Excerpt — not a complete module
+
+```tsx
+<div data-ui="field" data-part="root">
+  <div data-part="header">
+    <label data-part="label" for="cnpj-control">
+      Tax ID
+      <span aria-hidden="true" data-part="mark">
+        *
+      </span>
+    </label>
+    <button aria-describedby="cnpj-help" aria-label="More information" data-part="help">
+      <span data-part="help-text" hidden id="cnpj-help">
+        Numbers only.
+      </span>
+    </button>
+  </div>
+  <input
+    aria-describedby="cnpj-help cnpj-description cnpj-error"
+    aria-invalid="true"
+    aria-required="true"
+    id="cnpj-control"
+  />
+</div>;
+```
+
+### controls.tsx
+
+Example
+
+```tsx
+import { DatePicker } from '@slotted/react/date-picker';
+import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';
+import { NumberField } from '@slotted/react/number-field';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  type SelectOption,
+  SelectTrigger,
+  SelectValue,
+} from '@slotted/react/select';
+import { Stack } from '@slotted/react/stack';
+
+const TERMS: SelectOption[] = [
+  { value: 'net-15', label: 'Net 15' },
+  { value: 'net-30', label: 'Net 30' },
+  { value: 'net-60', label: 'Net 60' },
+];
+
+export default function FieldControls() {
+  return (
+    <Stack gap={5}>
+      <Field required>
+        <FieldLabel>Payment terms</FieldLabel>
+        <Select defaultValue="net-30" items={TERMS}>
+          <SelectTrigger>
+            <SelectValue placeholder="Choose terms" />
+          </SelectTrigger>
+          <SelectContent>
+            {TERMS.map((term) => (
+              <SelectItem key={term.value} value={term.value}>
+                {term.label}
+              </SelectItem>
+            ))}
+          </SelectContent>
+        </Select>
+      </Field>
+      <Field required>
+        <FieldLabel>Quantity</FieldLabel>
+        <NumberField defaultValue={12} min={1} max={500} />
+        <FieldDescription>Cases of 24 bags.</FieldDescription>
+      </Field>
+      <Field>
+        <FieldLabel>Delivery date</FieldLabel>
+        <DatePicker locale="en-US" />
+      </Field>
+    </Stack>
+  );
+}
+```
+
+### custom-control.tsx
+
+Example
+
+```tsx
+import { Field, FieldControl, FieldDescription, FieldLabel } from '@slotted/react/field';
+
+export default function FieldCustomControl() {
+  return (
+    <Field>
+      <FieldLabel>Brand colour</FieldLabel>
+      <FieldControl type="color" defaultValue="#2f6fde" />
+      <FieldDescription>Used on invoices and in the customer portal.</FieldDescription>
+    </Field>
+  );
+}
+```
+
+### defaults.tsx
+
+Example
+
+```tsx
+import { Field, FieldDefaultsProvider, FieldLabel } from '@slotted/react/field';
+import { Stack } from '@slotted/react/stack';
+import { TextField } from '@slotted/react/text-field';
+
+export default function FieldDefaults() {
+  return (
+    <FieldDefaultsProvider size="sm" labelPlacement="side" necessity="optional">
+      <Stack gap={3}>
+        <Field required>
+          <FieldLabel>Warehouse</FieldLabel>
+          <TextField defaultValue="Seattle — Pier 91" />
+        </Field>
+        <Field required>
+          <FieldLabel>Bin location</FieldLabel>
+          <TextField defaultValue="A-14-03" />
+        </Field>
+        <Field>
+          <FieldLabel>Picking note</FieldLabel>
+          <TextField />
+        </Field>
+      </Stack>
+    </FieldDefaultsProvider>
+  );
+}
+```
+
+### help.tsx
+
+Example
+
+```tsx
+import { Field, FieldHeader, FieldHelp, FieldLabel } from '@slotted/react/field';
+import { Stack } from '@slotted/react/stack';
+import { TextField } from '@slotted/react/text-field';
+
+export default function FieldHelpExample() {
+  return (
+    <Stack gap={5}>
+      <Field required>
+        <FieldHeader>
+          <FieldLabel>Cost centre</FieldLabel>
+          <FieldHelp>
+            The four-digit code finance assigns to your team. It appears on every invoice line.
+          </FieldHelp>
+        </FieldHeader>
+        <TextField inputMode="numeric" defaultValue="4120" />
+      </Field>
+      <Field disabled>
+        <FieldHeader>
+          <FieldLabel>Billing currency</FieldLabel>
+          <FieldHelp>Set when the workspace was created. Contact support to change it.</FieldHelp>
+        </FieldHeader>
+        <TextField defaultValue="USD — US dollar" />
+      </Field>
+    </Stack>
+  );
+}
+```
+
+### narrow.tsx
+
+Example
+
+```tsx
+import { Field, FieldLabel } from '@slotted/react/field';
+import { Grid } from '@slotted/react/grid';
+import { TextField } from '@slotted/react/text-field';
+
+export default function FieldNarrow() {
+  return (
+    <Grid columns={2} minItemWidth="xs" gap={4}>
+      <Field labelPlacement="side">
+        <FieldLabel>City</FieldLabel>
+        <TextField defaultValue="Seattle" />
+      </Field>
+      <Field labelPlacement="side">
+        <FieldLabel>Postal code</FieldLabel>
+        <TextField defaultValue="98104" />
+      </Field>
+    </Grid>
+  );
+}
+```
+
+### validation.tsx
+
+Example
+
+```tsx
+import { useState, type SubmitEvent } from 'react';
+import { Button } from '@slotted/react/button';
+import { Field, FieldError, FieldLabel } from '@slotted/react/field';
+import { Inline } from '@slotted/react/inline';
+import { Stack } from '@slotted/react/stack';
+import { TextField } from '@slotted/react/text-field';
+
+function emailError(value: string): string {
+  if (value.trim() === '') return 'Enter the address invoices are sent to.';
+  if (!/^\S+@\S+\.\S+$/.test(value)) return 'Enter an address like billing@company.com.';
+  return '';
+}
+
+export default function FieldValidation() {
+  const [email, setEmail] = useState('');
+  const [submitted, setSubmitted] = useState(false);
+  const [saved, setSaved] = useState(false);
+  const error = submitted ? emailError(email) : '';
+
+  const submit = (event: SubmitEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    setSubmitted(true);
+    setSaved(emailError(email) === '');
+  };
+
+  return (
+    <form noValidate onSubmit={submit}>
+      <Stack gap={4}>
+        <Field required invalid={error !== '' ? true : undefined}>
+          <FieldLabel>Billing email</FieldLabel>
+          <TextField
+            type="email"
+            value={email}
+            onValueChange={(value) => {
+              setEmail(value);
+              setSaved(false);
+            }}
+          />
+          <FieldError live="polite" reserve>
+            {error}
+          </FieldError>
+        </Field>
+        <Inline gap={3} align="center">
+          <Button type="submit">Save billing details</Button>
+          {saved ? <span role="status">Saved.</span> : null}
+        </Inline>
+      </Stack>
+    </form>
+  );
+}
+```