@bitforgehq/ui 0.3.0

package/ai/components/textarea.md

@@ -0,0 +1,371 @@
+# bf-textarea
+
+Multi-line text field with label, help and error text, and Signal Forms binding
+
+`BfTextareaComponent` from `@bitforgehq/ui` · Forms · since 0.1.0
+
+## Example
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfTextareaComponent } from '@bitforgehq/ui';
+
+/**
+ * The bf-textarea overview.
+ *
+ * Live demo of `bf-textarea`: a bound fixed-rows field with a character count and an auto-resizing one; then the sm, md and lg sizes in a row.
+ */
+@Component({
+  selector: 'app-example-textarea-overview',
+  imports: [BfTextareaComponent],
+  template: `
+    <div class="flex flex-col gap-3">
+      <bf-textarea label="Notes" [rows]="3" placeholder="Add a note" [(value)]="notes" />
+      <p data-status aria-live="polite" class="text-caption text-text-muted">
+        {{ notes().length }} characters
+      </p>
+      <bf-textarea label="Description" [autoResize]="true" value="Grows with the content" />
+      <div data-sizes class="flex flex-wrap items-center gap-3">
+        <bf-textarea
+          size="sm"
+          ariaLabel="Small textarea"
+          placeholder="sm"
+          [rows]="2"
+          class="w-40"
+        />
+        <bf-textarea ariaLabel="Medium textarea" placeholder="md" [rows]="2" class="w-40" />
+        <bf-textarea
+          size="lg"
+          ariaLabel="Large textarea"
+          placeholder="lg"
+          [rows]="2"
+          class="w-40"
+        />
+      </div>
+    </div>
+  `,
+})
+export class TextareaOverviewExampleComponent {
+  readonly notes = signal('');
+}
+```
+
+## Overview
+
+Multi-line text field with the same chrome and Signal Forms binding as `bf-input`.
+
+The multi-line text field. Same label, help and error chrome as `bf-input`, same Signal Forms binding.
+
+## When to use
+
+Use `bf-textarea` for free text that runs over several lines: a comment, a description, notes. Use [bf-input](https://bitforge-ui.web.app/components/input) instead for a single value such as a title or an email.
+
+## Basic usage
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfTextareaComponent } from '@bitforgehq/ui';
+
+/** A four-row description field bound to a signal. */
+@Component({
+  selector: 'app-example-textarea-basic',
+  imports: [BfTextareaComponent],
+  template: `
+    <bf-textarea
+      label="Description"
+      [rows]="4"
+      placeholder="What is this project about?"
+      [(value)]="description"
+    />
+  `,
+})
+export class TextareaBasicExampleComponent {
+  protected readonly description = signal('');
+}
+```
+
+`(changed)` emits the new text right after each user edit, the moment `value` changes; a
+programmatic write to `value` does not emit.
+
+## Auto-resize
+
+`autoResize` lets the box grow with its content using CSS field sizing (`field-sizing: content`). It starts at `rows` lines, empty or not, so it is exactly as tall as a fixed textarea with the same `rows`. Pair it with a length limit to keep the text bounded: the `maxLength` input, or with Signal Forms a `maxLength()` rule, which binds the native `maxlength` itself (`[maxLength]` cannot be set next to `[formField]`). A browser without field sizing (Firefox before its support) keeps the fixed `rows` and the resize handle instead.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { FormField, form, maxLength } from '@angular/forms/signals';
+import { BfTextareaComponent } from '@bitforgehq/ui';
+
+/** A notes field that grows with its text; the `maxLength()` rule caps it at 500 characters. */
+@Component({
+  selector: 'app-example-textarea-auto-resize',
+  imports: [FormField, BfTextareaComponent],
+  template: ` <bf-textarea label="Notes" [autoResize]="true" [formField]="task.notes" /> `,
+})
+export class TextareaAutoResizeExampleComponent {
+  private readonly model = signal({ notes: '' });
+  protected readonly task = form(this.model, (p) => {
+    maxLength(p.notes, 500);
+  });
+}
+```
+
+## Bounded auto-resize
+
+`maxRows` stops the growth: past that many lines the box keeps its height and scrolls. Use it for a comment box in a dense layout, so a long paste never pushes the page's actions out of view.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfTextareaComponent } from '@bitforgehq/ui';
+
+/**
+ * A comment box that grows from 3 to 6 lines, then scrolls.
+ *
+ * `autoResize` with `rows` 3 and `maxRows` 6.
+ */
+@Component({
+  selector: 'app-example-textarea-max-rows',
+  imports: [BfTextareaComponent],
+  template: `
+    <bf-textarea
+      label="Comment"
+      autoResize
+      [rows]="3"
+      [maxRows]="6"
+      [(value)]="comment"
+      class="w-full sm:w-80"
+    />
+  `,
+})
+export class TextareaMaxRowsExampleComponent {
+  protected readonly comment = signal('');
+}
+```
+
+## Read-only
+
+`readonly` keeps the text selectable and the field in the tab order on the muted surface; nothing
+can be typed. Signal Forms binds it from `readonly()` rules.
+
+```ts
+import { Component } from '@angular/core';
+import { BfTextareaComponent } from '@bitforgehq/ui';
+
+/** A read-only notes field. */
+@Component({
+  selector: 'app-example-textarea-readonly',
+  imports: [BfTextareaComponent],
+  template: `<bf-textarea label="Notes" [readonly]="true" [value]="notes" />`,
+})
+export class TextareaReadonlyExampleComponent {
+  protected readonly notes = 'Kick-off on Monday; the client brings the brand book.';
+}
+```
+
+## Without a visible label
+
+An inline comment box or a grid cell editor can skip the visible `label`; give it `ariaLabel`, or
+`ariaLabelledby` pointing at the element that names it. A textarea without a visible label needs
+one of the two. Both are ignored while `label` is set.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfTextareaComponent } from '@bitforgehq/ui';
+
+/** A comment box named by `ariaLabel` instead of a visible label. */
+@Component({
+  selector: 'app-example-textarea-unlabelled',
+  imports: [BfTextareaComponent],
+  template: `<bf-textarea ariaLabel="Comment" [rows]="2" [(value)]="comment" />`,
+})
+export class TextareaUnlabelledExampleComponent {
+  protected readonly comment = signal('');
+}
+```
+
+## Sizes
+
+A textarea has no fixed height (`rows` and `autoResize` set it), so its step sets the padding and the type to match the single-line fields of the same step: `sm` (12 px sides, 13 px type), `md` (default, 14 px sides, 14 px type), `lg` (16 px sides, 15 px type on 24 px lines). Unset, `size` follows `provideBfDefaults()`'s `fieldSize`, `md` by default; a Capacitor app sets `provideBfDefaults({ fieldSize: 'lg' })` once for the 48 px phone look, and a dense sub-tree (a filter bar, a table) can set `{ size: 'sm' }` in a component's `providers`. Fields get no touch extension: `sm`/`md` fields stay 32/40 px under a coarse pointer, so touch apps use `provideBfDefaults({ fieldSize: 'lg' })`.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfTextareaComponent } from '@bitforgehq/ui';
+
+/** The sm, md and lg textarea sizes. */
+@Component({
+  selector: 'app-example-textarea-sizes',
+  imports: [BfTextareaComponent],
+  template: `
+    <div class="flex flex-col gap-3">
+      <bf-textarea size="sm" label="Comment" [rows]="2" [(value)]="comment" />
+      <bf-textarea label="Notes" [(value)]="notes" />
+      <bf-textarea size="lg" label="Description" [(value)]="description" />
+    </div>
+  `,
+})
+export class TextareaSizesExampleComponent {
+  protected readonly comment = signal('');
+  protected readonly notes = signal('');
+  protected readonly description = signal('');
+}
+```
+
+## Validation
+
+Once the control is touched it shows the first error as text: the error's own `message`, else the default for its kind from `provideBfLabels()`'s `validation` labels (`required` "Fill in this field", `email`, `pattern`, `parse`, `min(n)`, `max(n)`, `minLength(n)` "Use at least n characters", `maxLength(n)`, `minDate(d)`, `maxDate(d)`, and `fallback` "Check this value" for any other kind), so it never turns red without text. Reactive Forms `Validators.*` errors carry no message and get the same defaults (`minlength`/`maxlength` read their limit from the error's `context`). An explicit `errorMessage` wins over both and shows at once, e.g. for a server error.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { FormField, FormRoot, form, minLength } from '@angular/forms/signals';
+import { BfButtonComponent, BfTextareaComponent } from '@bitforgehq/ui';
+
+/**
+ * A minimum length with the default message.
+ *
+ * `minLength(p.notes, 5)` has no message, so a short note shows "Use at least 5 characters".
+ */
+@Component({
+  selector: 'app-example-textarea-validation',
+  imports: [FormField, FormRoot, BfButtonComponent, BfTextareaComponent],
+  template: `
+    <form [formRoot]="report" class="flex flex-col items-start gap-3">
+      <bf-textarea label="Notes" class="self-stretch" [formField]="report.notes" />
+      <bf-button type="submit">Send</bf-button>
+    </form>
+  `,
+})
+export class TextareaValidationExampleComponent {
+  private readonly model = signal({ notes: 'Hi' });
+  protected readonly report = form(
+    this.model,
+    (p) => {
+      minLength(p.notes, 5);
+    },
+    { submission: { action: () => Promise.resolve(undefined) } },
+  );
+}
+```
+
+## Desktop
+
+The field has no hover state; the text cursor shows over it. The `primary` border and the focus ring show on every focus, by mouse or keyboard, because a focused field takes typing. A textarea has no fixed height: `rows` and `autoResize` set it, and the `size` step sets only the padding and the type (`sm` 12 px sides and 13 px type for a dense desktop form, `md` 14 px by default); `provideBfDefaults({ fieldSize: 'sm' })` sets it for a sub-tree ([density guide](https://bitforge-ui.web.app/density)). Without `autoResize` the browser's resize handle lets the user drag the box taller; with it the box grows by itself (to `maxRows`, then scrolls with the wheel or trackpad).
+
+## Theming
+
+- Border: `border-strong` (the control boundary, ≥ 3:1), switching to `danger-border` on error; focus: `primary` border with a `ring` ring.
+- Disabled: `surface-sunken` border, `surface-muted` background, `text-disabled` text. Read-only: `surface-muted` background. Placeholder: `text-muted` (≥ 4.5:1).
+- Label, help and error text come from the `bf-field` wrapper (see its Theming section).
+
+## Accessibility
+
+Native `<textarea>`, so it inherits the platform's resize and selection behaviour. `bf-field` renders the `<label for>`; the textarea itself wires `aria-describedby` to the help paragraph and the error paragraph under it (both while shown, help first) and, while it is invalid, `aria-errormessage` to the error paragraph; `aria-invalid` is set once the field is touched and invalid (an explicit `errorMessage` shows immediately); `maxlength` and `minlength` reflect `maxLength` and `minLength` (Signal Forms binds both from its rules). `aria-label` and `aria-labelledby` carry `ariaLabel` and `ariaLabelledby` only while there is no visible `label`. `readonly` uses the native attribute: the textarea stays in the tab order and is announced as read-only. `focus()` focuses the native textarea; Signal Forms calls it from `focusBoundControl()`.
+
+### Keyboard
+
+| Key                                              | Action                                                                        |
+| ------------------------------------------------ | ----------------------------------------------------------------------------- |
+| <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> | Moves focus to and from the textarea; a `readonly` one stays in the tab order |
+| <kbd>Enter</kbd>                                 | Inserts a line break; it never submits the form                               |
+
+## Inputs
+
+| Name             | Type                                                        | Default     | Description                                                                                                                                          |
+| ---------------- | ----------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `size`           | `BfSize \| undefined` (`'sm' \| 'md' \| 'lg' \| undefined`) | `undefined` | Padding and type step: sm, md, lg (a textarea's height comes from `rows`); unset follows `provideBfDefaults()` (`fieldSize`, `md` by default).       |
+| `label`          | `string`                                                    | `''`        | Visible label above the control.                                                                                                                     |
+| `ariaLabel`      | `string`                                                    | `''`        | Accessible name when no visible label is rendered (e.g. an inline comment box). Ignored when `label` is set.                                         |
+| `ariaLabelledby` | `string`                                                    | `''`        | Id(s) of the element(s) that name the field when no visible label is rendered. Ignored when `label` is set.                                          |
+| `placeholder`    | `string`                                                    | `''`        | Example value shown while empty.                                                                                                                     |
+| `helpText`       | `string`                                                    | `''`        | Helper text under the control.                                                                                                                       |
+| `errorMessage`   | `string`                                                    | `''`        | Explicit error text; takes precedence over Signal Forms errors.                                                                                      |
+| `disabled`       | `boolean`                                                   | `false`     | Disables the control. Set by `[formField]`; do not bind it yourself.                                                                                 |
+| `readonly`       | `boolean`                                                   | `false`     | Makes the control read-only. Set by `[formField]`; do not bind it yourself.                                                                          |
+| `required`       | `boolean`                                                   | `false`     | Marks the control required. Set by `[formField]`; do not bind it yourself.                                                                           |
+| `invalid`        | `boolean`                                                   | `false`     | Field validity from Signal Forms. Set by `[formField]`; do not bind it yourself.                                                                     |
+| `touched`        | `boolean`                                                   | `false`     | Whether the user has left the field. Set by `[formField]`; do not bind it yourself.                                                                  |
+| `errors`         | `readonly ValidationError.WithOptionalFieldTree[]`          | `[]`        | Validation errors from Signal Forms. Set by `[formField]`; do not bind it yourself.                                                                  |
+| `name`           | `string`                                                    | `''`        | Native name attribute. Set by `[formField]`; do not bind it yourself.                                                                                |
+| `id`             | `string`                                                    | `generated` | Control id; generated when not set.                                                                                                                  |
+| `rows`           | `number`                                                    | `3`         | Visible rows; with `autoResize`, the rows the empty box starts at.                                                                                   |
+| `autoResize`     | `boolean`                                                   | `false`     | Grows with the content (CSS `field-sizing: content`) from `rows` up to `maxRows`. Where the browser has no `field-sizing` it keeps the fixed `rows`. |
+| `maxRows`        | `number \| undefined`                                       | `undefined` | With `autoResize`, the rows the box grows to at most; past them it scrolls. Unset, it grows without a bound.                                         |
+| `maxLength`      | `number \| undefined`                                       | `undefined` | Maximum number of characters (native `maxlength`); bound by Signal Forms `maxLength()`. Set by `[formField]`; do not bind it yourself.               |
+| `minLength`      | `number \| undefined`                                       | `undefined` | Minimum number of characters (native `minlength`); bound by Signal Forms `minLength()`. Set by `[formField]`; do not bind it yourself.               |
+| `value`          | `string`                                                    | `''`        | The text value; two-way bindable and bound by `[formField]`. Two-way: `[(value)]`.                                                                   |
+
+## Outputs
+
+| Name      | Payload      | Description                                                                                             |
+| --------- | ------------ | ------------------------------------------------------------------------------------------------------- |
+| `changed` | `string`     | Emitted with the new text right after the user changes it (each keystroke or paste).                    |
+| `focused` | `FocusEvent` | Emitted when the control gains focus.                                                                   |
+| `blurred` | `FocusEvent` | Emitted when the control loses focus.                                                                   |
+| `touch`   | `void`       | Emitted on blur so Signal Forms marks the field touched. Set by `[formField]`; do not bind it yourself. |
+
+## Methods
+
+### `focus(options?: FocusOptions): void`
+
+Focuses the native textarea; Signal Forms calls it from `focusBoundControl()`.
+
+| Parameter  | Type           | Description                                                           |
+| ---------- | -------------- | --------------------------------------------------------------------- |
+| `options?` | `FocusOptions` | Passed on to the native `focus()`, such as `{ preventScroll: true }`. |
+
+## Notes
+
+### Do
+
+- Set `rows` to the typical length of the expected text.
+- Show remaining characters in `helpText` when `maxLength` matters.
+
+### Don't
+
+- Don't use a textarea for single values; use `bf-input`.
+
+## Migration notes
+
+### 0.3.0
+
+New `changed` output: the new text right after each user edit (not for a programmatic write).
+
+**Breaking:** the default `size` is `md` instead of `lg`; `size` is a `BfSize` (`sm` is new) and,
+unset, follows `provideBfDefaults()`'s `fieldSize`. A step sets padding and type, never a height
+(`rows` and `autoResize` do), and the docs now say so. See Migration 2.
+
+**Behaviour:** an error without a message shows its kind's default text (was a red border only):
+once touched, the field shows the first error's own `message`, else `provideBfLabels()`'s
+`validation` text for its kind (Signal Forms and Reactive interop kinds), else
+`validation.fallback`. `errorMessage` still wins. See Migration 1.
+
+JSDoc of `textarea.component.ts` for the API reference: `@param` docs; template handlers and
+framework hooks marked `@internal`, so the reference leaves them out. No behaviour change.
+
+**Behaviour:** the help text stays while an error shows, with the error under it (F-020):
+`aria-describedby` lists both (`"<id>-help <id>-error"`), and `aria-errormessage` points at the
+error paragraph while `aria-invalid="true"`. See Migration 25.
+
+New `maxRows = input<number | undefined>(undefined)` (F-019). With `autoResize` the box keeps
+`field-sizing: content` and now starts at `rows` lines (a `min-block-size` of `rows` times `1lh`
+plus the size's padding and border), so an empty auto-resizing textarea is as tall as a fixed one with the
+same `rows` (it was one line); with `maxRows` it stops at that many lines (`max-block-size`, the same
+way) and scrolls. **Behaviour:** where the browser has no `field-sizing` (`CSS.supports()` says no, read once;
+also on the server) the box keeps its fixed `rows` and the resize
+handle instead of the one-line box it had.
+
+### 0.2.0
+
+The rest border is `border-strong` and the placeholder `text-muted`, as on `bf-input`.
+
+Changed: the border narrows to 1 px (was 1.5 px), as on `bf-input`.
+
+Changed: the focus ring narrows to 2 px (was 4 px), as on `bf-input`.
+
+Added: `minLength` (native `minlength`), and `ariaLabel` / `ariaLabelledby` for a textarea without a
+visible `label` (ignored while `label` is set). `focus(options?)` focuses the native control, so
+Signal Forms' `focusBoundControl()` and "focus the first invalid field" on submit now work (they
+were no-ops).
+
+### 0.1.0
+
+Same `md`/`lg` size rename as `bf-input`. The host no longer reflects a static `id` attribute onto `<bf-textarea>`.