@bitforgehq/ui 0.3.0

package/ai/components/icon-button.md

@@ -0,0 +1,221 @@
+# bf-icon-button
+
+Round icon-only button for toolbars and rows, with a required accessible label
+
+`BfIconButtonComponent` from `@bitforgehq/ui` · Actions · since 0.1.0
+
+## Example
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfIconButtonComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { Ellipsis, Plus, Search, X } from 'lucide';
+
+/**
+ * The bf-icon-button overview.
+ *
+ * Live demo of `bf-icon-button`: the four visual variants, each reporting its press; then the sm, md and lg sizes in a row.
+ */
+@Component({
+  selector: 'app-example-icon-button-overview',
+  imports: [BfIconButtonComponent, BfIconComponent],
+  template: `
+    <div class="flex flex-col gap-3">
+      <div class="flex flex-wrap items-center gap-3">
+        <bf-icon-button label="Search" variant="tonal" (clicked)="press('Search')">
+          <bf-icon [icon]="search" />
+        </bf-icon-button>
+        <bf-icon-button label="Add" variant="primary" (clicked)="press('Add')">
+          <bf-icon [icon]="plus" />
+        </bf-icon-button>
+        <bf-icon-button label="More" variant="outline" (clicked)="press('More')">
+          <bf-icon [icon]="ellipsis" />
+        </bf-icon-button>
+        <bf-icon-button label="Close" variant="text" (clicked)="press('Close')">
+          <bf-icon [icon]="x" />
+        </bf-icon-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-icon-button size="sm" label="New task, sm"><bf-icon [icon]="plus" /></bf-icon-button>
+        <bf-icon-button label="New task, md"><bf-icon [icon]="plus" /></bf-icon-button>
+        <bf-icon-button size="lg" label="New task, lg"><bf-icon [icon]="plus" /></bf-icon-button>
+      </div>
+    </div>
+  `,
+})
+export class IconButtonOverviewExampleComponent {
+  readonly search = Search;
+  readonly plus = Plus;
+  readonly ellipsis = Ellipsis;
+  readonly x = X;
+  readonly status = signal('Press an icon button.');
+
+  press(label: string): void {
+    this.status.set(`Pressed ${label}.`);
+  }
+}
+```
+
+## Overview
+
+Round button that holds a single icon, for toolbars, headers and list rows. The `label` is
+required because the icon alone gives assistive tech no name.
+
+A round button for a single icon: search in a header, close on a sheet, more-actions on a row. `label` is required and becomes the accessible name.
+
+## When to use
+
+Use `bf-icon-button` for a frequent action whose icon is unmistakable: search, close, more, edit in a table row. Use [bf-button](https://bitforge-ui.web.app/components/button) instead when the action needs a word to be understood, and [bf-menu-button](https://bitforge-ui.web.app/components/menu-button) with `iconOnly` for a "More" button that opens a menu.
+
+## Basic usage
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfIconButtonComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { Search } from 'lucide';
+
+/**
+ * An icon button named by its label.
+ *
+ * The label is the accessible name (and the tooltip); `clicked` reports the press.
+ */
+@Component({
+  selector: 'app-example-icon-button-basic',
+  imports: [BfIconButtonComponent, BfIconComponent],
+  template: `
+    <div class="flex items-center gap-3">
+      <bf-icon-button label="Search" (clicked)="opened.set(true)">
+        <bf-icon [icon]="search" />
+      </bf-icon-button>
+      <span aria-live="polite" class="text-caption text-text-muted">{{
+        opened() ? 'Search opened.' : ''
+      }}</span>
+    </div>
+  `,
+})
+export class IconButtonBasicExampleComponent {
+  protected readonly search = Search;
+  protected readonly opened = signal(false);
+}
+```
+
+## Variants and sizes
+
+`tonal` (default), `primary`, `outline`, `text`; square sizes `sm` 32, `md` 40 (default), `lg` 48 px, the `BfSize` scale of `bf-button`. 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.
+
+```ts
+import { Component } from '@angular/core';
+import { BfIconButtonComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { Ellipsis, Plus } from 'lucide';
+
+/** A large primary icon button and a small text one. */
+@Component({
+  selector: 'app-example-icon-button-variants',
+  imports: [BfIconButtonComponent, BfIconComponent],
+  template: `
+    <div class="flex items-center gap-3">
+      <bf-icon-button label="Add" variant="primary" size="lg"
+        ><bf-icon [icon]="plus"
+      /></bf-icon-button>
+      <bf-icon-button label="More" variant="text" size="sm"
+        ><bf-icon [icon]="ellipsis"
+      /></bf-icon-button>
+    </div>
+  `,
+})
+export class IconButtonVariantsExampleComponent {
+  protected readonly plus = Plus;
+  protected readonly ellipsis = Ellipsis;
+}
+```
+
+## Desktop
+
+Hover tints the button (`tonal`, `text`) or darkens it (`primary`, the `outline` border), with the pointer cursor; disabled 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. There is no built-in tooltip, and `label` is read by assistive tech only, so keep to icons whose meaning is clear without one. Under a fine pointer the 32/40/48 px square is the hit area. 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:
+
+- `tonal` (default): `primary-soft` / `primary-strong` → `primary-soft-hover`
+- `primary`: `primary` / `on-primary` → `primary-hover`
+- `outline`: `surface` / `text` / `border-strong` (the control boundary, ≥ 3:1) → `text-muted` border; focus swaps the border to `primary`
+- `text`: `text-muted` → `surface-muted` / `text`
+
+Pressed: `primary` → `primary-pressed`; `tonal`, `outline` and `text` → `primary-soft-pressed`
+(the `text` icon turns `text`). A disabled icon button has no pressed state.
+
+Cursor: `pointer` while enabled, `not-allowed` when disabled. Disabled (any variant):
+`surface-sunken` / `text-disabled`, border turns transparent. Focus ring: `ring`. Shape: `rounded-control` (`--radius-control`, `9999px` by default, so a pill); override the token to move every pill control off the pill at once.
+
+## Accessibility
+
+Native `<button>`; its `type` reflects the `type` input. `label` is required and becomes the button's `aria-label`, since the icon inside carries no text of its own. `disabled` sets the native attribute, which also removes it from the tab order and swallows clicks.
+
+### Keyboard
+
+| Key                                 | Action                                                 |
+| ----------------------------------- | ------------------------------------------------------ |
+| <kbd>Tab</kbd>                      | Moves focus to the button; a `disabled` one is skipped |
+| <kbd>Enter</kbd> / <kbd>Space</kbd> | Activates it and emits `clicked`                       |
+
+## Inputs
+
+| Name       | Type                                                                  | Default     | Description                                                                                                         |
+| ---------- | --------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------- |
+| `variant`  | `BfIconButtonVariant` (`'tonal' \| 'primary' \| 'outline' \| 'text'`) | `'tonal'`   | Visual style: tonal (soft tint, default), primary, outline, text.                                                   |
+| `size`     | `BfSize \| undefined` (`'sm' \| 'md' \| 'lg' \| undefined`)           | `undefined` | Height step: sm 32, md 40, lg 48 px (square); unset follows `provideBfDefaults()` (`controlSize`, `md` by default). |
+| `type`     | `BfButtonType` (`'button' \| 'submit' \| 'reset'`)                    | `'button'`  | Native button type.                                                                                                 |
+| `disabled` | `boolean`                                                             | `false`     | Disables the control and swallows clicks.                                                                           |
+| `label`    | `string`                                                              | required    | Accessible name announced instead of the icon.                                                                      |
+
+## Outputs
+
+| Name      | Payload | Description                     |
+| --------- | ------- | ------------------------------- |
+| `clicked` | `Event` | Emitted on click while enabled. |
+
+## Slots
+
+- `default`: The icon, a `bf-icon`.
+
+## Notes
+
+### Do
+
+- Write the label as the action ("Search", "Close"), not the icon name.
+- Use `text` inside list rows and cards so the row stays calm.
+
+### Don't
+
+- Don't put text in the slot; use `bf-button` with an icon slot instead.
+
+## Migration notes
+
+### 0.3.0
+
+**Behaviour:** `size` is a `BfSize` and, unset, follows `provideBfDefaults()`'s `controlSize`. The
+44 px hit extension applies only under a coarse pointer, and the `outline` variant's compensates its
+1.5 px border.
+
+**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 `icon-button.component.ts` for the API reference: `@summary`/`@since` on the exported
+symbols; `@slot` docs for `default`; 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` icon turns `text`) while the button is held down. None while disabled; under forced colours the system colours win.
+
+### 0.2.0
+
+The `outline` border is `border-strong` (hover `text-muted`).
+
+Fixed: pointer cursor while enabled, `not-allowed` when disabled.
+
+### 0.1.0
+
+New `bf-icon-button`: a round button that holds a single icon, with `tonal` (default), `primary`, `outline` and `text` variants and `sm`/`md`/`lg` (32/40/48 px) square sizes. `label` is required and renders as `aria-label` since the icon alone gives assistive tech no name. `sm` and `md` extend the hit area vertically to 44 px with an invisible `::after`, matching `bf-button`, so adjacent icon buttons in a toolbar don't overlap.

package/ai/components/icon.md

@@ -0,0 +1,176 @@
+# bf-icon
+
+Tree-shakable Lucide icon renderer, decorative by default or labelled when meaningful
+
+`BfIconComponent` from `@bitforgehq/ui/icons` · Icons · since 0.1.0
+
+## Example
+
+```ts
+import { Component } from '@angular/core';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { ChevronLeft, Heart, Search } from 'lucide';
+
+/**
+ * The bf-icon overview.
+ *
+ * Live demo of `bf-icon`: three Lucide icons across the three visual sizes.
+ */
+@Component({
+  selector: 'app-example-icon-overview',
+  imports: [BfIconComponent],
+  template: `
+    <div class="text-text flex flex-wrap items-center gap-4">
+      <bf-icon [icon]="search" size="sm" />
+      <bf-icon [icon]="search" size="md" />
+      <bf-icon [icon]="search" size="lg" />
+      <bf-icon [icon]="heart" size="sm" />
+      <bf-icon [icon]="heart" size="md" />
+      <bf-icon [icon]="heart" size="lg" />
+      <bf-icon [icon]="chevronLeft" size="sm" />
+      <bf-icon [icon]="chevronLeft" size="md" />
+      <bf-icon [icon]="chevronLeft" size="lg" />
+    </div>
+  `,
+})
+export class IconOverviewExampleComponent {
+  readonly search = Search;
+  readonly heart = Heart;
+  readonly chevronLeft = ChevronLeft;
+}
+```
+
+## Overview
+
+Renders a Lucide icon from its data, tree-shakably and without a registry.
+Import the icon you need from `lucide` (e.g. `import { Search } from 'lucide'`) and bind it.
+Decorative by default; pass `label` when the icon carries meaning on its own (e.g. an icon-only
+control without visible text).
+
+Renders a Lucide icon from its data. Import the icon you need from `lucide` and bind it; nothing is registered globally and unused icons are tree-shaken. Every widget's icon slot accepts a `bf-icon`, and also any other SVG or component, including privately licensed icon sets.
+
+## When to use
+
+Use `bf-icon` for a Lucide icon anywhere an icon is needed, in a widget's icon slot or on its own. Use [bf-icon-button](https://bitforge-ui.web.app/components/icon-button) instead when the icon is a control, and [bf-avatar](https://bitforge-ui.web.app/components/avatar) for a person.
+
+## Basic usage
+
+```ts
+import { Component } from '@angular/core';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { Search } from 'lucide';
+
+/** An icon from its imported data. */
+@Component({
+  selector: 'app-example-icon-basic',
+  imports: [BfIconComponent],
+  template: `<bf-icon [icon]="search" />`,
+})
+export class IconBasicExampleComponent {
+  readonly search = Search;
+}
+```
+
+## Sizes
+
+`sm` 16 px, `md` 20 px (default), `lg` 24 px. The stroke follows `currentColor`.
+
+```ts
+import { Component } from '@angular/core';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { Search } from 'lucide';
+
+/** A large icon that takes its colour from a text class. */
+@Component({
+  selector: 'app-example-icon-sizes',
+  imports: [BfIconComponent],
+  template: `<bf-icon [icon]="search" size="lg" class="text-text-muted" />`,
+})
+export class IconSizesExampleComponent {
+  protected readonly search = Search;
+}
+```
+
+## Filled details
+
+A few Lucide icons fill small shapes on top of their strokes: the dots of `Palette`, the points of `ChartScatter`, the hole of `KeyRound`. `bf-icon` renders every attribute Lucide sets on an element, including its `fill`, so those shapes show as solid `currentColor` dots instead of disappearing. `tools/lucide-attributes.test.ts` fails if a Lucide release adds an attribute the renderer does not bind.
+
+```ts
+import { Component } from '@angular/core';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { ChartScatter, KeyRound, Palette } from 'lucide';
+
+/** Icons whose Lucide data fills some shapes: the palette dots, the scatter points, the key hole. */
+@Component({
+  selector: 'app-example-icon-filled',
+  imports: [BfIconComponent],
+  template: `
+    <div class="text-text flex items-center gap-4">
+      <bf-icon [icon]="palette" size="lg" label="Palette" />
+      <bf-icon [icon]="chartScatter" size="lg" label="Scatter chart" />
+      <bf-icon [icon]="keyRound" size="lg" label="Key" />
+    </div>
+  `,
+})
+export class IconFilledExampleComponent {
+  protected readonly palette = Palette;
+  protected readonly chartScatter = ChartScatter;
+  protected readonly keyRound = KeyRound;
+}
+```
+
+## Theming
+
+`bf-icon` defines no color of its own; its stroke (and any fill Lucide sets) uses `currentColor`, so it takes on whatever text color its parent sets (a class like `text-text-muted`, or the button/link text color around it).
+
+## Accessibility
+
+Icons are decorative by default (`aria-hidden`). Pass `label` when the icon carries meaning on its own, for example in an icon-only control.
+
+```ts
+import { Component } from '@angular/core';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { Search } from 'lucide';
+
+/** An icon that carries meaning, named by its label. */
+@Component({
+  selector: 'app-example-icon-labelled',
+  imports: [BfIconComponent],
+  template: `<bf-icon [icon]="search" label="Search" />`,
+})
+export class IconLabelledExampleComponent {
+  protected readonly search = Search;
+}
+```
+
+## Inputs
+
+| Name    | Type                                  | Default  | Description                                                             |
+| ------- | ------------------------------------- | -------- | ----------------------------------------------------------------------- |
+| `icon`  | `IconNode`                            | required | Lucide icon data, e.g. `Search` from `lucide`.                          |
+| `size`  | `BfIconSize` (`'sm' \| 'md' \| 'lg'`) | `'md'`   | Visual size: 16, 20 or 24 px.                                           |
+| `label` | `string`                              | `''`     | Accessible name. Leave empty for decorative icons next to visible text. |
+
+## Notes
+
+### Do
+
+- Put icons in a widget's `icon-start` / `icon-end` slot rather than in its default slot.
+- Use `label` only when there is no visible text saying the same thing.
+
+### Don't
+
+- Don't inline `<svg>` markup in app templates; use `bf-icon` or an icon component.
+- Don't ship Streamline pro icons in a public package; use them in your app's private code through the slots.
+
+## Migration notes
+
+### 0.3.0
+
+JSDoc of `icon.component.ts` for the API reference: `@summary`/`@since` on the exported symbols. No
+behaviour change.
+
+**Behaviour:** `bf-icon` binds `[attr.fill]` on every element it renders (F-065), so the filled
+details of Lucide icons show (`Palette`'s dots and 9 other distinct icons); elements without a Lucide
+`fill` get no attribute and inherit the `none` of the `<svg>`. `tools/lucide-attributes.test.ts`
+fails when an installed Lucide icon sets an attribute the renderer does not bind. See Migration 27.