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

package/docs/checkbox-group.examples.md

@@ -0,0 +1,612 @@
+<!-- index: ./index.md -->
+# checkbox-group
+
+`data-ui="checkbox-group"` · Set of checkboxes under one label.
+
+## Examples
+
+### Playground
+
+One set with every axis on it, driven by the controls below the canvas. Tick two options and watch the array in the actions panel: the order is the set’s, never the click order.
+
+Excerpt — not a complete module
+
+```html
+<div slCheckboxGroup name="days" [allValues]="days" [defaultValue]="['mon']">
+  <div slCheckbox value="mon">Segunda</div>
+  <div slCheckbox value="wed">Quarta</div>
+  <div slCheckbox value="fri">Sexta</div>
+</div>
+```
+
+### How the choices flow
+
+A horizontal set wraps rather than scrolling or clipping, because a row whose last option nobody can see is worse than two rows — and the distance between two choices is twice the distance between a box and its own label.
+
+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-group-orientation',
+  imports: [SlCheckbox, SlCheckboxGroup, SlFieldGroup, SlFieldGroupLegend],
+  template: `
+    <fieldset slFieldGroup>
+      <legend slFieldGroupLegend>Invoice status</legend>
+      <div slCheckboxGroup orientation="horizontal" [defaultValue]="['open', 'overdue']">
+        <div slCheckbox value="draft">Draft</div>
+        <div slCheckbox value="open">Open</div>
+        <div slCheckbox value="paid">Paid</div>
+        <div slCheckbox value="overdue">Overdue</div>
+        <div slCheckbox value="void">Void</div>
+      </div>
+    </fieldset>
+  `,
+})
+export class CheckboxGroupOrientation {}
+```
+
+### A set of framed choices
+
+The variant belongs to the group, not to each box: a set with one plain choice among four tiles is a set nobody meant to write. Arrangement is not the group’s — Grid already owns columns, minItemWidth and a stretching alignment, so tiles in a row come out the same width and the same height.
+
+Excerpt — not a complete module
+
+```html
+<div slCheckboxGroup variant="tile" [defaultValue]="['pix']">
+  <div slGrid minItemWidth="sm">
+    <div slCheckbox value="pix">
+      Pix
+      <p slCheckboxDescription>Compensação imediata.</p>
+    </div>
+    <div slCheckbox value="card">
+      Cartão de crédito
+      <p slCheckboxDescription>Parcelamento em até doze vezes.</p>
+    </div>
+  </div>
+</div>
+```
+
+### One box that commands the set
+
+The parent is derived and never entered: ticked when every value is selected, mixed between the two, and its request replaces the whole selection rather than toggling a value of its own.
+
+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-group-parent',
+  imports: [SlCheckbox, SlCheckboxGroup, SlFieldGroup, SlFieldGroupLegend],
+  template: `
+    <fieldset slFieldGroup>
+      <legend slFieldGroupLegend>Columns to export</legend>
+      <div
+        slCheckboxGroup
+        name="columns"
+        [allValues]="columns"
+        [defaultValue]="['order', 'customer', 'total']"
+      >
+        <div slCheckbox parent>All columns</div>
+        <div slCheckbox value="order">Order number</div>
+        <div slCheckbox value="customer">Customer</div>
+        <div slCheckbox value="placed">Placed on</div>
+        <div slCheckbox value="total">Total</div>
+        <div slCheckbox value="status">Status</div>
+      </div>
+    </fieldset>
+  `,
+})
+export class CheckboxGroupParent {
+  readonly columns = ['order', 'customer', 'placed', 'total', 'status'];
+}
+```
+
+### What the group says to every box in it
+
+Each of the four is unstated rather than false, so a group defers to the field around it and a box defers to the group; stated anywhere, it wins from there down and every box paints it.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlCheckbox } from '@slotted/angular/checkbox';
+import { SlCheckboxGroup } from '@slotted/angular/checkbox-group';
+import {
+  SlFieldGroup,
+  SlFieldGroupDescription,
+  SlFieldGroupError,
+  SlFieldGroupLegend,
+} from '@slotted/angular/field-group';
+import { SlStack } from '@slotted/angular/stack';
+
+@Component({
+  selector: 'app-checkbox-group-states',
+  imports: [
+    SlCheckbox,
+    SlCheckboxGroup,
+    SlFieldGroup,
+    SlFieldGroupDescription,
+    SlFieldGroupError,
+    SlFieldGroupLegend,
+    SlStack,
+  ],
+  template: `
+    <div slStack [gap]="6">
+      <fieldset slFieldGroup required>
+        <legend slFieldGroupLegend>Sales regions</legend>
+        <span slFieldGroupError>Choose at least one region for this price list.</span>
+        <div slCheckboxGroup invalid orientation="horizontal">
+          <div slCheckbox value="us">United States</div>
+          <div slCheckbox value="ca">Canada</div>
+          <div slCheckbox value="eu">European Union</div>
+        </div>
+      </fieldset>
+      <fieldset slFieldGroup readOnly>
+        <legend slFieldGroupLegend>Tax exemptions</legend>
+        <span slFieldGroupDescription>Set by the finance team on the customer record.</span>
+        <div slCheckboxGroup orientation="horizontal" [defaultValue]="['resale']">
+          <div slCheckbox value="resale">Resale</div>
+          <div slCheckbox value="nonprofit">Nonprofit</div>
+        </div>
+      </fieldset>
+      <fieldset slFieldGroup disabled>
+        <legend slFieldGroupLegend>Carriers</legend>
+        <span slFieldGroupDescription>Carriers open once a ship-from address is saved.</span>
+        <div slCheckboxGroup orientation="horizontal" [defaultValue]="['ups']">
+          <div slCheckbox value="ups">UPS</div>
+          <div slCheckbox value="fedex">FedEx</div>
+          <div slCheckbox value="usps">USPS</div>
+        </div>
+      </fieldset>
+    </div>
+  `,
+})
+export class CheckboxGroupStates {}
+```
+
+### How many of them are chosen
+
+The number reaches the field’s label row through the channel a text field opened for characters, so a reader finds "2/5" where they already look for a count rather than in a sentence under the set.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlCheckbox } from '@slotted/angular/checkbox';
+import { SlCheckboxGroup } from '@slotted/angular/checkbox-group';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+
+@Component({
+  selector: 'app-checkbox-group-count',
+  imports: [SlCheckbox, SlCheckboxGroup, SlField, SlFieldDescription, SlFieldLabel],
+  template: `
+    <div slField>
+      <label slFieldLabel>Fulfil from</label>
+      <div
+        slCheckboxGroup
+        name="warehouses"
+        showCount
+        [allValues]="warehouses"
+        [defaultValue]="['seattle', 'tacoma']"
+      >
+        <div slCheckbox value="seattle">Seattle</div>
+        <div slCheckbox value="tacoma">Tacoma</div>
+        <div slCheckbox value="portland">Portland</div>
+        <div slCheckbox value="boise">Boise</div>
+      </div>
+      <span slFieldDescription>Orders ship from the nearest selected warehouse.</span>
+    </div>
+  `,
+})
+export class CheckboxGroupCount {
+  readonly warehouses = ['seattle', 'tacoma', 'portland', 'boise'];
+}
+```
+
+### Inside a group of fields, and in a reactive form
+
+The fieldset and its legend are what group and name the set, so this group withdraws its own role — and the same element takes formControlName, because the accessor and the validator both live on the root.
+
+Excerpt — not a complete module
+
+```html
+<fieldset slFieldGroup required>
+  <legend slFieldGroupLegend>Notificações</legend>
+  <div slCheckboxGroup required 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 set of long options keeps every box on the first line of its own label, a narrow column turns a horizontal set into a stack without a media query, and a right-to-left set mirrors whole rather than rearranging.
+
+Excerpt — not a complete module
+
+```html
+<div slCheckboxGroup orientation="horizontal">
+  <div slCheckbox value="a">
+    Autorizo o uso dos dados de navegação para personalizar as recomendações
+  </div>
+  <div slCheckbox value="b">E também para medir o alcance das campanhas</div>
+</div>
+```
+
+### Setting it once, and reaching past it
+
+The token carries the three decisions an application takes once, exportAs reaches the instance, and the root is the consumer’s own element — so a set of choices can be a real list.
+
+Excerpt — not a complete module
+
+```html
+<ul slCheckboxGroup class="slotted-demo-list" [defaultValue]="['a']">
+  <li slCheckbox value="a">Um item</li>
+  <li slCheckbox value="b">E outro abaixo dele</li>
+</ul>
+```
+
+### What the keyboard does, and who implements it
+
+Every box is its own tab stop and Space toggles it, because a checkbox is one choice made on its own — which is exactly what tells this family apart from a radio group, where the whole set is one stop.
+
+Excerpt — not a complete module
+
+```html
+<!-- The group binds no key at all: each box is a native checkbox, so Tab
+     reaches every one of them and Space toggles the one that has focus. -->
+<div slCheckboxGroup>
+  <div slCheckbox value="a">Tab até aqui</div>
+  <div slCheckbox value="b">E de novo até aqui</div>
+</div>
+```
+
+### controlled.ts
+
+Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { SlCheckbox } from '@slotted/angular/checkbox';
+import { SlCheckboxGroup } from '@slotted/angular/checkbox-group';
+import { SlFieldGroup, SlFieldGroupLegend } from '@slotted/angular/field-group';
+import { SlStack } from '@slotted/angular/stack';
+
+const ORDERS: Record<string, number> = { card: 812, transfer: 145, paypal: 96 };
+
+@Component({
+  selector: 'app-checkbox-group-controlled',
+  imports: [SlCheckbox, SlCheckboxGroup, SlFieldGroup, SlFieldGroupLegend, SlStack],
+  template: `
+    <div slStack [gap]="4">
+      <fieldset slFieldGroup>
+        <legend slFieldGroupLegend>Payment method</legend>
+        <div
+          slCheckboxGroup
+          orientation="horizontal"
+          [value]="methods()"
+          (valueChange)="methods.set($event.value)"
+        >
+          <div slCheckbox value="card">Card</div>
+          <div slCheckbox value="transfer">Bank transfer</div>
+          <div slCheckbox value="paypal">PayPal</div>
+        </div>
+      </fieldset>
+      <span>Showing {{ shown() }} orders</span>
+    </div>
+  `,
+})
+export class CheckboxGroupControlled {
+  readonly methods = signal<readonly string[]>(['card', 'transfer']);
+  readonly shown = computed(() =>
+    this.methods().reduce((sum, method) => sum + (ORDERS[method] ?? 0), 0),
+  );
+}
+```
+
+### defaults.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlCheckbox } from '@slotted/angular/checkbox';
+import { provideCheckboxGroupDefaults, SlCheckboxGroup } from '@slotted/angular/checkbox-group';
+import { SlFieldGroup, SlFieldGroupLegend } from '@slotted/angular/field-group';
+import { SlStack } from '@slotted/angular/stack';
+
+@Component({
+  selector: 'app-checkbox-group-defaults',
+  imports: [SlCheckbox, SlCheckboxGroup, SlFieldGroup, SlFieldGroupLegend, SlStack],
+  providers: [provideCheckboxGroupDefaults({ orientation: 'horizontal' })],
+  template: `
+    <div slStack [gap]="5">
+      <fieldset slFieldGroup>
+        <legend slFieldGroupLegend>Fulfilment</legend>
+        <div slCheckboxGroup [defaultValue]="['unfulfilled', 'partial']">
+          <div slCheckbox value="unfulfilled">Unfulfilled</div>
+          <div slCheckbox value="partial">Partial</div>
+          <div slCheckbox value="fulfilled">Fulfilled</div>
+        </div>
+      </fieldset>
+      <fieldset slFieldGroup>
+        <legend slFieldGroupLegend>Sales channel</legend>
+        <div slCheckboxGroup [defaultValue]="['online']">
+          <div slCheckbox value="online">Online</div>
+          <div slCheckbox value="retail">Retail</div>
+          <div slCheckbox value="wholesale">Wholesale</div>
+        </div>
+      </fieldset>
+    </div>
+  `,
+})
+export class CheckboxGroupDefaults {}
+```
+
+### descriptions.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlCheckbox, SlCheckboxDescription } from '@slotted/angular/checkbox';
+import { SlCheckboxGroup } from '@slotted/angular/checkbox-group';
+import { SlFieldGroup, SlFieldGroupLegend } from '@slotted/angular/field-group';
+
+@Component({
+  selector: 'app-checkbox-group-descriptions',
+  imports: [SlCheckbox, SlCheckboxDescription, SlCheckboxGroup, SlFieldGroup, SlFieldGroupLegend],
+  template: `
+    <fieldset slFieldGroup>
+      <legend slFieldGroupLegend>When stock runs low</legend>
+      <div slCheckboxGroup [defaultValue]="['alert']">
+        <div slCheckbox value="alert">
+          Alert the buyer
+          <p slCheckboxDescription>
+            Sent to the buyer for the SKU when on-hand drops below the reorder point.
+          </p>
+        </div>
+        <div slCheckbox value="draft-po">
+          Draft a purchase order
+          <p slCheckboxDescription>
+            Created for the preferred supplier at the usual order quantity, waiting for approval.
+          </p>
+        </div>
+        <div slCheckbox value="hide">
+          Stop selling online at zero
+          <p slCheckboxDescription>
+            The product page shows Out of stock instead of a delivery date.
+          </p>
+        </div>
+      </div>
+    </fieldset>
+  `,
+})
+export class CheckboxGroupDescriptions {}
+```
+
+### disabled-option.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlCheckbox, SlCheckboxDescription } from '@slotted/angular/checkbox';
+import { SlCheckboxGroup } from '@slotted/angular/checkbox-group';
+import { SlFieldGroup, SlFieldGroupLegend } from '@slotted/angular/field-group';
+
+@Component({
+  selector: 'app-checkbox-group-disabled-option',
+  imports: [SlCheckbox, SlCheckboxDescription, SlCheckboxGroup, SlFieldGroup, SlFieldGroupLegend],
+  template: `
+    <fieldset slFieldGroup>
+      <legend slFieldGroupLegend>Send order updates by</legend>
+      <div slCheckboxGroup name="updates" [defaultValue]="['email']">
+        <div slCheckbox value="email">Email</div>
+        <div slCheckbox value="sms" disabled>
+          Text message
+          <p slCheckboxDescription>Add a mobile number to the customer record to turn this on.</p>
+        </div>
+        <div slCheckbox value="webhook">Webhook to the storefront</div>
+      </div>
+    </fieldset>
+  `,
+})
+export class CheckboxGroupDisabledOption {}
+```
+
+### label-placement.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-group-label-placement',
+  imports: [SlCheckbox, SlCheckboxGroup, SlFieldGroup, SlFieldGroupLegend],
+  template: `
+    <fieldset slFieldGroup>
+      <legend slFieldGroupLegend>Email reports</legend>
+      <div slCheckboxGroup labelPlacement="start" [defaultValue]="['weekly']">
+        <div slCheckbox value="daily">Daily sales summary</div>
+        <div slCheckbox value="weekly">Weekly stock report</div>
+        <div slCheckbox value="monthly">Monthly statement</div>
+      </div>
+    </fieldset>
+  `,
+})
+export class CheckboxGroupLabelPlacement {}
+```
+
+### sizes.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';
+import { SlStack } from '@slotted/angular/stack';
+
+@Component({
+  selector: 'app-checkbox-group-sizes',
+  imports: [SlCheckbox, SlCheckboxGroup, SlFieldGroup, SlFieldGroupLegend, SlStack],
+  template: `
+    <div slStack [gap]="5">
+      <fieldset slFieldGroup size="sm">
+        <legend slFieldGroupLegend>Show columns</legend>
+        <div slCheckboxGroup orientation="horizontal" [defaultValue]="['sku', 'on-hand']">
+          <div slCheckbox value="sku">SKU</div>
+          <div slCheckbox value="on-hand">On hand</div>
+          <div slCheckbox value="reserved">Reserved</div>
+        </div>
+      </fieldset>
+      <fieldset slFieldGroup size="md">
+        <legend slFieldGroupLegend>Ship from</legend>
+        <div slCheckboxGroup orientation="horizontal" [defaultValue]="['seattle']">
+          <div slCheckbox value="seattle">Seattle</div>
+          <div slCheckbox value="tacoma">Tacoma</div>
+          <div slCheckbox value="portland">Portland</div>
+        </div>
+      </fieldset>
+      <fieldset slFieldGroup size="lg">
+        <legend slFieldGroupLegend>Accept payment by</legend>
+        <div slCheckboxGroup orientation="horizontal" [defaultValue]="['card', 'transfer']">
+          <div slCheckbox value="card">Card</div>
+          <div slCheckbox value="transfer">Bank transfer</div>
+        </div>
+      </fieldset>
+    </div>
+  `,
+})
+export class CheckboxGroupSizes {}
+```
+
+### tiles.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlCheckbox, SlCheckboxDescription } from '@slotted/angular/checkbox';
+import { SlCheckboxGroup } from '@slotted/angular/checkbox-group';
+import { SlFieldGroup, SlFieldGroupLegend } from '@slotted/angular/field-group';
+import { SlGrid } from '@slotted/angular/grid';
+
+@Component({
+  selector: 'app-checkbox-group-tiles',
+  imports: [
+    SlCheckbox,
+    SlCheckboxDescription,
+    SlCheckboxGroup,
+    SlFieldGroup,
+    SlFieldGroupLegend,
+    SlGrid,
+  ],
+  template: `
+    <fieldset slFieldGroup>
+      <legend slFieldGroupLegend>Add-ons</legend>
+      <div slCheckboxGroup name="add-ons" variant="tile" [defaultValue]="['audit-log']">
+        <div slGrid minItemWidth="xs">
+          <div slCheckbox value="audit-log">
+            Audit log
+            <p slCheckboxDescription>$29 per month. Every change kept for a year.</p>
+          </div>
+          <div slCheckbox value="sso">
+            Single sign-on
+            <p slCheckboxDescription>$49 per month. SAML and SCIM provisioning.</p>
+          </div>
+          <div slCheckbox value="support">
+            Priority support
+            <p slCheckboxDescription>$99 per month. Replies within four hours.</p>
+          </div>
+        </div>
+      </div>
+    </fieldset>
+  `,
+})
+export class CheckboxGroupTiles {}
+```
+
+### validation.ts
+
+Example
+
+```ts
+import { Component, signal } from '@angular/core';
+import { FormControl, ReactiveFormsModule } from '@angular/forms';
+import { SlButton } from '@slotted/angular/button';
+import { SlCheckbox } from '@slotted/angular/checkbox';
+import { SlCheckboxGroup } from '@slotted/angular/checkbox-group';
+import { SlFieldGroup, SlFieldGroupError, SlFieldGroupLegend } from '@slotted/angular/field-group';
+import { SlInline } from '@slotted/angular/inline';
+import { SlStack } from '@slotted/angular/stack';
+
+@Component({
+  selector: 'app-checkbox-group-validation',
+  imports: [
+    ReactiveFormsModule,
+    SlButton,
+    SlCheckbox,
+    SlCheckboxGroup,
+    SlFieldGroup,
+    SlFieldGroupError,
+    SlFieldGroupLegend,
+    SlInline,
+    SlStack,
+  ],
+  template: `
+    <form novalidate (submit)="submit($event)">
+      <div slStack [gap]="4">
+        <fieldset slFieldGroup required>
+          <legend slFieldGroupLegend>Send shipping confirmations by</legend>
+          <span slFieldGroupError live="polite" reserve>{{
+            missing ? 'Choose at least one channel.' : ''
+          }}</span>
+          <div slCheckboxGroup [formControl]="channels" [invalid]="missing ? true : undefined">
+            <div slCheckbox value="email">Email</div>
+            <div slCheckbox value="sms">Text message</div>
+            <div slCheckbox value="in-app">In-app notification</div>
+          </div>
+        </fieldset>
+        <div slInline [gap]="3" align="center">
+          <button slButton type="submit">Save preferences</button>
+          @if (submitted() && channels.valid) {
+            <span role="status">Preferences saved.</span>
+          }
+        </div>
+      </div>
+    </form>
+  `,
+})
+export class CheckboxGroupValidation {
+  /* The group is the form control and its validator: inside a required field
+     group, an empty selection fails with { required: true }. */
+  readonly channels = new FormControl<readonly string[]>([], { nonNullable: true });
+  readonly submitted = signal(false);
+
+  get missing(): boolean {
+    return this.submitted() && this.channels.invalid;
+  }
+
+  submit(event: Event): void {
+    event.preventDefault();
+    this.submitted.set(true);
+  }
+}
+```