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

package/docs/button.examples.md

@@ -0,0 +1,621 @@
+<!-- index: ./index.md -->
+# button
+
+`data-ui="button"` · Button, link button, icon button and toggle button.
+
+## Examples
+
+### An action
+
+Excerpt — not a complete module
+
+```html
+<button slButton (click)="save()">
+  <span slButtonStart><ng-icon aria-hidden="true" name="lucideSave" /></span>
+  Save changes
+</button>
+```
+
+### Waiting for the action to finish
+
+Excerpt — not a complete module
+
+```html
+<button
+  slButton
+  [loading]="saving()"
+  [loadingDelay]="300"
+  [messages]="{ loading: 'Saving' }"
+  (click)="save()"
+>
+  <span slButtonStart><ng-icon aria-hidden="true" name="lucideSave" /></span>
+  Save changes
+</button>
+```
+
+### Every action in the application, decided once
+
+Excerpt — not a complete module
+
+```ts
+bootstrapApplication(App, {
+  providers: [provideButtonDefaults({ size: 'sm' })],
+});
+```
+
+### Navigating
+
+Excerpt — not a complete module
+
+```html
+<a slButtonLink href="/settings">Open settings</a>
+```
+
+### Navigation the router owns
+
+Excerpt — not a complete module
+
+```html
+<a slButtonLink variant="outline" routerLink="/settings">Open settings</a>
+```
+
+### A named icon-only action
+
+Excerpt — not a complete module
+
+```html
+<button slIconButton tone="danger" aria-label="Delete invoice" (click)="remove()">
+  <ng-icon aria-hidden="true" name="lucideTrash2" />
+</button>
+```
+
+### An icon toggle in a toolbar
+
+Excerpt — not a complete module
+
+```html
+<button slIconButton aria-label="Bold" [pressed]="bold()" (pressedChange)="bold.set($event.value)">
+  <ng-icon aria-hidden="true" name="lucideBold" />
+</button>
+```
+
+### A toggle that owns its own state
+
+Excerpt — not a complete module
+
+```html
+<button slToggleButton defaultPressed>Pin</button>
+```
+
+### A toggle the consumer owns, with the reason
+
+Excerpt — not a complete module
+
+```html
+<button slToggleButton [pressed]="pinned()" (pressedChange)="onPinnedChange($event)">Pin</button>
+```
+
+### confirm-delete.ts
+
+Example
+
+```ts
+import { Component, signal } from '@angular/core';
+import { SlButton, SlButtonStart } from '@slotted/angular/button';
+import {
+  SlAlertDialog,
+  SlAlertDialogAction,
+  SlAlertDialogCancel,
+  SlAlertDialogIcon,
+  SlDialogDescription,
+  SlDialogFooter,
+  SlDialogHeader,
+  SlDialogTitle,
+  SlDialogTrigger,
+} from '@slotted/angular/dialog';
+import { SlGlyph } from '@slotted/angular/icon';
+import { SlInline } from '@slotted/angular/inline';
+import { SlText } from '@slotted/angular/typography';
+
+@Component({
+  selector: 'app-button-confirm-delete',
+  imports: [
+    SlAlertDialog,
+    SlAlertDialogAction,
+    SlAlertDialogCancel,
+    SlAlertDialogIcon,
+    SlButton,
+    SlButtonStart,
+    SlDialogDescription,
+    SlDialogFooter,
+    SlDialogHeader,
+    SlDialogTitle,
+    SlDialogTrigger,
+    SlGlyph,
+    SlInline,
+    SlText,
+  ],
+  template: `
+    <div slInline align="center" [gap]="2">
+      <button
+        slButton
+        tone="danger"
+        variant="outline"
+        focusableWhenDisabled
+        [disabled]="deleted()"
+        [slDialogTrigger]="dialog"
+      >
+        <span slButtonStart><svg slGlyph name="trash"></svg></span>
+        Delete supplier
+      </button>
+      <sl-alert-dialog #dialog="slAlertDialog" [(open)]="open">
+        <header slDialogHeader>
+          <span slAlertDialogIcon></span>
+          <h2 slDialogTitle>Delete Northwind Traders?</h2>
+          <p slDialogDescription>
+            The supplier and its 18 open purchase orders are removed for everyone. This cannot be
+            undone.
+          </p>
+        </header>
+        <footer slDialogFooter>
+          <button slButton slAlertDialogCancel tone="secondary" variant="outline">
+            Keep supplier
+          </button>
+          <button slButton slAlertDialogAction tone="danger" (click)="deleted.set(true)">
+            Delete supplier
+          </button>
+        </footer>
+      </sl-alert-dialog>
+      @if (deleted()) {
+        <span slText size="sm" tone="muted">Northwind Traders was deleted.</span>
+        <button slButton size="sm" tone="secondary" variant="ghost" (click)="deleted.set(false)">
+          Undo
+        </button>
+      }
+    </div>
+  `,
+})
+export class ButtonConfirmDelete {
+  readonly open = signal(false);
+  readonly deleted = signal(false);
+}
+```
+
+### defaults.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { provideButtonDefaults, SlButton, SlButtonStart } from '@slotted/angular/button';
+import { SlGlyph } from '@slotted/angular/icon';
+import { SlInline } from '@slotted/angular/inline';
+
+@Component({
+  selector: 'app-button-defaults',
+  imports: [SlButton, SlButtonStart, SlGlyph, SlInline],
+  providers: [provideButtonDefaults({ size: 'sm', tone: 'secondary', variant: 'outline' })],
+  template: `
+    <div slInline [gap]="2">
+      <button slButton>
+        <span slButtonStart><svg slGlyph name="funnel"></svg></span>
+        Filter
+      </button>
+      <button slButton>Columns</button>
+      <button slButton>Export</button>
+      <button slButton tone="accent" variant="solid">
+        <span slButtonStart><svg slGlyph name="plus"></svg></span>
+        New order
+      </button>
+    </div>
+  `,
+})
+export class ButtonDefaults {}
+```
+
+### disabled.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlButton } from '@slotted/angular/button';
+import { SlInline } from '@slotted/angular/inline';
+import { SlStack } from '@slotted/angular/stack';
+import { SlText } from '@slotted/angular/typography';
+
+@Component({
+  selector: 'app-button-disabled',
+  imports: [SlButton, SlInline, SlStack, SlText],
+  template: `
+    <div slStack [gap]="2">
+      <div slInline [gap]="2">
+        <button slButton disabled tone="secondary" variant="outline">Export</button>
+        <button slButton aria-describedby="submit-hint" disabled focusableWhenDisabled>
+          Submit for approval
+        </button>
+      </div>
+      <span slText id="submit-hint" size="sm" tone="muted">
+        Add at least one line item before submitting.
+      </span>
+    </div>
+  `,
+})
+export class ButtonDisabled {}
+```
+
+### full-width.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlButton } from '@slotted/angular/button';
+import { SlStack } from '@slotted/angular/stack';
+
+@Component({
+  selector: 'app-button-full-width',
+  imports: [SlButton, SlStack],
+  template: `
+    <div slStack [gap]="2">
+      <button slButton fullWidth>Pay $1,240.00</button>
+      <button slButton fullWidth tone="secondary" variant="outline">Pay by bank transfer</button>
+    </div>
+  `,
+})
+export class ButtonFullWidth {}
+```
+
+### group.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlButton, SlIconButton } from '@slotted/angular/button';
+import { SlButtonGroup } from '@slotted/angular/button-group';
+import { SlGlyph } from '@slotted/angular/icon';
+
+@Component({
+  selector: 'app-button-group',
+  imports: [SlButton, SlButtonGroup, SlGlyph, SlIconButton],
+  template: `
+    <div slButtonGroup aria-label="Invoice actions" tone="secondary" variant="outline">
+      <button slButton>Edit</button>
+      <button slButton>Duplicate</button>
+      <button slButton>Send</button>
+      <button slIconButton aria-label="More invoice actions">
+        <svg slGlyph name="ellipsis"></svg>
+      </button>
+    </div>
+  `,
+})
+export class ButtonGroupExample {}
+```
+
+### icon-button.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlIconButton } from '@slotted/angular/button';
+import { SlGlyph } from '@slotted/angular/icon';
+import { SlInline } from '@slotted/angular/inline';
+
+@Component({
+  selector: 'app-button-icon-button',
+  imports: [SlGlyph, SlIconButton, SlInline],
+  template: `
+    <div slInline align="center" [gap]="2">
+      <button slIconButton aria-label="Copy invoice number">
+        <svg slGlyph name="copy"></svg>
+      </button>
+      <button slIconButton aria-label="Refresh balances" variant="outline">
+        <svg slGlyph name="rotate-ccw"></svg>
+      </button>
+      <button slIconButton aria-label="Delete draft" tone="danger">
+        <svg slGlyph name="trash"></svg>
+      </button>
+      <button slIconButton aria-label="Add note" shape="circle" tone="accent" variant="solid">
+        <svg slGlyph name="plus"></svg>
+      </button>
+    </div>
+  `,
+})
+export class ButtonIconButton {}
+```
+
+### icons.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlButton, SlButtonEnd, SlButtonStart } from '@slotted/angular/button';
+import { SlGlyph } from '@slotted/angular/icon';
+import { SlInline } from '@slotted/angular/inline';
+
+@Component({
+  selector: 'app-button-icons',
+  imports: [SlButton, SlButtonEnd, SlButtonStart, SlGlyph, SlInline],
+  template: `
+    <div slInline [gap]="2">
+      <button slButton>
+        <span slButtonStart><svg slGlyph name="plus"></svg></span>
+        New order
+      </button>
+      <button slButton tone="secondary" variant="outline">
+        <span slButtonStart><svg slGlyph name="upload"></svg></span>
+        Import CSV
+      </button>
+      <button slButton tone="secondary" variant="ghost">
+        Continue to payment
+        <span slButtonEnd><svg slGlyph name="chevron-right"></svg></span>
+      </button>
+    </div>
+  `,
+})
+export class ButtonIcons {}
+```
+
+### link.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlButtonEnd, SlButtonLink } from '@slotted/angular/button';
+import { SlGlyph } from '@slotted/angular/icon';
+import { SlInline } from '@slotted/angular/inline';
+
+@Component({
+  selector: 'app-button-link',
+  imports: [SlButtonEnd, SlButtonLink, SlGlyph, SlInline],
+  template: `
+    <div slInline [gap]="2">
+      <a slButtonLink href="/invoices/INV-2041">
+        View invoice
+        <span slButtonEnd><svg slGlyph name="chevron-right"></svg></span>
+      </a>
+      <a slButtonLink disabled href="/statements/2026-09.pdf" tone="secondary" variant="outline">
+        Download statement
+      </a>
+    </div>
+  `,
+})
+export class ButtonLinkExample {}
+```
+
+### loading.ts
+
+Example
+
+```ts
+import { Component, signal } from '@angular/core';
+import { SlButton, SlButtonStart } from '@slotted/angular/button';
+import { SlGlyph } from '@slotted/angular/icon';
+import { SlInline } from '@slotted/angular/inline';
+
+@Component({
+  selector: 'app-button-loading',
+  imports: [SlButton, SlButtonStart, SlGlyph, SlInline],
+  template: `
+    <div slInline [gap]="2">
+      <button
+        slButton
+        tone="secondary"
+        variant="outline"
+        [loading]="syncing()"
+        [messages]="{ loading: 'Syncing' }"
+        (click)="sync()"
+      >
+        <span slButtonStart><svg slGlyph name="rotate-ccw"></svg></span>
+        Sync inventory
+      </button>
+      <button
+        slButton
+        [loading]="sending()"
+        [loadingDelay]="300"
+        [messages]="{ loading: 'Sending' }"
+        (click)="send()"
+      >
+        Send invoice
+      </button>
+    </div>
+  `,
+})
+export class ButtonLoading {
+  readonly syncing = signal(false);
+  readonly sending = signal(false);
+
+  sync(): void {
+    this.syncing.set(true);
+    setTimeout(() => this.syncing.set(false), 2000);
+  }
+
+  send(): void {
+    this.sending.set(true);
+    setTimeout(() => this.sending.set(false), 2000);
+  }
+}
+```
+
+### sizes.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlButton } from '@slotted/angular/button';
+import { SlInline } from '@slotted/angular/inline';
+
+@Component({
+  selector: 'app-button-sizes',
+  imports: [SlButton, SlInline],
+  template: `
+    <div slInline align="center" [gap]="2">
+      <button slButton size="sm">Add line item</button>
+      <button slButton size="md">Add line item</button>
+      <button slButton size="lg">Add line item</button>
+    </div>
+  `,
+})
+export class ButtonSizes {}
+```
+
+### toggle.ts
+
+Example
+
+```ts
+import { Component, signal } from '@angular/core';
+import { SlButtonStart, SlIconButton, SlToggleButton } from '@slotted/angular/button';
+import { SlGlyph } from '@slotted/angular/icon';
+import { SlInline } from '@slotted/angular/inline';
+import { SlStack } from '@slotted/angular/stack';
+import { SlText } from '@slotted/angular/typography';
+
+@Component({
+  selector: 'app-button-toggle',
+  imports: [SlButtonStart, SlGlyph, SlIconButton, SlInline, SlStack, SlText, SlToggleButton],
+  template: `
+    <div slStack [gap]="2">
+      <div slInline align="center" [gap]="2">
+        <button
+          slToggleButton
+          [pressed]="autoRefresh()"
+          (pressedChange)="autoRefresh.set($event.value)"
+        >
+          Auto-refresh
+        </button>
+        <button slToggleButton defaultPressed>
+          <span slButtonStart><svg slGlyph name="pin"></svg></span>
+          Pin to dashboard
+        </button>
+        <button slIconButton aria-label="Mark as priority" [defaultPressed]="false">
+          <svg slGlyph name="star"></svg>
+        </button>
+      </div>
+      <span slText size="sm" tone="muted">
+        {{ autoRefresh() ? 'Balances refresh every 30 seconds.' : 'Balances refresh on demand.' }}
+      </span>
+    </div>
+  `,
+})
+export class ButtonToggle {
+  readonly autoRefresh = signal(true);
+}
+```
+
+### tones.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlButton } from '@slotted/angular/button';
+import { SlInline } from '@slotted/angular/inline';
+import { SlStack } from '@slotted/angular/stack';
+
+@Component({
+  selector: 'app-button-tones',
+  imports: [SlButton, SlInline, SlStack],
+  template: `
+    <div slStack [gap]="3">
+      <div slInline [gap]="2">
+        <button slButton>Create order</button>
+        <button slButton tone="secondary">Export</button>
+        <button slButton tone="success">Approve</button>
+        <button slButton tone="warning">Hold shipment</button>
+        <button slButton tone="danger">Void invoice</button>
+      </div>
+      <div slInline [gap]="2">
+        <button slButton variant="outline">Create order</button>
+        <button slButton tone="secondary" variant="outline">Export</button>
+        <button slButton tone="success" variant="outline">Approve</button>
+        <button slButton tone="warning" variant="outline">Hold shipment</button>
+        <button slButton tone="danger" variant="outline">Void invoice</button>
+      </div>
+    </div>
+  `,
+})
+export class ButtonTones {}
+```
+
+### toolbar.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlButton, SlButtonStart, SlIconButton } from '@slotted/angular/button';
+import { SlGlyph } from '@slotted/angular/icon';
+import { SlToolbar, SlToolbarSeparator, SlToolbarSpacer } from '@slotted/angular/toolbar';
+import { SlText } from '@slotted/angular/typography';
+
+@Component({
+  selector: 'app-button-toolbar',
+  imports: [
+    SlButton,
+    SlButtonStart,
+    SlGlyph,
+    SlIconButton,
+    SlText,
+    SlToolbar,
+    SlToolbarSeparator,
+    SlToolbarSpacer,
+  ],
+  template: `
+    <div slToolbar aria-label="Order SO-1187">
+      <button slButton tone="secondary" variant="ghost">
+        <span slButtonStart><svg slGlyph name="file-text"></svg></span>
+        Packing slip
+      </button>
+      <button slButton tone="secondary" variant="ghost">Duplicate</button>
+      <div slToolbarSeparator></div>
+      <button slIconButton aria-label="Copy order number">
+        <svg slGlyph name="copy"></svg>
+      </button>
+      <button
+        slIconButton
+        aria-describedby="delete-reason"
+        aria-label="Delete order"
+        disabled
+        focusableWhenDisabled
+        tone="danger"
+      >
+        <svg slGlyph name="trash"></svg>
+      </button>
+      <div slToolbarSpacer></div>
+      <span slText id="delete-reason" size="sm" tone="muted">
+        Shipped orders cannot be deleted.
+      </span>
+    </div>
+  `,
+})
+export class ButtonToolbar {}
+```
+
+### variants.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlButton } from '@slotted/angular/button';
+import { SlInline } from '@slotted/angular/inline';
+
+@Component({
+  selector: 'app-button-variants',
+  imports: [SlButton, SlInline],
+  template: `
+    <div slInline [gap]="2">
+      <button slButton>Publish invoice</button>
+      <button slButton tone="secondary" variant="outline">Save draft</button>
+      <button slButton tone="secondary" variant="ghost">Discard</button>
+    </div>
+  `,
+})
+export class ButtonVariants {}
+```