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

package/docs/checkbox.examples.md

@@ -0,0 +1,546 @@
+<!-- index: ./index.md -->
+# checkbox
+
+`data-ui="checkbox"` · Box that turns one option on or off.
+
+## Examples
+
+### Playground
+
+One box with every axis on it, driven by the controls below the canvas. Click the label, not only the box: the target runs from the square to the end of the text.
+
+Excerpt — not a complete module
+
+```html
+<div slCheckbox defaultChecked>
+  Enviar recibo
+  <p slCheckboxDescription>Enviaremos o recibo por e-mail.</p>
+</div>
+```
+
+### The step the box sits at
+
+The square is the control glyph scale, so the three steps shrink together with the type and the gap when the toolbar switches to dense — and the label keeps its 24-pixel target at every one of them.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlCheckbox } from '@slotted/angular/checkbox';
+import { SlStack } from '@slotted/angular/stack';
+
+@Component({
+  selector: 'app-checkbox-sizes',
+  imports: [SlCheckbox, SlStack],
+  template: `
+    <div slStack [gap]="4">
+      <div slCheckbox size="sm" defaultChecked>Show archived orders</div>
+      <div slCheckbox size="md" defaultChecked>Notify the warehouse</div>
+      <div slCheckbox size="lg" defaultChecked>Remember this device</div>
+    </div>
+  `,
+})
+export class CheckboxSizes {}
+```
+
+### The choice as a framed surface
+
+Click anywhere inside a tile, not only the box: the label’s hit area stretches over the whole surface, so the target is the frame. Chosen says it with a two-pixel accent edge as well as a tint, because the high-contrast scheme flattens every tint to white and only the width survives.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlCheckbox, SlCheckboxDescription } from '@slotted/angular/checkbox';
+import { SlGrid } from '@slotted/angular/grid';
+
+@Component({
+  selector: 'app-checkbox-tile',
+  imports: [SlCheckbox, SlCheckboxDescription, SlGrid],
+  template: `
+    <div slGrid [gap]="4" minItemWidth="sm">
+      <div slCheckbox variant="tile" defaultChecked>
+        Daily backup
+        <p slCheckboxDescription>One copy a day, kept for 30 days.</p>
+      </div>
+      <div slCheckbox variant="tile">
+        Audit log
+        <p slCheckboxDescription>Who changed what, and when, exported as CSV.</p>
+      </div>
+      <div slCheckbox variant="tile" disabled>
+        Secondary region
+        <p slCheckboxDescription>Available on the Scale plan.</p>
+      </div>
+    </div>
+  `,
+})
+export class CheckboxTile {}
+```
+
+### Every state the box paints
+
+Read-only keeps full-strength ink, its ring and its tab stop, because the value is real and still submitted; disabled loses all three. Invalid thickens the border as well as reddening it, because the high-contrast scheme paints every border the same black.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlCheckbox, SlCheckboxDescription } from '@slotted/angular/checkbox';
+import { SlStack } from '@slotted/angular/stack';
+
+@Component({
+  selector: 'app-checkbox-states',
+  imports: [SlCheckbox, SlCheckboxDescription, SlStack],
+  template: `
+    <div slStack [gap]="4">
+      <div slCheckbox readOnly defaultChecked>
+        Tax exempt
+        <p slCheckboxDescription>Set by the customer's tax certificate.</p>
+      </div>
+      <div slCheckbox disabled>
+        Same-day delivery
+        <p slCheckboxDescription>Not offered from the Seattle warehouse.</p>
+      </div>
+      <div slCheckbox invalid>
+        I counted every item on shelf A-14
+        <p slCheckboxDescription>Confirm the count before closing the cycle.</p>
+      </div>
+    </div>
+  `,
+})
+export class CheckboxStates {}
+```
+
+### The mixed state, and the box that commands a set
+
+Mixed is a state and never a third value: the form still submits a boolean. Tick the parent and the whole set follows; untick one child and the parent goes back to the dash on its own.
+
+Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { SlCheckbox, SlCheckboxDescription } from '@slotted/angular/checkbox';
+import { SlStack } from '@slotted/angular/stack';
+import { SlText } from '@slotted/angular/typography';
+
+function summary(taxable: boolean | 'mixed'): string {
+  if (taxable === 'mixed') return 'Taxed on 2 of the 3 selected products.';
+  return taxable
+    ? 'All 3 selected products will be taxed.'
+    : 'None of the 3 selected products will be taxed.';
+}
+
+@Component({
+  selector: 'app-checkbox-indeterminate',
+  imports: [SlCheckbox, SlCheckboxDescription, SlStack, SlText],
+  template: `
+    <div slStack [gap]="3">
+      <span slText weight="medium">Edit 3 products</span>
+      <div
+        slCheckbox
+        [checked]="taxable() === true"
+        [indeterminate]="taxable() === 'mixed'"
+        (checkedChange)="taxable.set($event.value)"
+      >
+        Taxable
+        <p slCheckboxDescription>{{ summary() }}</p>
+      </div>
+    </div>
+  `,
+})
+export class CheckboxIndeterminate {
+  readonly taxable = signal<boolean | 'mixed'>('mixed');
+  readonly summary = computed(() => summary(this.taxable()));
+}
+```
+
+### Which side of its label the box is on
+
+start pushes the box to the end of the row, which is where a settings list puts a control — and it is why the column is a fraction rather than the label’s own width: five boxes have to line up with each other.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlCheckbox } from '@slotted/angular/checkbox';
+import { SlStack } from '@slotted/angular/stack';
+
+@Component({
+  selector: 'app-checkbox-placement',
+  imports: [SlCheckbox, SlStack],
+  template: `
+    <div slStack [gap]="3">
+      <div slCheckbox labelPlacement="start" defaultChecked>Email when an order ships</div>
+      <div slCheckbox labelPlacement="start">Email when stock runs low</div>
+      <div slCheckbox labelPlacement="start" defaultChecked>Weekly sales digest</div>
+    </div>
+  `,
+})
+export class CheckboxPlacement {}
+```
+
+### Saying more than the label does
+
+The description aligns under the label rather than under the box, in both placements and both writing directions, and it is announced as the control’s description rather than as part of its name.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlCheckbox, SlCheckboxDescription } from '@slotted/angular/checkbox';
+import { SlStack } from '@slotted/angular/stack';
+
+@Component({
+  selector: 'app-checkbox-description',
+  imports: [SlCheckbox, SlCheckboxDescription, SlStack],
+  template: `
+    <div slStack [gap]="4">
+      <div slCheckbox defaultChecked>
+        Email me when a payment fails
+        <p slCheckboxDescription>One message per failed payment, sent to the billing contact.</p>
+      </div>
+      <div slCheckbox>
+        Send a daily summary instead
+        <p slCheckboxDescription>
+          Sent at 08:00 in the account's time zone, and skipped on days with no failures.
+        </p>
+      </div>
+    </div>
+  `,
+})
+export class CheckboxDescription {}
+```
+
+### Inside a field, and in a reactive form
+
+The box reads the field for its step and its four shared states and never for its identifier, and the same element is where formControlName goes — the value accessor is on the root.
+
+Excerpt — not a complete module
+
+```html
+<fieldset slFieldGroup required>
+  <legend slFieldGroupLegend>Notificações</legend>
+  <div slCheckboxGroup name="alerts" formControlName="alerts">
+    <div slCheckbox value="approved">Pedido aprovado</div>
+    <div slCheckbox value="refused">Pedido recusado</div>
+  </div>
+</fieldset>
+```
+
+### Content the family did not choose
+
+A label that wraps to three lines keeps the box on the first of them rather than in the middle of the block, an unbroken token breaks instead of taking the page with it, and a right-to-left label mirrors the whole row.
+
+Excerpt — not a complete module
+
+```html
+<div slCheckbox>
+  Concordo em receber comunicações sobre alterações contratuais e prazos de entrega.
+  <p slCheckboxDescription>A caixa continua na primeira linha do rótulo.</p>
+</div>
+
+<div slCheckbox dir="rtl">أوافق على تلقي رسائل حول التغييرات في العقد.</div>
+```
+
+### Setting it once, and reaching past it
+
+The token carries the two decisions an application takes once, exportAs reaches the instance and the native element behind it, and the root is the consumer’s own element rather than one the family renders.
+
+Excerpt — not a complete module
+
+```html
+<!-- exportAs reaches the instance; inputElement reaches the input,
+     which already has focus() and click(). -->
+<div slCheckbox #box="slCheckbox">Uma caixa</div>
+<button type="button" (click)="box.inputElement.focus()">Focar</button>
+```
+
+### What the keyboard does, and who implements it
+
+Space toggles and Enter submits the form, and neither is a listener this family writes: the control is a native checkbox, so the whole table is the platform’s and arrives translated and mirrored for free.
+
+Excerpt — not a complete module
+
+```html
+<!-- Space and a pointer arrive as one click. A click synthesised by the
+     keyboard reports no detail, which is how the reason is told apart
+     without a key listener existing anywhere in the family. -->
+<div slCheckbox (checkedChange)="log($event.reason)">Marque com o teclado</div>
+```
+
+### controlled.ts
+
+Example
+
+```ts
+import { Component, signal } from '@angular/core';
+import { SlCheckbox, SlCheckboxDescription } from '@slotted/angular/checkbox';
+import { SlField, SlFieldLabel } from '@slotted/angular/field';
+import { SlStack } from '@slotted/angular/stack';
+import { SlTextField, SlTextFieldInput } from '@slotted/angular/text-field';
+
+@Component({
+  selector: 'app-checkbox-controlled',
+  imports: [
+    SlCheckbox,
+    SlCheckboxDescription,
+    SlField,
+    SlFieldLabel,
+    SlStack,
+    SlTextField,
+    SlTextFieldInput,
+  ],
+  template: `
+    <div slStack [gap]="4">
+      <div slCheckbox [checked]="sameAddress()" (checkedChange)="sameAddress.set($event.value)">
+        Bill to the shipping address
+        <p slCheckboxDescription>Ships to 12 Orchestra Terrace, Walla Walla, WA 99362.</p>
+      </div>
+      @if (!sameAddress()) {
+        <div slField required>
+          <label slFieldLabel>Billing address</label>
+          <div slTextField>
+            <input slTextFieldInput autocomplete="billing street-address" />
+          </div>
+        </div>
+      }
+    </div>
+  `,
+})
+export class CheckboxControlled {
+  readonly sameAddress = signal(true);
+}
+```
+
+### defaults.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { provideCheckboxDefaults, SlCheckbox } from '@slotted/angular/checkbox';
+import { SlStack } from '@slotted/angular/stack';
+
+@Component({
+  selector: 'app-checkbox-defaults',
+  imports: [SlCheckbox, SlStack],
+  providers: [provideCheckboxDefaults({ size: 'sm', labelPlacement: 'start' })],
+  template: `
+    <div slStack [gap]="2">
+      <div slCheckbox defaultChecked>Show prices with tax</div>
+      <div slCheckbox>Show discontinued products</div>
+      <div slCheckbox defaultChecked>Group orders by customer</div>
+    </div>
+  `,
+})
+export class CheckboxDefaults {}
+```
+
+### form.ts
+
+Example
+
+```ts
+import { Component, signal } from '@angular/core';
+import { SlButton } from '@slotted/angular/button';
+import { SlCheckbox } from '@slotted/angular/checkbox';
+import { SlFieldGroup, SlFieldGroupLegend } from '@slotted/angular/field-group';
+import { SlInline } from '@slotted/angular/inline';
+import { SlStack } from '@slotted/angular/stack';
+import { SlText } from '@slotted/angular/typography';
+
+@Component({
+  selector: 'app-checkbox-form',
+  imports: [SlButton, SlCheckbox, SlFieldGroup, SlFieldGroupLegend, SlInline, SlStack, SlText],
+  template: `
+    <form (submit)="submit($event)" (reset)="saved.set(null)">
+      <div slStack [gap]="4">
+        <fieldset slFieldGroup>
+          <legend slFieldGroupLegend>Reports emailed each morning</legend>
+          <div slStack [gap]="2">
+            <div slCheckbox name="reports" value="daily-sales" defaultChecked>Daily sales</div>
+            <div slCheckbox name="reports" value="low-stock">Low stock</div>
+            <div slCheckbox name="reports" value="payouts" defaultChecked>Payouts</div>
+          </div>
+        </fieldset>
+        <div slInline [gap]="3" align="center">
+          <button slButton type="submit">Save</button>
+          <button slButton type="reset" variant="outline" tone="secondary">Reset</button>
+        </div>
+        <span slText size="sm" tone="muted" role="status">
+          {{ saved() === null ? '' : 'Submitted reports: ' + saved() + '.' }}
+        </span>
+      </div>
+    </form>
+  `,
+})
+export class CheckboxForm {
+  readonly saved = signal<string | null>(null);
+
+  submit(event: SubmitEvent): void {
+    event.preventDefault();
+    const reports = new FormData(event.target as HTMLFormElement).getAll('reports');
+    this.saved.set(reports.length === 0 ? 'none' : reports.join(', '));
+  }
+}
+```
+
+### hidden-label.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlCheckbox } from '@slotted/angular/checkbox';
+import { SlInline } from '@slotted/angular/inline';
+import { SlStack } from '@slotted/angular/stack';
+import { SlText } from '@slotted/angular/typography';
+import { SlVisuallyHidden } from '@slotted/angular/visually-hidden';
+
+@Component({
+  selector: 'app-checkbox-hidden-label',
+  imports: [SlCheckbox, SlInline, SlStack, SlText, SlVisuallyHidden],
+  template: `
+    <div slStack [gap]="2">
+      @for (invoice of invoices; track invoice.id) {
+        <div slInline [gap]="3" align="center">
+          <div slCheckbox size="sm" [value]="invoice.id">
+            <span slVisuallyHidden>Select {{ invoice.id }}</span>
+          </div>
+          <span slText numeric="tabular">{{ invoice.id }}</span>
+          <span slText tone="muted">{{ invoice.customer }}</span>
+          <span slText numeric="tabular">{{ invoice.amount }}</span>
+        </div>
+      }
+    </div>
+  `,
+})
+export class CheckboxHiddenLabel {
+  readonly invoices = [
+    { id: 'INV-1042', customer: 'Alfreds Futterkiste', amount: '$1,250.00' },
+    { id: 'INV-1043', customer: 'Ernst Handel', amount: '$4,318.40' },
+    { id: 'INV-1044', customer: 'Island Trading', amount: '$872.15' },
+  ];
+}
+```
+
+### long-label.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlCheckbox, SlCheckboxDescription } from '@slotted/angular/checkbox';
+import { SlStack } from '@slotted/angular/stack';
+
+@Component({
+  selector: 'app-checkbox-long-label',
+  imports: [SlCheckbox, SlCheckboxDescription, SlStack],
+  template: `
+    <div slStack [gap]="4">
+      <div slCheckbox defaultChecked>
+        Send notices about contract changes, delivery deadlines and changes to the return policy for
+        this store and every other store in the group
+        <p slCheckboxDescription>Notices go to the billing contact on the account.</p>
+      </div>
+      <div slCheckbox>
+        Forward order events to https://hooks.northwind.example/orders/fulfilment-updates
+      </div>
+    </div>
+  `,
+})
+export class CheckboxLongLabel {}
+```
+
+### parent.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlCheckbox } from '@slotted/angular/checkbox';
+import { SlCheckboxGroup } from '@slotted/angular/checkbox-group';
+import { SlFieldGroup, SlFieldGroupLegend } from '@slotted/angular/field-group';
+
+@Component({
+  selector: 'app-checkbox-parent',
+  imports: [SlCheckbox, SlCheckboxGroup, SlFieldGroup, SlFieldGroupLegend],
+  template: `
+    <fieldset slFieldGroup>
+      <legend slFieldGroupLegend>Delivery days</legend>
+      <div
+        slCheckboxGroup
+        [allValues]="weekdays"
+        [defaultValue]="['mon', 'wed', 'fri']"
+        name="days"
+      >
+        <div slCheckbox parent>Every weekday</div>
+        <div slCheckbox value="mon">Monday</div>
+        <div slCheckbox value="tue">Tuesday</div>
+        <div slCheckbox value="wed">Wednesday</div>
+        <div slCheckbox value="thu">Thursday</div>
+        <div slCheckbox value="fri">Friday</div>
+      </div>
+    </fieldset>
+  `,
+})
+export class CheckboxParent {
+  readonly weekdays = ['mon', 'tue', 'wed', 'thu', 'fri'];
+}
+```
+
+### validation.ts
+
+Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { toSignal } from '@angular/core/rxjs-interop';
+import { FormControl, ReactiveFormsModule, Validators } from '@angular/forms';
+import { SlButton } from '@slotted/angular/button';
+import { SlCheckbox } from '@slotted/angular/checkbox';
+import { SlField, SlFieldError } from '@slotted/angular/field';
+import { SlInline } from '@slotted/angular/inline';
+import { SlStack } from '@slotted/angular/stack';
+
+@Component({
+  selector: 'app-checkbox-validation',
+  imports: [ReactiveFormsModule, SlButton, SlCheckbox, SlField, SlFieldError, SlInline, SlStack],
+  template: `
+    <form novalidate (submit)="submit($event)">
+      <div slStack [gap]="4">
+        <div slField required [invalid]="error() !== '' ? true : undefined">
+          <div slCheckbox [formControl]="terms" (checkedChange)="placed.set(false)">
+            I accept the supplier terms for this purchase order
+          </div>
+          <span slFieldError live="polite" reserve>{{ error() }}</span>
+        </div>
+        <div slInline [gap]="3" align="center">
+          <button slButton type="submit">Place order</button>
+          @if (placed()) {
+            <span role="status">Order placed.</span>
+          }
+        </div>
+      </div>
+    </form>
+  `,
+})
+export class CheckboxValidation {
+  readonly terms = new FormControl(false, {
+    nonNullable: true,
+    validators: Validators.requiredTrue,
+  });
+  readonly accepted = toSignal(this.terms.valueChanges, { initialValue: this.terms.value });
+  readonly submitted = signal(false);
+  readonly placed = signal(false);
+  readonly error = computed(() =>
+    this.submitted() && !this.accepted() ? 'Accept the supplier terms to place the order.' : '',
+  );
+
+  submit(event: Event): void {
+    event.preventDefault();
+    this.submitted.set(true);
+    this.placed.set(this.terms.valid);
+  }
+}
+```