@bitforgehq/ui 0.3.0

package/ai/components/empty-state.md

@@ -0,0 +1,146 @@
+# bf-empty-state
+
+Placeholder for an empty screen or list with icon, title, message and action
+
+`BfEmptyStateComponent` from `@bitforgehq/ui` · Feedback · since 0.1.0
+
+## Example
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfButtonComponent, BfEmptyStateComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { ListTodo } from 'lucide';
+
+/**
+ * The bf-empty-state overview.
+ *
+ * Live demo of `bf-empty-state`: an icon tile, a title, a description and a primary action that counts the tasks it creates.
+ */
+@Component({
+  selector: 'app-example-empty-state-overview',
+  imports: [BfEmptyStateComponent, BfIconComponent, BfButtonComponent],
+  template: `
+    <div class="flex flex-col gap-3">
+      <bf-empty-state title="No tasks yet" description="Add your first task to get started.">
+        <bf-icon bfSlot="icon" [icon]="listTodo" size="lg" />
+        <bf-button bfSlot="actions" (clicked)="created.set(created() + 1)">New task</bf-button>
+      </bf-empty-state>
+      <p data-status aria-live="polite" class="text-caption text-text-muted text-center">
+        {{ created() === 0 ? 'No task created yet.' : 'Created ' + created() + ' task(s).' }}
+      </p>
+    </div>
+  `,
+})
+export class EmptyStateOverviewExampleComponent {
+  readonly listTodo = ListTodo;
+  readonly created = signal(0);
+}
+```
+
+## Overview
+
+Placeholder for a screen or list with nothing in it yet: an icon tile, a title, one sentence,
+and the action that fills it.
+
+An empty state fills the space where a list or screen would otherwise show nothing: an icon tile, a title, one sentence of explanation, and the action that gets the user unstuck.
+
+## When to use
+
+Use `bf-empty-state` where a list, a search result or a screen has nothing to show yet, with the one action that fills it. Use [bf-spinner](https://bitforge-ui.web.app/components/spinner) instead while the content is still loading, and [bf-alert](https://bitforge-ui.web.app/components/alert) when loading failed.
+
+## Basic usage
+
+```ts
+import { Component } from '@angular/core';
+import { BfEmptyStateComponent } from '@bitforgehq/ui';
+
+/** An empty state with a title and a description. */
+@Component({
+  selector: 'app-example-empty-state-basic',
+  imports: [BfEmptyStateComponent],
+  template: `
+    <bf-empty-state title="No tasks yet" description="Add your first task to get started." />
+  `,
+})
+export class EmptyStateBasicExampleComponent {}
+```
+
+## With an action
+
+Put the icon in the `icon` slot (a `bf-icon` or any glyph) and the primary action in the `actions` slot; the empty state centers both for you.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfButtonComponent, BfEmptyStateComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { ListTodo } from 'lucide';
+
+/** An empty state with an icon and an action. */
+@Component({
+  selector: 'app-example-empty-state-action',
+  imports: [BfButtonComponent, BfEmptyStateComponent, BfIconComponent],
+  template: `
+    <bf-empty-state
+      title="No tasks yet"
+      [description]="created() ? 'Task created.' : 'Add your first task to get started.'"
+    >
+      <bf-icon bfSlot="icon" [icon]="listTodo" size="lg" />
+      <bf-button bfSlot="actions" (clicked)="created.set(true)">New task</bf-button>
+    </bf-empty-state>
+  `,
+})
+export class EmptyStateActionExampleComponent {
+  protected readonly listTodo = ListTodo;
+  protected readonly created = signal(false);
+}
+```
+
+Set `headingLevel` to `3` when the empty state sits inside a section that already opened with an `h2`, so the page outline stays in order.
+
+## Theming
+
+- Icon tile: `surface-sunken` background, `text-muted` icon color, `tile` radius.
+- Title: `text`. Description: `text-muted`.
+
+## Accessibility
+
+The title renders as an `<h2>` by default and an `<h3>` when `headingLevel` is `3`, so it slots into the surrounding page outline instead of always claiming the top level. The icon and action slots carry their own accessibility — an icon should stay decorative, and the action needs its own accessible name.
+
+## Inputs
+
+| Name           | Type                                  | Default  | Description                                                          |
+| -------------- | ------------------------------------- | -------- | -------------------------------------------------------------------- |
+| `title`        | `string`                              | required | What is missing, as a short title.                                   |
+| `description`  | `string`                              | `''`     | One sentence on how to fill it.                                      |
+| `headingLevel` | `BfEmptyStateHeadingLevel` (`2 \| 3`) | `2`      | Heading level of the title so the empty state fits the page outline. |
+
+## Slots
+
+- `icon`: The icon in the tile above the title.
+- `actions`: Buttons under the description, such as Create.
+
+## Notes
+
+### Do
+
+- Keep `description` to one sentence that says what to do next.
+- Offer the action that resolves the empty state, not a link elsewhere.
+
+### Don't
+
+- Don't use `bf-empty-state` for a loading screen; that is `bf-spinner`.
+
+## Migration notes
+
+### 0.3.0
+
+New exported `BfEmptyStateHeadingLevel` (`2 | 3`), the type of `headingLevel` (was an inline union
+with the same values).
+
+JSDoc of `empty-state.component.ts` for the API reference: `@slot` docs for `icon`, `actions`. No
+behaviour change.
+
+### 0.1.0
+
+New `bf-empty-state`: a centered placeholder with a 64 px `icon` tile, a required `title`, an optional `description`, and an `actions` slot for the action that fills it. Added `headingLevel` (`2` default or `3`) so the title renders as `h2` or `h3` to fit the page outline.

