forty-cdk 0.2.0 → 0.3.0

package/radio-group/README.md

@@ -0,0 +1,129 @@
+# Radio Group
+
+Headless implementation of the [WAI-ARIA Radio Group pattern](https://www.w3.org/WAI/ARIA/apg/patterns/radio/) with selection-on-focus, wrap-around arrow navigation, and `FormValueControl<string>` integration for Angular Signal Forms.
+
+## Pieces
+
+| Class           | Selector          | Role                                                                                                            |
+| --------------- | ----------------- | --------------------------------------------------------------------------------------------------------------- |
+| `ForRadioGroup` | `[forRadioGroup]` | Container. Owns the selected value, orientation, disabled / readonly / form state. Provides the shared context. |
+| `ForRadio`      | `[forRadio]`      | One radio. Apply on a `<button type="button">`.                                                                 |
+
+## Inputs / models
+
+### `ForRadioGroup`
+
+| API                                                          | Type                                                      | Description                                                                                                                                       |
+| ------------------------------------------------------------ | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `value`                                                      | `model<string>`                                           | Two-way bindable. The selected radio's value. Empty string = none selected (matches HTML form semantics). Required by `FormValueControl<string>`. |
+| `orientation`                                                | `input<'horizontal' \| 'vertical'>`                       | Default `'vertical'`. Drives keyboard navigation and `aria-orientation`.                                                                          |
+| `dir`                                                        | `input<'ltr' \| 'rtl'>`                                   | Default `'ltr'`. Swaps ArrowLeft / ArrowRight in horizontal layouts.                                                                              |
+| `disabled` / `readonly` / `required` / `invalid` / `pending` | `input<boolean>`                                          | Reflected as `aria-*` / `data-*`. `disabled` and `readonly` block all selection.                                                                  |
+| `loop`                                                       | `input<boolean>`                                          | When true (default), arrow nav wraps around past the first / last enabled radio. Set to `false` for a non-wrapping group.                         |
+| `name`                                                       | `input<string>`                                           | For form association.                                                                                                                             |
+| `errors`                                                     | `input<readonly ValidationError.WithOptionalFieldTree[]>` | Wired by `[formField]`.                                                                                                                           |
+| `touched`                                                    | `model<boolean>`                                          | Set to `true` when focus leaves the group entirely.                                                                                               |
+
+The group host gets `data-orientation`, `data-disabled`, and `data-readonly` for CSS hooks.
+
+### `ForRadio`
+
+| API        | Type                     | Description                                                                                          |
+| ---------- | ------------------------ | ---------------------------------------------------------------------------------------------------- |
+| `value`    | `input.required<string>` | This radio's identifier. Must be unique within the group and non-empty.                              |
+| `disabled` | `input<boolean>`         | Disables this radio independently of the group. Disabled radios are skipped during arrow navigation. |
+
+The radio host gets `aria-checked`, `aria-disabled`, `tabindex`, `data-state`, and `data-disabled`. A disabled radio reflects `aria-disabled="true"` + `data-disabled=""` (no native `disabled`, per APG) — announced but non-selectable, and skipped during arrow nav. Tabindex is `0` for the selected radio (or, when no radio is selected, the first enabled one) and `-1` for the rest.
+
+## Stand-alone usage
+
+```ts
+import { Component, signal } from '@angular/core';
+import { ForRadio, ForRadioGroup } from 'forty-cdk/radio-group';
+
+@Component({
+  selector: 'demo-color',
+  imports: [ForRadioGroup, ForRadio],
+  template: `
+    <div forRadioGroup [(value)]="color" aria-labelledby="color-label">
+      <span id="color-label">Color</span>
+      <button type="button" forRadio class="radio-group-item" value="red">Red</button>
+      <button type="button" forRadio class="radio-group-item" value="green">Green</button>
+      <button type="button" forRadio class="radio-group-item" value="blue" disabled>Blue</button>
+    </div>
+  `,
+})
+export class DemoColor {
+  readonly color = signal('red');
+}
+```
+
+## Signal Forms usage
+
+```ts
+import { Component, signal } from '@angular/core';
+import { form, required } from '@angular/forms/signals';
+import { ForRadio, ForRadioGroup } from 'forty-cdk/radio-group';
+
+@Component({
+  selector: 'demo-shipping',
+  imports: [ForRadioGroup, ForRadio /* , FormField from @angular/forms */],
+  template: `
+    <div forRadioGroup [formField]="checkout.shipping" aria-labelledby="ship-label">
+      <span id="ship-label">Shipping</span>
+      <button type="button" forRadio class="radio-group-item" value="standard">Standard</button>
+      <button type="button" forRadio class="radio-group-item" value="express">Express</button>
+      <button type="button" forRadio class="radio-group-item" value="overnight">Overnight</button>
+    </div>
+  `,
+})
+export class DemoShipping {
+  readonly model = signal({ shipping: '' });
+  readonly checkout = form(this.model, (s) => required(s.shipping));
+}
+```
+
+## 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                     |
+| --------------------- | ------------------ | -------------------------- |
+| `[forRadioGroup]`     | `data-orientation` | `horizontal` \| `vertical` |
+| `[forRadioGroup]`     | `data-disabled`    | present \| absent          |
+| `[forRadioGroup]`     | `data-readonly`    | present \| absent          |
+| `[forRadio]`          | `data-state`       | `checked` \| `unchecked`   |
+| `[forRadio]`          | `data-disabled`    | present \| absent          |
+| `[forRadio]`          | `data-orientation` | `horizontal` \| `vertical` |
+| `[forRadioIndicator]` | `data-state`       | `checked` \| `unchecked`   |
+| `[forRadioIndicator]` | `data-orientation` | `horizontal` \| `vertical` |
+
+```css
+.radio-group-indicator[data-state='unchecked'] {
+  display: none;
+}
+
+.radio-group-item:not([data-disabled]):hover {
+  cursor: pointer;
+}
+```
+
+## Keyboard
+
+- **Tab** moves focus into / out of the group; lands on the selected radio (or the first enabled one if nothing is selected).
+- **Space** / **Enter** select the focused radio (Space is APG; Enter comes from the underlying `<button>` and is harmless).
+- **ArrowDown** / **ArrowUp** in a vertical group, **ArrowRight** / **ArrowLeft** in a horizontal group: move focus AND change selection ("selection on focus"), wrapping at the ends. RTL swaps Left/Right.
+- **Home** / **End** jump to the first / last enabled radio (and select it).
+- Disabled radios are skipped.
+
+## Accessibility notes
+
+- **Provide a group label.** Use `aria-labelledby` (pointing to a heading or `<span>`) or `aria-label`. Without one, screen readers cannot announce the group's purpose.
+- **Selection-on-focus** is the APG-mandated behavior for standard radio groups (toolbars use a different model). Be aware that arrow navigation immediately changes the form value.
+- **`role="radio"`** on a `<button>` is the most accessible host: it gets keyboard activation and SR-friendly semantics. Other host elements lose those defaults.
+
+## Wrapping in a design system
+
+Both supported wrapper patterns — `hostDirectives` with the exported `FOR_RADIO_GROUP_HOST_DIRECTIVE_INPUTS` / `FOR_RADIO_GROUP_HOST_DIRECTIVE_OUTPUTS` name tuples, and subclassing — are documented in [Wrapping form primitives](../../../../../docs/wrapping-form-primitives.md).

package/scroll-area/README.md

@@ -0,0 +1,184 @@
+# ScrollArea
+
+Headless custom-scrollbar primitive. Hides native scrollbars on the inner viewport and exposes synthetic `scrollbar` + `thumb` + `corner` directives that the consumer styles freely.
+
+This is the **only** primitive in forty-cdk that ships CSS — a single `<style>` tag (id `for-scroll-area-hide-native`) is injected into `document.head` the first time a viewport mounts. It hides webkit / Firefox / IE native scrollbars on `[forScrollAreaViewport]` only, leaving the rest of your CSS untouched.
+
+## Pieces
+
+| Class                    | Selector                   | Role                                                                                             |
+| ------------------------ | -------------------------- | ------------------------------------------------------------------------------------------------ |
+| `ForScrollArea`          | `[forScrollArea]`          | Root. Owns `type`, `scrollHideDelay`, hover / scrolling state.                                   |
+| `ForScrollAreaViewport`  | `[forScrollAreaViewport]`  | The actual scrolling element.                                                                    |
+| `ForScrollAreaContent`   | `[forScrollAreaContent]`   | Marks the content element inside the viewport so its size changes drive the synthetic scrollbar. |
+| `ForScrollAreaScrollbar` | `[forScrollAreaScrollbar]` | Synthetic track. Required `orientation`.                                                         |
+| `ForScrollAreaThumb`     | `[forScrollAreaThumb]`     | Draggable thumb sized & translated automatically.                                                |
+| `ForScrollAreaCorner`    | `[forScrollAreaCorner]`    | Only shows when both scrollbars are visible.                                                     |
+
+## Inputs (root)
+
+| API               | Type                                               | Description                                                                                                                                                                                |
+| ----------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `type`            | `input<'auto' \| 'always' \| 'scroll' \| 'hover'>` | Visibility behavior. Default `'hover'`. `'always'` keeps the track painted even with no overflow; `'auto'` self-hides — see [Notes](#notes) and the grid example for reserving the gutter. |
+| `scrollHideDelay` | `input<number>`                                    | ms after the most recent scroll before scrollbars fade (`'scroll'` and `'hover'`). Default `600`.                                                                                          |
+| `dir`             | `input<WritingDirection>`                          | Reflected as `dir`.                                                                                                                                                                        |
+
+The scrollbar reflects `data-orientation`, `data-state` (`'visible'` / `'hidden'`); the thumb reflects `data-orientation` and `data-state`. Position is driven by inline `transform: translate{X,Y}(…)` on the thumb.
+
+## Usage
+
+```ts
+import { Component } from '@angular/core';
+import {
+  ForScrollArea,
+  ForScrollAreaContent,
+  ForScrollAreaCorner,
+  ForScrollAreaScrollbar,
+  ForScrollAreaThumb,
+  ForScrollAreaViewport,
+} from 'forty-cdk/scroll-area';
+
+@Component({
+  selector: 'demo-scroll',
+  imports: [
+    ForScrollArea,
+    ForScrollAreaViewport,
+    ForScrollAreaContent,
+    ForScrollAreaScrollbar,
+    ForScrollAreaThumb,
+    ForScrollAreaCorner,
+  ],
+  template: `
+    <div forScrollArea class="scroll-area">
+      <div forScrollAreaViewport class="scroll-area-viewport">
+        <div forScrollAreaContent class="content">…lots of stuff…</div>
+      </div>
+      <div forScrollAreaScrollbar class="scroll-area-scrollbar" orientation="vertical">
+        <div forScrollAreaThumb class="scroll-area-thumb"></div>
+      </div>
+      <div forScrollAreaScrollbar class="scroll-area-scrollbar" orientation="horizontal">
+        <div forScrollAreaThumb class="scroll-area-thumb"></div>
+      </div>
+      <div forScrollAreaCorner class="scroll-area-corner"></div>
+    </div>
+  `,
+  styles: [
+    `
+      .scroll-area {
+        position: relative;
+        width: 240px;
+        height: 240px;
+      }
+      .scroll-area-viewport {
+        position: absolute;
+        inset: 0;
+      }
+      .scroll-area-scrollbar[orientation='vertical'] {
+        position: absolute;
+        top: 0;
+        right: 0;
+        width: 8px;
+        height: 100%;
+        background: rgba(0, 0, 0, 0.04);
+        transition: opacity 0.2s;
+      }
+      .scroll-area-scrollbar[orientation='horizontal'] {
+        position: absolute;
+        bottom: 0;
+        left: 0;
+        height: 8px;
+        width: 100%;
+        background: rgba(0, 0, 0, 0.04);
+        transition: opacity 0.2s;
+      }
+      .scroll-area-scrollbar[data-state='hidden'] {
+        opacity: 0;
+        pointer-events: none;
+      }
+      .scroll-area-thumb {
+        background: rgba(0, 0, 0, 0.4);
+        border-radius: 4px;
+      }
+      .scroll-area-corner {
+        position: absolute;
+        right: 0;
+        bottom: 0;
+        width: 8px;
+        height: 8px;
+        background: rgba(0, 0, 0, 0.04);
+      }
+    `,
+  ],
+})
+export class DemoScroll {}
+```
+
+## Notes
+
+- **`type="always"` keeps a stable, always-painted track.** Unlike `auto` / `scroll` / `hover` — which render a scrollbar only for an axis that actually overflows and self-hide otherwise — `always` keeps both scrollbars (and the corner) mounted and `data-state="visible"` regardless of overflow. When the axis does not overflow the thumb fills the full track and dragging it is a no-op, so the track never appears/disappears as content crosses the overflow boundary.
+- **Reserving the gutter with `type="always"` is the consumer's layout job.** forty-cdk is headless and does not own layout, so it cannot literally reserve a gutter — `always` only guarantees the track stays painted. To get "no content shift" behavior, lay the scrollbar out _in flow_ (a grid column) rather than `position: absolute`, so the always-present track occupies real space:
+
+  ```css
+  .scroll-area {
+    display: grid;
+    grid-template-columns: 1fr auto; /* content | reserved scrollbar gutter */
+    grid-template-rows: 1fr auto;
+    width: 240px;
+    height: 240px;
+  }
+  .scroll-area-viewport {
+    grid-column: 1;
+    grid-row: 1;
+  }
+  .scroll-area-scrollbar[orientation='vertical'] {
+    grid-column: 2;
+    grid-row: 1;
+    width: 8px;
+  }
+  .scroll-area-scrollbar[orientation='horizontal'] {
+    grid-column: 1;
+    grid-row: 2;
+    height: 8px;
+  }
+  .scroll-area-corner {
+    grid-column: 2;
+    grid-row: 2;
+  }
+  ```
+
+  With `type="always"` the vertical track's grid column is always filled, so the viewport width stays constant whether or not the content overflows — no reflow when it crosses the boundary. The `position: absolute` layout in the [Usage](#usage) example above is the right default for `auto` / `hover` / `scroll`, where an overlaid self-hiding scrollbar is the desired look.
+
+- **Native scrollbars are hidden globally on `[forScrollAreaViewport]`** via an injected `<style>` tag. If you need to opt out (e.g. for a debug build), remove `#for-scroll-area-hide-native` from the head — but that defeats the primitive's purpose.
+- **Keyboard scrolling stays native.** PageUp / PageDown / arrows / Tab still scroll the viewport because the underlying element keeps `overflow: scroll`. The thumb is just a visual + drag affordance.
+- **Drag uses pointer-capture** so the cursor doesn't lose the thumb if it briefly leaves the track. The `pointermove` / `pointerup` listeners are attached to the owner document (capture still routes them there), and an in-flight drag pins the track `data-state="visible"` and painted — so a drag is never silently aborted if the scrollbar would otherwise self-hide mid-gesture (e.g. a `type="scroll"` fade, or a consumer `display: none` on `[data-state="hidden"]`).
+- **RTL is handled on the horizontal axis.** When the root resolves to `dir="rtl"`, the horizontal thumb starts pinned to the right edge of the track and a leftward drag scrolls the content forward (the browser's native negative-`scrollLeft` model). Set the direction the standard way — `[dir]` on the root or an ancestor `dir` attribute.
+- **Minimum thumb size is 8px**, matching common UI conventions for very long content.
+- **The corner only shows when both scrollbars are visible** (or always, under `type="always"`, where both tracks are permanently present). Otherwise the directive hides it with an inline `display: none` in addition to the `hidden` attribute that removes it from the accessibility tree (the only place the rule "primitives never apply `[hidden]`" doesn't apply — the corner has no logical presence without two scrollbars). Because the inline style beats any author selector rule, you can give `[forScrollAreaCorner]` a custom `display` without a `.x[hidden] { display: none }` workaround — the directive's `display: none` still wins while the corner is hidden, and your `display` applies once both scrollbars show.
+- **Content observation is opt-in**: the viewport observes its own size automatically, but only observes the content element when the consumer tags it with `[forScrollAreaContent]`. Skipping the directive is allowed (the viewport still scrolls and the scrollbars still render); the scrollbars just won't react to content reflows. The library never guesses `firstElementChild`, since that silently breaks when content is wrapped in a layer or split across siblings.
+
+## 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                                    |
+| -------------------------- | ------------------ | ----------------------------------------- |
+| `[forScrollArea]`          | `data-type`        | `auto` \| `always` \| `scroll` \| `hover` |
+| `[forScrollAreaScrollbar]` | `data-orientation` | `horizontal` \| `vertical`                |
+| `[forScrollAreaScrollbar]` | `data-state`       | `visible` \| `hidden`                     |
+| `[forScrollAreaThumb]`     | `data-orientation` | `horizontal` \| `vertical`                |
+| `[forScrollAreaThumb]`     | `data-state`       | `visible` \| `hidden`                     |
+
+The resolved writing direction is reflected on the root via the native `dir` attribute (`ltr` / `rtl`), not a `data-*` hook — select on `[dir='rtl']` / `:dir(rtl)` to flip layout. `[forScrollAreaViewport]`, `[forScrollAreaContent]`, and `[forScrollAreaCorner]` carry no `data-*` attributes; the scrollbar and corner additionally self-remove via the `hidden` attribute plus an inline `display: none` when their axis has no overflow (except under `type="always"`).
+
+```css
+.scroll-area-scrollbar[data-state='hidden'] {
+  opacity: 0;
+  pointer-events: none;
+}
+
+.scroll-area-scrollbar[data-orientation='vertical'] {
+  width: 8px;
+}
+```

package/search/README.md

@@ -0,0 +1,42 @@
+# Search
+
+Headless `role="searchbox"` text field. `[forSearch]` applies on a native
+`<input>` and wires its value to a signal, reflects WAI-ARIA validation state,
+and exposes a `clear()` / `focusInput()` API for the companion `[forSearchClear]`
+clear button.
+
+There is no dedicated WAI-ARIA APG pattern page for "search" — the primitive
+is a thin `role="searchbox"` text input (https://www.w3.org/TR/wai-aria-1.2/#searchbox)
+that reuses `[forInput]`'s form-value wiring wholesale.
+
+## Basic usage
+
+```html
+<input forSearch #s="forSearch" [(value)]="query" placeholder="Search…" />
+<button [forSearchClear]="s" aria-label="Clear search">×</button>
+```
+
+`[forSearchClear]` self-hides while the value is empty and refocuses the input
+on activation. Pass the exported `#s="forSearch"` reference through the
+selector input — no wrapping element is required.
+
+## With Signal Forms and Field
+
+```html
+<div forField>
+  <label forLabel>Search</label>
+  <input forSearch [formField]="searchForm.query" />
+</div>
+```
+
+`[formField]` auto-wires the `FormValueControl<string>` contract — `required`,
+`invalid`, `touched`, and the value itself flow in and out without extra glue.
+
+## Accessibility notes
+
+- The `role="searchbox"` attribute is set statically by the directive.
+- Validation state (`aria-required`, `aria-invalid`, `aria-readonly`,
+  `aria-disabled`) is reflected as truthy-only attributes (absent when `false`).
+- `[forSearchClear]` carries `aria-label="Clear"` by default; override it with
+  a consumer-set `aria-label` on the same element if the default label is not
+  appropriate for the context.