@slotted/angular 0.0.0-stage → 0.1.0-beta.1

package/docs/field.examples.md

@@ -0,0 +1,676 @@
+<!-- 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
+
+```html
+<div slField required>
+  <label slFieldLabel>Email</label>
+  <input slFieldControl type="email" />
+  <span slFieldDescription>We will use this address for billing.</span>
+</div>
+```
+
+### 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 input an application sets once.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldLabel } from '@slotted/angular/field';
+import { SlStack } from '@slotted/angular/stack';
+import { SlTextField, SlTextFieldInput } from '@slotted/angular/text-field';
+
+@Component({
+  selector: 'app-field-necessity',
+  imports: [SlField, SlFieldLabel, SlStack, SlTextField, SlTextFieldInput],
+  template: `
+    <div slStack [gap]="5">
+      <div slField required>
+        <label slFieldLabel>Company name</label>
+        <div slTextField><input slTextFieldInput /></div>
+      </div>
+      <div slField necessity="optional">
+        <label slFieldLabel>Purchase order</label>
+        <div slTextField><input slTextFieldInput /></div>
+      </div>
+      <div slField necessity="words" required>
+        <label slFieldLabel>Tax ID</label>
+        <div slTextField><input slTextFieldInput /></div>
+      </div>
+    </div>
+  `,
+})
+export class FieldNecessity {}
+```
+
+### 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
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import { SlStack } from '@slotted/angular/stack';
+import { SlTextField, SlTextFieldInput } from '@slotted/angular/text-field';
+
+@Component({
+  selector: 'app-field-placement',
+  imports: [SlField, SlFieldDescription, SlFieldLabel, SlStack, SlTextField, SlTextFieldInput],
+  template: `
+    <div slStack [gap]="4">
+      <div slField labelPlacement="side" required>
+        <label slFieldLabel>Legal name</label>
+        <div slTextField><input slTextFieldInput defaultValue="Northwind Traders Ltd." /></div>
+      </div>
+      <div slField labelPlacement="side" required>
+        <label slFieldLabel>Billing email</label>
+        <div slTextField>
+          <input slTextFieldInput type="email" defaultValue="billing@northwind.example" />
+        </div>
+        <span slFieldDescription>Invoices and payment receipts are sent here.</span>
+      </div>
+      <div slField labelPlacement="side">
+        <label slFieldLabel>VAT number</label>
+        <div slTextField><input slTextFieldInput defaultValue="GB 284 9113 07" /></div>
+      </div>
+    </div>
+  `,
+})
+export class FieldPlacement {}
+```
+
+### 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
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldLabel } from '@slotted/angular/field';
+import { SlStack } from '@slotted/angular/stack';
+import { SlTextField, SlTextFieldInput } from '@slotted/angular/text-field';
+
+@Component({
+  selector: 'app-field-sizes',
+  imports: [SlField, SlFieldLabel, SlStack, SlTextField, SlTextFieldInput],
+  template: `
+    <div slStack [gap]="5">
+      <div slField size="sm">
+        <label slFieldLabel>SKU</label>
+        <div slTextField><input slTextFieldInput defaultValue="NW-CHAI-24" /></div>
+      </div>
+      <div slField size="md">
+        <label slFieldLabel>Product name</label>
+        <div slTextField><input slTextFieldInput defaultValue="Chai tea, 24 bags" /></div>
+      </div>
+      <div slField size="lg">
+        <label slFieldLabel>Shelf label</label>
+        <div slTextField><input slTextFieldInput defaultValue="Chai — spiced black tea" /></div>
+      </div>
+    </div>
+  `,
+})
+export class FieldSizes {}
+```
+
+### 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
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldDescription, SlFieldError, SlFieldLabel } from '@slotted/angular/field';
+import { SlStack } from '@slotted/angular/stack';
+import { SlTextField, SlTextFieldInput } from '@slotted/angular/text-field';
+
+@Component({
+  selector: 'app-field-states',
+  imports: [
+    SlField,
+    SlFieldDescription,
+    SlFieldError,
+    SlFieldLabel,
+    SlStack,
+    SlTextField,
+    SlTextFieldInput,
+  ],
+  template: `
+    <div slStack [gap]="5">
+      <div slField invalid required>
+        <label slFieldLabel>Card number</label>
+        <div slTextField>
+          <input slTextFieldInput inputmode="numeric" defaultValue="4242 4242 42" />
+        </div>
+        <span slFieldError>Six digits are missing.</span>
+      </div>
+      <div slField readOnly>
+        <label slFieldLabel>Account ID</label>
+        <div slTextField><input slTextFieldInput defaultValue="acct_9f2c41" /></div>
+        <span slFieldDescription>Quote this ID when you contact support.</span>
+      </div>
+      <div slField disabled>
+        <label slFieldLabel>Workspace URL</label>
+        <div slTextField><input slTextFieldInput defaultValue="northwind.slotted.app" /></div>
+        <span slFieldDescription>Only the workspace owner can change the URL.</span>
+      </div>
+    </div>
+  `,
+})
+export class FieldStates {}
+```
+
+### Help, errors, and the line held open for one
+
+Both messages are inline-message roots the field renders around what the page wrote, so the error carries a clipped “Error:” a screen reader reads first. The right-hand column keeps its line with reserve, so the button below does not move when the error arrives.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldDescription, SlFieldError, SlFieldLabel } from '@slotted/angular/field';
+import { SlStack } from '@slotted/angular/stack';
+import { SlTextField, SlTextFieldInput } from '@slotted/angular/text-field';
+
+@Component({
+  selector: 'app-field-messages',
+  imports: [
+    SlField,
+    SlFieldDescription,
+    SlFieldError,
+    SlFieldLabel,
+    SlStack,
+    SlTextField,
+    SlTextFieldInput,
+  ],
+  template: `
+    <div slStack [gap]="5">
+      <div slField>
+        <label slFieldLabel>Purchase order</label>
+        <div slTextField><input slTextFieldInput defaultValue="PO-20418" /></div>
+        <span slFieldDescription>Printed on the invoice so your accounts team can match it.</span>
+      </div>
+      <div slField invalid>
+        <label slFieldLabel>Postal code</label>
+        <div slTextField><input slTextFieldInput defaultValue="981" /></div>
+        <span slFieldDescription>Five digits, as on the shipping label.</span>
+        <span slFieldError>Enter all five digits.</span>
+      </div>
+      <div slField>
+        <label slFieldLabel>Discount</label>
+        <div slTextField><input slTextFieldInput defaultValue="45%" /></div>
+        <span slFieldError tone="warning">Above 40% the order waits for a manager's approval.</span>
+      </div>
+    </div>
+  `,
+})
+export class FieldMessages {}
+```
+
+### 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
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import {
+  SlField,
+  SlFieldCounter,
+  SlFieldDescription,
+  SlFieldHeader,
+  SlFieldLabel,
+} from '@slotted/angular/field';
+import { SlStack } from '@slotted/angular/stack';
+import { SlTextarea } from '@slotted/angular/textarea';
+import { SlTextField, SlTextFieldInput } from '@slotted/angular/text-field';
+
+const MAX_TAGS = 5;
+
+@Component({
+  selector: 'app-field-counter',
+  imports: [
+    SlField,
+    SlFieldCounter,
+    SlFieldDescription,
+    SlFieldHeader,
+    SlFieldLabel,
+    SlStack,
+    SlTextarea,
+    SlTextField,
+    SlTextFieldInput,
+  ],
+  template: `
+    <div slStack [gap]="5">
+      <div slField>
+        <label slFieldLabel>Public description</label>
+        <textarea
+          slTextarea
+          autoSize
+          countMax="140"
+          showCount
+          defaultValue="Ships within two business days. Returns are free for thirty days."
+        ></textarea>
+      </div>
+      <div slField [invalid]="over() ? true : undefined">
+        <div slFieldHeader>
+          <label slFieldLabel>Search tags</label>
+          <span slFieldCounter [invalid]="over()">{{ count() }}/{{ max }} tags</span>
+        </div>
+        <div slTextField>
+          <input slTextFieldInput [value]="tags()" (valueChange)="tags.set($event.value)" />
+        </div>
+        <span slFieldDescription>Separate tags with commas.</span>
+      </div>
+    </div>
+  `,
+})
+export class FieldCounter {
+  readonly max = MAX_TAGS;
+  readonly tags = signal('tea, organic, fair trade');
+  readonly count = computed(
+    () =>
+      this.tags()
+        .split(',')
+        .filter((tag) => tag.trim() !== '').length,
+  );
+  readonly over = computed(() => this.count() > MAX_TAGS);
+}
+```
+
+### 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
+
+```ts
+import { Component } from '@angular/core';
+import { SlBadge } from '@slotted/angular/badge';
+import {
+  SlField,
+  SlFieldAction,
+  SlFieldHeader,
+  SlFieldIndicator,
+  SlFieldLabel,
+} from '@slotted/angular/field';
+import { SlStack } from '@slotted/angular/stack';
+import { SlTextField, SlTextFieldInput } from '@slotted/angular/text-field';
+
+@Component({
+  selector: 'app-field-header',
+  imports: [
+    SlBadge,
+    SlField,
+    SlFieldAction,
+    SlFieldHeader,
+    SlFieldIndicator,
+    SlFieldLabel,
+    SlStack,
+    SlTextField,
+    SlTextFieldInput,
+  ],
+  template: `
+    <div slStack [gap]="5">
+      <div slField required>
+        <div slFieldHeader>
+          <label slFieldLabel>Password</label>
+          <a slFieldAction href="#reset-password">Forgot password?</a>
+        </div>
+        <div slTextField>
+          <input slTextFieldInput type="password" autocomplete="current-password" />
+        </div>
+      </div>
+      <div slField>
+        <div slFieldHeader>
+          <label slFieldLabel>Webhook URL</label>
+          <span slFieldIndicator>
+            <span slBadge size="sm" tone="accent" variant="soft">Beta</span>
+          </span>
+          <button slFieldAction>Send test event</button>
+        </div>
+        <div slTextField>
+          <input
+            slTextFieldInput
+            type="url"
+            defaultValue="https://hooks.northwind.example/orders"
+          />
+        </div>
+      </div>
+    </div>
+  `,
+})
+export class FieldHeader {}
+```
+
+### 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
+
+```html
+<div slField labelPlacement="side" lang="ar" dir="rtl">
+  <label slFieldLabel>رقم التعريف الضريبي</label>
+  <input slFieldControl />
+</div>
+```
+
+### Composition and escape hatches
+
+provideFieldDefaults sets the whole application’s fields once, exportAs hands a template the identifiers the field derived, and slFieldControl wires a control the library does not own without wrapping it in anything.
+
+Excerpt — not a complete module
+
+```ts
+bootstrapApplication(App, {
+  providers: [provideFieldDefaults({ size: 'sm', necessity: 'words' })],
+});
+```
+
+### 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
+
+```html
+<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 data-part="help" aria-label="More information" aria-describedby="cnpj-help">
+      <span data-part="help-text" id="cnpj-help" hidden>Numbers only.</span>
+    </button>
+  </div>
+  <input
+    data-part="control"
+    id="cnpj-control"
+    aria-describedby="cnpj-help cnpj-description cnpj-error"
+    aria-invalid="true"
+    aria-required="true"
+  />
+</div>
+```
+
+### controls.ts
+
+Example
+
+```ts
+import { Component, signal } from '@angular/core';
+import { SlDatePicker } from '@slotted/angular/date-picker';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import { SlNumberField, SlNumberFieldInput } from '@slotted/angular/number-field';
+import { SlSelect, SlSelectItem, type SelectOption } from '@slotted/angular/select';
+import { SlStack } from '@slotted/angular/stack';
+
+@Component({
+  selector: 'app-field-controls',
+  imports: [
+    SlDatePicker,
+    SlField,
+    SlFieldDescription,
+    SlFieldLabel,
+    SlNumberField,
+    SlNumberFieldInput,
+    SlSelect,
+    SlSelectItem,
+    SlStack,
+  ],
+  template: `
+    <div slStack [gap]="5">
+      <div slField required>
+        <label slFieldLabel>Payment terms</label>
+        <sl-select placeholder="Choose terms" [items]="termOptions" [(value)]="terms">
+          @for (term of termOptions; track term.value) {
+            <sl-select-item [value]="term.value">{{ term.label }}</sl-select-item>
+          }
+        </sl-select>
+      </div>
+      <div slField required>
+        <label slFieldLabel>Quantity</label>
+        <div slNumberField>
+          <input slNumberFieldInput defaultValue="12" min="1" max="500" />
+        </div>
+        <span slFieldDescription>Cases of 24 bags.</span>
+      </div>
+      <div slField>
+        <label slFieldLabel>Delivery date</label>
+        <div slDatePicker locale="en-US"></div>
+      </div>
+    </div>
+  `,
+})
+export class FieldControls {
+  readonly termOptions: SelectOption[] = [
+    { value: 'net-15', label: 'Net 15' },
+    { value: 'net-30', label: 'Net 30' },
+    { value: 'net-60', label: 'Net 60' },
+  ];
+  readonly terms = signal<string | null>('net-30');
+}
+```
+
+### custom-control.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldControl, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+
+@Component({
+  selector: 'app-field-custom-control',
+  imports: [SlField, SlFieldControl, SlFieldDescription, SlFieldLabel],
+  template: `
+    <div slField>
+      <label slFieldLabel>Brand colour</label>
+      <input slFieldControl type="color" value="#2f6fde" />
+      <span slFieldDescription>Used on invoices and in the customer portal.</span>
+    </div>
+  `,
+})
+export class FieldCustomControl {}
+```
+
+### defaults.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { provideFieldDefaults, SlField, SlFieldLabel } from '@slotted/angular/field';
+import { SlStack } from '@slotted/angular/stack';
+import { SlTextField, SlTextFieldInput } from '@slotted/angular/text-field';
+
+@Component({
+  selector: 'app-field-defaults',
+  imports: [SlField, SlFieldLabel, SlStack, SlTextField, SlTextFieldInput],
+  providers: [provideFieldDefaults({ size: 'sm', labelPlacement: 'side', necessity: 'optional' })],
+  template: `
+    <div slStack [gap]="3">
+      <div slField required>
+        <label slFieldLabel>Warehouse</label>
+        <div slTextField><input slTextFieldInput defaultValue="Seattle — Pier 91" /></div>
+      </div>
+      <div slField required>
+        <label slFieldLabel>Bin location</label>
+        <div slTextField><input slTextFieldInput defaultValue="A-14-03" /></div>
+      </div>
+      <div slField>
+        <label slFieldLabel>Picking note</label>
+        <div slTextField><input slTextFieldInput /></div>
+      </div>
+    </div>
+  `,
+})
+export class FieldDefaults {}
+```
+
+### help.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldHeader, SlFieldHelp, SlFieldLabel } from '@slotted/angular/field';
+import { SlStack } from '@slotted/angular/stack';
+import { SlTextField, SlTextFieldInput } from '@slotted/angular/text-field';
+
+@Component({
+  selector: 'app-field-help',
+  imports: [
+    SlField,
+    SlFieldHeader,
+    SlFieldHelp,
+    SlFieldLabel,
+    SlStack,
+    SlTextField,
+    SlTextFieldInput,
+  ],
+  template: `
+    <div slStack [gap]="5">
+      <div slField required>
+        <div slFieldHeader>
+          <label slFieldLabel>Cost centre</label>
+          <button
+            slFieldHelp="The four-digit code finance assigns to your team. It appears on every invoice line."
+          ></button>
+        </div>
+        <div slTextField><input slTextFieldInput inputmode="numeric" defaultValue="4120" /></div>
+      </div>
+      <div slField disabled>
+        <div slFieldHeader>
+          <label slFieldLabel>Billing currency</label>
+          <button
+            slFieldHelp="Set when the workspace was created. Contact support to change it."
+          ></button>
+        </div>
+        <div slTextField><input slTextFieldInput defaultValue="USD — US dollar" /></div>
+      </div>
+    </div>
+  `,
+})
+export class FieldHelp {}
+```
+
+### narrow.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldLabel } from '@slotted/angular/field';
+import { SlGrid } from '@slotted/angular/grid';
+import { SlTextField, SlTextFieldInput } from '@slotted/angular/text-field';
+
+@Component({
+  selector: 'app-field-narrow',
+  imports: [SlField, SlFieldLabel, SlGrid, SlTextField, SlTextFieldInput],
+  template: `
+    <div slGrid [columns]="2" minItemWidth="xs" [gap]="4">
+      <div slField labelPlacement="side">
+        <label slFieldLabel>City</label>
+        <div slTextField><input slTextFieldInput defaultValue="Seattle" /></div>
+      </div>
+      <div slField labelPlacement="side">
+        <label slFieldLabel>Postal code</label>
+        <div slTextField><input slTextFieldInput defaultValue="98104" /></div>
+      </div>
+    </div>
+  `,
+})
+export class FieldNarrow {}
+```
+
+### validation.ts
+
+Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { SlButton } from '@slotted/angular/button';
+import { SlField, SlFieldError, SlFieldLabel } from '@slotted/angular/field';
+import { SlInline } from '@slotted/angular/inline';
+import { SlStack } from '@slotted/angular/stack';
+import { SlTextField, SlTextFieldInput } from '@slotted/angular/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 '';
+}
+
+@Component({
+  selector: 'app-field-validation',
+  imports: [
+    SlButton,
+    SlField,
+    SlFieldError,
+    SlFieldLabel,
+    SlInline,
+    SlStack,
+    SlTextField,
+    SlTextFieldInput,
+  ],
+  template: `
+    <form novalidate (submit)="submit($event)">
+      <div slStack [gap]="4">
+        <div slField required [invalid]="error() !== '' ? true : undefined">
+          <label slFieldLabel>Billing email</label>
+          <div slTextField>
+            <input
+              slTextFieldInput
+              type="email"
+              [value]="email()"
+              (valueChange)="edit($event.value)"
+            />
+          </div>
+          <span slFieldError live="polite" reserve>{{ error() }}</span>
+        </div>
+        <div slInline [gap]="3" align="center">
+          <button slButton type="submit">Save billing details</button>
+          @if (saved()) {
+            <span role="status">Saved.</span>
+          }
+        </div>
+      </div>
+    </form>
+  `,
+})
+export class FieldValidation {
+  readonly email = signal('');
+  readonly submitted = signal(false);
+  readonly saved = signal(false);
+  readonly error = computed(() => (this.submitted() ? emailError(this.email()) : ''));
+
+  edit(value: string): void {
+    this.email.set(value);
+    this.saved.set(false);
+  }
+
+  submit(event: Event): void {
+    event.preventDefault();
+    this.submitted.set(true);
+    this.saved.set(emailError(this.email()) === '');
+  }
+}
+```