@bitforgehq/ui 0.3.0

package/ai/components/button.md

@@ -0,0 +1,431 @@
+# bf-button
+
+Pill-shaped action button with five variants, three sizes and a loading state
+
+`BfButtonComponent` from `@bitforgehq/ui` · Actions · since 0.1.0
+
+## Example
+
+```ts
+import { Component, DestroyRef, inject, signal } from '@angular/core';
+import { RouterLink } from '@angular/router';
+import { BfButtonComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { ArrowRight, Plus } from 'lucide';
+
+/**
+ * The bf-button overview.
+ *
+ * Live demo of `bf-button`: the five variants, plus loading, size and icon-start examples; every press is reported under the buttons; then the sm, md and lg sizes in a row, and an `a[bfButton]` link to this page's "As a link" section.
+ */
+@Component({
+  selector: 'app-example-button-overview',
+  imports: [RouterLink, BfButtonComponent, BfIconComponent],
+  template: `
+    <div class="flex flex-col gap-3">
+      <div class="flex flex-wrap items-center gap-3">
+        <bf-button (clicked)="press('Primary')">Primary</bf-button>
+        <bf-button variant="tonal" (clicked)="press('Tonal')">Tonal</bf-button>
+        <bf-button variant="outline" (clicked)="press('Outline')">Outline</bf-button>
+        <bf-button variant="text" (clicked)="press('Text')">Text</bf-button>
+        <bf-button variant="danger" (clicked)="press('Danger')">Danger</bf-button>
+      </div>
+      <div class="flex flex-wrap items-center gap-3">
+        <bf-button [loading]="saving()" (clicked)="save()">Save changes</bf-button>
+        <bf-button size="sm" (clicked)="press('Small')">Small</bf-button>
+        <bf-button variant="tonal" (clicked)="press('New task')">
+          <bf-icon bfSlot="icon-start" [icon]="plus" />
+          New task
+        </bf-button>
+        <bf-button variant="outline" [disabled]="true">Disabled</bf-button>
+      </div>
+      <p data-status aria-live="polite" class="text-caption text-text-muted">{{ status() }}</p>
+      <div data-sizes class="flex flex-wrap items-center gap-3">
+        <bf-button size="sm" variant="tonal">sm · 32 px</bf-button>
+        <bf-button variant="tonal">md · 40 px</bf-button>
+        <bf-button size="lg" variant="tonal">lg · 48 px</bf-button>
+      </div>
+      <!-- a[bfButton]: a real link (Enter, Ctrl/Cmd-click opens a new tab) that looks like the button. -->
+      <div data-links class="flex flex-wrap items-center gap-3">
+        <a bfButton variant="outline" routerLink="/components/button" fragment="as-a-link">
+          Button as a link
+          <bf-icon bfSlot="icon-end" [icon]="arrowRight" class="rtl:-scale-x-100" />
+        </a>
+      </div>
+    </div>
+  `,
+})
+export class ButtonOverviewExampleComponent {
+  private readonly destroyRef = inject(DestroyRef);
+
+  readonly plus = Plus;
+  readonly arrowRight = ArrowRight;
+  readonly saving = signal(false);
+  readonly status = signal('Press a button.');
+
+  /** The pending fake-save timer, so it can be cancelled if the page is left mid-save. */
+  private saveTimeoutId: ReturnType<typeof setTimeout> | undefined;
+
+  constructor() {
+    this.destroyRef.onDestroy(() => {
+      if (this.saveTimeoutId !== undefined) {
+        clearTimeout(this.saveTimeoutId);
+      }
+    });
+  }
+
+  press(name: string): void {
+    this.status.set(`Pressed ${name}.`);
+  }
+
+  /** Starts a two-second fake save; the button shows its spinner meanwhile. */
+  save(): void {
+    this.saving.set(true);
+    this.status.set('Saving…');
+    this.saveTimeoutId = setTimeout(() => {
+      this.saveTimeoutId = undefined;
+      this.saving.set(false);
+      this.status.set('Saved.');
+    }, 2000);
+  }
+}
+```
+
+## Overview
+
+Also matches: `a[bfButton]`
+
+Pill-shaped action button with five variants, three sizes, a loading state and icon slots. Put
+the label in the default slot and icons in the `icon-start` / `icon-end` slots; never place a
+`bf-button` inside another interactive element. For navigation, put `bfButton` on your own `<a>`
+(with `href` or `routerLink`): it renders as a real link that looks like the button.
+
+Buttons trigger an action or move the user forward. The shape is a pill in every variant; the variant encodes emphasis, so a screen reads correctly at a glance: one `primary`, `tonal` beside it, `text` for low-emphasis actions inside cards and rows.
+
+## When to use
+
+Use `bf-button` for an action on the page (Save, Send, open a dialog) and `a[bfButton]` for navigation that should look like a button (Get started, View invoice). Use [bf-icon-button](https://bitforge-ui.web.app/components/icon-button) instead for an action shown as an icon alone, [bf-menu-button](https://bitforge-ui.web.app/components/menu-button) when the button opens a list of actions, and a plain link inside running text.
+
+## Basic usage
+
+The label goes in the default slot. `clicked` fires on click while the button is enabled and not loading.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfButtonComponent } from '@bitforgehq/ui';
+
+/**
+ * A button that reports its clicks.
+ *
+ * The label goes in the default slot; `clicked` fires while the button is enabled and not loading.
+ */
+@Component({
+  selector: 'app-example-button-basic',
+  imports: [BfButtonComponent],
+  template: `
+    <div class="flex flex-col items-start gap-3">
+      <bf-button (clicked)="save()">Save changes</bf-button>
+      <p aria-live="polite" class="text-caption text-text-muted">{{ status() }}</p>
+    </div>
+  `,
+})
+export class ButtonBasicExampleComponent {
+  protected readonly status = signal('Not saved yet.');
+
+  protected save(): void {
+    this.status.set('Saved.');
+  }
+}
+```
+
+## Variants
+
+`primary` (filled sage), `tonal` (soft tint), `outline`, `text` and `danger`.
+
+```ts
+import { Component } from '@angular/core';
+import { BfButtonComponent } from '@bitforgehq/ui';
+
+/** The five button variants. */
+@Component({
+  selector: 'app-example-button-variants',
+  imports: [BfButtonComponent],
+  template: `
+    <div class="flex flex-wrap items-center gap-3">
+      <bf-button>Primary</bf-button>
+      <bf-button variant="tonal">Tonal</bf-button>
+      <bf-button variant="outline">Outline</bf-button>
+      <bf-button variant="text">Text</bf-button>
+      <bf-button variant="danger">Delete</bf-button>
+    </div>
+  `,
+})
+export class ButtonVariantsExampleComponent {}
+```
+
+## Sizes
+
+`sm` 32 px, `md` 40 px (default), `lg` 48 px — the `BfSize` scale shared with the fields, chips and segmented controls. Unset, `size` follows `provideBfDefaults()`'s `controlSize`, `md` by default (`provideBfDefaults({ size: 'lg' })` enlarges every control of a Capacitor app; `{ size: 'sm' }` in a component's `providers` makes a dense sub-tree). Under a fine pointer (mouse, trackpad) the visible box is the hit area (32 px and up, above the 24 px of WCAG 2.5.8), so dense rows never overlap; under a coarse pointer (touch) `sm` and `md` grow to a 44 px hit area through an invisible extension. The `outline` variant's extension adds its 1.5 px border back, so it reaches 44 px too.
+
+```ts
+import { Component } from '@angular/core';
+import { BfButtonComponent } from '@bitforgehq/ui';
+
+/** The sm, md and lg button sizes. */
+@Component({
+  selector: 'app-example-button-sizes',
+  imports: [BfButtonComponent],
+  template: `
+    <div class="flex flex-wrap items-center gap-3">
+      <bf-button size="sm">Small</bf-button>
+      <bf-button>Medium</bf-button>
+      <bf-button size="lg">Large</bf-button>
+    </div>
+  `,
+})
+export class ButtonSizesExampleComponent {}
+```
+
+## Icons
+
+Icons go into the `icon-start` or `icon-end` slot so spacing stays consistent.
+
+```ts
+import { Component } from '@angular/core';
+import { BfButtonComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { Plus } from 'lucide';
+
+/** A button with an icon in its icon-start slot. */
+@Component({
+  selector: 'app-example-button-icons',
+  imports: [BfButtonComponent, BfIconComponent],
+  template: `
+    <bf-button variant="tonal">
+      <bf-icon bfSlot="icon-start" [icon]="plus" />
+      New task
+    </bf-button>
+  `,
+})
+export class ButtonIconsExampleComponent {
+  protected readonly plus = Plus;
+}
+```
+
+## Loading and disabled
+
+`loading` swaps the start icon for a spinner and blocks activation, but keeps the variant fill and keyboard focus: the button reports `aria-disabled` and `aria-busy` instead of turning natively disabled, and a click on it is cancelled (so a `type="submit"` button cannot submit twice). `disabled` disables it outright. Neither emits `clicked`.
+
+```ts
+import { Component, DestroyRef, inject, signal } from '@angular/core';
+import { BfButtonComponent } from '@bitforgehq/ui';
+
+/**
+ * A loading button and a disabled one.
+ *
+ * Save shows its spinner for a second and stays focusable meanwhile; the disabled button is
+ * natively disabled.
+ */
+@Component({
+  selector: 'app-example-button-loading',
+  imports: [BfButtonComponent],
+  template: `
+    <div class="flex flex-wrap items-center gap-3">
+      <bf-button [loading]="saving()" (clicked)="save()">Save</bf-button>
+      <bf-button [disabled]="true">Unavailable</bf-button>
+    </div>
+  `,
+})
+export class ButtonLoadingExampleComponent {
+  protected readonly saving = signal(false);
+  private timer: ReturnType<typeof setTimeout> | undefined;
+
+  constructor() {
+    inject(DestroyRef).onDestroy(() => clearTimeout(this.timer));
+  }
+
+  protected save(): void {
+    this.saving.set(true);
+    this.timer = setTimeout(() => this.saving.set(false), 1000);
+  }
+}
+```
+
+## Full width
+
+```ts
+import { Component } from '@angular/core';
+import { BfButtonComponent } from '@bitforgehq/ui';
+
+/** A button that fills its container. */
+@Component({
+  selector: 'app-example-button-full-width',
+  imports: [BfButtonComponent],
+  template: `<bf-button [fullWidth]="true">Continue</bf-button>`,
+})
+export class ButtonFullWidthExampleComponent {}
+```
+
+## As a link
+
+Navigation is a link, not a button: put `bfButton` on your own `<a>` and give it `href` or `routerLink`. The `<a>` itself takes the button's variant, size and full-width classes (no inner `<button>`, no underline), so it looks exactly like the button form, while the browser treats it as a link: Enter follows it (Space does not), Ctrl/Cmd-click and middle-click open it in a new tab, and the URL shows on hover and can be copied. The widget stays router-free; `clicked` still emits on every click. The underline is removed with an important utility, so an unlayered global rule of the app (`a { text-decoration: underline }`) cannot bring it back; a global unlayered link colour (`a:visited { color: … }`) can still win over the variant's text colour, so scope such rules away from buttons (`a:not([bfButton])`). `type`, `disabled` and `loading` do not apply: a link is never disabled, so render a disabled `bf-button` instead while the destination is unavailable.
+
+```ts
+import { Component } from '@angular/core';
+import { RouterLink } from '@angular/router';
+import { BfButtonComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { ExternalLink } from 'lucide';
+
+/**
+ * Links that look like buttons.
+ *
+ * `bfButton` on your own `<a>`: a router link and an external link with an icon-end.
+ */
+@Component({
+  selector: 'app-example-button-link',
+  imports: [RouterLink, BfButtonComponent, BfIconComponent],
+  template: `
+    <div class="flex flex-wrap items-center gap-3">
+      <a bfButton variant="outline" routerLink="/components">All components</a>
+      <a bfButton variant="text" size="sm" href="https://bitforge.ch">
+        Bitforge
+        <bf-icon bfSlot="icon-end" [icon]="externalLink" />
+      </a>
+    </div>
+  `,
+})
+export class ButtonLinkExampleComponent {
+  protected readonly externalLink = ExternalLink;
+}
+```
+
+## Desktop
+
+Hover darkens the fill (`primary`, `tonal`, `danger`), the border (`outline`) or the text (`text`), with the pointer cursor; a disabled button shows `not-allowed`. Hover styles apply only on devices that can hover, so a tap never leaves one stuck. The focus ring shows on keyboard focus only (`focus-visible`), never after a mouse click. Under a fine pointer the visible box is the hit area, so `sm` (32 px) buttons sit side by side in toolbars and table rows without overlapping hit areas. Desktop density is the default `md` step; `provideBfDefaults({ size: 'sm' })`, or `{ size: 'sm' }` in a component's `providers`, makes a dense toolbar, table or sidebar ([density guide](https://bitforge-ui.web.app/density)).
+
+## Theming
+
+Consumes tokens by variant, rest → hover:
+
+- `primary`: `primary` / `on-primary` → `primary-hover`
+- `tonal`: `primary-soft` / `primary-strong` → `primary-soft-hover`
+- `outline`: `surface` / `text` / `border-strong` (the control boundary, ≥ 3:1) → `text-muted` border; focus swaps the border to `primary`
+- `text`: `primary-text` (primary as text, ≥ 4.5:1 on `bg` and `surface`) → `primary-strong`
+- `danger`: `danger-soft` / `danger` → `danger` / `danger-soft`
+
+Pressed (while the mouse button, a touch or the Space key holds it down): `primary` →
+`primary-pressed`; `tonal`, `outline` and `text` → `primary-soft-pressed` (the `text` label turns
+`primary-strong`); `danger` → `danger-pressed` with `danger-soft` text. `a[bfButton]` presses the
+same way. A disabled or loading button has no pressed state, and under forced colours the system
+colours win.
+
+Enabled buttons show a pointer cursor. Disabled (any variant): `surface-sunken` / `text-disabled`, border turns transparent (never opacity), `not-allowed` cursor. Focus ring: `ring` (≥ 3:1 on `bg` and `surface`). Shape: `rounded-control` (`--radius-control`, `9999px` by default, so a pill); override the token to move every pill control off the pill at once.
+
+Icon and label sit 8 px apart. A label longer than its container truncates with an ellipsis; the icons keep their size.
+
+## Accessibility
+
+`bf-button` renders a native `<button>`; its `type` reflects the `type` input. Native `disabled` is set only by `disabled`. While `loading`, the button stays focusable and in the tab order with `aria-disabled="true"` and `aria-busy="true"`, so focus does not fall to `<body>` when an action starts; a click or Enter/Space is cancelled (`preventDefault`) and emits nothing. The spinner inside is `decorative`, so it adds no second status announcement; announce the outcome in your own message. Being a real button, it gets keyboard activation (Enter/Space) and the button role for free — no ARIA role is added. The focus-visible ring uses the `ring` token.
+
+`a[bfButton]` is your own `<a>`, so it keeps the link role and link keyboard behaviour ([WAI-ARIA APG link pattern](https://www.w3.org/WAI/ARIA/apg/patterns/link/)): it is exposed as `link`, is in the tab order while it has an `href` (in Safari and iOS WKWebView, Tab reaches links only when the user turns on "Press Tab to highlight each item" (Option+Tab otherwise); VoiceOver and Full Keyboard Access are unaffected), activates with Enter only, and opens in a new tab with Ctrl/Cmd-click. Use it whenever activation navigates to a URL, and `bf-button` whenever it performs an action on the page ([APG button pattern](https://www.w3.org/WAI/ARIA/apg/patterns/button/)). No ARIA is added, and none of `disabled`, `loading` or `type` applies.
+
+### Keyboard
+
+| Key                                 | Action                                                                                         |
+| ----------------------------------- | ---------------------------------------------------------------------------------------------- |
+| <kbd>Tab</kbd>                      | Moves focus to the button; a `loading` one stays in the tab order, a `disabled` one is skipped |
+| <kbd>Enter</kbd> / <kbd>Space</kbd> | `bf-button`: activates it and emits `clicked`; nothing while `loading`                         |
+| <kbd>Enter</kbd>                    | `a[bfButton]`: follows the link; <kbd>Space</kbd> does not                                     |
+
+## Inputs
+
+| Name        | Type                                                                          | Default     | Description                                                                                                                                                                                                  |
+| ----------- | ----------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `variant`   | `BfButtonVariant` (`'primary' \| 'tonal' \| 'outline' \| 'text' \| 'danger'`) | `'primary'` | Visual style: primary (filled), tonal (soft tint), outline, text, danger.                                                                                                                                    |
+| `size`      | `BfSize \| undefined` (`'sm' \| 'md' \| 'lg' \| undefined`)                   | `undefined` | Height step: sm 32, md 40, lg 48 px; unset follows `provideBfDefaults()` (`controlSize`, `md` by default).                                                                                                   |
+| `type`      | `BfButtonType` (`'button' \| 'submit' \| 'reset'`)                            | `'button'`  | Native button type. Use `submit` inside a form. Ignored on `a[bfButton]`.                                                                                                                                    |
+| `disabled`  | `boolean`                                                                     | `false`     | Disables the control and swallows clicks. Ignored on `a[bfButton]`: a link is never disabled; render a disabled `bf-button` instead.                                                                         |
+| `loading`   | `boolean`                                                                     | `false`     | Shows a spinner instead of the start icon and blocks activation. The button stays focusable (`aria-disabled` and `aria-busy`, never native `disabled`) and keeps its variant fill. Ignored on `a[bfButton]`. |
+| `fullWidth` | `boolean`                                                                     | `false`     | Stretches the button to its container's width.                                                                                                                                                               |
+
+## Outputs
+
+| Name      | Payload | Description                                                                                                  |
+| --------- | ------- | ------------------------------------------------------------------------------------------------------------ |
+| `clicked` | `Event` | Emitted on click while enabled and not loading; on `a[bfButton]`, on every click (the link still navigates). |
+
+## Slots
+
+- `icon-start`: An icon before the label.
+- `default`: The label.
+- `icon-end`: An icon after the label.
+
+## Notes
+
+### Do
+
+- Use `primary` once per screen for the main action; `tonal` for secondary actions next to it; `text` for low-emphasis actions inside cards and lists.
+- Bind `[loading]` to the pending state of the action so the user gets feedback and cannot double-submit.
+- Use `type="submit"` inside a `<form>` so Enter submits.
+
+### Don't
+
+- Don't nest `bf-button` in an `<a>` or another button, and don't navigate from `(clicked)`; put `bfButton` on the `<a>` itself (`<a bfButton routerLink="…">`).
+- Don't disable a link; render a disabled `bf-button` while the destination is unavailable.
+- Don't add `dark:` classes or colors on the element; the theme handles both.
+- Don't put a `bf-icon` in the default slot; use the `icon-start` / `icon-end` slots so spacing stays right.
+- Don't rely on truncation for long labels (German "Einstellungen speichern" in a narrow row): shorten the label or give the button the room; the ellipsis is a safety net.
+
+## Migration notes
+
+### 0.3.0
+
+**Behaviour:** `size` is a `BfSize` and, unset, follows `provideBfDefaults()`'s `controlSize`
+(`md` by default, as before). The 44 px hit extension of `sm` and `md` applies only under a coarse
+pointer (`pointer-coarse:`), so dense desktop rows do not overlap; the `outline` variant's
+extension adds its 1.5 px border back and reaches 44 px (was 42). See Migration 5 for
+`BfButtonSize`.
+
+New link form: the selector is `bf-button, a[bfButton]`. `<a bfButton routerLink="…">` (or
+`href`) puts the variant, size and full-width classes on your own `<a>` (plus an important
+`no-underline!`, so an unlayered global link rule cannot underline it; no
+inner `<button>`), so a navigation action is a real link that looks like the button: exposed as
+`link`, activated with Enter (not Space), opened in a new tab with Ctrl/Cmd-click, the URL
+visible. `clicked` still emits; `type`, `disabled` and `loading` do not apply (a link is never
+disabled; render a disabled `bf-button` instead). Additive. The host of `bf-button` now binds its
+classes through `[class]`; a consumer's own `class` on the element is kept.
+
+**Behaviour:** the `text` variant is coloured `primary-text` (new token, ≥ 4.5:1 on `bg` and
+`surface`; was `primary`), still `primary-strong` on hover. The `danger` variant's hover label is
+`danger-soft` on `danger` (was `on-primary`, which a custom light primary can turn black, 2.7:1 on
+the default danger).
+
+**Behaviour:** shaped with the new `rounded-control` (`--radius-control`, `9999px` by default, so
+it renders as before); override the token to move off the pill.
+
+JSDoc of `button.component.ts` for the API reference: `@summary`/`@since` on the exported symbols;
+`@slot` docs for `icon-start`, `default`, `icon-end`; template handlers and framework hooks marked
+`@internal`, so the reference leaves them out. No behaviour change.
+
+**Behaviour:** a pressed state (F-045): `primary` takes `primary-pressed`, `tonal`, `outline` and `text` `primary-soft-pressed` (the `text` label turns `primary-strong`), `danger` `danger-pressed` with `danger-soft` text, while the button is held down (`enabled:active:`, and `active:` on `a[bfButton]`). None while disabled or loading; under forced colours the system colours win.
+
+### 0.2.0
+
+The loading spinner is `md` (20 px), the size of a default `bf-icon`, so swapping the start icon
+for the spinner no longer changes the button's width. The `outline` border is `border-strong`
+(hover `text-muted`). The label renders in a `data-label` span that truncates with an ellipsis
+(`max-w-full min-w-0 truncate`) when the container is narrower than the label; the icons keep
+their size, and the host and button are capped at `max-w-full`.
+
+Fixed: the enabled button shows a pointer cursor (`cursor-pointer`; Tailwind's preflight gave
+`<button>` the default arrow), `not-allowed` when disabled.
+
+Behaviour change: `loading` no longer sets native `disabled`, so keyboard focus stays on the button
+when an action starts (it fell to `<body>` in Chromium and WebKit). While loading the button carries
+`aria-disabled="true"` and `aria-busy="true"`, stays in the tab order, cancels a click or Enter/Space
+with `preventDefault()` (a `type="submit"` button no longer submits its form) and emits nothing. It
+keeps its variant fill instead of the disabled grey, with a `cursor-progress` cursor (a new `STATE`
+class map: `idle` `cursor-pointer`, `loading` `cursor-progress`). The spinner inside is
+`decorative`, so it adds no second status announcement. Consumers styling `:disabled` on a loading
+button see the change.