@bitforgehq/ui 0.3.0

package/ai/components/chip.md

@@ -0,0 +1,300 @@
+# bf-chip
+
+Toggleable filter chip with a check mark when selected, in tonal or ink style
+
+`BfChipComponent` from `@bitforgehq/ui` · Forms · since 0.1.0
+
+## Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { BfChipComponent } from '@bitforgehq/ui';
+
+/**
+ * The bf-chip overview.
+ *
+ * Live demo of `bf-chip`: a tonal filter row with two selected, and a single-choice ink row; the selection is echoed underneath; then the sm, md and lg sizes in a row.
+ */
+@Component({
+  selector: 'app-example-chip-overview',
+  imports: [BfChipComponent],
+  template: `
+    <div class="flex flex-col gap-3">
+      <div class="flex flex-wrap gap-2">
+        <bf-chip [(selected)]="filterDesign">Design</bf-chip>
+        <bf-chip [(selected)]="filterDevelopment">Development</bf-chip>
+        <bf-chip [(selected)]="filterCopy">Copy</bf-chip>
+        <bf-chip [(selected)]="filterResearch">Research</bf-chip>
+      </div>
+      <div class="flex flex-wrap gap-2">
+        @for (option of statusOptions; track option.value) {
+          <bf-chip
+            variant="ink"
+            [selected]="statusFilter() === option.value"
+            [deselectable]="false"
+            (changed)="setStatusFilter(option.value)"
+          >
+            {{ option.label }}
+          </bf-chip>
+        }
+      </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-chip size="sm">sm · 32 px</bf-chip>
+        <bf-chip>md · 40 px</bf-chip>
+        <bf-chip size="lg">lg · 48 px</bf-chip>
+      </div>
+    </div>
+  `,
+})
+export class ChipOverviewExampleComponent {
+  readonly filterDesign = signal(true);
+  readonly filterDevelopment = signal(false);
+  readonly filterCopy = signal(true);
+  readonly filterResearch = signal(false);
+
+  readonly statusFilter = signal('all');
+  readonly statusOptions: { value: string; label: string }[] = [
+    { value: 'all', label: 'All' },
+    { value: 'open', label: 'Open' },
+    { value: 'done', label: 'Done' },
+  ];
+
+  readonly status = computed(() => {
+    const filters = [
+      this.filterDesign() ? 'Design' : '',
+      this.filterDevelopment() ? 'Development' : '',
+      this.filterCopy() ? 'Copy' : '',
+      this.filterResearch() ? 'Research' : '',
+    ].filter(Boolean);
+    const status = this.statusOptions.find((o) => o.value === this.statusFilter())?.label ?? '';
+    return `Filters: ${filters.length > 0 ? filters.join(', ') : 'none'} · Status: ${status}`;
+  });
+
+  setStatusFilter(value: string): void {
+    this.statusFilter.set(value);
+  }
+}
+```
+
+## Overview
+
+Toggleable filter chip. Selected chips carry a check mark and a tint (`tonal`) or the ink
+treatment used by mobile filter rows (`ink`). For a single-choice row, put the chips in a
+`bf-chip-group`, which makes them a radio group.
+
+Chips are toggles for filters and tags. A selected chip shows a check mark and a tint; on mobile filter rows the `ink` variant gives the stronger contrast the design uses.
+
+## When to use
+
+Use `bf-chip` for filters and tags the user toggles, alone or in a row: "Open", "Mine", "This week". Use [bf-chip-group](https://bitforge-ui.web.app/components/chip-group) around the chips of a single-choice row, [bf-segmented](https://bitforge-ui.web.app/components/segmented) instead when two to four choices switch a whole view, [bf-badge](https://bitforge-ui.web.app/components/badge) for a read-only status, and [bf-checkbox](https://bitforge-ui.web.app/components/checkbox) for choices in a form that is submitted later.
+
+## Basic usage
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfChipComponent } from '@bitforgehq/ui';
+
+/** Two filter chips, each toggling its own filter. */
+@Component({
+  selector: 'app-example-chip-basic',
+  imports: [BfChipComponent],
+  template: `
+    <div class="flex flex-wrap gap-2">
+      <bf-chip [(selected)]="design">Design</bf-chip>
+      <bf-chip [(selected)]="copy">Copy</bf-chip>
+    </div>
+  `,
+})
+export class ChipBasicExampleComponent {
+  protected readonly design = signal(true);
+  protected readonly copy = signal(false);
+}
+```
+
+## Single-choice filter row
+
+For a row where exactly one chip is selected, put the chips in a [bf-chip-group](https://bitforge-ui.web.app/components/chip-group): it gives them radio semantics ("radio, 1 of 3, selected"), one tab stop and arrow-key navigation, and holds the selected chip's `value`. A row without a group keeps working as before: drive `selected` from your state and react to `changed`, with `[deselectable]="false"` so clicking the already-selected chip does nothing instead of clearing the selection; each chip then announces as a separate toggle button.
+
+`value` (any type, compared with `Object.is`) is what a chip stands for inside a `bf-chip-group`; outside one it is unused.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfChipComponent } from '@bitforgehq/ui';
+
+type View = 'all' | 'open' | 'done';
+
+/**
+ * A single-choice filter row.
+ *
+ * Exactly one chip is selected; `deselectable` false keeps the selected one from turning off.
+ */
+@Component({
+  selector: 'app-example-chip-single-choice',
+  imports: [BfChipComponent],
+  template: `
+    <div class="flex flex-wrap gap-2">
+      @for (option of options; track option.value) {
+        <bf-chip
+          variant="ink"
+          [selected]="view() === option.value"
+          [deselectable]="false"
+          (changed)="view.set(option.value)"
+          >{{ option.label }}</bf-chip
+        >
+      }
+    </div>
+  `,
+})
+export class ChipSingleChoiceExampleComponent {
+  protected readonly options: { value: View; label: string }[] = [
+    { value: 'all', label: 'All' },
+    { value: 'open', label: 'Open' },
+    { value: 'done', label: 'Done' },
+  ];
+  protected readonly view = signal<View>('all');
+}
+```
+
+## Sizes
+
+`sm` 32 px, `md` 40 px (default), `lg` 48 px — the `BfSize` scale of `bf-button` and the fields, so a filter row lines up with the search field beside it. 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, signal } from '@angular/core';
+import { BfChipComponent } from '@bitforgehq/ui';
+
+/** The sm, md and lg chip sizes. */
+@Component({
+  selector: 'app-example-chip-sizes',
+  imports: [BfChipComponent],
+  template: `
+    <div class="flex flex-wrap items-center gap-2">
+      <bf-chip size="sm" [(selected)]="design">Design</bf-chip>
+      <bf-chip [(selected)]="copy">Copy</bf-chip>
+      <bf-chip size="lg" [(selected)]="video">Video</bf-chip>
+    </div>
+  `,
+})
+export class ChipSizesExampleComponent {
+  protected readonly design = signal(true);
+  protected readonly copy = signal(false);
+  protected readonly video = signal(false);
+}
+```
+
+## Desktop
+
+Hover darkens the unselected border (`text-muted`) or the selected fill, 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. Under a fine pointer the pill is the hit area, so `sm` chips make a compact filter row beside an `sm` search field. 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 state, unselected then selected:
+
+- Unselected: `surface` / `text` / `border-strong` (the control boundary, ≥ 3:1), hover border `text-muted`.
+- Selected `tonal` (default): `primary-soft` / `primary-strong`, hover `primary-soft-hover`.
+- Selected `ink`: `text` / `bg`, hover `text-secondary`.
+- Pressed: unselected `surface-pressed`; selected `tonal` `primary-soft-pressed`; selected `ink` `text-secondary`. None while disabled.
+- Cursor: `pointer` while enabled, `not-allowed` when disabled.
+- Focus ring: `ring`. Disabled: `surface-sunken` / `text-disabled`, border turns transparent (never opacity).
+- 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 (or check mark) and label sit 6 px apart, tighter than `bf-button`'s 8 px to keep the pill's proportions. A long label truncates with an ellipsis.
+
+## Accessibility
+
+Native `<button type="button">` with `aria-pressed` mirroring `selected`, so it announces as a toggle button (inside a `single` `bf-chip-group` it is `role="radio"` with `aria-checked` instead, and the group owns the tab stop and the arrow keys); the check mark is `aria-hidden` since the pressed state already carries the meaning. Keyboard: native button activation (Enter/Space). `disabled` sets the native attribute, which also removes the chip from the tab order.
+
+### Keyboard
+
+| Key                                 | Action                                                                                           |
+| ----------------------------------- | ------------------------------------------------------------------------------------------------ |
+| <kbd>Tab</kbd>                      | Moves focus to the chip; a `disabled` one is skipped                                             |
+| <kbd>Enter</kbd> / <kbd>Space</kbd> | Toggles `selected` and emits `changed`; nothing on a selected chip with `[deselectable]="false"` |
+
+## Inputs
+
+| Name           | Type                                                        | Default     | Description                                                                                                                                                      |
+| -------------- | ----------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `value`        | `unknown`                                                   | `undefined` | The value this chip stands for inside a `bf-chip-group` (compared with `Object.is`); unused outside one.                                                         |
+| `variant`      | `BfChipVariant` (`'tonal' \| 'ink'`)                        | `'tonal'`   | Selected treatment: tonal tint (default) or ink.                                                                                                                 |
+| `disabled`     | `boolean`                                                   | `false`     | Disables the chip.                                                                                                                                               |
+| `label`        | `string`                                                    | `''`        | Label text; the default slot works too.                                                                                                                          |
+| `size`         | `BfSize \| undefined` (`'sm' \| 'md' \| 'lg' \| undefined`) | `undefined` | Height step: sm 32, md 40, lg 48 px; unset follows `provideBfDefaults()` (`controlSize`, `md` by default).                                                       |
+| `deselectable` | `boolean`                                                   | `true`      | When false, clicking an already selected chip does nothing (single-choice rows).                                                                                 |
+| `selected`     | `boolean`                                                   | `false`     | Whether the chip is selected; two-way bindable. Inside a `single`-mode `bf-chip-group` the group's `value` decides and this is ignored. Two-way: `[(selected)]`. |
+
+## Outputs
+
+| Name      | Payload   | Description                                                                                                                   |
+| --------- | --------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `changed` | `boolean` | Emitted with the new state after a user toggle.                                                                               |
+| `toggled` | `boolean` | Emitted with the new state after a user toggle, together with `changed`. **Deprecated** (0.3.0 use changed; removed in 0.4.0) |
+
+## Slots
+
+- `icon-start`: An icon before the label.
+- `default`: Rich label content, before the `label` text.
+
+## Methods
+
+### `focus(options?: FocusOptions): void`
+
+Focuses the chip's button.
+
+| Parameter  | Type           | Description                                                           |
+| ---------- | -------------- | --------------------------------------------------------------------- |
+| `options?` | `FocusOptions` | Passed on to the native `focus()`, such as `{ preventScroll: true }`. |
+
+## Notes
+
+### Do
+
+- Keep chip labels to one or two words.
+- Use `bf-segmented` when the choices switch a whole view and there are two to four of them.
+
+### Don't
+
+- Don't use chips for status; that is `bf-badge`.
+- Don't rely on truncation for long labels; a chip row should read at a glance.
+
+## Migration notes
+
+### 0.3.0
+
+**Deprecated:** `toggled` → `changed`. The new `changed` output emits the new `selected` state
+after a user toggle; `toggled` still emits the same value right after it until 0.4.0 (see
+Migration 23).
+
+**Breaking:** new `size` (`BfSize`; unset follows `provideBfDefaults()`'s `controlSize`): `sm` 32,
+`md` 40 (default, was a fixed 36), `lg` 48 px. The hit extension applies only under a coarse
+pointer and compensates the chip's 1.5 px border, so it reaches 44 px (was 42). See Migration 4.
+
+**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 `chip.component.ts` for the API reference: `@summary`/`@since` on the exported symbols;
+`@slot` docs for `icon-start`, `default`; template handlers and framework hooks marked `@internal`,
+so the reference leaves them out. No behaviour change.
+
+**Behaviour:** a pressed state (F-045): unselected chips take `surface-pressed`, selected `tonal` ones `primary-soft-pressed`, selected `ink` ones `text-secondary` while held down. None while disabled; under forced colours the system colours win.
+
+New `value = input<unknown>(undefined)`: what the chip stands for inside a `bf-chip-group`
+(compared with `Object.is`); unused outside one. Inside a `single` group the chip renders
+`role="radio"` with `aria-checked` (no `aria-pressed`), takes the group's roving `tabindex`, is
+disabled with the group, and its own `selected` is ignored: the group's `value` decides. A
+single-choice row without a group keeps working, and `deselectable` keeps its behaviour; the docs'
+single-choice section now points to the group. New `focus(options?)` focuses the chip's button.
+
+### 0.2.0
+
+The unselected border is `border-strong` (hover `text-muted`). Disabled uses tokens instead of
+`opacity-60`: `surface-sunken` / `text-disabled`, transparent border. The label renders in a
+`data-label` span that truncates with an ellipsis; the chip and its host are capped at
+`max-w-full`. Icon to label stays 6 px (the pill's proportion at 36 px; `bf-button` uses 8).
+
+Fixed: pointer cursor while enabled; a selected chip now has a hover too (`tonal`
+`primary-soft-hover`, `ink` `text-secondary`, fill and border).
+
+### 0.1.0
+
+New `bf-chip`: a toggleable pill for filters and tags, 36 px tall, with `tonal` (default) and `ink` treatments. Renders a `<button aria-pressed>` and shows a `::before` check mark while selected. Two-way `[(selected)]` model plus a `toggled` output fired after a user click; the hit area extends vertically with `::after`, matching `bf-button`. Fixed the check mark rendering as a thin vertical line instead of a tick: the `::before` pseudo-element had no `display` utility, and an inline, non-replaced box ignores explicit `width`/`height`; added `before:block`. Added `deselectable` (default `true`): set it `false` in a single-choice filter row so clicking the already-selected chip does nothing instead of clearing the selection. The unselected state's hover border is now `enabled:hover:border-border-strong` so a disabled chip doesn't show a hover state it can't act on.