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

package/docs/select.examples.md

@@ -0,0 +1,1214 @@
+<!-- index: ./index.md -->
+# select
+
+`data-ui="select"` · Picks one option from a popup list.
+
+## Examples
+
+### Playground
+
+One select with every axis on it, driven by the controls under the canvas. Change size, variant and width and watch the control and its popup answer together.
+
+Excerpt — not a complete module
+
+```html
+<sl-select aria-label="Fruit" placeholder="Choose a fruit">
+  <sl-select-item value="apple">Apple</sl-select-item>
+  <sl-select-item value="blueberry">Blueberry</sl-select-item>
+</sl-select>
+```
+
+### Two-way, and the request
+
+The model moves the value in both directions; the request output arrives first and carries the reason, so a page can tell a press from a key — or refuse the change.
+
+Excerpt — not a complete module
+
+```html
+<sl-select [(value)]="fruit" (valueChangeRequest)="log($event.reason)">…</sl-select>
+```
+
+### Placeholder and unresolved values
+
+Nothing chosen shows the placeholder in the muted step. A value the collection cannot name shows the value itself, which is what an async list holds for one render.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldLabel } from '@slotted/angular/field';
+import { SlSelect, SlSelectItem, type SelectOption } from '@slotted/angular/select';
+import { SlStack } from '@slotted/angular/stack';
+
+const REASONS: SelectOption[] = [
+  { value: 'damaged', label: 'Arrived damaged' },
+  { value: 'wrong-item', label: 'Wrong item shipped' },
+  { value: 'not-needed', label: 'No longer needed' },
+];
+
+const TERMS: SelectOption[] = [
+  { value: 'prepaid', label: 'Prepaid' },
+  { value: 'net-30', label: 'Net 30' },
+  { value: 'net-45', label: 'Net 45' },
+];
+
+@Component({
+  selector: 'app-select-placeholder',
+  imports: [SlField, SlFieldLabel, SlSelect, SlSelectItem, SlStack],
+  template: `
+    <div slStack [gap]="5">
+      <div slField>
+        <label slFieldLabel>Return reason</label>
+        <sl-select placeholder="Choose a reason">
+          @for (reason of reasons; track reason.value) {
+            <sl-select-item [value]="reason.value">{{ reason.label }}</sl-select-item>
+          }
+        </sl-select>
+      </div>
+      <div slField>
+        <label slFieldLabel>Payment terms</label>
+        <sl-select placeholder="Choose terms" value="net-30" [items]="terms">
+          @for (term of terms; track term.value) {
+            <sl-select-item [value]="term.value">{{ term.label }}</sl-select-item>
+          }
+        </sl-select>
+      </div>
+    </div>
+  `,
+})
+export class SelectPlaceholder {
+  protected readonly reasons = REASONS;
+  protected readonly terms = TERMS;
+}
+```
+
+### Groups, icons and descriptions
+
+Two named groups with a line between them. Every label starts on the same line whether or not its option carries artwork, because the column belongs to the list.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldLabel } from '@slotted/angular/field';
+import {
+  SlSelect,
+  SlSelectGroup,
+  SlSelectItem,
+  SlSelectSeparator,
+  type SelectOptionGroup,
+} from '@slotted/angular/select';
+
+const METHODS: SelectOptionGroup[] = [
+  {
+    label: 'Ground',
+    options: [
+      { value: 'ups-ground', label: 'UPS Ground' },
+      { value: 'fedex-ground', label: 'FedEx Ground' },
+    ],
+  },
+  {
+    label: 'Express',
+    options: [
+      { value: 'ups-2day', label: 'UPS 2nd Day Air' },
+      { value: 'fedex-overnight', label: 'FedEx Priority Overnight' },
+    ],
+  },
+  {
+    label: 'Freight',
+    options: [{ value: 'ltl', label: 'LTL freight, palletised' }],
+  },
+];
+
+@Component({
+  selector: 'app-select-groups',
+  imports: [SlField, SlFieldLabel, SlSelect, SlSelectGroup, SlSelectItem, SlSelectSeparator],
+  template: `
+    <div slField>
+      <label slFieldLabel>Shipping method</label>
+      <sl-select placeholder="Choose a method">
+        @for (group of methods; track group.label; let first = $first) {
+          @if (!first) {
+            <sl-select-separator />
+          }
+          <sl-select-group [label]="group.label">
+            @for (method of group.options; track method.value) {
+              <sl-select-item [value]="method.value">{{ method.label }}</sl-select-item>
+            }
+          </sl-select-group>
+        }
+      </sl-select>
+    </div>
+  `,
+})
+export class SelectGroups {
+  protected readonly methods = METHODS;
+}
+```
+
+### Multiple selection
+
+The popup stays open as options are taken, and the control shows the first label and how many more. Space toggles without closing, which is the listbox pattern’s own model.
+
+Example
+
+```ts
+import { Component, signal } from '@angular/core';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import {
+  SlSelect,
+  SlSelectItem,
+  type SelectOption,
+  type SelectSelection,
+} from '@slotted/angular/select';
+
+const TEAMS: SelectOption[] = [
+  { value: 'fulfilment', label: 'Fulfilment' },
+  { value: 'finance', label: 'Finance' },
+  { value: 'customer-care', label: 'Customer care' },
+  { value: 'purchasing', label: 'Purchasing' },
+  { value: 'returns', label: 'Returns desk' },
+];
+
+@Component({
+  selector: 'app-select-multiple',
+  imports: [SlField, SlFieldDescription, SlFieldLabel, SlSelect, SlSelectItem],
+  template: `
+    <div slField>
+      <label slFieldLabel>Notify teams</label>
+      <sl-select
+        multiple
+        clearable
+        placeholder="No one is notified"
+        [items]="teams"
+        [(value)]="notified"
+      >
+        @for (team of teams; track team.value) {
+          <sl-select-item [value]="team.value">{{ team.label }}</sl-select-item>
+        }
+      </sl-select>
+      <span slFieldDescription>Each team gets an email when the order is delayed.</span>
+    </div>
+  `,
+})
+export class SelectMultiple {
+  protected readonly teams = TEAMS;
+  protected readonly notified = signal<SelectSelection>(['fulfilment', 'finance']);
+}
+```
+
+### Clearable
+
+The clear button appears only once something is chosen, and focus goes back to the control it belonged to rather than to the document.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import { SlSelect, SlSelectItem, type SelectOption } from '@slotted/angular/select';
+
+const OWNERS: SelectOption[] = [
+  { value: 'avery', label: 'Avery Collins' },
+  { value: 'kenji', label: 'Kenji Watanabe' },
+  { value: 'lucia', label: 'Lucía Fernández' },
+  { value: 'ruth', label: 'Ruth Adeyemi' },
+];
+
+@Component({
+  selector: 'app-select-clearable',
+  imports: [SlField, SlFieldDescription, SlFieldLabel, SlSelect, SlSelectItem],
+  template: `
+    <div slField>
+      <label slFieldLabel>Assignee</label>
+      <sl-select clearable placeholder="Unassigned" value="kenji" [items]="owners">
+        @for (owner of owners; track owner.value) {
+          <sl-select-item [value]="owner.value">{{ owner.label }}</sl-select-item>
+        }
+      </sl-select>
+      <span slFieldDescription>Clear the assignee to return the ticket to the queue.</span>
+    </div>
+  `,
+})
+export class SelectClearable {
+  protected readonly owners = OWNERS;
+}
+```
+
+### Sizes
+
+Three steps, and every one of them reads control geometry — so a select beside a text field of the same size is the same height to the pixel.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldLabel } from '@slotted/angular/field';
+import {
+  SlSelect,
+  SlSelectItem,
+  type SelectOption,
+  type SelectSize,
+} from '@slotted/angular/select';
+import { SlStack } from '@slotted/angular/stack';
+
+const SIZES: { size: SelectSize; label: string }[] = [
+  { size: 'sm', label: 'Small' },
+  { size: 'md', label: 'Medium' },
+  { size: 'lg', label: 'Large' },
+];
+
+const WAREHOUSES: SelectOption[] = [
+  { value: 'RNO', label: 'Reno, NV' },
+  { value: 'CMH', label: 'Columbus, OH' },
+  { value: 'SAV', label: 'Savannah, GA' },
+];
+
+@Component({
+  selector: 'app-select-sizes',
+  imports: [SlField, SlFieldLabel, SlSelect, SlSelectItem, SlStack],
+  template: `
+    <div slStack [gap]="5">
+      @for (step of sizes; track step.size) {
+        <div slField>
+          <label slFieldLabel>{{ step.label }}</label>
+          <sl-select value="RNO" [size]="step.size" [items]="warehouses">
+            @for (warehouse of warehouses; track warehouse.value) {
+              <sl-select-item [value]="warehouse.value">{{ warehouse.label }}</sl-select-item>
+            }
+          </sl-select>
+        </div>
+      }
+    </div>
+  `,
+})
+export class SelectSizes {
+  protected readonly sizes = SIZES;
+  protected readonly warehouses = WAREHOUSES;
+}
+```
+
+### Variants
+
+outline on the page, subtle where a form sinks into its card, and plain for a table cell that is only a control while it is being used.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldLabel } from '@slotted/angular/field';
+import { SlSelect, SlSelectItem, type SelectVariant } from '@slotted/angular/select';
+import { SlStack } from '@slotted/angular/stack';
+
+const VARIANTS: { variant: SelectVariant; label: string }[] = [
+  { variant: 'outline', label: 'Outline' },
+  { variant: 'subtle', label: 'Subtle' },
+  { variant: 'plain', label: 'Plain' },
+];
+
+const WAREHOUSES = [
+  { value: 'RNO', label: 'Reno, NV' },
+  { value: 'CMH', label: 'Columbus, OH' },
+  { value: 'SAV', label: 'Savannah, GA' },
+];
+
+@Component({
+  selector: 'app-select-variants',
+  imports: [SlField, SlFieldLabel, SlSelect, SlSelectItem, SlStack],
+  template: `
+    <div slStack [gap]="5">
+      @for (step of variants; track step.variant) {
+        <div slField>
+          <label slFieldLabel>{{ step.label }}</label>
+          <sl-select placeholder="Choose a warehouse" [variant]="step.variant">
+            @for (warehouse of warehouses; track warehouse.value) {
+              <sl-select-item [value]="warehouse.value">{{ warehouse.label }}</sl-select-item>
+            }
+          </sl-select>
+        </div>
+      }
+    </div>
+  `,
+})
+export class SelectVariants {
+  protected readonly variants = VARIANTS;
+  protected readonly warehouses = WAREHOUSES;
+}
+```
+
+### States
+
+Required, invalid, read-only and disabled side by side. Read-only keeps its value legible and refuses to open; disabled answers nothing at all.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldDescription, SlFieldError, SlFieldLabel } from '@slotted/angular/field';
+import { SlSelect, SlSelectItem, type SelectOption } from '@slotted/angular/select';
+import { SlStack } from '@slotted/angular/stack';
+
+const WAREHOUSES: SelectOption[] = [
+  { value: 'RNO', label: 'Reno, NV' },
+  { value: 'CMH', label: 'Columbus, OH' },
+  { value: 'SAV', label: 'Savannah, GA' },
+];
+
+@Component({
+  selector: 'app-select-states',
+  imports: [
+    SlField,
+    SlFieldDescription,
+    SlFieldError,
+    SlFieldLabel,
+    SlSelect,
+    SlSelectItem,
+    SlStack,
+  ],
+  template: `
+    <div slStack [gap]="5">
+      <div slField invalid required>
+        <label slFieldLabel>Return warehouse</label>
+        <sl-select value="SAV" [items]="warehouses">
+          @for (warehouse of warehouses; track warehouse.value) {
+            <sl-select-item [value]="warehouse.value">{{ warehouse.label }}</sl-select-item>
+          }
+        </sl-select>
+        <span slFieldError>Savannah does not accept returns. Choose Reno or Columbus.</span>
+      </div>
+      <div slField readOnly>
+        <label slFieldLabel>Origin warehouse</label>
+        <sl-select value="RNO" [items]="warehouses">
+          @for (warehouse of warehouses; track warehouse.value) {
+            <sl-select-item [value]="warehouse.value">{{ warehouse.label }}</sl-select-item>
+          }
+        </sl-select>
+        <span slFieldDescription>Set when the order was picked.</span>
+      </div>
+      <div slField disabled>
+        <label slFieldLabel>Transfer warehouse</label>
+        <sl-select value="CMH" [items]="warehouses">
+          @for (warehouse of warehouses; track warehouse.value) {
+            <sl-select-item [value]="warehouse.value">{{ warehouse.label }}</sl-select-item>
+          }
+        </sl-select>
+        <span slFieldDescription>Transfers open once the order is invoiced.</span>
+      </div>
+    </div>
+  `,
+})
+export class SelectStates {
+  protected readonly warehouses = WAREHOUSES;
+}
+```
+
+### Loading and empty
+
+A popup with nothing in it opens onto a sentence rather than onto a two-pixel box, and a loading one keeps that measure so nothing jumps when the options land.
+
+Excerpt — not a complete module
+
+```html
+<sl-select loading [messages]="{ loading: 'Fetching teams…' }">…</sl-select>
+<sl-select [messages]="{ empty: 'No teams yet' }"></sl-select>
+```
+
+### Content the family did not choose
+
+A translated label, an unbroken identifier and a hundred options. The label clamps at two lines with the whole string still in the DOM, and the token breaks inside the option.
+
+Excerpt — not a complete module
+
+```html
+<sl-select-item value="urn">urn:acme:catalogue:9f2c41ab8de07c5511903fbe</sl-select-item>
+```
+
+### Searching a long list
+
+search opens the popup onto a field. The query filters the options, the span it matched is marked, and the count is announced. It is transient: it never becomes a value, it is emptied when an option is taken, and the control goes on showing the chosen label. Escape clears the query before it closes the popup, and Tab commits and leaves the control.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldLabel } from '@slotted/angular/field';
+import { SlSelect, SlSelectItem, type SelectOption } from '@slotted/angular/select';
+
+const COUNTRIES: SelectOption[] = [
+  { value: 'AR', label: 'Argentina' },
+  { value: 'AU', label: 'Australia' },
+  { value: 'AT', label: 'Austria' },
+  { value: 'BE', label: 'Belgium' },
+  { value: 'BR', label: 'Brazil' },
+  { value: 'CA', label: 'Canada' },
+  { value: 'CL', label: 'Chile' },
+  { value: 'CO', label: 'Colombia' },
+  { value: 'CI', label: 'Côte d’Ivoire' },
+  { value: 'DK', label: 'Denmark' },
+  { value: 'FI', label: 'Finland' },
+  { value: 'FR', label: 'France' },
+  { value: 'DE', label: 'Germany' },
+  { value: 'IE', label: 'Ireland' },
+  { value: 'IT', label: 'Italy' },
+  { value: 'JP', label: 'Japan' },
+  { value: 'MX', label: 'Mexico' },
+  { value: 'NL', label: 'Netherlands' },
+  { value: 'NZ', label: 'New Zealand' },
+  { value: 'NO', label: 'Norway' },
+  { value: 'PL', label: 'Poland' },
+  { value: 'PT', label: 'Portugal' },
+  { value: 'ES', label: 'Spain' },
+  { value: 'SE', label: 'Sweden' },
+  { value: 'CH', label: 'Switzerland' },
+  { value: 'TR', label: 'Türkiye' },
+  { value: 'GB', label: 'United Kingdom' },
+  { value: 'US', label: 'United States' },
+  { value: 'UY', label: 'Uruguay' },
+  { value: 'VN', label: 'Vietnam' },
+];
+
+@Component({
+  selector: 'app-select-search',
+  imports: [SlField, SlFieldLabel, SlSelect, SlSelectItem],
+  template: `
+    <div slField>
+      <label slFieldLabel>Ship-to country</label>
+      <sl-select
+        search
+        placeholder="Choose a country"
+        value="US"
+        [items]="countries"
+        [messages]="{ searchPlaceholder: 'Filter countries' }"
+      >
+        @for (country of countries; track country.value) {
+          <sl-select-item [value]="country.value" [label]="country.label" />
+        }
+      </sl-select>
+    </div>
+  `,
+})
+export class SelectSearch {
+  protected readonly countries = COUNTRIES;
+}
+```
+
+### Placement and width
+
+The popup hangs from the start edge of its control. It is never narrower than the control and grows when an option needs more room, so a narrow control does not wrap its labels. width="anchor" pins it to the width of the control.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlInline } from '@slotted/angular/inline';
+import { SlSelect, SlSelectItem, type SelectOption } from '@slotted/angular/select';
+
+const PAGE_SIZES: SelectOption[] = [
+  { value: '25', label: '25 rows' },
+  { value: '50', label: '50 rows' },
+  { value: '100', label: '100 rows' },
+];
+
+const SORTS: (SelectOption & { description: string })[] = [
+  { value: 'newest', label: 'Newest', description: 'Most recent order date first.' },
+  { value: 'total', label: 'Total', description: 'Largest order total first.' },
+  { value: 'ship-date', label: 'Ship date', description: 'Earliest promised ship date first.' },
+];
+
+@Component({
+  selector: 'app-select-placement',
+  imports: [SlInline, SlSelect, SlSelectItem],
+  template: `
+    <div slInline [gap]="3" justify="between" align="center">
+      <sl-select
+        aria-label="Rows per page"
+        side="top"
+        value="25"
+        [fullWidth]="false"
+        [items]="pageSizes"
+      >
+        @for (size of pageSizes; track size.value) {
+          <sl-select-item [value]="size.value">{{ size.label }}</sl-select-item>
+        }
+      </sl-select>
+      <sl-select
+        aria-label="Sort orders"
+        align="end"
+        width="content"
+        value="newest"
+        [fullWidth]="false"
+        [items]="sorts"
+      >
+        @for (sort of sorts; track sort.value) {
+          <sl-select-item [value]="sort.value" [description]="sort.description">{{
+            sort.label
+          }}</sl-select-item>
+        }
+      </sl-select>
+    </div>
+  `,
+})
+export class SelectPlacement {
+  protected readonly pageSizes = PAGE_SIZES;
+  protected readonly sorts = SORTS;
+}
+```
+
+### Keyboard
+
+Focus never leaves the button: the arrows, Home, End and the page keys move aria-activedescendant, and typing jumps to the first option that begins with it.
+
+Excerpt — not a complete module
+
+```html
+<sl-select typeahead [typeaheadTimeout]="500" [loop]="false">…</sl-select>
+```
+
+### In a Reactive Form
+
+The control is a ControlValueAccessor and a Validator, so formControl moves the value and required is reported by the family — the hidden native select always holds an option, so the browser cannot answer it.
+
+Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { toSignal } from '@angular/core/rxjs-interop';
+import { FormControl, FormGroup, ReactiveFormsModule, Validators } from '@angular/forms';
+import { SlButton } from '@slotted/angular/button';
+import { SlField, SlFieldError, SlFieldLabel } from '@slotted/angular/field';
+import { SlInline } from '@slotted/angular/inline';
+import {
+  SlSelect,
+  SlSelectItem,
+  type SelectOption,
+  type SelectSelection,
+} from '@slotted/angular/select';
+import { SlStack } from '@slotted/angular/stack';
+import { SlText } from '@slotted/angular/typography';
+
+const WAREHOUSES: SelectOption[] = [
+  { value: 'RNO', label: 'Reno, NV' },
+  { value: 'CMH', label: 'Columbus, OH' },
+  { value: 'SAV', label: 'Savannah, GA' },
+];
+
+const CARRIERS: SelectOption[] = [
+  { value: 'ups', label: 'UPS Ground' },
+  { value: 'fedex', label: 'FedEx Ground' },
+  { value: 'usps', label: 'USPS Priority Mail' },
+];
+
+const labelOf = (options: SelectOption[], value: SelectSelection) =>
+  options.find((option) => option.value === value)?.label;
+
+@Component({
+  selector: 'app-select-form',
+  imports: [
+    ReactiveFormsModule,
+    SlButton,
+    SlField,
+    SlFieldError,
+    SlFieldLabel,
+    SlInline,
+    SlSelect,
+    SlSelectItem,
+    SlStack,
+    SlText,
+  ],
+  template: `
+    <form novalidate [formGroup]="form" (ngSubmit)="submit()" (reset)="clear()">
+      <div slStack [gap]="5">
+        <div slField required [invalid]="missing() ? true : undefined">
+          <label slFieldLabel>Fulfilment warehouse</label>
+          <sl-select
+            name="warehouse"
+            placeholder="Choose a warehouse"
+            formControlName="warehouse"
+            [items]="warehouses"
+          >
+            @for (warehouse of warehouses; track warehouse.value) {
+              <sl-select-item [value]="warehouse.value">{{ warehouse.label }}</sl-select-item>
+            }
+          </sl-select>
+          <span slFieldError live="polite" reserve>{{
+            missing() ? 'Choose the warehouse that ships this order.' : ''
+          }}</span>
+        </div>
+        <div slField>
+          <label slFieldLabel>Carrier</label>
+          <sl-select name="carrier" formControlName="carrier" [items]="carriers">
+            @for (carrier of carriers; track carrier.value) {
+              <sl-select-item [value]="carrier.value">{{ carrier.label }}</sl-select-item>
+            }
+          </sl-select>
+        </div>
+        <div slInline [gap]="3" align="center">
+          <button slButton type="submit">Save</button>
+          <button slButton type="reset" tone="secondary" variant="outline">Reset</button>
+          @if (saved(); as message) {
+            <span slText size="sm" tone="muted">{{ message }}</span>
+          }
+        </div>
+      </div>
+    </form>
+  `,
+})
+export class SelectForm {
+  protected readonly warehouses = WAREHOUSES;
+  protected readonly carriers = CARRIERS;
+  protected readonly form = new FormGroup({
+    warehouse: new FormControl<SelectSelection>(null, Validators.required),
+    carrier: new FormControl<SelectSelection>('ups', { nonNullable: true }),
+  });
+  private readonly warehouse = toSignal(this.form.controls.warehouse.valueChanges, {
+    initialValue: this.form.controls.warehouse.value,
+  });
+  private readonly submitted = signal(false);
+  protected readonly missing = computed(() => this.submitted() && this.warehouse() === null);
+  protected readonly saved = signal<string | null>(null);
+
+  protected submit(): void {
+    this.submitted.set(true);
+    const { warehouse, carrier } = this.form.getRawValue();
+    this.saved.set(
+      this.form.valid
+        ? `Ships from ${labelOf(WAREHOUSES, warehouse)} by ${labelOf(CARRIERS, carrier)}.`
+        : null,
+    );
+  }
+
+  protected clear(): void {
+    this.submitted.set(false);
+    this.saved.set(null);
+  }
+}
+```
+
+### Composition
+
+Defaults provided once for a whole application, a summary the consumer writes as a template, and the instance reached from the template through exportAs.
+
+Excerpt — not a complete module
+
+```ts
+providers: [provideSelectDefaults({ size: 'sm', variant: 'subtle', width: 'anchor' })];
+```
+
+### controlled.ts
+
+Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { SlField, SlFieldLabel } from '@slotted/angular/field';
+import { SlSelect, SlSelectItem, type SelectSelection } from '@slotted/angular/select';
+import { SlStack } from '@slotted/angular/stack';
+
+const SPEEDS = [
+  { value: 'ground', label: 'Ground', transit: '3–5 business days', price: '$8.40' },
+  { value: 'two-day', label: 'Two-day', transit: '2 business days', price: '$18.90' },
+  { value: 'overnight', label: 'Overnight', transit: 'Next business day', price: '$42.75' },
+];
+
+@Component({
+  selector: 'app-select-controlled',
+  imports: [SlField, SlFieldLabel, SlSelect, SlSelectItem, SlStack],
+  template: `
+    <div slStack [gap]="4">
+      <div slField>
+        <label slFieldLabel>Delivery speed</label>
+        <sl-select [items]="speeds" [(value)]="speed">
+          @for (option of speeds; track option.value) {
+            <sl-select-item [value]="option.value">{{ option.label }}</sl-select-item>
+          }
+        </sl-select>
+      </div>
+      <span>Arrives in {{ chosen()?.transit }}. Shipping: {{ chosen()?.price }}</span>
+    </div>
+  `,
+})
+export class SelectControlled {
+  protected readonly speeds = SPEEDS;
+  protected readonly speed = signal<SelectSelection>('ground');
+  protected readonly chosen = computed(() =>
+    SPEEDS.find((option) => option.value === this.speed()),
+  );
+}
+```
+
+### defaults.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldLabel } from '@slotted/angular/field';
+import {
+  provideSelectDefaults,
+  SlSelect,
+  SlSelectItem,
+  type SelectOption,
+} from '@slotted/angular/select';
+import { SlStack } from '@slotted/angular/stack';
+
+const OWNERS: SelectOption[] = [
+  { value: 'avery', label: 'Avery Collins' },
+  { value: 'kenji', label: 'Kenji Watanabe' },
+  { value: 'lucia', label: 'Lucía Fernández' },
+];
+
+const SEGMENTS: SelectOption[] = [
+  { value: 'enterprise', label: 'Enterprise' },
+  { value: 'wholesale', label: 'Wholesale' },
+  { value: 'retail', label: 'Retail' },
+];
+
+@Component({
+  selector: 'app-select-defaults',
+  imports: [SlField, SlFieldLabel, SlSelect, SlSelectItem, SlStack],
+  providers: [provideSelectDefaults({ size: 'sm', variant: 'subtle', clearable: true })],
+  template: `
+    <div slStack [gap]="4">
+      <div slField>
+        <label slFieldLabel>Account owner</label>
+        <sl-select placeholder="Any owner" value="lucia" [items]="owners">
+          @for (owner of owners; track owner.value) {
+            <sl-select-item [value]="owner.value">{{ owner.label }}</sl-select-item>
+          }
+        </sl-select>
+      </div>
+      <div slField>
+        <label slFieldLabel>Segment</label>
+        <sl-select placeholder="Any segment" value="wholesale" [items]="segments">
+          @for (segment of segments; track segment.value) {
+            <sl-select-item [value]="segment.value">{{ segment.label }}</sl-select-item>
+          }
+        </sl-select>
+      </div>
+    </div>
+  `,
+})
+export class SelectDefaults {
+  protected readonly owners = OWNERS;
+  protected readonly segments = SEGMENTS;
+}
+```
+
+### descriptions.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldLabel } from '@slotted/angular/field';
+import type { GlyphName } from '@slotted/angular/icon';
+import { SlSelect, SlSelectItem, type SelectOption } from '@slotted/angular/select';
+
+const FORMATS: (SelectOption & { icon: GlyphName; description: string })[] = [
+  {
+    value: 'csv',
+    label: 'CSV',
+    icon: 'file-spreadsheet',
+    description: 'Opens in Excel and Google Sheets.',
+  },
+  {
+    value: 'pdf',
+    label: 'PDF',
+    icon: 'file-text',
+    description: 'Paginated, with the company letterhead.',
+  },
+  {
+    value: 'json',
+    label: 'JSON',
+    icon: 'file',
+    description: 'For an import into another system.',
+  },
+];
+
+@Component({
+  selector: 'app-select-descriptions',
+  imports: [SlField, SlFieldLabel, SlSelect, SlSelectItem],
+  template: `
+    <div slField>
+      <label slFieldLabel>Export format</label>
+      <sl-select value="csv" [items]="formats">
+        @for (format of formats; track format.value) {
+          <sl-select-item
+            [value]="format.value"
+            [description]="format.description"
+            [icon]="format.icon"
+            >{{ format.label }}</sl-select-item
+          >
+        }
+      </sl-select>
+    </div>
+  `,
+})
+export class SelectDescriptions {
+  protected readonly formats = FORMATS;
+}
+```
+
+### disabled-options.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldLabel } from '@slotted/angular/field';
+import { SlSelect, SlSelectItem } from '@slotted/angular/select';
+
+const CARRIERS: { value: string; label: string; disabled?: boolean; description?: string }[] = [
+  { value: 'ups', label: 'UPS Ground' },
+  { value: 'fedex', label: 'FedEx Ground' },
+  {
+    value: 'dhl',
+    label: 'DHL Express',
+    disabled: true,
+    description: 'Account on hold until invoice INV-21462 is paid.',
+  },
+  { value: 'usps', label: 'USPS Priority Mail' },
+];
+
+@Component({
+  selector: 'app-select-disabled-options',
+  imports: [SlField, SlFieldLabel, SlSelect, SlSelectItem],
+  template: `
+    <div slField>
+      <label slFieldLabel>Carrier</label>
+      <sl-select placeholder="Choose a carrier">
+        @for (carrier of carriers; track carrier.value) {
+          <sl-select-item
+            [value]="carrier.value"
+            [disabled]="carrier.disabled ?? false"
+            [description]="carrier.description"
+            >{{ carrier.label }}</sl-select-item
+          >
+        }
+      </sl-select>
+    </div>
+  `,
+})
+export class SelectDisabledOptions {
+  protected readonly carriers = CARRIERS;
+}
+```
+
+### empty.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import { SlSelect } from '@slotted/angular/select';
+
+@Component({
+  selector: 'app-select-empty',
+  imports: [SlField, SlFieldDescription, SlFieldLabel, SlSelect],
+  template: `
+    <div slField>
+      <label slFieldLabel>Purchase order to receive</label>
+      <sl-select
+        placeholder="Choose a purchase order"
+        [messages]="{ empty: 'No open purchase orders for Kiln & Co.' }"
+      ></sl-select>
+      <span slFieldDescription>Only orders awaiting receipt are listed.</span>
+    </div>
+  `,
+})
+export class SelectEmpty {}
+```
+
+### loading.ts
+
+Example
+
+```ts
+import { Component, signal } from '@angular/core';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import { SlSelect, SlSelectItem, type SelectOption } from '@slotted/angular/select';
+
+const SLOTS: SelectOption[] = [
+  { value: 'thu-am', label: 'Thursday, 8:00–12:00' },
+  { value: 'thu-pm', label: 'Thursday, 13:00–17:00' },
+  { value: 'fri-am', label: 'Friday, 8:00–12:00' },
+];
+
+/** Stands in for a request to the carrier's pickup API. */
+const fetchSlots = () =>
+  new Promise<SelectOption[]>((resolve) => setTimeout(() => resolve(SLOTS), 1500));
+
+@Component({
+  selector: 'app-select-loading',
+  imports: [SlField, SlFieldDescription, SlFieldLabel, SlSelect, SlSelectItem],
+  template: `
+    <div slField>
+      <label slFieldLabel>Pickup slot</label>
+      <sl-select
+        placeholder="Choose a slot"
+        [loading]="loading()"
+        [items]="slots()"
+        [messages]="{ loading: 'Fetching pickup slots…' }"
+        (openChange)="load($event)"
+      >
+        @for (slot of slots(); track slot.value) {
+          <sl-select-item [value]="slot.value">{{ slot.label }}</sl-select-item>
+        }
+      </sl-select>
+      <span slFieldDescription>Slots load from the carrier when the list opens.</span>
+    </div>
+  `,
+})
+export class SelectLoading {
+  protected readonly slots = signal<SelectOption[]>([]);
+  protected readonly loading = signal(false);
+  private loaded = false;
+
+  protected async load(open: boolean): Promise<void> {
+    if (!open || this.loaded || this.loading()) return;
+    this.loading.set(true);
+    this.slots.set(await fetchSlots());
+    this.loading.set(false);
+    this.loaded = true;
+  }
+}
+```
+
+### long-labels.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldLabel } from '@slotted/angular/field';
+import { SlSelect, SlSelectItem, type SelectOption } from '@slotted/angular/select';
+
+const LISTINGS: SelectOption[] = [
+  {
+    value: 'mug-sage',
+    label: 'Stoneware mug, 12 oz, sage glaze, case of 24, for the autumn wholesale catalogue',
+  },
+  { value: 'mug-sku', label: 'SKU-NW-STONEWARE-MUG-12OZ-SAGE-GLAZE-CASE24-WHOLESALE' },
+  { value: 'tumbler', label: 'Glass tumbler, 8 oz' },
+];
+
+@Component({
+  selector: 'app-select-long-labels',
+  imports: [SlField, SlFieldLabel, SlSelect, SlSelectItem],
+  template: `
+    <div slField>
+      <label slFieldLabel>Catalogue listing</label>
+      <sl-select value="mug-sage" [items]="listings">
+        @for (listing of listings; track listing.value) {
+          <sl-select-item [value]="listing.value">{{ listing.label }}</sl-select-item>
+        }
+      </sl-select>
+    </div>
+  `,
+})
+export class SelectLongLabels {
+  protected readonly listings = LISTINGS;
+}
+```
+
+### narrow.ts
+
+Example
+
+```ts
+import { Component, signal } from '@angular/core';
+import { SlField, SlFieldLabel } from '@slotted/angular/field';
+import {
+  SlSelect,
+  SlSelectItem,
+  type SelectOption,
+  type SelectSelection,
+} from '@slotted/angular/select';
+import { SlStack } from '@slotted/angular/stack';
+
+const STATUSES: SelectOption[] = [
+  { value: 'open', label: 'Open' },
+  { value: 'on-hold', label: 'On hold' },
+  { value: 'shipped', label: 'Shipped' },
+];
+
+const CHANNELS: SelectOption[] = [
+  { value: 'web', label: 'Web store' },
+  { value: 'marketplace', label: 'Marketplace' },
+  { value: 'wholesale', label: 'Wholesale' },
+  { value: 'phone', label: 'Phone orders' },
+];
+
+const WAREHOUSES: SelectOption[] = [
+  { value: 'RNO', label: 'Reno, NV' },
+  { value: 'CMH', label: 'Columbus, OH' },
+  { value: 'SAV', label: 'Savannah, GA' },
+];
+
+@Component({
+  selector: 'app-select-narrow',
+  imports: [SlField, SlFieldLabel, SlSelect, SlSelectItem, SlStack],
+  template: `
+    <div slStack [gap]="4" style="inline-size: 7rem">
+      <div slField>
+        <label slFieldLabel>Status</label>
+        <sl-select size="sm" value="on-hold" [items]="statuses">
+          @for (status of statuses; track status.value) {
+            <sl-select-item [value]="status.value">{{ status.label }}</sl-select-item>
+          }
+        </sl-select>
+      </div>
+      <div slField>
+        <label slFieldLabel>Channels</label>
+        <sl-select size="sm" multiple [items]="channels" [(value)]="chosenChannels">
+          @for (channel of channels; track channel.value) {
+            <sl-select-item [value]="channel.value">{{ channel.label }}</sl-select-item>
+          }
+        </sl-select>
+      </div>
+      <div slField>
+        <label slFieldLabel>Warehouse</label>
+        <sl-select size="sm" width="content" value="CMH" [items]="warehouses">
+          @for (warehouse of warehouses; track warehouse.value) {
+            <sl-select-item [value]="warehouse.value">{{ warehouse.label }}</sl-select-item>
+          }
+        </sl-select>
+      </div>
+    </div>
+  `,
+})
+export class SelectNarrow {
+  protected readonly statuses = STATUSES;
+  protected readonly channels = CHANNELS;
+  protected readonly warehouses = WAREHOUSES;
+  protected readonly chosenChannels = signal<SelectSelection>(['web', 'marketplace', 'wholesale']);
+}
+```
+
+### status-filter.ts
+
+Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import type { GlyphName } from '@slotted/angular/icon';
+import { SlInline } from '@slotted/angular/inline';
+import {
+  SlSelect,
+  SlSelectItem,
+  SlSelectSeparator,
+  type SelectOption,
+  type SelectSelection,
+} from '@slotted/angular/select';
+import { SlStack } from '@slotted/angular/stack';
+import {
+  SlTable,
+  SlTableBody,
+  SlTableCell,
+  SlTableColumnHeader,
+  SlTableContent,
+  SlTableHead,
+  SlTableRow,
+  SlTableRowHeader,
+} from '@slotted/angular/table';
+import { SlText } from '@slotted/angular/typography';
+
+const ORDERS = [
+  { id: 'SO-10482', customer: 'Harbor & Pine', status: 'open', total: '$1,240.00' },
+  { id: 'SO-10483', customer: 'Brightline Studio', status: 'on-hold', total: '$318.50' },
+  { id: 'SO-10484', customer: 'Northgate Labs', status: 'shipped', total: '$2,906.10' },
+  { id: 'SO-10485', customer: 'Verde Kitchen', status: 'delayed', total: '$86.00' },
+  { id: 'SO-10486', customer: 'Quill & Co.', status: 'shipped', total: '$540.25' },
+  { id: 'SO-10487', customer: 'Atlas Freight', status: 'open', total: '$1,912.00' },
+];
+
+const STATUSES: (SelectOption & { icon: GlyphName })[] = [
+  { value: 'open', label: 'Open', icon: 'circle' },
+  { value: 'on-hold', label: 'On hold', icon: 'clock' },
+  { value: 'delayed', label: 'Delayed', icon: 'triangle-alert' },
+  { value: 'shipped', label: 'Shipped', icon: 'circle-check' },
+];
+
+const ALL: SelectOption = { value: 'all', label: 'All statuses' };
+
+@Component({
+  selector: 'app-select-status-filter',
+  imports: [
+    SlInline,
+    SlSelect,
+    SlSelectItem,
+    SlSelectSeparator,
+    SlStack,
+    SlTable,
+    SlTableBody,
+    SlTableCell,
+    SlTableColumnHeader,
+    SlTableContent,
+    SlTableHead,
+    SlTableRow,
+    SlTableRowHeader,
+    SlText,
+  ],
+  template: `
+    <div slStack [gap]="3">
+      <div slInline [gap]="3" justify="between" align="center">
+        <span slText size="sm" tone="muted">{{ rows().length }} of {{ orders.length }} orders</span>
+        <sl-select
+          aria-label="Filter by status"
+          size="sm"
+          align="end"
+          [fullWidth]="false"
+          [items]="options"
+          [(value)]="status"
+        >
+          <sl-select-item [value]="all.value">{{ all.label }}</sl-select-item>
+          <sl-select-separator />
+          @for (option of statuses; track option.value) {
+            <sl-select-item [value]="option.value" [icon]="option.icon">{{
+              option.label
+            }}</sl-select-item>
+          }
+        </sl-select>
+      </div>
+      <div slTable [columns]="4">
+        <div slTableContent aria-label="Orders">
+          <thead slTableHead>
+            <tr slTableRow>
+              <th slTableColumnHeader>Order</th>
+              <th slTableColumnHeader>Customer</th>
+              <th slTableColumnHeader>Status</th>
+              <th slTableColumnHeader numeric>Total</th>
+            </tr>
+          </thead>
+          <tbody slTableBody>
+            @for (order of rows(); track order.id) {
+              <tr slTableRow [value]="order.id">
+                <th slTableRowHeader>{{ order.id }}</th>
+                <td slTableCell>{{ order.customer }}</td>
+                <td slTableCell>{{ labelOf(order.status) }}</td>
+                <td slTableCell numeric>{{ order.total }}</td>
+              </tr>
+            }
+          </tbody>
+        </div>
+      </div>
+    </div>
+  `,
+})
+export class SelectStatusFilter {
+  protected readonly orders = ORDERS;
+  protected readonly statuses = STATUSES;
+  protected readonly all = ALL;
+  protected readonly options = [ALL, ...STATUSES];
+  protected readonly status = signal<SelectSelection>('all');
+  protected readonly rows = computed(() => {
+    const status = this.status();
+    return status === 'all' ? ORDERS : ORDERS.filter((order) => order.status === status);
+  });
+
+  protected labelOf(status: string): string | undefined {
+    return STATUSES.find((option) => option.value === status)?.label;
+  }
+}
+```