forty-cdk 0.2.0 → 0.3.0

package/context-menu/README.md

@@ -0,0 +1,139 @@
+# ContextMenu
+
+> 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 right-click menu — variant of the [WAI-ARIA Menu pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menubar/) opened via the `contextmenu` event (right-click, long-press on touch) and via the keyboard activators `Shift+F10` and the dedicated `ContextMenu` key. The native browser context menu is suppressed.
+
+Pointer activations anchor the menu at the cursor; keyboard activations anchor it at the bounding rect of the focused element so screen-reader / keyboard-only users get the menu next to whatever they're working on. Floating-ui's virtual element handles either case — placement, flip, and shift middleware still apply, so the menu is repositioned to stay on-screen automatically.
+
+## Usage
+
+```ts
+import { Component, signal } from '@angular/core';
+import { ForContextMenu, ForContextMenuTrigger } from 'forty-cdk/context-menu';
+import { ForMenuContent, ForMenuItem } from 'forty-cdk/menu';
+
+@Component({
+  selector: 'demo-context',
+  imports: [ForContextMenu, ForContextMenuTrigger, ForMenuContent, ForMenuItem],
+  template: `
+    <div forContextMenu #menu="forContextMenu">
+      <div forContextMenuTrigger class="canvas context-menu-trigger">
+        Right-click anywhere here.
+      </div>
+      @if (menu.open()) {
+        <div forMenuContent animate.leave="fade-out">
+          <button forMenuItem (activate)="rename()">Rename</button>
+          <button forMenuItem (activate)="duplicate()">Duplicate</button>
+          <button forMenuItem (activate)="delete()">Delete</button>
+        </div>
+      }
+    </div>
+  `,
+})
+export class DemoContext {
+  rename() {
+    /* ... */
+  }
+  duplicate() {
+    /* ... */
+  }
+  delete() {
+    /* ... */
+  }
+}
+```
+
+The trigger is focusable out of the box: `[forContextMenuTrigger]` host-binds a default `tabindex="-1"` so focus returns there programmatically when the menu closes — no consumer setup required. Override it with your own `tabindex` (e.g. `tabindex="0"` to put the region in the Tab order) and it wins.
+
+### `#menu="forContextMenu"` vs. `[(open)]`
+
+The minimal "right-click → show menu" case needs **neither** a separate `open` signal **nor** a two-way binding. `[forContextMenu]` is `exportAs: 'forContextMenu'`, so expose the directive instance with a template reference variable — `#menu="forContextMenu"` — and drive the `@if` straight off its own `open()` signal, as above. The contextmenu gesture, item activation, Escape, and outside dismissal all flip it.
+
+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 forContextMenu [(open)]="open">
+  <div forContextMenuTrigger class="context-menu-trigger">Right-click anywhere here.</div>
+  @if (open()) {
+  <div forMenuContent>…</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 `[forContextMenuTrigger]` 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="forContextMenu"` and pass it through the outlet context. The bare valueless attribute keeps resolving via DI.
+
+```html
+<div forContextMenu #root="forContextMenu">
+  <ng-container *ngTemplateOutlet="chip; context: { root }" />
+  @if (root.open()) {
+  <div forMenuContent>…</div>
+  }
+</div>
+
+<ng-template #chip let-root="root">
+  <span [forContextMenuTrigger]="root">Right-click here</span>
+</ng-template>
+```
+
+## Pieces
+
+| Class                   | Selector                  | Role                                                                                                                                                                                             |
+| ----------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `ForContextMenu`        | `[forContextMenu]`        | Root. Owns open state, the virtual anchor (pointer position), navigation, typeahead.                                                                                                             |
+| `ForContextMenuTrigger` | `[forContextMenuTrigger]` | The right-click region. Captures `contextmenu`, `Shift+F10`, and the `ContextMenu` key, prevents the native menu, and opens — anchored at the pointer (mouse) or the focused element (keyboard). |
+
+The menu items themselves come from the [`menu/`](../menu/README.md) folder.
+
+## Inputs (`ForContextMenu`)
+
+| API           | Default    | Description                                                                                                                                                                    |
+| ------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `open`        | `false`    | Two-way bindable. Whether the menu is shown.                                                                                                                                   |
+| `side`        | `'bottom'` | Anchor side relative to the pointer.                                                                                                                                           |
+| `align`       | `'start'`  | Alignment along `side` (`'start'` / `'center'` / `'end'`).                                                                                                                     |
+| `sideOffset`  | `0`        | Gap (px) between the pointer and the menu along the main axis.                                                                                                                 |
+| `alignOffset` | `0`        | Gap (px) along the cross axis (parallel to `side`).                                                                                                                            |
+| `loop`        | `true`     | Whether arrow navigation wraps.                                                                                                                                                |
+| `dir`         | `'ltr'`    | Writing direction. In RTL, ArrowLeft opens submenus and ArrowRight closes them — the swap is automatic. Inherited by every nested `[forMenuSub]` underneath unless overridden. |
+| `disabled`    | `false`    | When `true`, the contextmenu event falls through to the native browser menu.                                                                                                   |
+| `dismissible` | `true`     | When `false`, Escape and outside interactions don't close.                                                                                                                     |
+| `returnFocus` | `true`     | When `true`, focus returns to the trigger element on close.                                                                                                                    |
+| `ariaLabel`   | `null`     | Manual `aria-label` on `[forMenuContent]`.                                                                                                                                     |
+
+## Outputs (`ForContextMenu`)
+
+Same vetoable dismiss API as DropdownMenu — `(escapeKeyDown)`, `(pointerDownOutside)`, `(focusOutside)`, `(interactOutside)`. Each handler receives a `VetoableNativeEvent<E>` (the original DOM event lives on `.event`); call `preventDefault()` on the veto to keep the menu open.
+
+`(autoFocusOnOpen)` / `(autoFocusOnClose)` fire just before the imperative focus move on mount / unmount. Each receives a `VetoableEvent`; call `preventDefault()` on the veto to skip the move while keeping the menu mounted. These are output-shape because ContextMenu 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.
+
+## 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             |
+| ------------------------- | --------------- | ------------------ |
+| `[forContextMenu]`        | `data-state`    | `open` \| `closed` |
+| `[forContextMenu]`        | `data-disabled` | present \| absent  |
+| `[forContextMenuTrigger]` | `data-state`    | `open` \| `closed` |
+| `[forContextMenuTrigger]` | `data-disabled` | present \| absent  |
+
+> The menu content (`[forMenuContent]`, from the [`menu/`](../menu/README.md) folder) portals to `document.body`, so it sits outside the trigger's DOM subtree — descendant selectors won't reach it. Style it with **global CSS** or a class on the content element. The content host also exposes the shared positioner custom properties (`--for-anchor-width` / `--for-anchor-height`, `--for-available-width` / `--for-available-height`, `--for-content-transform-origin`); see [Styling floating content](../../../../../docs/styling-floating-content.md) for the full list and the animation rules.
+
+```css
+.context-menu-trigger[data-state='open'] {
+  outline: 2px solid hotpink;
+}
+```
+
+## Behavior notes
+
+- **Trigger is NOT exempt** from outside-pointer / outside-focus checks. Unlike DropdownMenu (where the trigger button toggles via its own click handler), the context-menu region is treated like any other "outside" element — a left-click on the region while the menu is open closes it. Right-clicking again immediately reopens at the new position. This is a full close → open cycle, not an in-place reposition: re-right-clicking while the menu is already open tears the surface down and rebuilds it (so any `animate.enter` / `animate.leave` replays and focus resets). Keep enter/leave animations cheap, or gate expensive ones, since a user can fire this rapidly — the directive deliberately exempts nothing, so there is no smooth reposition path to attach to.
+- **Virtual anchor.** Right-click captures a 0×0 rect at the pointer location. `Shift+F10` and `ContextMenu` snapshot the bounding rect of the focused element (or the trigger if focus is on it directly), so the menu floats off the element under attention. Both forms feed floating-ui's `flip` and `shift` middleware, so corners and screen edges work without special-casing.
+- **Keyboard activators only fire while focus is inside the trigger.** Keyboard events dispatch to the focused element, so `Shift+F10` / `ContextMenu` anywhere outside the trigger goes to the browser default. The trigger is focusable by default (host-bound `tabindex="-1"`), so this works out of the box; use `tabindex="0"` if you want the region itself reachable via Tab.
+- **Native menu suppressed.** The trigger calls `event.preventDefault()` on `contextmenu` and on the keyboard activators. Set `disabled` to let the browser's native menu surface for that region.
+- **Mount equals open.** Same convention as the rest of the library — wrap `[forMenuContent]` in `@if (open())` and use `animate.enter` / `animate.leave` for transitions.

package/date-field/README.md

@@ -0,0 +1,184 @@
+# DateField
+
+Headless, segmented, spin-editable date input — the keyboard-first counterpart to [Calendar](../calendar/README.md). There is **no single WAI-ARIA APG pattern** for a date field; it is a composition of [Spinbuttons](https://www.w3.org/WAI/ARIA/apg/patterns/spinbutton/) inside a labelled `role="group"`. Each day / month / year part is an independent `role="spinbutton"` segment, so entry is unambiguous and locale-correct — no free-text parsing, no `03/04`-is-it-March-4th guesswork. Segment **order** and separators follow the runtime locale (`MM/DD/YYYY` vs `DD.MM.YYYY` vs `YYYY/MM/DD`).
+
+`ForDateField` implements `FormValueControl<D | null>` from `@angular/forms/signals`, so it auto-wires with `[formField]` and auto-associates inside a `[forField]` (label / description / error) with no extra markup. The value stays `null` until every segment is filled.
+
+## Date adapter — pick one (required)
+
+All date math goes through the same pluggable `DateAdapter<D>` as `ForCalendar`, so the library hard-depends on **no** date library. Provide exactly one adapter in your application (or component) providers:
+
+| Provider                                | Date type `D`                              | Dependency                                                                                                |
+| --------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------- |
+| `provideInternationalizedDateAdapter()` | `CalendarDate` (`@internationalized/date`) | **Recommended.** From `forty-cdk/internationalized-date`; needs `@internationalized/date` (optional peer) |
+| `provideNativeDateAdapter()`            | `Date`                                     | None (zero-dependency fallback)                                                                           |
+
+```ts
+import { bootstrapApplication } from '@angular/platform-browser';
+import { provideInternationalizedDateAdapter } from 'forty-cdk/internationalized-date';
+
+bootstrapApplication(App, {
+  providers: [provideInternationalizedDateAdapter()],
+});
+```
+
+## Pieces
+
+| Class                 | Selector                | Role                                                                                               |
+| --------------------- | ----------------------- | -------------------------------------------------------------------------------------------------- |
+| `ForDateField`        | `[forDateField]`        | Root (`role="group"`). Owns the entered parts, composes the value, and exposes `segments()`.       |
+| `ForDateFieldSegment` | `[forDateFieldSegment]` | One editable part (`role="spinbutton"`). Roving tab stop, ARIA value reflection, keyboard editing. |
+| `ForDateFieldLiteral` | `[forDateFieldLiteral]` | A decorative separator (`/`, `.`, `-`). `aria-hidden`, out of the tab order.                       |
+
+## Inputs / models — `ForDateField`
+
+| API           | Type                                                  | Description                                                                                                                         |
+| ------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `value`       | `model<D \| null>`                                    | Two-way bindable entered date, or `null` while any segment is empty. The `FormValueControl` backing. Default `null`.                |
+| `minDate`     | `input<D \| null>`                                    | Minimum date (inclusive). A composed value below it is clamped up. Named `minDate` — see note below. Default `null`.                |
+| `maxDate`     | `input<D \| null>`                                    | Maximum date (inclusive). A composed value above it is clamped down. Default `null`.                                                |
+| `granularity` | `input<'day' \| 'hour' \| 'minute' \| 'second'>`      | Date-time precision. `'day'` (default) is date-only; coarser-than-day off appends time segments. See below.                         |
+| `hourCycle`   | `input<12 \| 24 \| null>`                             | 12/24-hour cycle for the time segments. Default `null` → locale. 12-hour adds the AM/PM segment.                                    |
+| `locale`      | `input<string \| null>`                               | BCP 47 locale driving segment order, separators, and month name. Default `null` → runtime locale.                                   |
+| `placeholder` | `input<Partial<Record<DateTimeSegmentType, string>>>` | Per-segment placeholder while empty. Unspecified parts fall back to `dd` / `mm` / `yyyy` / `hh` / `mm` / `ss` / `--`. Default `{}`. |
+| `ariaLabel`   | `input<string \| null>`                               | Accessible name for the group. Emits no `aria-label` while `null`. Default `null`.                                                  |
+| `dir`         | `input<'ltr' \| 'rtl' \| null>`                       | Writing direction. Default `null` resolves the ambient direction; mirrors ArrowLeft / ArrowRight segment navigation.                |
+
+Plus the shared `FormUiControl` members from `@angular/forms/signals`: `disabled`, `readonly`, `required`, `invalid`, `name`, `errors`, `touched` (bound automatically by `[formField]`).
+
+> **Why `minDate` / `maxDate`, not `min` / `max`?** `FormUiControl.min` / `max` are reserved members typed `number | undefined` for numeric validators bound by `[formField]`. A date-typed `min` / `max` would break the `FormValueControl` contract, so the date bounds use distinct names.
+
+## Usage
+
+```ts
+import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
+import { CalendarDate } from '@internationalized/date';
+import { ForDateField, ForDateFieldLiteral, ForDateFieldSegment } from 'forty-cdk/date-field';
+
+@Component({
+  selector: 'app-dob',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [ForDateField, ForDateFieldSegment, ForDateFieldLiteral],
+  template: `
+    <div
+      forDateField
+      class="date-field"
+      [(value)]="date"
+      [ariaLabel]="'Date of birth'"
+      #field="forDateField"
+    >
+      @for (seg of field.segments(); track seg.id) {
+        @if (seg.isLiteral) {
+          <span forDateFieldLiteral>{{ seg.text }}</span>
+        } @else {
+          <span forDateFieldSegment class="date-field-segment" [segment]="seg.type!">{{
+            seg.text
+          }}</span>
+        }
+      }
+    </div>
+  `,
+})
+export class DobField {
+  readonly date = signal<CalendarDate | null>(null);
+}
+```
+
+The library is styleless: style the boolean `data-*` hooks on the segments yourself — `[data-highlighted]` (the focused/roving segment), `[data-placeholder]` (empty), `[data-disabled]`, `[data-readonly]` — and `[data-empty]` / `[data-disabled]` / `[data-readonly]` on the root group.
+
+## Keyboard (per segment)
+
+Horizontal arrows mirror under `dir="rtl"`.
+
+| Key                        | Behavior                                                                 |
+| -------------------------- | ------------------------------------------------------------------------ |
+| **0–9**                    | Type the value; auto-advances to the next segment when full.             |
+| **ArrowUp / ArrowDown**    | Step the value. Day and month wrap; year clamps. Empty seeds from today. |
+| **ArrowLeft / ArrowRight** | Move to the previous / next segment (no wrap).                           |
+| **Home / End**             | Jump to the segment minimum / maximum.                                   |
+| **Backspace / Delete**     | Clear the segment (the value becomes `null` until refilled).             |
+
+The day clamps to the current month's length (e.g. 31 → 28 in February), and a composed value is clamped into `[minDate, maxDate]`.
+
+## Date-time field (`granularity > 'day'`)
+
+Set `granularity` to `'hour'`, `'minute'`, or `'second'` to append time segments — hour / minute / second and, in 12-hour mode, an AM·PM `dayPeriod` — after the date segments in the same `role="group"`. The whole field stays a single tab stop with one roving cursor across **all** segments; `field.segments()` already returns the combined, locale-ordered list, so the same `@for` template renders it. This needs a **time-capable** adapter — `provideNativeDateAdapter()` (`Date`) or `provideInternationalizedDateTimeAdapter()` (`CalendarDateTime`); the day-only `provideInternationalizedDateAdapter()` (`CalendarDate`) throws.
+
+```html
+<div
+  forDateField
+  class="date-field"
+  [(value)]="when"
+  granularity="minute"
+  [hourCycle]="24"
+  #field="forDateField"
+>
+  @for (seg of field.segments(); track seg.id) { @if (seg.isLiteral) {
+  <span forDateFieldLiteral>{{ seg.text }}</span>
+  } @else {
+  <span forDateFieldSegment class="date-field-segment" [segment]="seg.type!">{{ seg.text }}</span>
+  } }
+</div>
+```
+
+On the AM/PM segment, `a` / `p` set the period and ArrowUp / ArrowDown toggle it; the period is derived from the entered hour, so clearing it is a no-op (clear or step the hour instead). The value stays `null` until every visible segment — date **and** time — is filled.
+
+## Scope defaults
+
+```ts
+import { provideForDateFieldDefaults } from 'forty-cdk/date-field';
+
+// app config or a component's providers — localize segment labels and the
+// empty-segment announcement for every nested [forDateField].
+providers: [
+  provideForDateFieldDefaults({
+    emptySegmentText: 'Vacío',
+    segmentLabels: { day: 'día', month: 'mes', year: 'año', dayPeriod: 'AM/PM' },
+  }),
+];
+```
+
+`segmentLabels` supplies each segment's default `aria-label`, keyed by part type. Unset keys keep the library default (the part name, and `'AM/PM'` for the `dayPeriod` segment), so overriding a single key never wipes the rest. A segment's own `[ariaLabel]` still wins over the scope default.
+
+## 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            |
+| ----------------------- | ------------------ | ----------------- |
+| `[forDateField]`        | `data-disabled`    | present \| absent |
+| `[forDateField]`        | `data-readonly`    | present \| absent |
+| `[forDateField]`        | `data-empty`       | present \| absent |
+| `[forDateFieldSegment]` | `data-highlighted` | present \| absent |
+| `[forDateFieldSegment]` | `data-placeholder` | present \| absent |
+| `[forDateFieldSegment]` | `data-disabled`    | present \| absent |
+| `[forDateFieldSegment]` | `data-readonly`    | present \| absent |
+
+`data-empty` marks the whole field while any segment is still unfilled (the value is `null`); `data-placeholder` marks each individual segment that is still empty. `data-highlighted` is the current roving-tabindex segment — the only focus hook the consumer gets, shared with the other roving primitives. `[forDateFieldLiteral]` carries no data-\* attributes (it is `aria-hidden` and out of the tab order).
+
+```css
+.date-field-segment[data-placeholder] {
+  color: GrayText;
+}
+.date-field-segment[data-highlighted] {
+  background: Highlight;
+  color: HighlightText;
+}
+.date-field[data-disabled] {
+  opacity: 0.5;
+}
+```
+
+## Accessibility notes
+
+- **`role="group"`** on the root carries the field's accessible name (`ariaLabel`, or point native `aria-labelledby` at a visible label).
+- **`role="spinbutton"`** per segment, with `aria-valuemin` / `aria-valuemax` / `aria-valuenow` reflected; the month segment also exposes a localized `aria-valuetext` ("March"), so screen readers read the name rather than the number.
+- **Roving tabindex**: exactly one segment is tabbable, so `Tab` enters and leaves the whole field in one stop; arrows move between segments.
+- **Literals are `aria-hidden`** and never focusable — assistive tech reads only the spinbutton segments.
+- **Boolean `data-*`** on each segment — `data-highlighted` (focused/roving), `data-placeholder` (empty), `data-disabled`, `data-readonly` — present when true, absent when false.
+
+## Wrapping in a design system
+
+Both supported wrapper patterns — `hostDirectives` with the exported `FOR_DATE_FIELD_HOST_DIRECTIVE_INPUTS` / `FOR_DATE_FIELD_HOST_DIRECTIVE_OUTPUTS` name tuples, and subclassing — are documented in [Wrapping form primitives](../../../../../docs/wrapping-form-primitives.md).