forty-cdk 0.2.0 → 0.3.0

package/pagination/README.md

@@ -0,0 +1,61 @@
+# Pagination
+
+Headless pagination control implementing a [WAI-ARIA `navigation` landmark](https://www.w3.org/WAI/ARIA/apg/patterns/landmarks/examples/navigation.html) with [`aria-current="page"`](https://www.w3.org/TR/wai-aria-1.2/#aria-current) on the active page. Derives the visible page list (with ellipsis gaps) from `page`, `count`, `siblingCount`, and `boundaryCount`. Ships no styles — apply your own.
+
+## Pieces
+
+| Class                   | Selector                  | Role                                                                    |
+| ----------------------- | ------------------------- | ----------------------------------------------------------------------- |
+| `ForPagination`         | `[forPagination]`         | Root. `role="navigation"`. Owns the page model and computed items list. |
+| `ForPaginationItem`     | `[forPaginationItem]`     | Page number button. `aria-current="page"` when current.                 |
+| `ForPaginationPrevious` | `[forPaginationPrevious]` | Previous-page button. Native `disabled` at the first page.              |
+| `ForPaginationNext`     | `[forPaginationNext]`     | Next-page button. Native `disabled` at the last page.                   |
+
+## Usage
+
+```ts
+import { Component, signal } from '@angular/core';
+import {
+  ForPagination,
+  ForPaginationItem,
+  ForPaginationNext,
+  ForPaginationPrevious,
+} from 'forty-cdk/pagination';
+
+@Component({
+  selector: 'demo-pagination',
+  imports: [ForPagination, ForPaginationItem, ForPaginationPrevious, ForPaginationNext],
+  template: `
+    <nav forPagination [(page)]="page" [count]="20" ariaLabel="Pagination" #pg="forPagination">
+      <button forPaginationPrevious ariaLabel="Previous page">‹</button>
+      @for (item of pg.items(); track $index) {
+        @if (item.type === 'page') {
+          <button forPaginationItem [page]="item.value!">{{ item.value }}</button>
+        } @else {
+          <span aria-hidden="true">…</span>
+        }
+      }
+      <button forPaginationNext ariaLabel="Next page">›</button>
+    </nav>
+  `,
+})
+export class DemoPagination {
+  readonly page = signal(1);
+}
+```
+
+## Styling
+
+forty-cdk ships no styles. Style the current page via `[aria-current="page"]` and disabled prev/next via `:disabled`.
+
+```css
+[forPaginationItem][aria-current='page'] {
+  font-weight: bold;
+}
+
+[forPaginationPrevious]:disabled,
+[forPaginationNext]:disabled {
+  opacity: 0.4;
+  pointer-events: none;
+}
+```

package/pane-resizer/README.md

@@ -0,0 +1,136 @@
+# Pane Resizer
+
+Headless implementation of the [WAI-ARIA Window Splitter pattern](https://www.w3.org/WAI/ARIA/apg/patterns/windowsplitter/): the focusable divider between two resizable panes. It carries `role="separator"` plus live `aria-value*`, is tabbable, handles arrow / Page / Home / End keys, and drives a pointer-drag resize with `setPointerCapture`.
+
+It is essentially a 1-D slider wearing a separator role. The static visual divider lives in the separate [`ForSeparator`](../separator/README.md) primitive so a plain `<hr forSeparator>` never pulls the drag / keyboard-resize code in.
+
+## Pieces
+
+| Class            | Selector           | Role                                                                                  |
+| ---------------- | ------------------ | ------------------------------------------------------------------------------------- |
+| `ForPaneResizer` | `[forPaneResizer]` | Single attribute directive. Focusable resizer: tabbable, exposes `aria-value*`, drag. |
+
+## Inputs
+
+| API           | Type                                | Description                                                                                                |
+| ------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `orientation` | `input<'horizontal' \| 'vertical'>` | Axis the divider line runs along. Defaults to `'horizontal'`. The resize axis runs perpendicular.          |
+| `disabled`    | `input<boolean>`                    | Drops the resizer out of tab order; reflects `aria-disabled` / `data-disabled`; blocks keyboard / pointer. |
+| `value`       | `model<number>`                     | Two-way bindable value along the resize axis. Units are consumer-defined (px, %, fr…).                     |
+| `min`         | `input<number>`                     | Lower bound. Default `0`.                                                                                  |
+| `max`         | `input<number>`                     | Upper bound. Default `100`.                                                                                |
+| `step`        | `input<number>`                     | Step applied by ArrowKeys. Default `1`.                                                                    |
+| `largeStep`   | `input<number>`                     | Step applied by `Page Up` / `Page Down`. Default `10`.                                                     |
+| `valueText`   | `input<string \| null>`             | Optional `aria-valuetext` string for human-readable values.                                                |
+| `controls`    | `input<string \| null>`             | Space-separated list of pane ids surfaced as `aria-controls`.                                              |
+| `collapsible` | `input<boolean>`                    | Opt-in `Enter` / `Space` toggle: collapses to `min`, restores to the previous size on the next press.      |
+| `dir`         | `input<'ltr' \| 'rtl'>`             | Reading direction. RTL inverts ArrowLeft / ArrowRight and the horizontal axis of pointer drag.             |
+
+## Outputs
+
+| API            | Payload  | Fires                                                                                                          |
+| -------------- | -------- | -------------------------------------------------------------------------------------------------------------- |
+| `valueChange`  | `number` | Implicit emitter from `model()`. Fires on internal updates only — silent on consumer writes via `[(value)]`.   |
+| `resize`       | `number` | Verb-named alias for `valueChange`. Useful when wiring one-way without `[(value)]`.                            |
+| `resizeCommit` | `number` | Fires once at the end of a resize burst (key release, pointerup, or `pointercancel`). Persist final size here. |
+
+The host gets `data-orientation="horizontal" \| "vertical"` for CSS hooks. When `disabled`, the host also gets `data-disabled=""`.
+
+## Usage
+
+```ts
+import { Component, signal } from '@angular/core';
+import { ForPaneResizer } from 'forty-cdk/pane-resizer';
+
+@Component({
+  selector: 'demo-split-pane',
+  imports: [ForPaneResizer],
+  template: `
+    <div class="split" [style.--start.px]="size()">
+      <section id="pane-a" class="pane-a">…</section>
+
+      <div
+        class="resizer"
+        forPaneResizer
+        orientation="vertical"
+        [(value)]="size"
+        [min]="120"
+        [max]="640"
+        [step]="8"
+        [largeStep]="80"
+        [valueText]="size() + ' pixels'"
+        aria-controls="pane-a pane-b"
+        (resizeCommit)="persist($event)"
+      ></div>
+
+      <section id="pane-b" class="pane-b">…</section>
+    </div>
+  `,
+  styles: `
+    .split {
+      display: grid;
+      grid-template-columns: var(--start) 4px 1fr;
+      block-size: 100%;
+    }
+    .resizer {
+      cursor: col-resize;
+      background: var(--border);
+    }
+    .resizer:focus-visible {
+      outline: 2px solid currentColor;
+      outline-offset: 2px;
+    }
+    .resizer[data-disabled] {
+      cursor: default;
+      opacity: 0.5;
+    }
+  `,
+})
+export class DemoSplitPane {
+  readonly size = signal(280);
+  persist(px: number) {
+    localStorage.setItem('pane-a-size', String(px));
+  }
+}
+```
+
+### Pointer drag
+
+`pointerdown` captures the pointer, records the starting value, and on each `pointermove` adds the **raw px delta** along the resize axis to `value`, clamped to `[min, max]`. Use this directly for px-unit layouts; for percentage / fractional layouts, listen to `(resizing)` and translate yourself, or skip pointer drag and stick to keyboard.
+
+## 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                     |
+| ------------------ | ------------------ | -------------------------- |
+| `[forPaneResizer]` | `data-orientation` | `horizontal` \| `vertical` |
+| `[forPaneResizer]` | `data-disabled`    | present \| absent          |
+
+```css
+.resizer[data-orientation='vertical'] {
+  cursor: col-resize;
+}
+.resizer[data-orientation='horizontal'] {
+  cursor: row-resize;
+}
+.resizer[data-disabled] {
+  cursor: default;
+  opacity: 0.5;
+}
+```
+
+## Accessibility notes
+
+- **Follows the Window Splitter pattern verbatim.**
+  - `aria-orientation` is reflected **explicitly** (both `'horizontal'` and `'vertical'`) so AT can announce the resize axis.
+  - **Arrow keys** move along the resize axis: `Arrow←` / `Arrow→` for a vertical separator (horizontal pane stack), `Arrow↑` / `Arrow↓` for a horizontal separator (vertical pane stack). RTL inverts the horizontal pair.
+  - **`Page Up` / `Page Down`** apply `largeStep` (canonical APG large-step keys, not `Shift+Arrow`).
+  - **`Home` / `End`** snap to `min` / `max`.
+  - **`Enter` / `Space`** toggle to / from `min` when `collapsible` is enabled. Off by default — opt-in because it changes the meaning of `Enter`.
+  - `aria-controls` is recommended: point it at the panes the resizer splits so AT can relate them.
+- **`aria-valuetext`** when the bare number is not meaningful (e.g. `"30 percent of viewport"`).
+- **`data-disabled`** is reflected when `disabled` is true so consumers can flip styling and pointer affordances in CSS.
+- **Accessible name.** Provide a name via native `aria-label` / `aria-labelledby` on the host so AT announces what the resizer adjusts.

package/popover/README.md

@@ -0,0 +1,262 @@
+# Popover
+
+> 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 implementation of the [WAI-ARIA Modeless Dialog pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/), positioned against an internal trigger via [`@floating-ui/dom`](https://floating-ui.com/).
+
+A popover is a non-modal dialog: focus moves into the surface on open and returns to the trigger on close, but Tab is allowed to leave (no focus trap). For a modal version, use `[forDialog]`. For a non-interactive label that follows the cursor / focus, use `[forTooltip]`.
+
+## Usage
+
+```ts
+import { Component } from '@angular/core';
+import {
+  ForPopover,
+  ForPopoverArrow,
+  ForPopoverClose,
+  ForPopoverContent,
+  ForPopoverDescription,
+  ForPopoverTitle,
+  ForPopoverTrigger,
+} from 'forty-cdk/popover';
+
+@Component({
+  selector: 'demo-popover',
+  imports: [
+    ForPopover,
+    ForPopoverTrigger,
+    ForPopoverContent,
+    ForPopoverTitle,
+    ForPopoverDescription,
+    ForPopoverClose,
+    ForPopoverArrow,
+  ],
+  template: `
+    <div forPopover #popover="forPopover" side="bottom" align="start">
+      <button forPopoverTrigger>Settings</button>
+
+      @if (popover.open()) {
+        <div forPopoverContent class="popover" animate.leave="fade-out">
+          <h2 forPopoverTitle>Display</h2>
+          <p forPopoverDescription>Adjust theme and density.</p>
+          <!-- your content -->
+          <button forPopoverClose>Close</button>
+          <span forPopoverArrow class="arrow"></span>
+        </div>
+      }
+    </div>
+  `,
+})
+export class DemoPopover {}
+```
+
+`[forPopoverContent]` portals to `document.body` and is positioned with floating-ui — it must be wrapped with `@if` so mount and unmount drive `animate.enter` / `animate.leave`.
+
+### `#popover="forPopover"` vs. `[(open)]`
+
+The minimal "click trigger → show content" case needs **neither** a separate `open` signal **nor** a two-way binding. `[forPopover]` is `exportAs: 'forPopover'`, so expose the directive instance with a template reference variable — `#popover="forPopover"` — and drive the `@if` straight off its own `open()` signal, as above. The trigger toggles it; Escape and outside dismissal flip it back.
+
+Reach for the explicit `[(open)]="mySignal"` model binding only when the component class needs to read or drive open state — open it programmatically, persist it, or react to it elsewhere:
+
+```html
+<div forPopover [(open)]="open">
+  <button forPopoverTrigger>Settings</button>
+  @if (open()) {
+  <div forPopoverContent>…</div>
+  }
+</div>
+```
+
+### Triggers stamped from outside-declared templates
+
+Angular resolves `ng-template` DI at the template's **declaration** site, not where it is stamped. A `[forPopoverTrigger]` 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="forPopover"` and pass it through the outlet context. The bare valueless attribute keeps resolving via DI.
+
+```html
+<div forPopover #root="forPopover">
+  <ng-container *ngTemplateOutlet="trig; context: { root }" />
+  @if (root.open()) {
+  <div forPopoverContent>…</div>
+  }
+</div>
+
+<ng-template #trig let-root="root">
+  <button [forPopoverTrigger]="root">Settings</button>
+</ng-template>
+```
+
+## Pieces
+
+| Class                   | Selector                  | Role                                                                                                                                                                                                                                                        |
+| ----------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ForPopover`            | `[forPopover]`            | Root. Owns `open`, side / align positioning, dismissible, returnFocus, initialFocus.                                                                                                                                                                        |
+| `ForPopoverTrigger`     | `[forPopoverTrigger]`     | Toggles `open` on click. Wires `aria-haspopup` / `aria-expanded` / `aria-controls`. Used as the floating-ui anchor unless a `[forPopoverAnchor]` is registered.                                                                                             |
+| `ForPopoverAnchor`      | `[forPopoverAnchor]`      | Optional. When present, the popover is positioned against this element instead of the trigger — useful when "what opens it" and "where it appears" differ (cursor follower, contextual help anchored to a row, popover anchored to a text-selection range). |
+| `ForPopoverContent`     | `[forPopoverContent]`     | The popover surface. `role="dialog"`, portaled to body, positioned, dismissable.                                                                                                                                                                            |
+| `ForPopoverTitle`       | `[forPopoverTitle]`       | Generates an id and registers it as `aria-labelledby`.                                                                                                                                                                                                      |
+| `ForPopoverDescription` | `[forPopoverDescription]` | Same, for `aria-describedby`.                                                                                                                                                                                                                               |
+| `ForPopoverClose`       | `[forPopoverClose]`       | Button that sets `open` to `false`. Bypasses `dismissible`.                                                                                                                                                                                                 |
+| `ForPopoverArrow`       | `[forPopoverArrow]`       | Optional decorative arrow positioned by floating-ui.                                                                                                                                                                                                        |
+
+## Inputs (`ForPopover`)
+
+| API                | Default    | Description                                                                                                      |
+| ------------------ | ---------- | ---------------------------------------------------------------------------------------------------------------- |
+| `open`             | `false`    | Two-way bindable visibility.                                                                                     |
+| `side`             | `'bottom'` | Anchor side (`'top'` / `'right'` / `'bottom'` / `'left'`). Falls back to `provideForPopoverDefaults`.            |
+| `align`            | `'center'` | Alignment along the chosen side (`'start'` / `'center'` / `'end'`). Falls back to `provideForPopoverDefaults`.   |
+| `sideOffset`       | `8`        | Gap (px) between trigger and content along the main axis. Falls back to `provideForPopoverDefaults`.             |
+| `alignOffset`      | `0`        | Gap (px) along the cross axis (parallel to `side`).                                                              |
+| `collisionPadding` | `8`        | Padding (px) for the `flip` / `shift` / `size` collision middlewares. Falls back to `provideForPopoverDefaults`. |
+| `disabled`         | `false`    | When `true`, trigger does not toggle.                                                                            |
+| `dismissible`      | `true`     | When `false`, Escape / outside-pointer / outside-focus do not close.                                             |
+| `returnFocus`      | `true`     | Focus returns to the trigger on close.                                                                           |
+| `initialFocus`     | `'first'`  | `'first'` (first focusable inside content) or `'container'` (the content host).                                  |
+| `ariaLabel`        | `null`     | Manual `aria-label` on the content when no `[forPopoverTitle]` is rendered.                                      |
+
+## Inputs (`ForPopoverTrigger`)
+
+| API        | Default | Description                                                                                                                                                       |
+| ---------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `disabled` | `false` | Disables this trigger only — merged OR with the root's `disabled`. The effective state drives `disabled` / `aria-disabled` / `data-disabled` and the click guard. |
+
+## Scoped defaults
+
+`provideForPopoverDefaults` configures positioning 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).
+
+| Key                | Library fallback | Meaning                                                                      |
+| ------------------ | ---------------- | ---------------------------------------------------------------------------- |
+| `side`             | `'bottom'`       | Anchor side for popovers that don't set `side` themselves.                   |
+| `align`            | `'center'`       | Alignment along `side` for popovers that don't set `align` themselves.       |
+| `sideOffset`       | `8`              | Main-axis gap (px) for popovers that don't set `sideOffset` themselves.      |
+| `collisionPadding` | `8`              | Collision-middleware padding (px) for popovers that don't set it themselves. |
+
+Per-instance inputs always win over the scope defaults.
+
+```ts
+import { provideForPopoverDefaults } from 'forty-cdk/popover';
+
+// Top-anchored popovers app-wide
+bootstrapApplication(App, {
+  providers: [provideForPopoverDefaults({ side: 'top', sideOffset: 4 })],
+});
+
+// component-level override layers on top, per key
+@Component({
+  providers: [provideForPopoverDefaults({ align: 'start' })],
+  ...
+})
+class Toolbar {}
+```
+
+## Outputs (`ForPopover`)
+
+The dismiss outputs and the auto-focus pair are vetoable: each receives a `VetoableEvent` (or `VetoableNativeEvent<E>` when there is a native DOM event to surface). Call `preventDefault()` on the emitted veto to suppress the automatic close / focus move; the original DOM event, when present, is on `.event`.
+
+| Output               | Payload                                           | Fires on                                                                                            |
+| -------------------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| `escapeKeyDown`      | `VetoableNativeEvent<KeyboardEvent>`              | Escape while this popover is the topmost dismissable layer.                                         |
+| `pointerDownOutside` | `VetoableNativeEvent<PointerEvent>`               | Pointer-down outside the content (and outside the trigger).                                         |
+| `focusOutside`       | `VetoableNativeEvent<FocusEvent>`                 | Focus moves outside the content (and outside the trigger).                                          |
+| `interactOutside`    | `VetoableNativeEvent<PointerEvent \| FocusEvent>` | Composite: fires alongside both of the above (and shares their veto state).                         |
+| `autoFocusOnOpen`    | `VetoableEvent`                                   | Just before focus moves into the popover on mount. `preventDefault()` skips the move.               |
+| `autoFocusOnClose`   | `VetoableEvent`                                   | Just before focus returns to the trigger on unmount. `preventDefault()` skips the return-focus.     |
+| `openChange`         | `boolean`                                         | Implicit from `model()`. Emits only on internal transitions, not on consumer writes via `[(open)]`. |
+
+`(autoFocusOnOpen)` / `(autoFocusOnClose)` are output-shape because Popover always routes close transitions through `[(open)]` (via the implicit `openChange` emitter). See [CLAUDE.md › Auto-focus hook shape](../../../../../CLAUDE.md#auto-focus-hook-shape) for why Dialog uses callback-shape inputs instead.
+
+### Open without stealing focus
+
+```html
+<div forPopover [(open)]="open">
+  <input forPopoverAnchor #q type="search" (input)="open.set(true)" placeholder="Search…" />
+  <button forPopoverTrigger hidden></button>
+
+  @if (open()) {
+  <div
+    forPopoverContent
+    (autoFocusOnOpen)="$event.preventDefault()"
+    (autoFocusOnClose)="$event.preventDefault()"
+  >
+    …
+  </div>
+  }
+</div>
+```
+
+The popover opens / closes alongside the input but never steals focus from it — handy for live-search panels where every keystroke matters.
+
+## 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             |
+| --------------------- | --------------------- | ------------------ |
+| `[forPopover]`        | `data-state`          | `open` \| `closed` |
+| `[forPopover]`        | `data-disabled`       | present \| absent  |
+| `[forPopover]`        | `data-reduced-motion` | present \| absent  |
+| `[forPopoverTrigger]` | `data-state`          | `open` \| `closed` |
+| `[forPopoverTrigger]` | `data-disabled`       | present \| absent  |
+| `[forPopoverContent]` | `data-state`          | `open` \| `closed` |
+| `[forPopoverContent]` | `data-reduced-motion` | present \| absent  |
+| `[forPopoverArrow]`   | `data-popover-arrow`  | present            |
+
+### CSS custom properties
+
+See also: [Styling floating content](../../../../../docs/styling-floating-content.md) — animation rules, standalone `scale`/`opacity`, and the arrow recipe.
+
+`[forPopoverContent]` 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 `[forPopoverArrow]` reads the consumer-settable `--for-arrow-offset`:
+
+| Element               | Custom property                  | Type / range        | Direction | Meaning                                                                                                      |
+| --------------------- | -------------------------------- | ------------------- | --------- | ------------------------------------------------------------------------------------------------------------ |
+| `[forPopoverContent]` | `--for-anchor-width`             | px                  | out       | Trigger (reference) width — match it with `width: var(--for-anchor-width)`.                                  |
+| `[forPopoverContent]` | `--for-anchor-height`            | px                  | out       | Trigger (reference) height.                                                                                  |
+| `[forPopoverContent]` | `--for-available-width`          | px                  | out       | Space available along the inline axis (floating-ui `size` middleware) — clamp with `max-width`.              |
+| `[forPopoverContent]` | `--for-available-height`         | px                  | out       | Space available along the block axis — clamp with `max-height`.                                              |
+| `[forPopoverContent]` | `--for-content-transform-origin` | `<origin>` keywords | out       | `transform-origin` matching the resolved side / align, so a `scale` enter animation pivots from the trigger. |
+| `[forPopoverArrow]`   | `--for-arrow-offset`             | px (default `0px`)  | in        | Consumer-set. How far the arrow pokes out past the popover edge — typically a negative `px` (e.g. `-4px`).   |
+
+> `[forPopoverContent]` portals to `document.body`, so ancestor-scoped CSS can't reach it. Style it with global CSS or a class — see [Styling floating content](../../../../../docs/styling-floating-content.md) for the full positioner-property list and the floating-content rules.
+
+```css
+.popover-trigger .chevron {
+  transition: transform 150ms;
+}
+.popover-trigger[data-state='open'] .chevron {
+  transform: rotate(180deg);
+}
+```
+
+### Reduced motion
+
+`[forPopover]` and `[forPopoverContent]` reflect `data-reduced-motion` (present / absent) whenever the OS `prefers-reduced-motion: reduce` media query matches, so you can opt your own `animate.enter` / `animate.leave` and CSS transitions out without re-deriving the query. The attribute flips reactively if the preference changes mid-session. The popover toggles open / closed synchronously on click, so there is no JS-coordinated timing to skip — only the visual transitions (which are yours) opt out.
+
+```css
+.popover-content[data-reduced-motion] {
+  transition: none;
+}
+```
+
+## Keyboard
+
+- **Tab / Shift+Tab** moves focus through the popover and beyond (no trap). When focus leaves, `focusOutside` fires and the popover closes unless prevented.
+- **Escape** closes when `dismissible`. Use `(escapeKeyDown)="$event.preventDefault()"` to ask "are you sure?" first.
+- **Enter / Space** on the trigger toggles (native button behavior).
+
+## Behavior notes
+
+- **Portal**: the content is moved to `document.body` on first render. CSS scoped to ancestors won't reach it — use global styles or classes.
+- **Trigger exemption**: clicks on the trigger never fire `pointerDownOutside` or `interactOutside`. Their only effect is the trigger's own toggle.
+- **Anchor vs. trigger**: `[forPopoverAnchor]` only changes the floating-ui reference. The trigger keeps `aria-controls` / `aria-expanded`, the click toggle, and focus return on close. The anchor is _not_ exempt from outside dismissal — clicking it is treated as outside.
+- **Non-modal**: no focus trap, no body scroll lock, no `aria-modal`. If you need modal semantics, use `[forDialog]` instead.
+- **No backdrop**: popovers don't render an overlay. Outside dismissal is event-driven.
+- **Focus return**: on unmount, focus is sent back to the registered trigger element (unless `returnFocus="false"`). The return happens before the portal helper removes the node, so the trigger receives `focusin` against a stable layout.
+- **Arrow offset**: `[forPopoverArrow]` writes `position: absolute`, the floating-ui-resolved `left` / `top`, and `var(--for-arrow-offset, 0px)` on the side opposite the popover (so the arrow points back at the trigger). 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`. Defaults to `0px` (flush with the popover edge); the helper ships no default visual.
+
+## Accessibility notes
+
+- Always provide an accessible name: render a `[forPopoverTitle]` or pass `ariaLabel`.
+- `[forPopoverDescription]` is optional — use it for explanatory copy beyond the title.
+- `aria-haspopup="dialog"` advertises the popover as a dialog (matches `role="dialog"` on the content). For menus or listboxes, build a different primitive.
+- The popover is not modal: assistive tech users can still navigate around it. That's intentional — modeless surfaces should not interrupt.

package/progress/README.md

@@ -0,0 +1,115 @@
+# Progress
+
+Headless [WAI-ARIA `progressbar`](https://www.w3.org/TR/wai-aria-1.2/#progressbar) for tasks whose completion you can communicate visually.
+
+Pass a numeric `value` for a determinate bar, or `null` for indeterminate ("loading…"). The directive owns ARIA + state; the visual fill is yours via `[forProgressIndicator]`.
+
+## Pieces
+
+| Class                  | Selector                 | Role                                                                |
+| ---------------------- | ------------------------ | ------------------------------------------------------------------- |
+| `ForProgress`          | `[forProgress]`          | Root. Owns `value` / `max`, reflects `role="progressbar"` and ARIA. |
+| `ForProgressIndicator` | `[forProgressIndicator]` | Visual fill. Reflects `data-state` and `data-percentage`.           |
+
+## Inputs / models
+
+| API                  | Type                                      | Description                                                                                                                              |
+| -------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `value`              | `model<number \| null>`                   | Two-way bindable. Current progress in `[0, max]`. `null` = indeterminate.                                                                |
+| `max`                | `input<number>`                           | Upper bound. Defaults to `100`. A non-positive `max` is clamped to `1` for ARIA so `aria-valuemax` always exceeds `aria-valuemin` (`0`). |
+| `getValueLabel`      | `input<((value, max) => string) \| null>` | Override for `aria-valuetext` (e.g. "Step 3 of 5").                                                                                      |
+| `announceCompletion` | `input<boolean>`                          | Announce `Complete` (or the label) once via `aria-live` on the loading→complete transition.                                              |
+
+The host carries `data-state="indeterminate" \| "loading" \| "complete"`, `data-value`, `data-min`, `data-max`, and `data-percentage` (absent while indeterminate), matching the meter root so the root can be styled from `data-percentage` directly. The indicator reflects the same `data-percentage` plus the CSS custom property `--for-progress-percentage` (e.g. `25%`) that you can use directly in `transform` / `width`.
+
+## Usage
+
+```ts
+import { Component, signal } from '@angular/core';
+import { ForProgress, ForProgressIndicator } from 'forty-cdk/progress';
+
+@Component({
+  selector: 'demo-upload',
+  imports: [ForProgress, ForProgressIndicator],
+  template: `
+    <div forProgress class="progress" [value]="uploaded()" [max]="total()" announceCompletion>
+      <div forProgressIndicator class="progress-indicator"></div>
+    </div>
+  `,
+  styles: [
+    `
+      .progress {
+        position: relative;
+        height: 8px;
+        width: 240px;
+        background: #eee;
+        border-radius: 4px;
+        overflow: hidden;
+      }
+      .progress-indicator {
+        position: absolute;
+        inset: 0;
+        background: #4f46e5;
+        transform-origin: left center;
+        transition: transform 120ms;
+      }
+      .progress-indicator[data-state='loading'] {
+        transform: scaleX(calc(var(--for-progress-percentage) / 100));
+      }
+      .progress-indicator[data-state='indeterminate'] {
+        transform: scaleX(0.4);
+        animation: slide 1.2s infinite ease-in-out;
+      }
+      @keyframes slide {
+        from {
+          transform: translateX(-100%) scaleX(0.4);
+        }
+        to {
+          transform: translateX(250%) scaleX(0.4);
+        }
+      }
+    `,
+  ],
+})
+export class DemoUpload {
+  readonly uploaded = signal(0);
+  readonly total = signal(200);
+}
+```
+
+## 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                                     |
+| ------------------------ | ----------------- | ------------------------------------------ |
+| `[forProgress]`          | `data-state`      | `indeterminate` \| `loading` \| `complete` |
+| `[forProgress]`          | `data-value`      | clamped value (absent while indeterminate) |
+| `[forProgress]`          | `data-min`        | `0`                                        |
+| `[forProgress]`          | `data-max`        | the `max` value                            |
+| `[forProgress]`          | `data-percentage` | `0`–`100` (absent while indeterminate)     |
+| `[forProgressIndicator]` | `data-state`      | `indeterminate` \| `loading` \| `complete` |
+| `[forProgressIndicator]` | `data-value`      | clamped value (absent while indeterminate) |
+| `[forProgressIndicator]` | `data-max`        | the `max` value                            |
+| `[forProgressIndicator]` | `data-percentage` | `0`–`100` (absent while indeterminate)     |
+
+### CSS custom properties
+
+| Property                    | Meaning                                                                                                                      |
+| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `--for-progress-percentage` | Completion as a CSS percentage (e.g. `25%`), set on `[forProgressIndicator]`. Absent while indeterminate (`value === null`). |
+
+```css
+.progress-indicator[data-state='loading'] {
+  transform: scaleX(calc(var(--for-progress-percentage) / 100));
+}
+```
+
+## Accessibility notes
+
+- **`role="progressbar"`** is announced as "progressbar" with the current value as a percentage (or your `aria-valuetext` if `getValueLabel` is set).
+- **Indeterminate omits `aria-valuenow`.** Per spec, the absence of `aria-valuenow` is what tells AT the bar is indeterminate. The directive enforces this; `data-state="indeterminate"` is the CSS hook.
+- **Announce sparingly.** `announceCompletion` is opt-in; only enable it on flows where the user explicitly waits for completion (uploads, submissions). For background activity, the silent state change is enough.
+- **Keep the bar focusable only if it has actions.** A vanilla `[forProgress]` is non-interactive and should not be in the tab order.