laif-ds 1.0.0 → 1.0.2-app-data-grid.76

package/dist/agent-docs/components/AppEditor.md

@@ -8,18 +8,18 @@ Rich text editor powered by Lexical with optional Markdown sync. Supports config
 
 ## Props
 
-| Prop             | Type                         | Default                                               | Description                                                                                             |
-| ---------------- | ---------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | ---------------------- |
-| `defaultValue`   | `string`                     | `undefined`                                           | Initial content. Interpreted as Markdown when `onlyMarkdown=true`, plain text otherwise.                |
-| `onValueChange`  | `(markdown: string, meta: { mentions: MentionItem[] }) => void` | `undefined`        | Fires on every edit with the current Markdown and a metadata object. `meta.mentions` is the deduped (by `id`) list of mentions in the text (empty when mentions are disabled). Takes precedence over `onMarkdownEdit`. |
-| `onMarkdownEdit` | `(markdown: string) => void` | `undefined`                                           | **Deprecated** — use `onValueChange`. Still honored as a fallback when `onValueChange` is not provided, but never receives mention metadata. |
-| `plugins`        | `("clear" \| "counter")[]`   | `[]`                                                  | Enable optional plugins: clear buttons, character counter.                                              |
-| `toolbars`       | `("block-format" \| "font-format" \| "history")[]` | `[]`                            | Enable toolbar groups.                                                                                  |
-| `placeholder`    | `string`                     | `"Start typing..."`                                   | Placeholder for empty editor.                                                                           |
-| `onlyMarkdown`   | `boolean`                    | `true`                                                | Treat `defaultValue` as Markdown and sync editor to Markdown. If `false`, `defaultValue` is plain text. |
-| `className`      | `string`                     | `"overflow-hidden rounded-lg border border-d-border"` | Extra classes for the content editable.                                                                 |
-| `mentions`         | `MentionItem[] \| (() => MentionItem[] \| Promise<MentionItem[]>)` | `undefined` | Enables @mention support when provided. Either a ready array (filtered client-side) or a **loader** called once on first menu open (no preload on mount). When omitted, no mention node/plugin/transformer is registered and output is identical to a mention-less editor. |
-| `mentionTrigger`   | `string`                   | `"@"`       | Single character that opens the mention typeahead menu.                                                 |
+| Prop             | Type                                                               | Default                                               | Description                                                                                                                                                                                                                                                                |
+| ---------------- | ------------------------------------------------------------------ | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `defaultValue`   | `string`                                                           | `undefined`                                           | Initial content. Interpreted as Markdown when `onlyMarkdown=true`, plain text otherwise.                                                                                                                                                                                   |
+| `onValueChange`  | `(markdown: string, meta: { mentions: MentionItem[] }) => void`    | `undefined`                                           | Fires on every edit with the current Markdown and a metadata object. `meta.mentions` is the deduped (by `id`) list of mentions in the text (empty when mentions are disabled). Takes precedence over `onMarkdownEdit`.                                                     |
+| `onMarkdownEdit` | `(markdown: string) => void`                                       | `undefined`                                           | **Deprecated** — use `onValueChange`. Still honored as a fallback when `onValueChange` is not provided, but never receives mention metadata.                                                                                                                               |
+| `plugins`        | `("clear" \| "counter")[]`                                         | `[]`                                                  | Enable optional plugins: clear buttons, character counter.                                                                                                                                                                                                                 |
+| `toolbars`       | `("block-format" \| "font-format" \| "history")[]`                 | `[]`                                                  | Enable toolbar groups.                                                                                                                                                                                                                                                     |
+| `placeholder`    | `string`                                                           | `"Start typing..."`                                   | Placeholder for empty editor.                                                                                                                                                                                                                                              |
+| `onlyMarkdown`   | `boolean`                                                          | `true`                                                | Treat `defaultValue` as Markdown and sync editor to Markdown. If `false`, `defaultValue` is plain text.                                                                                                                                                                    |
+| `className`      | `string`                                                           | `"overflow-hidden rounded-lg border border-d-border"` | Extra classes for the content editable.                                                                                                                                                                                                                                    |
+| `mentions`       | `MentionItem[] \| (() => MentionItem[] \| Promise<MentionItem[]>)` | `undefined`                                           | Enables @mention support when provided. Either a ready array (filtered client-side) or a **loader** called once on first menu open (no preload on mount). When omitted, no mention node/plugin/transformer is registered and output is identical to a mention-less editor. |
+| `mentionTrigger` | `string`                                                           | `"@"`                                                 | Single character that opens the mention typeahead menu.                                                                                                                                                                                                                    |
 
 ### MentionItem
 