package/ai/components/field.md

@@ -0,0 +1,319 @@
+# bf-field
+
+Label, help text and error text wrapper that wires ids for assistive tech
+
+`BfFieldComponent` from `@bitforgehq/ui` · Forms · since 0.1.0
+
+## Example
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfFieldComponent, bfFieldControlClass } from '@bitforgehq/ui';
+
+/**
+ * The bf-field overview.
+ *
+ * Live demo of `bf-field`: wrapping a native `<input>` with a label and help text, styled by
+ * `bfFieldControlClass()` like `bf-input` and described by the field's help text; the typed value
+ * is echoed.
+ */
+@Component({
+  selector: 'app-example-field-overview',
+  imports: [BfFieldComponent],
+  template: `
+    <div class="flex flex-col gap-3">
+      <bf-field
+        #field
+        label="Project name"
+        helpText="Visible to your team"
+        controlId="field-demo-project"
+      >
+        <input
+          #project
+          id="field-demo-project"
+          placeholder="Atlas rebrand"
+          [class]="controlClass"
+          [attr.aria-describedby]="field.describedBy()"
+          (input)="name.set(project.value)"
+        />
+      </bf-field>
+      <p data-status aria-live="polite" class="text-caption text-text-muted">
+        {{ name() ? 'Name: ' + name() : 'Type a project name.' }}
+      </p>
+    </div>
+  `,
+})
+export class FieldOverviewExampleComponent {
+  readonly name = signal('');
+  protected readonly controlClass = bfFieldControlClass({
+    size: 'md',
+    invalid: false,
+    disabled: false,
+    readonly: false,
+  });
+}
+```
+
+## Overview
+
+Label, help text and error text around a form control, with the id wiring assistive tech needs.
+The form widgets use it internally; use it directly only to dress a custom control the same way.
+
+A field wraps a control with its label, helper text and error text, and wires the ids that screen readers use. Every form widget in the library renders one internally; reach for it directly when you build a custom control and want it to look and behave like the others.
+
+## When to use
+
+Use `bf-field` around a control you build yourself, so it gets the library's label, help and error text and their ids. Use [bf-input](https://bitforge-ui.web.app/components/input), [bf-select](https://bitforge-ui.web.app/components/select) or [bf-textarea](https://bitforge-ui.web.app/components/textarea) instead for a standard field: each renders its own `bf-field`.
+
+## Basic usage
+
+Give the control an id and pass the same id as `controlId`. Style a native control with `bfFieldControlClass({ size, invalid, disabled, readonly })` from `@bitforgehq/ui` (`@since 0.3.0`): it returns the class list `bf-input` renders on its own `<input>` in the same state, so the custom control has the library's box, height per `BfSize` step, focus ring and danger border. Set the native `disabled` and `readonly` attributes on the control as well; their styles come from `:disabled` and `:read-only`. Take the field's template reference (`#field`) and bind the control's `aria-describedby` to `field.describedBy()`, and its `aria-invalid` to your own error state, so help and error text are announced.
+
+```ts
+import { Component, computed, inject, signal } from '@angular/core';
+import { BF_DEFAULTS, BfFieldComponent, bfFieldControlClass } from '@bitforgehq/ui';
+
+/** Keeps the control id unique when the example renders more than once. */
+let nextId = 0;
+
+/**
+ * A custom control inside bf-field.
+ *
+ * A native `<input>` for a project code, styled by `bfFieldControlClass()` exactly like
+ * `bf-input` (size from `provideBfDefaults()`, the danger border once the code is invalid). The
+ * field's template reference hands `describedBy()` to the control's `aria-describedby`, so the
+ * help text, and after a wrong entry the error text, is announced. The code shows in capitals
+ * as it is typed (CSS `uppercase`, so the caret stays where it is) and is stored in capitals when
+ * the field is left.
+ */
+@Component({
+  selector: 'app-example-field-custom-control',
+  imports: [BfFieldComponent],
+  template: `
+    <bf-field
+      #field
+      label="Project code"
+      helpText="Three letters, a dash and three digits, e.g. ATL-204"
+      [error]="error()"
+      [controlId]="id"
+    >
+      <input
+        #control
+        [id]="id"
+        autocomplete="off"
+        spellcheck="false"
+        placeholder="ATL-204"
+        [value]="code()"
+        [class]="controlClass() + ' uppercase'"
+        [attr.aria-invalid]="error() ? 'true' : null"
+        [attr.aria-describedby]="field.describedBy()"
+        (input)="code.set(control.value)"
+        (blur)="leave(control.value)"
+      />
+    </bf-field>
+  `,
+})
+export class FieldCustomControlExampleComponent {
+  private readonly size = inject(BF_DEFAULTS).fieldSize;
+
+  protected readonly id = `project-code-${nextId++}`;
+  protected readonly code = signal('');
+  protected readonly touched = signal(false);
+  protected readonly error = computed(() =>
+    this.touched() && !/^[A-Z]{3}-\d{3}$/i.test(this.code()) ? 'Enter a code like ATL-204' : '',
+  );
+  protected readonly controlClass = computed(() =>
+    bfFieldControlClass({
+      size: this.size,
+      invalid: this.error() !== '',
+      disabled: false,
+      readonly: false,
+    }),
+  );
+
+  /** Marks the field touched and stores the code in capitals, as it is shown. */
+  protected leave(value: string): void {
+    this.code.set(value.toUpperCase());
+    this.touched.set(true);
+  }
+}
+```
+
+## Error state
+
+Setting `error` renders the error text in `danger` under the control; the control itself decides how it renders invalid (`bfFieldControlClass({ …, invalid: true })` gives it the danger border).
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfFieldComponent, bfFieldControlClass } from '@bitforgehq/ui';
+
+/**
+ * A field in its error state.
+ *
+ * `error` shows under the control in the danger colour; the control shows the danger border
+ * itself, here through `bfFieldControlClass({ invalid: true, … })`.
+ */
+@Component({
+  selector: 'app-example-field-error',
+  imports: [BfFieldComponent],
+  template: `
+    <bf-field #field label="Email" [error]="emailError()" controlId="field-error-email">
+      <input
+        id="field-error-email"
+        type="email"
+        value="lena@studio"
+        [class]="controlClass"
+        aria-invalid="true"
+        [attr.aria-describedby]="field.describedBy()"
+      />
+    </bf-field>
+  `,
+})
+export class FieldErrorExampleComponent {
+  protected readonly emailError = signal('Enter a valid email address');
+  protected readonly controlClass = bfFieldControlClass({
+    size: 'md',
+    invalid: true,
+    disabled: false,
+    readonly: false,
+  });
+}
+```
+
+## Help and error
+
+The help text stays while an error shows: the error sits under it, so the hint the user needs to fix the value ("Letters and numbers only") never disappears at the moment it matters. `describedBy()` then lists both ids, help first (`"<controlId>-help <controlId>-error"`), so a screen reader reads the hint and the error.
+
+An error that appears while the primary mouse button, a finger or a pen is held down is shown only once the press ends. A field is marked touched on blur, and a press on the form's Save button blurs it on mousedown: showing the message right then would push Save down by a line before the mouseup, and the click would be lost. During the press the message is already in the page, visually hidden, so the ids in `describedBy()` resolve and a screen reader reads it as soon as focus returns to the field; the same paragraph becomes visible a moment after the release, once the click has gone through. A key press or a pointer move with no button down shows it at once. An error that goes away during a press stays on screen until the release, for the same reason.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { FormField, FormRoot, form, pattern, required } from '@angular/forms/signals';
+import { BfButtonComponent, BfInputComponent } from '@bitforgehq/ui';
+
+/**
+ * Help text that stays when the error shows.
+ *
+ * Press Save: the error appears under the help text, and the field is described by both.
+ */
+@Component({
+  selector: 'app-example-field-help-and-error',
+  imports: [FormField, FormRoot, BfButtonComponent, BfInputComponent],
+  template: `
+    <form [formRoot]="account" class="flex w-full flex-col gap-4 sm:w-80">
+      <bf-input
+        label="Username"
+        helpText="Letters and numbers only"
+        [formField]="account.username"
+      />
+      <bf-button type="submit" class="self-start">Save</bf-button>
+    </form>
+  `,
+})
+export class FieldHelpAndErrorExampleComponent {
+  private readonly model = signal({ username: 'lena moser' });
+  protected readonly account = form(
+    this.model,
+    (p) => {
+      required(p.username);
+      pattern(p.username, /^[a-z0-9]+$/i, { message: 'Use letters and numbers only, no spaces' });
+    },
+    {
+      submission: {
+        action: () => Promise.resolve(undefined),
+        onInvalid: (f) => f().errorSummary()[0]?.fieldTree().focusBoundControl(),
+      },
+    },
+  );
+}
+```
+
+## Theming
+
+- Label: `text-muted`, switching to `primary-text` (primary as text, ≥ 4.5:1 on `bg` and `surface`) while the control inside is focused (`group-focus-within/bf-field`) and to `text-disabled` when `disabled`.
+- Required marker: `danger`. Error text: `danger`. Help text: `text-muted`.
+
+Label, control, help text and error text sit 6 px apart, the same label-to-message spacing as `bf-checkbox`, `bf-radio-group` and `bf-toggle`.
+
+## Accessibility
+
+The field renders the label as a native `<label for>` pointing at `controlId`, and gives the help and error paragraphs stable ids (`<controlId>-help` / `<controlId>-error`); both render together, the error under the help text. Label, help and error text break long words anywhere (`overflow-wrap: anywhere`), so a German or Finnish compound never runs past the field at 320 px or 400 % zoom. It sets no ARIA on the control itself — bind the projected control's `aria-describedby` to `describedBy()` (and its own `aria-invalid`, plus `aria-errormessage` pointing at `<controlId>-error` while it is invalid, as the library's controls do) so the wiring actually reaches assistive tech.
+
+## Inputs
+
+| Name        | Type      | Default  | Description                                                                                                                                                                                                                                                                                         |
+| ----------- | --------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `label`     | `string`  | `''`     | Visible label; rendered as a `<label for>` pointing at `controlId`.                                                                                                                                                                                                                                 |
+| `helpText`  | `string`  | `''`     | Helper text under the control; stays while `error` is shown.                                                                                                                                                                                                                                        |
+| `error`     | `string`  | `''`     | Error text under the help text. One that appears while a pointer button is held down (the press on a Save button that blurred the field) renders visually hidden until the press ends, so assistive tech has it at once and the layout never moves under the pointer between mousedown and mouseup. |
+| `required`  | `boolean` | `false`  | Adds the required marker to the label.                                                                                                                                                                                                                                                              |
+| `disabled`  | `boolean` | `false`  | Dims the label; the control carries its own disabled styling.                                                                                                                                                                                                                                       |
+| `controlId` | `string`  | required | The id of the control inside the default slot.                                                                                                                                                                                                                                                      |
+
+## Slots
+
+- `default`: The control the field labels, such as a native input styled with `bfFieldControlClass`.
+
+## Notes
+
+### Do
+
+- Always give a control a visible label; use `placeholder` only as an example value.
+- Keep help text to one short sentence.
+
+### Don't
+
+- Don't nest one `bf-field` inside another.
+- Don't use it for buttons or read-only text.
+
+## Migration notes
+
+### 0.3.0
+
+**Behaviour:** the label of a focused field is `primary-text` (was `primary`).
+
+New export `bfFieldControlClass(state: { size: BfSize; invalid: boolean; disabled: boolean;
+readonly: boolean }): string` (and its `BfFieldControlState` type) from `@bitforgehq/ui`: the class
+list `bf-input` renders on its native `<input>` in the same state (box, height and type per size,
+padding, focus ring, `border-strong` or, while `invalid`, `danger-border`), so a custom control
+inside `bf-field` looks like the library's own fields without copying its classes. The disabled
+and read-only styles come from the control's native `disabled`/`readonly` attributes. `bf-input`
+builds its own list from the same pieces, and a spec asserts the two agree for every size and
+state. The field docs and the `@example` bind the control's `aria-describedby` to the field's
+`describedBy()` through a template reference (`#field`); the new `field/custom-control` example
+does so for a native input styled by `bfFieldControlClass()`.
+
+JSDoc of `field-classes.ts` for the API reference: `@summary`/`@since` on the exported symbols;
+`@param` docs. No behaviour change.
+
+JSDoc of `field.component.ts` for the API reference: `@slot` docs for `default`. No behaviour
+change.
+
+**Behaviour:** the help paragraph renders always (when set) and the error paragraph under it;
+help text no longer disappears on error (F-020). `describedBy()` lists both ids,
+`"<controlId>-help <controlId>-error"`, `"<controlId>-help"`, `"<controlId>-error"` or `null`. A new
+`error` that arrives while a pointer button is held down anywhere in the page shows one task after
+the release (or at once on a key press, or a pointer move with no button down): the press on a
+Save button blurs the field and marks it touched on mousedown, and the message pushed Save about
+22 px down before the mouseup, so the click was lost in every browser. The field holds its layout
+through the press instead of reserving an empty line under every field. See Migration 25.
+
+`fieldDescribedBy(id, errorText, helpText)` (internal, `ɵfieldDescribedBy`) returns
+`"<id>-help <id>-error"`, `"<id>-help"`, `"<id>-error"` or `null`; the new internal
+`ɵfieldErrorMessageId` gives the controls' `aria-errormessage`.
+
+While a press holds a new error back, its paragraph is already rendered, visually hidden
+(`sr-only`), so the controls' `aria-describedby` and `aria-errormessage` always point at an element
+that exists and assistive tech reads the error when focus returns to the field; the same paragraph
+turns visible on release. Only the primary mouse button, a touch or a pen starts a hold (a
+right-click never does). The self-rendering controls (checkbox, toggle, radio group, segmented)
+behave the same way.
+
+### 0.2.0
+
+Fixed: the label, help and error text break long words anywhere (`wrap-anywhere`), so a German or
+Finnish compound no longer runs past the field at 320 px.
+
+### 0.1.0
+
+`disabled` no longer dims the whole field; it dims only the label. Controls already carry their own disabled styling.