@bitforgehq/ui 0.3.0

package/ai/components/spinner.md

@@ -0,0 +1,171 @@
+# bf-spinner
+
+Indeterminate loading spinner in three sizes that inherits its parent's text color
+
+`BfSpinnerComponent` from `@bitforgehq/ui` · Feedback · since 0.1.0
+
+## Example
+
+```ts
+import { Component } from '@angular/core';
+import { BfSpinnerComponent } from '@bitforgehq/ui';
+
+/**
+ * The bf-spinner overview.
+ *
+ * Live demo of `bf-spinner`: the three sizes on a muted background, as it inherits `currentColor`.
+ */
+@Component({
+  selector: 'app-example-spinner-overview',
+  imports: [BfSpinnerComponent],
+  template: `
+    <div class="text-text-muted flex flex-wrap items-center gap-3">
+      <bf-spinner size="sm" />
+      <bf-spinner size="md" />
+      <bf-spinner size="lg" />
+    </div>
+  `,
+})
+export class SpinnerOverviewExampleComponent {}
+```
+
+## Overview
+
+Indeterminate progress indicator. Inherits `currentColor`, so place it inside a colored parent
+(a button, a muted paragraph) rather than coloring it directly.
+
+An indeterminate progress indicator for short waits. It inherits the current text color, so placing it inside a muted paragraph or a button gives the right tone without extra classes.
+
+## When to use
+
+Use `bf-spinner` for a short wait of unknown length inside a region: a panel loading, a list refreshing. Use [bf-button](https://bitforge-ui.web.app/components/button) `loading` instead while a button's own action runs, and [bf-progress](https://bitforge-ui.web.app/components/progress) when the share of work done is known.
+
+## Basic usage
+
+```ts
+import { Component } from '@angular/core';
+import { BfSpinnerComponent } from '@bitforgehq/ui';
+
+/** A small spinner beside its loading text. */
+@Component({
+  selector: 'app-example-spinner-basic',
+  imports: [BfSpinnerComponent],
+  template: `
+    <p class="text-text-muted flex items-center gap-2"><bf-spinner size="sm" /> Loading recipes</p>
+  `,
+})
+export class SpinnerBasicExampleComponent {}
+```
+
+## Sizes
+
+`sm` 16 px, `md` 20 px (default), `lg` 24 px: the `bf-icon` sizes, so a spinner can replace an icon without shifting the layout.
+
+```ts
+import { Component } from '@angular/core';
+import { BfSpinnerComponent } from '@bitforgehq/ui';
+
+/** The sm, md and lg spinner sizes. */
+@Component({
+  selector: 'app-example-spinner-sizes',
+  imports: [BfSpinnerComponent],
+  template: `
+    <div class="flex items-center gap-4">
+      <bf-spinner size="sm" />
+      <bf-spinner />
+      <bf-spinner size="lg" />
+    </div>
+  `,
+})
+export class SpinnerSizesExampleComponent {}
+```
+
+## Decorative
+
+Inside a control that already reports its busy state (`aria-busy`), mark the spinner `decorative` so assistive tech does not hear a second status.
+
+```ts
+import { Component } from '@angular/core';
+import { BfSpinnerComponent } from '@bitforgehq/ui';
+
+/**
+ * A decorative spinner inside a busy button.
+ *
+ * The button already says it is busy, so the spinner adds no second announcement.
+ */
+@Component({
+  selector: 'app-example-spinner-decorative',
+  imports: [BfSpinnerComponent],
+  template: `
+    <button
+      type="button"
+      aria-busy="true"
+      aria-disabled="true"
+      class="bg-surface-muted text-text rounded-control inline-flex h-10 items-center gap-2 px-4"
+    >
+      <bf-spinner size="sm" decorative /> Syncing
+    </button>
+  `,
+})
+export class SpinnerDecorativeExampleComponent {}
+```
+
+## Theming
+
+`bf-spinner` defines no color of its own. It is a pure-CSS ring (no SVG): a `rounded-full` box whose border is `currentColor` at 25 % for the track and a solid `currentColor` top edge for the arc, so it takes on whatever text color its parent sets. The ring is 14, 18 or 22 px inset by a 1 px margin, so the box stays the `bf-icon` size, with a 2, 2 or 3 px border; its arc ends are square.
+
+## Accessibility
+
+The wrapper is `role="status"` with `aria-live="polite"`; the ring itself is `aria-hidden`, and the visible-but-`sr-only` `label` text is what gets announced; without a `label` it is `provideBfLabels()`'s `loading` ("Loading"), so translate it once app-wide. With `decorative`, the spinner has no role, no live region and no label, and the wrapper is `aria-hidden="true"`: use it inside a control that already reports its busy state (a loading `bf-button` does this for you).
+
+The ring rotates only when motion is allowed (`motion-safe:animate-spin`). Under `prefers-reduced-motion: reduce` it does not rotate at all; it pulses its opacity instead (`motion-reduce:animate-pulse`), so the wait still reads as ongoing without spinning motion. Under forced colours (Windows High Contrast) the track is drawn in `GrayText` and the arc in `CanvasText`, so the arc stays distinct.
+
+## Inputs
+
+| Name         | Type                                     | Default | Description                                                                                                                                                                          |
+| ------------ | ---------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `size`       | `BfSpinnerSize` (`'sm' \| 'md' \| 'lg'`) | `'md'`  | Visual size: 16, 20 or 24 px (the `bf-icon` sizes).                                                                                                                                  |
+| `label`      | `string`                                 | `''`    | Screen-reader text; keep it a short verb phrase. Empty falls back to `provideBfLabels()`'s `loading` ("Loading"). Not rendered while `decorative`.                                   |
+| `decorative` | `boolean`                                | `false` | Hides the spinner from assistive tech (no status role, no live region, no label), for a spinner inside a control that already reports its busy state, such as a loading `bf-button`. |
+
+## Notes
+
+### Do
+
+- Give `label` a short verb phrase ("Saving") when the default "Loading" is wrong; translate the default with `provideBfLabels({ loading: 'Laden' })`.
+- Prefer `bf-button [loading]` over a spinner next to a button.
+
+### Don't
+
+- Don't color the spinner directly; color its parent.
+- Don't use it for waits longer than a few seconds; show progress or a skeleton instead.
+
+## Migration notes
+
+### 0.3.0
+
+**Behaviour:** `label` defaults to `''` and falls back to `provideBfLabels()`'s `loading`
+("Loading"); the rendered English default is unchanged.
+
+JSDoc of `spinner.component.ts` for the API reference: `@summary`/`@since` on the exported symbols.
+No behaviour change.
+
+**Behaviour:** a pure-CSS ring with no inline SVG (F-066): a `rounded-full` ring sized
+`size-3.5`, `size-4.5` or `size-5.5` (14/18/22 px, close to the old SVG's 14/17.5/21 px outer
+edge) and inset by `m-px`, so the box stays 16/20/24 px, with a `border-2`, `border-2` or
+`border-[3px]` border, `border-current/25` for the track and `border-t-current` for the arc; the
+arc ends are square. It rotates with `motion-safe:animate-spin`; under `prefers-reduced-motion` it no longer
+rotates at all but pulses its opacity (`motion-reduce:animate-pulse`, F-064). Under forced colours
+the track is `GrayText` and the arc `CanvasText`. The `decorative`, `label` and status semantics
+are unchanged.
+
+**Deprecated:** `px` (the box in px, 16/20/24): use the `size` input; removed in 0.4.0. See
+Migration 26.
+
+### 0.2.0
+
+Sizes are now the `bf-icon` sizes: `sm` 16, `md` 20 (default), `lg` 24 px (were 16/24/32).
+
+Added: `decorative` input (`booleanAttribute`). A decorative spinner has no `role="status"`, no
+`aria-live` and no `sr-only` label, and its wrapper is `aria-hidden="true"`: for a spinner inside a
+control that already reports its busy state, such as a loading `bf-button`.