forty-cdk 0.2.0 → 0.3.0

package/field/README.md

@@ -0,0 +1,97 @@
+# Field
+
+Headless form-field wiring. It renders **nothing** and imposes no layout: it only associates a label, a description, and an error region with a single control (via `id` / `aria-labelledby` / `aria-describedby` / `aria-errormessage`) and reflects the control's validation state as `data-*` styling hooks.
+
+There is no rendered chrome, no appearance variants, and **no control contract to implement**: every forty-cdk form primitive (`FormValueControl` / `FormCheckboxControl`) already exposes the state the field needs, so wrapping one in a `[forField]` auto-associates it with zero extra markup.
+
+## Pieces
+
+| Class                 | Selector                | Role                                                                                                           |
+| --------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `ForField`            | `[forField]`            | Root. Owns the generated ids and reflects `data-invalid` / `data-disabled` / `data-required` / `data-touched`. |
+| `ForLabel`            | `[forLabel]`            | Accessible label. Inside a field it wires `aria-labelledby` (and `for` on a `<label>`); usable standalone.     |
+| `ForFieldDescription` | `[forFieldDescription]` | Hint / description. Wires `aria-describedby`.                                                                  |
+| `ForFieldError`       | `[forFieldError]`       | Error region (`role="alert"`). Reads the control's Signal Forms errors automatically.                          |
+| `ForFieldControl`     | `[forFieldControl]`     | Opt-in marker for a **native** `<input>` / `<textarea>` (forty-cdk controls don't need it).                    |
+
+## How the control connects
+
+- **forty-cdk controls** (`forSwitch`, `forCheckbox`, `forSlider`, `forSelect`, `forListbox`, `forCombobox`, `forRadioGroup`, `forToggle`, `forToggleGroup`) auto-wire — they inherit the association from the shared form base. No marker needed.
+- **Native controls** add `[forFieldControl]` and drive validation state via its `invalid` / `required` / `disabled` / `touched` inputs.
+
+`ForField` owns the control's `id` (it assigns one if the control has none, otherwise it adopts the existing id), so a `<label forLabel>`'s `for` always resolves to the control.
+
+## `ForFieldError` — automatic Signal Forms errors
+
+`ForFieldError` reads the control's `errors()` automatically and exposes them as signals:
+
+- `errors()` — the raw `ValidationError[]`.
+- `messages()` — `string[]` of human-readable messages.
+- `hasErrors()` / `shown()` — `shown()` is `true` when the control is invalid and has errors.
+
+You render them; the field handles the ARIA. The error id is wired into `aria-errormessage` (and folded into `aria-describedby`) only while the control is invalid.
+
+## Example
+
+```ts
+import { Component, signal } from '@angular/core';
+import { form, FormField, required } from '@angular/forms/signals';
+import { ForField, ForFieldDescription, ForFieldError, ForLabel } from 'forty-cdk/field';
+import { ForSwitch } from 'forty-cdk/switch';
+
+@Component({
+  selector: 'demo-field',
+  imports: [ForField, ForLabel, ForFieldDescription, ForFieldError, ForSwitch, FormField],
+  template: `
+    <div forField class="field">
+      <label forLabel class="field-label">Notifications</label>
+      <button forSwitch [formField]="settings.notify"></button>
+      <p forFieldDescription>We'll only email you about security.</p>
+      @if (err.shown()) {
+        <p forFieldError #err="forFieldError">{{ err.messages().join(', ') }}</p>
+      }
+    </div>
+  `,
+})
+export class DemoField {
+  readonly model = signal({ notify: false });
+  readonly settings = form(this.model, (s) => {
+    required(s.notify, { message: 'Please choose a preference' });
+  });
+}
+```
+
+Style off the reflected state:
+
+```css
+.field[data-invalid] .field-label {
+  color: var(--color-danger);
+}
+```
+
+### Label-click activation
+
+Clicking the label activates the control on both host shapes, not just focuses it. A native `<label forLabel>` emits `for` and the browser forwards the click; a non-`<label>` `[forLabel]` (e.g. `<span forLabel>`) has no native `for` forwarding, so the directive forwards the click itself. Either way, clicking the label toggles a `[forSwitch]` / checkbox-role control, activates a button-host control, or focuses a text input — matching native `<label for>` behavior consistently.
+
+> Note: composite controls whose host is not the focusable element (`forListbox`, `forSelect`, `forCombobox`) still receive `aria-labelledby` correctly, and a label click is forwarded to the control's nominated focusable element (the Select trigger / Combobox input) rather than the wrapper host.
+
+## Styling
+
+forty-cdk ships no styles. Add your own class to each piece — the for\* selectors are the behavior API, not a styling contract (see [Styling forty-cdk](../../../../../docs/styling.md)). Key your CSS off the reflected data-\* attributes below.
+
+### Data attributes
+
+| Piece        | Attribute       | Values           |
+| ------------ | --------------- | ---------------- |
+| `[forField]` | `data-invalid`  | present / absent |
+| `[forField]` | `data-disabled` | present / absent |
+| `[forField]` | `data-required` | present / absent |
+| `[forField]` | `data-touched`  | present / absent |
+
+The reflected state mirrors the registered control: `data-invalid` while it is invalid, `data-required` while it is required, `data-touched` once it has been touched, and `data-disabled` from the control's own disabled state OR a surrounding `[forFieldset]`'s `disabled`. (`[forFieldControl]` additionally reflects `aria-invalid` on its own host, but that is an ARIA hook, not a styling one.)
+
+```css
+.field[data-invalid] .field-label {
+  color: var(--color-danger);
+}
+```

package/fieldset/README.md

@@ -0,0 +1,86 @@
+# Fieldset
+
+Headless grouping wiring — the styleless counterpart to a native `<fieldset>` + `<legend>`, and the grouping companion to [`Field`](../field/README.md). It gives a set of related fields (an address block, a preferences group) a **shared accessible name** and an optional shared `disabled` state. It renders nothing and imposes no layout.
+
+Use it on a real `<fieldset>` to lean on native grouping, or on any other element to get `role="group"` + `aria-labelledby` wired automatically.
+
+## Pieces
+
+| Class               | Selector              | Role                                                                                                       |
+| ------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `ForFieldset`       | `[forFieldset]`       | Group container. Emits `role="group"` + `aria-labelledby` on a non-`<fieldset>`; reflects `data-disabled`. |
+| `ForFieldsetLegend` | `[forFieldsetLegend]` | Group label. Adopts the fieldset's `legendId` so `aria-labelledby` resolves. Usable standalone (inert).    |
+
+## How grouping connects
+
+`ForFieldset` detects its host tag, exactly like `ForLabel`'s `<label>` check:
+
+- On a native **`<fieldset>`**, the browser groups its controls and labels them with the `<legend>` implicitly — so the directive emits **no** `role` and **no** `aria-labelledby`.
+- On **any other element**, it emits `role="group"` and `aria-labelledby` pointing at the `[forFieldsetLegend]`'s generated id.
+
+## Shared `disabled`
+
+The `disabled` input:
+
+- reflects `data-disabled` on the group host,
+- emits the native `disabled` attribute on a `<fieldset>` (or `aria-disabled="true"` on any other element),
+- and propagates to every descendant form control (`forSwitch`, `forCheckbox`, `forSelect`, `forSlider`, …) via context: each control ORs the group's disabled into its own effective disabled, so it becomes genuinely **inert** (interaction ignored, excluded from native form submission) and exposes `aria-disabled="true"` / `data-disabled`. This reaches custom-role controls that a native `<fieldset disabled>` cannot. A control outside any fieldset is unaffected.
+
+Nesting composes like native fieldsets: a disabled outer `[forFieldset]` keeps every control inside disabled even under an inner, enabled `[forFieldset]` — the inner group cannot re-enable what the outer disabled.
+
+## Example
+
+```ts
+import { Component, signal } from '@angular/core';
+import { ForField, ForFieldControl, ForLabel } from 'forty-cdk/field';
+import { ForFieldset, ForFieldsetLegend } from 'forty-cdk/fieldset';
+
+@Component({
+  selector: 'demo-fieldset',
+  imports: [ForFieldset, ForFieldsetLegend, ForField, ForLabel, ForFieldControl],
+  template: `
+    <fieldset forFieldset class="fieldset" [disabled]="locked()">
+      <legend forFieldsetLegend>Shipping address</legend>
+
+      <div forField>
+        <label forLabel>Street</label>
+        <input forFieldControl />
+      </div>
+      <div forField>
+        <label forLabel>City</label>
+        <input forFieldControl />
+      </div>
+    </fieldset>
+  `,
+})
+export class DemoFieldset {
+  readonly locked = signal(false);
+}
+```
+
+On custom markup (no native `<fieldset>`), the same wiring yields `role="group"` + `aria-labelledby`:
+
+```html
+<div forFieldset class="fieldset">
+  <span forFieldsetLegend>Shipping address</span>
+  <!-- … fields … -->
+</div>
+```
+
+## Styling
+
+forty-cdk ships no styles. Add your own class to each piece — the for\* selectors are the behavior API, not a styling contract (see [Styling forty-cdk](../../../../../docs/styling.md)). Key your CSS off the reflected data-\* attributes below.
+
+### Data attributes
+
+| Piece           | Attribute       | Values           |
+| --------------- | --------------- | ---------------- |
+| `[forFieldset]` | `data-disabled` | present / absent |
+
+`[forFieldsetLegend]` reflects no data-\* attributes (it only carries the generated `id` that the group's `aria-labelledby` resolves to).
+
+```css
+.fieldset[data-disabled] {
+  opacity: 0.5;
+}
+```

package/file-upload/README.md

@@ -0,0 +1,73 @@
+# FileUpload
+
+Headless drag-and-drop / dialog file-selection primitive. No ARIA role is imposed on the drop zone — it is a plain container. The `<input type="file">` remains the accessible form control; the trigger is a native `<button>`.
+
+## Usage
+
+```html
+<div forFileUpload accept="image/*,.pdf" (filesChange)="onFiles($event)">
+  <!-- Visually hidden input: keep it focusable for keyboard / AT users.
+       Apply your own sr-only / visually-hidden CSS utility. -->
+  <input forFileUploadInput aria-label="Upload files" class="sr-only" />
+
+  <!-- The trigger opens the native file dialog on click / Enter / Space. -->
+  <button forFileUploadTrigger type="button">Choose files</button>
+
+  <p>or drag and drop here</p>
+</div>
+```
+
+### Multiple files
+
+```html
+<div forFileUpload multiple (filesChange)="onFiles($event)">
+  <input forFileUploadInput aria-label="Upload files" class="sr-only" />
+  <button forFileUploadTrigger>Choose files</button>
+</div>
+```
+
+### Directory (folder) selection
+
+Set `directory` to switch the native picker into folder-selection mode (mirrored onto the input as `webkitdirectory`). The emitted `FileList` then contains every file inside the chosen folder, each carrying a `webkitRelativePath` the consumer reads to reconstruct the tree.
+
+```html
+<div forFileUpload directory (filesChange)="onFolder($event)">
+  <input forFileUploadInput aria-label="Upload folder" class="sr-only" />
+  <button forFileUploadTrigger>Choose folder</button>
+</div>
+```
+
+```ts
+onFolder(files: FileList): void {
+  for (const file of Array.from(files)) {
+    console.log(file.webkitRelativePath); // e.g. "photos/2024/img.jpg"
+  }
+}
+```
+
+Despite the `webkit-` prefix the attribute is supported across modern Chromium, Firefox, and WebKit. Directory drag-and-drop (`DataTransferItem.webkitGetAsEntry`) is out of scope — drop continues to surface `DataTransfer.files` only.
+
+### Disabled
+
+```html
+<div forFileUpload [disabled]="isDisabled()">
+  <input forFileUploadInput aria-label="Upload files" class="sr-only" />
+  <button forFileUploadTrigger>Choose files</button>
+</div>
+```
+
+## Inputs
+
+| Input       | Type             | Default | Description                                                                    |
+| ----------- | ---------------- | ------- | ------------------------------------------------------------------------------ |
+| `accept`    | `string \| null` | `null`  | MIME types or file extensions accepted by the chooser (e.g. `"image/*,.pdf"`). |
+| `multiple`  | `boolean`        | `false` | Whether multiple files can be selected at once.                                |
+| `directory` | `boolean`        | `false` | Whether the picker selects a whole folder (mirrored as `webkitdirectory`).     |
+| `disabled`  | `boolean`        | `false` | Whether the zone and all its pieces are disabled.                              |
+
+## Data attributes
+
+| Attribute       | When present                                         |
+| --------------- | ---------------------------------------------------- |
+| `data-dragging` | Files are actively being dragged over the drop zone. |
+| `data-disabled` | The zone (and all its pieces) is disabled.           |

package/hover-card/README.md

@@ -0,0 +1,171 @@
+# HoverCard
+
+> New to overlays in forty-cdk? [Your first overlay](../../../../../docs/your-first-overlay.md) walks a Popover from empty markup to styled-and-animated and explains the `@if` / open-state model and the portal → global CSS rule.
+
+Headless preview card that opens on hover or focus of a trigger. Use it for profile snapshots, link previews, definition cards — any **complementary** information that surfaces on dwell.
+
+There is no APG pattern for HoverCard. Treat it as a presentational layer: the trigger must already convey full meaning (it's a link, a name, a tag), so keyboard-only users miss nothing if they never see the card. Card content can be interactive — that's its main difference from `[forTooltip]`, where APG bans it.
+
+## Pieces
+
+| Class                 | Selector                | Role                                                                                                                     |
+| --------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `ForHoverCard`        | `[forHoverCard]`        | Root. Owns open state and delays.                                                                                        |
+| `ForHoverCardTrigger` | `[forHoverCardTrigger]` | Element that opens the card on hover / focus.                                                                            |
+| `ForHoverCardContent` | `[forHoverCardContent]` | The card surface. Portaled and floating-positioned. Pointer-enter cancels close, so the user can move the cursor inside. |
+| `ForHoverCardArrow`   | `[forHoverCardArrow]`   | Optional arrow positioned by floating-ui.                                                                                |
+
+## Inputs / models
+
+| API                | Type                                              | Description                                                                                                                                           |
+| ------------------ | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `open`             | `model<boolean>` (two-way bindable as `[(open)]`) | `(openChange)` fires only on internal transitions (delay timers, escape, blur, and the force-close that runs when `disabled` flips to true).          |
+| `side`             | `input<FloatingSide \| undefined>`                | Anchor side (`'top'` / `'right'` / `'bottom'` / `'left'`). Falls back to `provideForHoverCardDefaults` (`'top'`).                                     |
+| `align`            | `input<FloatingAlign \| undefined>`               | Alignment along `side` (`'start'` / `'center'` / `'end'`). Falls back to `provideForHoverCardDefaults` (`'center'`).                                  |
+| `sideOffset`       | `input<number \| undefined>`                      | Gap (px) between trigger and card along the main axis. Falls back to `provideForHoverCardDefaults` (`8`).                                             |
+| `alignOffset`      | `input<number>`                                   | Gap (px) along the cross axis. Default `0`.                                                                                                           |
+| `collisionPadding` | `input<number \| undefined>`                      | Padding (px) for the `flip` / `shift` / `size` collision middlewares. Falls back to `provideForHoverCardDefaults` (`8`).                              |
+| `openDelay`        | `input<number \| undefined>`                      | Per-card override for open delay. Falls back to `provideForHoverCardDefaults` (700ms).                                                                |
+| `closeDelay`       | `input<number \| undefined>`                      | Per-card override for close delay. Falls back to `provideForHoverCardDefaults` (300ms).                                                               |
+| `disabled`         | `input<boolean>`                                  | When true, hover / focus interaction is ignored AND any open card is force-closed (with `(openChange)` firing so a `[(open)]` binding stays in sync). |
+
+## Outputs
+
+| Output          | Payload         | Description                                                                                                                                                                                |
+| --------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `escapeKeyDown` | `KeyboardEvent` | Fires when Escape is pressed while the card is open, regardless of where focus currently lives (trigger, portaled content, or an unrelated element). Call `preventDefault()` to keep open. |
+
+## Defaults
+
+`provideForHoverCardDefaults` configures defaults for an injector subtree — at the application root or in any component's `providers` array. Partial overrides inherit unspecified keys from the parent scope (or the library fallbacks at the root). Each call also establishes a fresh skip-delay coordinator scope: peer cards inside the scope share a skip-delay window (the next open is instant within `skipDelayDuration` after a peer closed); cards in other scopes don't.
+
+| Key                 | Library fallback | Meaning                                                                   |
+| ------------------- | ---------------- | ------------------------------------------------------------------------- |
+| `openDelay`         | `700`            | ms before showing after hover/focus enters.                               |
+| `closeDelay`        | `300`            | ms before hiding after hover/focus leaves.                                |
+| `skipDelayDuration` | `300`            | Window (ms) after a peer closes during which the next open is instant.    |
+| `side`              | `'top'`          | Anchor side for cards that don't set `side` themselves.                   |
+| `align`             | `'center'`       | Alignment along `side` for cards that don't set `align` themselves.       |
+| `sideOffset`        | `8`              | Main-axis gap (px) for cards that don't set `sideOffset` themselves.      |
+| `collisionPadding`  | `8`              | Collision-middleware padding (px) for cards that don't set it themselves. |
+
+Per-instance inputs always win over the scope defaults.
+
+The HoverCard coordinator is **independent** from `TooltipCoordinator` — the two patterns have different cadences and shouldn't share their skip-delay windows.
+
+```ts
+import { provideForHoverCardDefaults } from 'forty-cdk/hover-card';
+
+// Right-aligned profile cards app-wide
+bootstrapApplication(App, {
+  providers: [provideForHoverCardDefaults({ side: 'right', sideOffset: 4 })],
+});
+
+// component-level override layers on top, per key
+@Component({
+  providers: [provideForHoverCardDefaults({ openDelay: 200 })],
+  ...
+})
+class ProfileList {}
+```
+
+## Usage
+
+```ts
+import { Component, signal } from '@angular/core';
+import {
+  ForHoverCard,
+  ForHoverCardArrow,
+  ForHoverCardContent,
+  ForHoverCardTrigger,
+} from 'forty-cdk/hover-card';
+
+@Component({
+  selector: 'demo-profile-link',
+  imports: [ForHoverCard, ForHoverCardTrigger, ForHoverCardContent, ForHoverCardArrow],
+  template: `
+    <span forHoverCard #card="forHoverCard">
+      <a forHoverCardTrigger href="/users/ada">Ada Lovelace</a>
+      @if (card.open()) {
+        <div forHoverCardContent animate.enter="card-in" animate.leave="card-out">
+          <img src="/api/avatar/ada" alt="" width="64" height="64" />
+          <h3>Ada Lovelace</h3>
+          <p>Mathematician — designed the first algorithm.</p>
+          <span forHoverCardArrow class="arrow"></span>
+        </div>
+      }
+    </span>
+  `,
+})
+export class DemoProfileLink {}
+```
+
+### Triggers stamped from outside-declared templates
+
+Angular resolves `ng-template` DI at the template's **declaration** site, not where it is stamped. A `[forHoverCardTrigger]` declared in a template outside the root throws the orphan error even when the template is rendered inside the root via `ngTemplateOutlet`. For that case the selector attribute accepts the root reference as a value, `routerLink`-style — grab it with `#root="forHoverCard"` and pass it through the outlet context. The bare valueless attribute keeps resolving via DI.
+
+```html
+<span forHoverCard #root="forHoverCard">
+  <ng-container *ngTemplateOutlet="trig; context: { root }" />
+  @if (root.open()) {
+  <div forHoverCardContent>…</div>
+  }
+</span>
+
+<ng-template #trig let-root="root">
+  <a [forHoverCardTrigger]="root" href="/users/ada">Ada Lovelace</a>
+</ng-template>
+```
+
+## Behavior notes
+
+- **Arrow offset**: `[forHoverCardArrow]` writes `position: absolute`, the floating-ui-resolved `left` / `top`, and `var(--for-arrow-offset, 0px)` on the side opposite the card. Set `--for-arrow-offset` on the arrow element (or any ancestor) to control how far the arrow pokes out — typically a negative `px` value such as `-4px`. The helper ships no default visual.
+
+## Styling
+
+forty-cdk ships no styles. Add your own class to each piece — the `for*` selectors are the behavior API, not a styling contract (see [Styling forty-cdk](../../../../../docs/styling.md)). Key your CSS off the reflected `data-*` attributes below.
+
+### Data attributes
+
+| Piece                   | Attribute               | Values             |
+| ----------------------- | ----------------------- | ------------------ |
+| `[forHoverCard]`        | `data-state`            | `open` \| `closed` |
+| `[forHoverCard]`        | `data-disabled`         | present \| absent  |
+| `[forHoverCardTrigger]` | `data-state`            | `open` \| `closed` |
+| `[forHoverCardContent]` | `data-state`            | `open` \| `closed` |
+| `[forHoverCardArrow]`   | `data-hover-card-arrow` | present (always)   |
+
+### CSS custom properties
+
+See also: [Styling floating content](../../../../../docs/styling-floating-content.md) — animation rules, standalone `scale`/`opacity`, and the arrow recipe.
+
+`[forHoverCardContent]` is portaled to `document.body` and gets its position resolved by floating-ui. It exposes that geometry as custom properties on the content host (cleared on close), and `[forHoverCardArrow]` reads the consumer-settable `--for-arrow-offset`:
+
+| Element                 | Custom property                  | Type / range        | Direction | Meaning                                                                                                      |
+| ----------------------- | -------------------------------- | ------------------- | --------- | ------------------------------------------------------------------------------------------------------------ |
+| `[forHoverCardContent]` | `--for-anchor-width`             | px                  | out       | Trigger (reference) width.                                                                                   |
+| `[forHoverCardContent]` | `--for-anchor-height`            | px                  | out       | Trigger (reference) height.                                                                                  |
+| `[forHoverCardContent]` | `--for-available-width`          | px                  | out       | Space available along the inline axis (floating-ui `size` middleware) — clamp with `max-width`.              |
+| `[forHoverCardContent]` | `--for-available-height`         | px                  | out       | Space available along the block axis — clamp with `max-height`.                                              |
+| `[forHoverCardContent]` | `--for-content-transform-origin` | `<origin>` keywords | out       | `transform-origin` matching the resolved side / align, so a `scale` enter animation pivots from the trigger. |
+| `[forHoverCardArrow]`   | `--for-arrow-offset`             | px (default `0px`)  | in        | Consumer-set. How far the arrow pokes out past the card edge — typically a negative `px` (e.g. `-4px`).      |
+
+> `[forHoverCardContent]` (and the projected `[forHoverCardArrow]`) is portaled to `document.body`, so it sits outside your component's view-encapsulated styles. Style it with **global CSS or a class** you pass on the content element — component-scoped styles won't reach it. The positioner also writes the shared geometry custom properties listed above (`--for-anchor-width` / `-height`, `--for-available-width` / `-height`, `--for-content-transform-origin`); see [Styling floating content](../../../../../docs/styling-floating-content.md) for the full list and the side/align animation recipe.
+
+```css
+.card[data-state='open'] {
+  animation: card-in 120ms ease-out;
+}
+.card {
+  max-width: var(--for-available-width);
+  transform-origin: var(--for-content-transform-origin);
+}
+```
+
+## Accessibility notes
+
+- **Not for tooltips.** If your overlay is a non-interactive label / hint, use `[forTooltip]`. HoverCard does not set `aria-describedby`; the trigger keeps its own label.
+- **Trigger must stand alone.** Keyboard users don't see hover-only previews. Make sure the trigger's text / `aria-label` already describes its destination or action.
+- **Focus opens the card** so keyboard users get the preview when tabbing through a list. Blur closes it; Escape closes immediately, no matter where focus currently lives — on the trigger, on a link inside the content, or on an unrelated element (the common case for a card opened by hover). Escape is routed through a document-level dismissable layer that is active only while the card is open.
+- **Pointer interaction inside the card.** Moving the cursor from the trigger to the content cancels the close timer, so users can copy text or follow nested links. This holds even when the content overlaps its trigger (a negative `sideOffset`) and `closeDelay` is `0`: the trigger recognises a pointer leaving _into_ the card (via `relatedTarget`) and keeps the card open instead of flickering open/closed.
+- **Use `provideForHoverCardDefaults` per scope** when you need a different cadence for, e.g., a list of profile cards (faster) vs. a sidebar of glossary entries (slower).

package/input/README.md

@@ -0,0 +1,156 @@
+# Input / Textarea
+
+Headless text form controls that implement Angular's `FormValueControl<string>` from `@angular/forms/signals`, so they auto-wire with `[formField]` and auto-associate inside a [`[forField]`](../field/README.md) — label, description, and error wiring — with zero extra markup.
+
+These are thin wrappers, not re-implementations: the native `<input>` / `<textarea>` keeps its own `type`, caret, IME composition, and native form submission. The directive only bridges the value to a signal and reflects validation state.
+
+## Pieces
+
+| Class         | Selector        | Element      | Role                      |
+| ------------- | --------------- | ------------ | ------------------------- |
+| `ForInput`    | `[forInput]`    | `<input>`    | Single-line text control. |
+| `ForTextarea` | `[forTextarea]` | `<textarea>` | Multi-line text control.  |
+
+Both expose the identical API below; `[forTextarea]` adds the optional `autosize` input.
+
+## Inputs / models
+
+| API        | Type                                                      | Description                                                                                                   |
+| ---------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `value`    | `model<string>`                                           | Two-way bindable text value. Defaults to `''`; reflected as `data-empty` while empty.                         |
+| `disabled` | `input<boolean>`                                          | Reflects native `disabled` + `aria-disabled="true"` + `data-disabled`.                                        |
+| `readonly` | `input<boolean>`                                          | Reflects native `readonly` + `aria-readonly="true"` + `data-readonly`.                                        |
+| `required` | `input<boolean>`                                          | Reflects `aria-required="true"`.                                                                              |
+| `invalid`  | `input<boolean>`                                          | Reflects `aria-invalid="true"` + `data-invalid`.                                                              |
+| `pending`  | `input<boolean>`                                          | Reflects `aria-busy="true"` + `data-pending` while async validation is in flight.                             |
+| `dirty`    | `input<boolean>`                                          | Reflects `data-dirty`.                                                                                        |
+| `name`     | `input<string>`                                           | Reflected on the native `name` attribute for form submission.                                                 |
+| `errors`   | `input<readonly ValidationError.WithOptionalFieldTree[]>` | Validation errors fed by `[formField]`. The directive does not render them — that is consumer territory.      |
+| `touched`  | `model<boolean>`                                          | Set to `true` on blur. Two-way so the field can read it back.                                                 |
+| `autosize` | `input<boolean>`                                          | `[forTextarea]` only. Grows/shrinks the height to fit content; reflects `data-autosize`. Defaults to `false`. |
+
+The host gets `data-empty` (while the value is `''`), `data-disabled`, and `data-readonly` for CSS hooks, plus `data-touched` / `data-dirty` / `data-pending` / `data-invalid` from the shared form-control reflection.
+
+## Auto-resizing textarea
+
+`[forTextarea]` accepts an optional `autosize` input. When set, the textarea's height tracks its content — it grows as the value gets taller and shrinks back as it gets shorter, recomputed on every edit, on programmatic `value` writes, and on width reflow. The directive only sets the element's `height`; pair it with `resize: none; overflow: hidden;` (key off the reflected `data-autosize`) so the native resize grip and scrollbar don't fight the measured height.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { ForTextarea } from 'forty-cdk/input';
+
+@Component({
+  selector: 'demo-comment',
+  imports: [ForTextarea],
+  template: `<textarea forTextarea autosize class="textarea" [(value)]="comment"></textarea>`,
+})
+export class DemoComment {
+  readonly comment = signal('');
+}
+```
+
+```css
+.textarea[data-autosize] {
+  resize: none;
+  overflow: hidden;
+}
+```
+
+Auto-resize is a browser-only DOM side effect, so it is inert under server-side rendering and hydrates without a layout jump.
+
+## Stand-alone usage
+
+```ts
+import { Component, signal } from '@angular/core';
+import { ForInput, ForTextarea } from 'forty-cdk/input';
+
+@Component({
+  selector: 'demo-profile',
+  imports: [ForInput, ForTextarea],
+  template: `
+    <input forInput class="input" [(value)]="email" type="email" placeholder="you@example.com" />
+    <textarea forTextarea class="textarea" [(value)]="bio" placeholder="About you"></textarea>
+    <p>{{ email() }} — {{ bio().length }} chars</p>
+  `,
+})
+export class DemoProfile {
+  readonly email = signal('');
+  readonly bio = signal('');
+}
+```
+
+## Field composition
+
+Drop the control inside a `[forField]` and it auto-associates with the label, description, and error region — no `id` / `aria-*` wiring by hand.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { form, required } from '@angular/forms/signals';
+import { FormField } from '@angular/forms/signals';
+import { ForField, ForFieldError, ForLabel } from 'forty-cdk/field';
+import { ForInput } from 'forty-cdk/input';
+
+@Component({
+  selector: 'demo-signup',
+  imports: [ForField, ForLabel, ForFieldError, ForInput, FormField],
+  template: `
+    <form>
+      <div forField>
+        <label forLabel>Full name</label>
+        <input forInput class="input" [formField]="profile.name" />
+        @if (err.shown()) {
+          <p forFieldError #err="forFieldError">{{ err.messages().join(', ') }}</p>
+        }
+      </div>
+    </form>
+  `,
+})
+export class DemoSignup {
+  readonly model = signal({ name: '' });
+  readonly profile = form(this.model, (p) => {
+    required(p.name, { message: 'Name is required' });
+  });
+}
+```
+
+`[formField]` detects the `FormValueControl<string>` interface and wires everything — value, disabled, required, invalid, errors, touched — without any glue.
+
+## Styling
+
+forty-cdk ships no styles. Add your own class to each piece — the `for*` selectors are the behavior API, not a styling contract (see [Styling forty-cdk](../../../../../docs/styling.md)). Key your CSS off the reflected `data-*` attributes below.
+
+`[forInput]` and `[forTextarea]` reflect the identical set of attributes on their native host element.
+
+### Data attributes
+
+| Piece                         | Attribute       | Values                           |
+| ----------------------------- | --------------- | -------------------------------- |
+| `[forInput]`, `[forTextarea]` | `data-empty`    | present (value is `''`) / absent |
+| `[forInput]`, `[forTextarea]` | `data-disabled` | present / absent                 |
+| `[forInput]`, `[forTextarea]` | `data-readonly` | present / absent                 |
+| `[forInput]`, `[forTextarea]` | `data-touched`  | present / absent                 |
+| `[forInput]`, `[forTextarea]` | `data-dirty`    | present / absent                 |
+| `[forInput]`, `[forTextarea]` | `data-pending`  | present / absent                 |
+| `[forInput]`, `[forTextarea]` | `data-invalid`  | present / absent                 |
+| `[forTextarea]`               | `data-autosize` | present (`autosize` on) / absent |
+
+```css
+.input[data-invalid] {
+  border-color: red;
+}
+
+.input[data-empty]::placeholder {
+  opacity: 0.5;
+}
+```
+
+## Accessibility notes
+
+- **The native element is the control.** It stays the focusable, submittable form field, so screen readers, mobile keyboards (`type`, `inputmode`), autofill, and native validation all behave exactly as they would on a bare `<input>` / `<textarea>`.
+- **No hidden input.** Because the visible element carries `name` and its `.value` _is_ the form value, the browser serializes it natively — unlike `ForSwitch` (a `<button>`) or `ForNumberInput` (formatted display), which mount a hidden input. A disabled control is skipped by native serialization automatically.
+- **Falsy state styling selects on absence.** `aria-disabled` / `aria-readonly` / `aria-required` / `aria-invalid` / `aria-busy` are emitted only when truthy — style the off state with `:not([aria-invalid])`, never `[aria-invalid="false"]`.
+- **`@angular/forms` is an optional peer.** If you're not using Signal Forms, don't install it — the directive runs fine on a plain `[(value)]` binding (the only `@angular/forms/signals` reference is a type import, erased at build).
+
+## Wrapping in a design system
+
+Both supported wrapper patterns — `hostDirectives` with the exported `FOR_INPUT_HOST_DIRECTIVE_INPUTS` / `FOR_INPUT_HOST_DIRECTIVE_OUTPUTS` and `FOR_TEXTAREA_HOST_DIRECTIVE_INPUTS` / `FOR_TEXTAREA_HOST_DIRECTIVE_OUTPUTS` name tuples, and subclassing — are documented in [Wrapping form primitives](../../../../../docs/wrapping-form-primitives.md).