@@ -161,7 +161,12 @@ import { AppEditor, type MentionItem } from "laif-ds";
 
 const people: MentionItem[] = [
   { id: 1, label: "Alice Rossi", value: "alice@laif.it", sublabel: "Product" },
-  { id: 2, label: "Bob Bianchi", value: "bob@laif.it", sublabel: "Engineering" },
+  {
+    id: 2,
+    label: "Bob Bianchi",
+    value: "bob@laif.it",
+    sublabel: "Engineering",
+  },
 ];
 
 export function EditorWithMentions() {

package/dist/agent-docs/components/AppSelect.md

@@ -49,6 +49,8 @@ The component uses discriminated union types based on the `multiple` prop.
 | `onClear`            | `() => void`                   | `undefined`                                      | Callback fired when clear button is clicked                 |
 | `id`                 | `string`                       | `undefined`                                      | HTML id attribute for the trigger (useful for testing)      |
 | `data-testid`        | `string`                       | `undefined`                                      | Test identifier attribute for E2E testing (e.g. Playwright) |
+| `aria-label`         | `string`                       | `undefined`                                      | Accessible name forwarded to the trigger. Applied ONLY when `label` is absent |
+| `aria-labelledby`    | `string`                       | `undefined`                                      | Id(s) of external element(s) naming the trigger. Applied ONLY when `label` is absent |
 
 ### Single Select Props
 
@@ -498,6 +500,54 @@ export function CustomRenderSelect() {
 
 ---
 
+## Accessibility and layer behaviour
+
+### Accessible name
+
+The trigger is a `role="combobox"`. How it is named depends on whether `label` is set:
+
+- **with `label`**: `aria-labelledby` points at the label plus the current value (`"<labelId> <valueId>"`). A `aria-label` / `aria-labelledby` passed by the consumer is ignored in this branch on purpose — a second name next to a visible label is a WCAG 2.5.3 risk.
+- **without `label`**: the trigger falls back to whatever the consumer passes — `aria-labelledby` first, then `aria-label` — and to NOTHING if neither is passed. It no longer falls back to the value id, which made the accessible name change every time the user picked an option (WCAG 4.1.2).
+
+Story: `SenzaEtichettaNomeAccessibile`.
+
+### Keyboard
+
+On the closed trigger: `Enter`, `Space`, `ArrowDown`, `ArrowUp`, `Home`, `End` open the list. With the list open: `ArrowDown` / `ArrowUp` / `Home` / `End` move the active option (disabled options are skipped), `Enter` commits the active option, `Space` closes, `Escape` dismisses, `Tab` moves to the next element in the document AND dismisses the list. `aria-activedescendant` tracks the active option while open; `aria-controls` points at the `[cmdk-list]` node that carries `role="listbox"`.
+
+Stories: `AccessibilitaTastiera`, `TastieraElencoAperto`, `CongedoDaTastieraEClickFuori`.
+
+### The popover is NOT modal (behaviour change) — measured
+
+The listbox is rendered inside a Radix `Popover` with `modal={false}`.
+
+**Why.** With `modal`, Radix renders `PopoverContentModal`, which calls `hideOthers()` from `aria-hidden`. Measured: with the list open, the trigger ended up inside an `aria-hidden="true"` subtree while focus was still on it (`onOpenAutoFocus` is prevented for the mobile-keyboard reason documented below). So exactly while `aria-expanded="true"`, no screen reader could read the combobox, its state, or its `aria-controls`. A select-only combobox is not modal per APG.
+
+**What else changed.** The modal branch carries four behaviours, and dropping it dropped all four: `hideOthers` (the one we wanted gone), `RemoveScroll`, `disableOutsidePointerEvents: true` and `trapFocus`. The table below is the measured delta — obtained by flipping `modal` in `app-select.tsx` and re-running the two stories in the browser test runner.
+
+| Situation | with `modal` (before) | with `modal={false}` (now) |
+| --- | --- | --- |
+| Trigger inside an `aria-hidden` subtree while the list is open | yes | no |
+| `AppSelect` nested in another `Popover`, ONE click on a target outside both | the select closes, the surrounding Popover stays open (`aria-expanded="true"`), the target's `onClick` does not fire (counter `0`) | both close (`"false"` / `"false"`) and the target's `onClick` fires (counter `1`) |
+| What a real click at the outside target's centre hits (`document.elementFromPoint`) | the `HTML` element — the target's computed `pointer-events` is `none` | the target itself — computed `pointer-events` is `auto` |
+| Page scroll with the list open | body carries `data-scroll-locked="1"`, computed body `overflow: hidden`, a `wheel` event is `defaultPrevented` | no lock attribute, `overflow: visible`, the `wheel` event is not prevented — the page scrolls under the open list |
+| `Tab` from the open trigger | focus reaches the next element, but the list stays OPEN (the modal branch prevents `onFocusOutside`) | focus reaches the next element and the list dismisses |
+
+Two notes on the measurement itself, so nobody re-derives them wrongly:
+
+- assigning `scrollTop` from script is NOT a probe for the scroll lock: it moved the page in both branches (200 → 200). `RemoveScroll` cancels the scroll *event* and hides the scrollbar, it does not disable the API.
+- `trapFocus` is inert in this component: `onOpenAutoFocus` is prevented, so focus never enters the portal and Radix's `FocusScope` has nothing to pull back. The `Tab` difference in the table comes from `onFocusOutside`, not from the focus trap.
+
+Stories: `DentroUnPopoverAnnidato`, `PaginaScorreEFuocoNonIntrappolato`, `DentroUnDialogModale`.
+
+### Residual limits
+
+- **A click outside now also activates what is under the pointer.** The modal branch gave a free "the first outside click only closes the menu" guard; it is gone. In a nested layout — an `AppSelect` inside another `Popover`, the shape used by the DataTable sorting panel — one click outside now dismisses BOTH layers and fires the underlying handler. If a consumer needs the old guard, it has to be added explicitly at that call site (e.g. `onInteractOutside` on the surrounding layer); `AppSelect` will not restore it, because bringing `modal` back would bring `hideOthers` back with it.
+- **The page scrolls under the open list.** The list stays anchored to the trigger (Radix repositions it), but the content behind it moves.
+- Inside a modal `Dialog` the non-modal popover still works: it opens after the dialog, so its dismissable layer sits higher in the stack and receives `pointer-events: auto` (measured by `DentroUnDialogModale`, which picks an option with the pointer).
+
+---
+
 ## Notes
 
 - **React 19 Compatible**: Properly handles JSX labels without ref warnings