forty-cdk 0.2.0 → 0.3.0

package/toolbar/README.md

@@ -0,0 +1,109 @@
+# Toolbar
+
+Headless implementation of the [WAI-ARIA Toolbar pattern](https://www.w3.org/WAI/ARIA/apg/patterns/toolbar/). A toolbar is a single Tab stop that contains a set of buttons, links, and toggle groups; arrow keys move focus inside.
+
+Composes naturally with `[forToggleGroup]` — toggle items nested inside a toolbar register with the toolbar's roving tabindex automatically, so arrows move fluidly across the whole bar.
+
+## Pieces
+
+| Class                 | Selector                | Role                                                                                                                                       |
+| --------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `ForToolbar`          | `[forToolbar]`          | Root. `role="toolbar"`. Owns roving + nav.                                                                                                 |
+| `ForToolbarButton`    | `[forToolbarButton]`    | Plain push button. Apply on `<button>`.                                                                                                    |
+| `ForToolbarLink`      | `[forToolbarLink]`      | Hyperlink. Apply on `<a>`.                                                                                                                 |
+| `ForToolbarSeparator` | `[forToolbarSeparator]` | Visual divider. Defaults `orientation` to the toolbar's cross-axis; reflects `role="separator"` + `aria-orientation` + `data-orientation`. |
+
+## Inputs (root)
+
+| API           | Type                                | Description                                                                                                                                                      |
+| ------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ariaLabel`   | `input<string \| null>`             | Reactive accessible name, reflected as `aria-label`. Default `null` (and `''`) emits no attribute. Prefer `aria-labelledby` when a visible label element exists. |
+| `orientation` | `input<'horizontal' \| 'vertical'>` | Layout direction. Default `'horizontal'`.                                                                                                                        |
+| `dir`         | `input<WritingDirection>`           | Reading direction. RTL swaps ArrowLeft / ArrowRight.                                                                                                             |
+| `loop`        | `input<boolean>`                    | Whether arrow nav wraps at the ends. Default `true`.                                                                                                             |
+| `disabled`    | `input<boolean>`                    | Disables every item.                                                                                                                                             |
+
+## Usage
+
+```ts
+import { Component, signal } from '@angular/core';
+import { ForToggleGroup, ForToggleGroupItem } from 'forty-cdk/toggle';
+import {
+  ForToolbar,
+  ForToolbarButton,
+  ForToolbarLink,
+  ForToolbarSeparator,
+} from 'forty-cdk/toolbar';
+
+@Component({
+  selector: 'demo-toolbar',
+  imports: [
+    ForToolbar,
+    ForToolbarButton,
+    ForToolbarLink,
+    ForToolbarSeparator,
+    ForToggleGroup,
+    ForToggleGroupItem,
+  ],
+  template: `
+    <div forToolbar class="toolbar" [ariaLabel]="'Formatting'">
+      <button forToolbarButton class="toolbar-button" (click)="undo()">Undo</button>
+      <button forToolbarButton class="toolbar-button" (click)="redo()">Redo</button>
+      <span forToolbarSeparator></span>
+      <div forToggleGroup multiple [(value)]="formatting">
+        <button forToggleGroupItem value="bold">B</button>
+        <button forToggleGroupItem value="italic">I</button>
+        <button forToggleGroupItem value="underline">U</button>
+      </div>
+      <span forToolbarSeparator></span>
+      <a forToolbarLink class="toolbar-link" href="/help">Help</a>
+    </div>
+  `,
+})
+export class DemoToolbar {
+  readonly formatting = signal<readonly string[]>([]);
+  undo() {}
+  redo() {}
+}
+```
+
+## 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                     |
+| ----------------------- | ------------------ | -------------------------- |
+| `[forToolbar]`          | `data-orientation` | `horizontal` \| `vertical` |
+| `[forToolbar]`          | `data-disabled`    | present \| absent          |
+| `[forToolbarButton]`    | `data-orientation` | `horizontal` \| `vertical` |
+| `[forToolbarButton]`    | `data-disabled`    | present \| absent          |
+| `[forToolbarLink]`      | `data-orientation` | `horizontal` \| `vertical` |
+| `[forToolbarLink]`      | `data-disabled`    | present \| absent          |
+| `[forToolbarSeparator]` | `data-orientation` | `horizontal` \| `vertical` |
+
+```css
+.toolbar {
+  display: flex;
+  gap: 0.25rem;
+}
+
+.toolbar[data-orientation='vertical'] {
+  flex-direction: column;
+}
+
+.toolbar-button[data-disabled],
+.toolbar-link[data-disabled] {
+  opacity: 0.4;
+  pointer-events: none;
+}
+```
+
+## Accessibility notes
+
+- **Single Tab stop that follows focus.** The toolbar takes one place in the tab order; only the entry-point item carries `tabindex="0"`. Before any interaction the entry point is the first enabled item; once you move focus with the arrows (or Home / End), the tab stop follows the last focused item, so Shift+Tab back into the toolbar restores it (matching APG and the Tabs / Tree primitives). Arrow keys move focus inside, Home / End jump to the first / last enabled item.
+- **Always label the toolbar.** Pass the reactive `[ariaLabel]` input (or a native `aria-labelledby` pointing at a visible label element) so screen-reader users know what the toolbar acts on. Not optional — APG requires it.
+- **Disabled items stay focusable on `<a forToolbarLink>`.** Native `<a>` has no `disabled` attribute; we expose `aria-disabled="true"` and suppress click. Removing the link from the focus order would deviate from APG; users can still hear "disabled".
+- **Toggle groups don't change roles.** Inside a toolbar, `[forToggleGroup]` keeps `role="group"` (semantically a related set of buttons). The toolbar role lives only on the outer container.
+- **Cross-axis separators.** `[forToolbarSeparator]` defaults to the orientation perpendicular to the toolbar so the line is visible. Override by setting `orientation` explicitly.

package/tooltip/README.md

@@ -0,0 +1,274 @@
+# Tooltip
+
+> 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 Tooltip pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/) with hover / focus delays, Escape-to-dismiss, portal rendering, and `@floating-ui/dom`-driven positioning.
+
+> APG: tooltips are for **non-interactive** descriptive text. If you need a click-to-open menu / popup with focusable contents, use a Popover primitive (not yet shipped).
+
+## Pieces
+
+| Class               | Selector              | Role                                                                                              |
+| ------------------- | --------------------- | ------------------------------------------------------------------------------------------------- |
+| `ForTooltip`        | `[forTooltip]`        | Wrapper. Owns `open`, delays, side / align positioning. Provides the shared context.              |
+| `ForTooltipTrigger` | `[forTooltipTrigger]` | Apply on a `<button>` or other focusable element. Emits the hover / focus / Escape signals.       |
+| `ForTooltipContent` | `[forTooltipContent]` | The bubble. Portaled to `document.body`, positioned by floating-ui while open.                    |
+| `ForTooltipArrow`   | `[forTooltipArrow]`   | Optional. Render inside the content; floating-ui's `arrow` middleware aligns it with the trigger. |
+
+## Inputs / models
+
+### `ForTooltip`
+
+| API                | Type                                | Description                                                                                                                                                 |
+| ------------------ | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `open`             | `model<boolean>`                    | Two-way bindable visibility.                                                                                                                                |
+| `side`             | `input<FloatingSide \| undefined>`  | Anchor side (`'top'` / `'right'` / `'bottom'` / `'left'`). Falls back to `provideForTooltipDefaults` (`'top'`).                                             |
+| `align`            | `input<FloatingAlign \| undefined>` | Alignment along `side` (`'start'` / `'center'` / `'end'`). Falls back to `provideForTooltipDefaults` (`'center'`).                                          |
+| `sideOffset`       | `input<number \| undefined>`        | Gap (px) between trigger and content along the main axis. Falls back to `provideForTooltipDefaults` (`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 `provideForTooltipDefaults` (`8`).                                      |
+| `openDelay`        | `input<number \| undefined>`        | ms before showing after hover/focus enters. Falls back to `provideForTooltipDefaults` (`700`).                                                              |
+| `closeDelay`       | `input<number \| undefined>`        | ms before hiding after hover/focus leaves. Escape ignores this. Falls back to `provideForTooltipDefaults` (`300`).                                          |
+| `disabled`         | `input<boolean>`                    | When `true`, all interaction is ignored.                                                                                                                    |
+| `showOnOverflow`   | `input<boolean \| undefined>`       | Show only when the trigger's own text is truncated (`scrollWidth > clientWidth`). Falls back to `provideForTooltipDefaults` (`false`).                      |
+| `hoverableContent` | `input<boolean \| undefined>`       | Let the pointer move into the content without dismissing it (drops `pointer-events: none` while open). Falls back to `provideForTooltipDefaults` (`false`). |
+
+### `ForTooltipTrigger`, `ForTooltipContent`, `ForTooltipArrow`
+
+No inputs of their own — they coordinate via the `ForTooltip` context.
+
+## Scoped defaults
+
+`provideForTooltipDefaults` 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 tooltips inside the scope share a skip-delay window; tooltips 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 tooltips that don't set `side` themselves.                                 |
+| `align`             | `'center'`       | Alignment along `side` for tooltips that don't set `align` themselves.                     |
+| `sideOffset`        | `8`              | Main-axis gap (px) for tooltips that don't set `sideOffset` themselves.                    |
+| `collisionPadding`  | `8`              | Collision-middleware padding (px) for tooltips that don't set it themselves.               |
+| `showOnOverflow`    | `false`          | Show only when the trigger's text is truncated, for tooltips that don't set it themselves. |
+| `hoverableContent`  | `false`          | Allow hovering into the content, for tooltips that don't set it themselves.                |
+
+Per-instance inputs always win over the scope defaults.
+
+```ts
+import { provideForTooltipDefaults } from 'forty-cdk/tooltip';
+
+// Bottom-anchored tooltips app-wide
+bootstrapApplication(App, {
+  providers: [provideForTooltipDefaults({ side: 'bottom', sideOffset: 4 })],
+});
+
+// component-level override layers on top, per key
+@Component({
+  providers: [provideForTooltipDefaults({ openDelay: 200 })],
+  ...
+})
+class Toolbar {}
+```
+
+## Stand-alone usage
+
+```ts
+import { Component, signal } from '@angular/core';
+import {
+  ForTooltip,
+  ForTooltipArrow,
+  ForTooltipContent,
+  ForTooltipTrigger,
+} from 'forty-cdk/tooltip';
+
+@Component({
+  selector: 'demo-save',
+  imports: [ForTooltip, ForTooltipTrigger, ForTooltipContent, ForTooltipArrow],
+  template: `
+    <span forTooltip side="top" [openDelay]="400">
+      <button type="button" forTooltipTrigger aria-label="Save">💾</button>
+      <div forTooltipContent class="my-tooltip">
+        Save changes
+        <span forTooltipArrow class="my-tooltip-arrow"></span>
+      </div>
+    </span>
+  `,
+  styles: `
+    .my-tooltip {
+      background: #111;
+      color: white;
+      padding: 4px 8px;
+      border-radius: 4px;
+      font-size: 12px;
+    }
+    .my-tooltip-arrow {
+      width: 8px;
+      height: 8px;
+      background: #111;
+      transform: rotate(45deg);
+      /* How far the arrow pokes out of the bubble. Negative values
+         straddle the edge; 0 keeps the arrow flush against the bubble. */
+      --for-arrow-offset: -4px;
+    }
+  `,
+})
+export class DemoSave {}
+```
+
+## Triggers stamped from outside-declared templates
+
+Angular resolves `ng-template` DI at the template's **declaration** site, not where it is stamped. A `[forTooltipTrigger]` 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="forTooltip"` and pass it through the outlet context. The bare valueless attribute keeps resolving via DI.
+
+```html
+<span forTooltip #root="forTooltip">
+  <ng-container *ngTemplateOutlet="trig; context: { root }" />
+  <div forTooltipContent>Save changes</div>
+</span>
+
+<ng-template #trig let-root="root">
+  <button type="button" [forTooltipTrigger]="root" aria-label="Save">💾</button>
+</ng-template>
+```
+
+## 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             |
+| --------------------- | --------------------- | ------------------ |
+| `[forTooltip]`        | `data-state`          | `open` \| `closed` |
+| `[forTooltip]`        | `data-disabled`       | present \| absent  |
+| `[forTooltip]`        | `data-reduced-motion` | present \| absent  |
+| `[forTooltipTrigger]` | `data-state`          | `open` \| `closed` |
+| `[forTooltipContent]` | `data-state`          | `open` \| `closed` |
+| `[forTooltipContent]` | `data-reduced-motion` | present \| absent  |
+
+### CSS custom properties
+
+See also: [Styling floating content](../../../../../docs/styling-floating-content.md) — animation rules, standalone `scale`/`opacity`, and the arrow recipe.
+
+`[forTooltipContent]` 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 `[forTooltipArrow]` reads the consumer-settable `--for-arrow-offset`:
+
+| Element               | Custom property                  | Type / range        | Direction | Meaning                                                                                                      |
+| --------------------- | -------------------------------- | ------------------- | --------- | ------------------------------------------------------------------------------------------------------------ |
+| `[forTooltipContent]` | `--for-anchor-width`             | px                  | out       | Trigger (reference) width.                                                                                   |
+| `[forTooltipContent]` | `--for-anchor-height`            | px                  | out       | Trigger (reference) height.                                                                                  |
+| `[forTooltipContent]` | `--for-available-width`          | px                  | out       | Space available along the inline axis (floating-ui `size` middleware) — clamp with `max-width`.              |
+| `[forTooltipContent]` | `--for-available-height`         | px                  | out       | Space available along the block axis — clamp with `max-height`.                                              |
+| `[forTooltipContent]` | `--for-content-transform-origin` | `<origin>` keywords | out       | `transform-origin` matching the resolved side / align, so a `scale` enter animation pivots from the trigger. |
+| `[forTooltipArrow]`   | `--for-arrow-offset`             | px (default `0px`)  | in        | Consumer-set. How far the arrow pokes out past the bubble edge — typically a negative `px` (e.g. `-4px`).    |
+
+> `[forTooltipContent]` is portaled to `document.body`, so styles scoped to the `[forTooltip]` wrapper won't reach it. Style the bubble with a global stylesheet or a class on the content directive itself. See [Styling floating content](../../../../../docs/styling-floating-content.md) for the full positioner custom-property list (`--for-anchor-width` / `-height`, `--for-available-width` / `-height`, `--for-content-transform-origin`) and the animation / arrow recipes.
+
+```css
+.my-tooltip {
+  opacity: 0;
+  transform: scale(0.9);
+  transform-origin: var(--for-content-transform-origin);
+  transition:
+    opacity 120ms,
+    transform 120ms;
+}
+.my-tooltip[data-state='open'] {
+  opacity: 1;
+  transform: scale(1);
+}
+```
+
+### Reduced motion
+
+`[forTooltip]` and `[forTooltipContent]` reflect `data-reduced-motion` (present / absent) whenever the OS `prefers-reduced-motion: reduce` media query matches, so you can opt your own transitions out without re-deriving the query in CSS or TypeScript. The attribute flips reactively if the preference changes mid-session.
+
+```css
+.my-tooltip[data-reduced-motion] {
+  transition: none;
+}
+```
+
+The tooltip's open / close delays are hover-intent debouncing rather than motion, so they are deliberately left unchanged under reduced motion — only the visual transitions (which are yours) should opt out.
+
+Tooltip content is template-provided and mounts via the consumer's own markup, so the tooltip cannot know the content would be empty before opening — it would happily open an empty bubble on hover/focus. The supported gate is the existing `disabled` input: drive it from whatever signal feeds the content. This is the recipe for design-system wrappers that take the tooltip text as a string input:
+
+```ts
+import { Component, input } from '@angular/core';
+import { ForTooltip, ForTooltipContent, ForTooltipTrigger } from 'forty-cdk/tooltip';
+
+@Component({
+  selector: 'my-tooltip-button',
+  imports: [ForTooltip, ForTooltipTrigger, ForTooltipContent],
+  template: `
+    <span forTooltip [disabled]="!message()">
+      <button type="button" forTooltipTrigger><ng-content /></button>
+      <div forTooltipContent class="my-tooltip">{{ message() }}</div>
+    </span>
+  `,
+})
+export class MyTooltipButton {
+  readonly message = input('');
+}
+```
+
+While `disabled` is `true`, hover and focus are ignored and an already-open tooltip force-closes — no empty bubble, no stale `aria-describedby`.
+
+## Imperative `show()` / `hide()`
+
+For programmatic control beyond hover and focus — e.g. a wrapper that drives the tooltip from a text-truncation observer — `ForTooltip` exposes `show()` and `hide()` methods. Grab the root with a template reference (`#tip="forTooltip"`) and call them:
+
+```ts
+import { Component } from '@angular/core';
+import { ForTooltip, ForTooltipContent, ForTooltipTrigger } from 'forty-cdk/tooltip';
+
+@Component({
+  selector: 'demo-imperative',
+  imports: [ForTooltip, ForTooltipTrigger, ForTooltipContent],
+  template: `
+    <span forTooltip #tip="forTooltip">
+      <button type="button" forTooltipTrigger>Save</button>
+      <div forTooltipContent class="my-tooltip">Save changes</div>
+    </span>
+
+    <button type="button" (click)="tip.show()">Show</button>
+    <button type="button" (click)="tip.hide()">Hide</button>
+  `,
+})
+export class DemoImperative {}
+```
+
+Both mirror the hover / focus lifecycle rather than bypassing it:
+
+- `show()` schedules the open after the resolved `openDelay` (instant when the delay is `0` or the scope's skip-delay window is active). It is a no-op while `disabled`, and a no-op under `showOnOverflow` when the trigger's own text is not truncated — the same gates a hover / focus open passes.
+- `hide()` schedules the close after the resolved `closeDelay` and disarms the hoverable-content grace bridge.
+
+For an **instant, unconditional** open or close that ignores the delays and both gates, write the `[(open)]` model directly (`open.set(true)` / `open.set(false)`) instead. To suppress empty-message tooltips, keep using the `disabled` input shown above rather than gating the `show()` call yourself.
+
+## Keyboard
+
+- **Tab** to the trigger → opens the tooltip after `openDelay`.
+- **Tab** away → closes after `closeDelay`.
+- **Escape** while open → closes immediately, regardless of `closeDelay`.
+
+## Behavior notes
+
+- **Portal**: the content element is moved to `document.body` on first render. Any styles you scope to the wrapper won't reach it — style the bubble globally or via a class on the content directive itself.
+- **`pointer-events: none`** is applied by default so hovering the bubble doesn't extend its lifetime and clicks pass through to whatever is behind. Setting `hoverableContent` drops it while open (see below). Override with your own CSS if your design needs a different behavior.
+- **Keep content non-interactive**. Tooltips don't trap focus and won't survive a click into them — APG explicitly forbids interactive children.
+- **`hoverableContent`** lets the pointer move into the bubble without dismissing it — useful for descriptive text the user may want to select. It drops the default `pointer-events: none` while open and bridges the trigger / content gap with a pointer-grace "safe triangle" so a slow diagonal traversal doesn't close the tooltip. The content must still stay non-interactive per APG.
+- **`showOnOverflow`** gates the tooltip on the trigger being truncated (`scrollWidth > clientWidth`) — the common pattern for ellipsized labels, where the tooltip adds nothing once the full text already fits. When the trigger's text fits, hover and focus are ignored.
+- **Touch**: APG flags tooltips as problematic on touch devices (no hover, no separate focus, no obvious dismiss). The trigger filters touch pointers out of both the hover-open and focus-open paths, so a tap does **not** open the tooltip — only mouse hover and keyboard focus do. For touch-first UI where the descriptive content must be reachable on tap, consider a Popover.
+- **Arrow offset**: `[forTooltipArrow]` writes `position: absolute`, the floating-ui-resolved `left` / `top`, and `var(--for-arrow-offset, 0px)` on the side opposite the bubble. Set `--for-arrow-offset` on the arrow (or any ancestor) to control how far the arrow pokes out — typically a negative `px` value such as `-4px`. Defaults to `0px`.
+- **Floating-ui dependency** is declared as an optional peer (`@floating-ui/dom`). Install it only if you actually use the Tooltip primitive:
+
+  ```bash
+  npm install @floating-ui/dom
+  ```
+
+## Accessibility notes
+
+- The trigger receives `aria-describedby="<content-id>"` only while the tooltip is open, matching APG.
+- A consumer-set `id` on the trigger element is preserved (and used as the trigger id internally); the generated `for-tooltip-trigger-*` id is only assigned when the element has none. Anchors, `aria-labelledby` references, and `<label for>` associations keep working.
+- The content carries `role="tooltip"` and a stable id wired to the trigger.
+- The optional arrow is `aria-hidden="true"` — it's purely decorative.
+- The tooltip never steals focus.