@mtdt/observeops-ds-spec 0.1.0

package/components/specs/input.md

@@ -0,0 +1,130 @@
+# Input (`MInput`) — Spec, Findings & Solutions
+
+| | |
+| --- | --- |
+| **Tier** | Atom (form control) |
+| **Maturity** | 🟢 Stable (core input primitive) |
+| **Source** | `@motadata/ui` → `ui/components/Input/Input.vue` (+ `InputNumber`, `InputSearch`, `InputGroup`); wraps Ant `a-input` |
+| **Storybook** | `Atoms/Input` (Examples · Usage · Accessibility · Changelog) |
+| **Registry** | [`../registry/input.json`](../registry/input.json) |
+| **Family** | form controls — almost always wrapped by **`FlotoFormItem`** (label + validation, 1783×, own entry TODO) |
+| **Figma** | TODO |
+
+## Usage (product analytics)
+
+- **`<MInput>` used 293×.** **`<FlotoFormItem>` used 1783×** — the dominant form-field wrapper
+  (label + validation around a control).
+- **`.material-input` 62×** (bottom-border style) · `full-border-text-area` 17× ·
+  `full-bordered-addon-input` 6× · `no-border-input` 3× · `auto-height-input`/`text-lg-input` 2×.
+- Kit siblings: `MInputNumber`, `MInputSearch`, `MInputGroup`.
+
+## Overview
+
+The product's text input. `MInput` is a **type-router**: the `type` prop selects the rendered
+control. v-model binds **`value` + `update`** (note: the event is `update`, not `input`).
+
+| `type` | Renders |
+| --- | --- |
+| `text` (default) | `a-input` |
+| `password` | `a-input` with `type=password` (no show/hide toggle — see F2) |
+| `number` | `MInputNumber` |
+| `search` | `MInputSearch` (enter button, emits `search`) |
+| `textarea` | `a-textarea` |
+| `datetime` | date picker (separate concern) |
+
+## Anatomy
+
+```text
+┌─ [prefix] ─ value ──────────── [suffix] ─┐   ← optional prefix/suffix inside the field
+│ addonBefore │   input   │ addonAfter │       ← optional attached segments
+└──────────────────────────────────────────┘
+```
+
+Slots: **prefix · suffix · addonBefore · addonAfter · enterButton** (search).
+
+## Options
+
+- **Type:** text · password · number (`MInputNumber`, 70× direct) · search · textarea (above).
+- **Adornments:** `prefix`/`suffix` icons; `addonBefore`/`addonAfter` segments.
+- **Clearable:** `allow-clear` (218× incl. pickers) — an **×** to clear when there's a value.
+- **maxlength:** native char cap (7×). *(No built-in char counter — `show-count` is not
+  supported by this Ant 1.4 kit; the product's `show-count` usage is on other components.)*
+- **Style classes (parallel API):** **`.material-input`** (62× — bottom border only,
+  Material underline) · `full-border-text-area` (17×, bordered textarea) ·
+  `full-bordered-addon-input` (6×) · `no-border-input` (3×, borderless e.g. inline edit) ·
+  `auto-height-input` / `text-lg-input` (2× each).
+- **States:** default · disabled · read-only · **error** (`.has-error` → red border `#f04e3e`,
+  applied by `FlotoFormItem` during validation).
+- **Sizes:** Ant `small`/`default`/`large` exist (via `$attrs`) but are **effectively unused** —
+  the product uses one height (`@input-height-base` 32px; search 36px).
+
+## Behaviors
+
+- **v-model = `value` + `update`** — bind `v-model` or `:value` + `@update`. Using `@input`
+  alone won't update the model (F1).
+- **Search** (`type=search`): Enter emits `search`; an enter/search button shows.
+- **Number** (`type=number`): `MInputNumber` with steppers.
+
+## Content & writing
+
+Use a clear `placeholder` as a hint (not a substitute for a label — the label comes from
+`FlotoFormItem`). Don't put the field's name only in the placeholder.
+
+## Accessibility
+
+- Native `<input>` / `<textarea>` — correct roles, keyboard, and (via `FlotoFormItem`) a
+  programmatic label. Provide a label (`FlotoFormItem`) or `aria-label` for a bare input.
+- ⚠️ **No visible focus ring** system-wide ([SF-001](../../findings/SF-001-focus-visible.md))
+  — inputs strip `outline`.
+- `placeholder` contrast: `--input-placeholder-color` is ~50% — verify it meets contrast.
+
+## Findings & Inconsistencies
+
+### F1 — v-model event is `update`, not `input` · Low · Documented
+
+`MInput` uses `model: { event: 'update' }`. `v-model` works, but `@input` handlers won't fire
+the model update — use `@update` (or `v-model`). **Solution:** document loudly (done); align to
+`input`/`update:value` in a future API pass.
+
+### F2 — `type="password"` has no show/hide toggle · Low · Open
+
+`type=password` falls through to `a-input[type=password]` (no visibility toggle). A separate
+`PasswordInput` component exists for show/hide. **Solution:** route `type=password` to
+`a-input-password` (Ant has it) or point users to `PasswordInput`.
+
+### F3 — No visible focus indicator · High · Open *(a11y)* → see [SF-001](../../findings/SF-001-focus-visible.md)
+
+Inputs strip the focus outline (system-wide).
+
+## Do / Don't
+
+### Do
+
+- Wrap inputs in **`FlotoFormItem`** for a label + validation (the standard form pattern).
+- Pick the `type` for the data (number/search/textarea/password); bind with `v-model`.
+- Use `prefix`/`suffix` for context icons; `addonBefore`/`addonAfter` for units/protocols.
+
+### Don't
+
+- Don't rely on `@input` to update the model — it's `update` (F1).
+- Don't use the placeholder as the only label.
+- Don't expect a password show/hide toggle from `MInput type=password` (F2).
+
+## Related
+
+`FlotoFormItem` (field wrapper — label + validation; own entry TODO) · `MInputNumber` ·
+`MInputSearch` · `MInputGroup` · `LooseTags` (tag input) · date picker (`type=datetime`).
+
+## Changelog
+
+- **2026-06-07** — Added (decision-grade Usage from the start). Deep-dive of `Input.vue`
+  (293×): type-router (text/password/number/search/textarea), v-model `value`/`update`,
+  prefix/suffix/addon slots. Verified all types + adornments + the `.material-input` (62×,
+  bottom-border `0/0/1/0`) in Storybook. Findings F1 (`update` event), F2 (no password toggle),
+  F3 (focus → SF-001). Noted `FlotoFormItem` (1783×) as the field wrapper — its own entry next.
+- **2026-06-07** — Deeper re-sweep (owner doubt re: missed variants). Added **Clearable**
+  (`allow-clear`, verified ×) and **Error/validation state** (`.has-error` red border,
+  verified) stories; deepened the Usage page (per-type descriptions + real product examples,
+  adornments, styles/states, sizes). Corrected: **sizes are effectively unused** (one height);
+  **`show-count` char counter is NOT supported** by the Ant 1.4 kit (so not an Input feature);
+  `MInputNumber` used directly 70×.

package/components/specs/link.md

@@ -0,0 +1,131 @@
+# Link (`FlotoLink`) — Spec, Findings & Solutions
+
+| | |
+| --- | --- |
+| **Tier** | Atom (navigation) |
+| **Maturity** | 🟢 Stable |
+| **Source** | `src/components/_base-app-link.vue` (global `FlotoLink`) |
+| **Storybook** | `Atoms/Link` (Examples · Usage · Accessibility · Changelog) |
+| **Registry** | [`../registry/link.json`](../registry/link.json) |
+| **Family** | the Button family's **navigation** relative (the thing a button should *not* be used for) |
+| **Figma** | TODO |
+
+## Usage (product analytics)
+
+- **`<FlotoLink>` used 67× across 48 files.** `:to` (route) ~9× explicit (most pass it via
+  `v-bind`); `as-button` form used for navigation CTAs. Wraps logos, menu items, breadcrumbs,
+  and clickable values.
+
+## Overview
+
+The product's **navigation** control. Two modes (one prop, `asButton`):
+
+- **Default** → renders a **`RouterLink`** (`<a>`): an in-content/inline navigation link.
+- **`as-button`** → renders an **`MButton`** that **pushes the route on click**: a
+  button-styled navigation CTA (takes any Button `variant`).
+
+Everything except `asButton` passes through via `$attrs` (`to`, `target`, button props).
+
+## Anatomy
+
+```text
+text link:   …go to ⟨the inventory list⟩…     ← <a href> (RouterLink), inherits text color
+as-button:   [ Go to settings ]               ← MButton; navigates via $router.push on click
+```
+
+## Options / API
+
+- **`asButton`** (Boolean, default false) — button-styled navigation vs a plain link.
+- **`to`** (via `$attrs`) — the route/target (router location or path).
+- **`target`**, and (when `asButton`) any **MButton** prop (`variant`, `size`, …) — all
+  passed through.
+- Slot: link/button content.
+
+## Link variations (the full surface)
+
+"Link" is broader than `FlotoLink`. The real variations in the product:
+
+| Variation | How | Notes |
+| --- | --- | --- |
+| **Internal text link** | `FlotoLink` (RouterLink) | the default — in-content/menu/breadcrumb navigation |
+| **Navigation CTA** | `FlotoLink as-button` | button-styled internal navigation (F1) |
+| **External / new-tab link** | **plain `<a href target="_blank">`** (147×) | `FlotoLink` is **internal-only** — RouterLink can't resolve external URLs. ⚠️ Set `rel="noopener noreferrer"` ([SF-004](../../findings/SF-004-blank-rel-noopener.md)). |
+| **In-table link style** | `class="k-link"` (25×) | subtle: `--page-text-color`, hover → pagination-active color (not brand-colored) |
+| **Other class styles** | `resource-link` (8×, mostly legacy/commented), `link-label` (5×), `completed-link` (3×), `admin-page-link` (1×) | app-context link treatments |
+
+Anchor appearance is also **context-scoped** (nav/header/dropdown/menu/steps style links
+differently in `header.less`/`left-list.less`/`dropdown.less`/… ) — chrome styling, not
+reusable variants.
+
+## Behaviors
+
+- **Default link** is a real `<a>` (RouterLink) → supports middle-click / open-in-new-tab.
+- **`as-button`** navigates programmatically (`$router.push`) and only pushes if the target
+  differs from the current route.
+
+## Content & writing
+
+Link text should name the destination ("the inventory list", "Settings") — not "click here".
+
+## Accessibility
+
+- **Default mode** is a true anchor — correct link semantics, keyboard + new-tab support. ✅
+- ⚠️ **`as-button` is a `<button>`, not an anchor (F1):** it navigates via JS, so it loses
+  native link affordances (no `href`, no middle-click / open-in-new-tab / right-click menu)
+  and is announced as a button, not a link.
+- **No visible focus ring** system-wide ([SF-001](../../findings/SF-001-focus-visible.md)).
+
+## Findings & Inconsistencies
+
+### F1 — `as-button` navigates but isn't a real link · Medium · Open *(a11y/UX)*
+
+`as-button` renders an `MButton` and calls `$router.push` on click — so a *navigation* is
+exposed as a *button* with no `href`. Users can't open it in a new tab / middle-click, and AT
+announces "button" not "link". **Solution:** for navigation CTAs prefer a real anchor styled
+as a button (RouterLink with a button class), so the href is present; reserve `as-button` for
+cases where a true anchor isn't possible.
+
+### F2 — Plain links have no built-in affordance · Low · Open
+
+A default `FlotoLink` **inherits text color** — there's no global link color/underline, so a
+bare link can look like normal text. Most usages add `text-primary` (navy) for affordance.
+**Solution:** consider a default link style (color + hover underline) so links are
+distinguishable without per-use classes.
+
+### F3 — No external-link component; `target="_blank"` lacks `rel` · Low · Open *(security)* → [SF-004](../../findings/SF-004-blank-rel-noopener.md)
+
+`FlotoLink` is **internal-only** (RouterLink), so external/help/doc links are written as raw
+`<a href target="_blank">` — **147× across the app, none with `rel="noopener noreferrer"`**
+(reverse-tabnabbing; mitigated by modern browsers but still flagged). **Solution:** a shared
+`FlotoExternalLink` (or extend `FlotoLink` for an external `href`) that always emits
+`target="_blank" rel="noopener noreferrer"`, plus a lint rule. Promoted to **SF-004**.
+
+## Do / Don't
+
+### Do
+
+- Use `FlotoLink` for **navigation** (route/URL) — inline links, menus, breadcrumbs, logos.
+- Use `as-button` for a **prominent navigation CTA**; pass a Button `variant`.
+- Give the link text that names the destination; add an affordance (`text-primary`) for inline links.
+
+### Don't
+
+- Don't use a link for an **action** (save/delete/apply) — use a **Button**.
+- Don't rely on `as-button` where users expect to open in a new tab (F1).
+
+## Related
+
+`MButton` (actions) · `MDropdown` (menus) · the Button family (this is its navigation member).
+
+## Changelog
+
+- **2026-06-07** — Added (decision-grade Usage from the start). Deep-dive of
+  `_base-app-link.vue` (67×/48 files): `RouterLink` default + `as-button` MButton route-push;
+  only own prop is `asButton`. Verified text link (`<a href>`) + as-button (navigating MButton)
+  in Storybook (RouterLink + `$router` stubbed in preview). Findings F1 (`as-button` not a real
+  link, a11y), F2 (no default link affordance). Closes the Button family's navigation relative.
+- **2026-06-07** — Thorough link-variation sweep (owner flagged possible missed variants).
+  Found and documented: **external links** (plain `<a target="_blank">`, 147×, FlotoLink is
+  internal-only) + **class-based link styles** (`k-link` 25×, `resource-link`, `link-label`, …);
+  added the **External link** story + variations table. New finding **F3** → promoted to
+  **SF-004** (`target="_blank"` links lack `rel="noopener noreferrer"`).

package/components/specs/loose-tags.md

@@ -0,0 +1,139 @@
+# LooseTags — Spec, Findings & Solutions
+
+| | |
+| --- | --- |
+| **Tier** | Molecule (form input) |
+| **Maturity** | 🟢 Stable (heavily used; a few small inconsistencies) |
+| **Source** | `src/components/loose-tags.vue` (composes `MSelect mode="tags"` / `FlotoDropdownPicker` / `SelectedItemPills`) |
+| **Storybook** | `Molecules/LooseTags` (Examples · Usage · Accessibility · Changelog) |
+| **Registry** | [`../registry/loose-tags.json`](../registry/loose-tags.json) |
+| **Family** | Tag family — the **input** member (see [`tag.md`](./tag.md); classification per [D12](../../decisions/DECISIONS.md)) |
+| **Figma** | TODO |
+
+## Usage (product analytics)
+
+- **`<LooseTags>` used 94× across 80 files** — one of the most-used form inputs.
+- Dominant config is the **default editable mode with a `:counter`** (counter passed ~69×,
+  it scopes which existing tags are suggested).
+- `asDropdown` ~10× · `tagType` ~24× · `userTagOnly` ~4× · `singleSelection` ~2×.
+
+## Overview
+
+A free-form **tag input**: the user types a value and presses Enter to add a removable
+teal pill; previously-used tags are offered as suggestions (fetched from the API). It is the
+home of the teal `key:value` pills — the default mode renders
+`<MSelect mode="tags" class="loose-tags-input">`, and the `.loose-tags-input` context is what
+paints the selected pills teal. v-model is an **array of strings**.
+
+It renders one of **three modes**:
+
+1. **Default (editable)** — `MSelect mode="tags"`; type-to-create + suggestions. *(Shown in
+   Storybook.)*
+2. **`disabled` (read-only)** — `SelectedItemPills` teal pills, truncated with `+N`; no input,
+   no API call. *(Shown in Storybook.)*
+3. **`asDropdown`** — a searchable, multi-select `FlotoDropdownPicker` rendered `as-input`.
+   *(Covered by the DropdownPicker spec.)*
+
+## Anatomy
+
+```text
+┌───────────────────────────────────────────────┐
+│  ⌜web-server ×⌟ ⌜database ×⌟ ⌜prod ×⌟  | type… │  ← teal pills (orange ×) + free-text input
+└───────────────────────────────────────────────┘
+       ▼ suggestions (existing tags, from API)
+```
+
+## Options / API
+
+- **`value`** (Array, v-model) — the tags. `model: { event: 'change' }`, so bind with
+  `v-model` or `:value` + `@change`.
+- **`disabled`** (Boolean) — read-only pills (mode 2).
+- **`asDropdown`** (Boolean) — searchable picker (mode 3).
+- **`singleSelection`** (Boolean) — caps selection to 1 (**only effective in `asDropdown`**
+  via `max-allowed-selection`).
+- **`counter`** (Object `{ key }`) — scopes suggestions; a `watch` refetches when it changes.
+- **`tagType`** (String) / **`userTagOnly`** (Boolean) — further filter the suggestion fetch.
+- **`placeholder`** (String, default `' '`) — **only used in `asDropdown`** (see F1).
+- **`sm`** (Boolean, default true) — **currently dead** (see F3).
+
+Emits **`change`** (the normalized array). Slots: `clearIcon` (set to `times-circle`).
+
+## Behaviors
+
+- **Default mode** normalizes on change: `lowercase` → `trim` → **de-duplicate** → drop empties.
+- **`asDropdown` mode** only `trim`s + drops empties (**preserves case** — see F2).
+- **Suggestions** are fetched once on `created()` (when not `disabled`) and refetched when
+  `counter` changes.
+
+## Content & writing
+
+Short, lowercase tag tokens (default mode lowercases anyway). Placeholder in the editable
+mode is the fixed string **"Add Tags"** (the `placeholder` prop is ignored there — F1).
+
+## Design tokens used
+
+`--main-tags-bg-color` / `--main-tags-text-color` (teal pills, themed: `#cdf1ed`/`#218b81`
+light → `#183a42`/`#2ec4b6` dark) · `--secondary-orange` (the pill remove ×). Pill font is
+**`JetBrains Mono`** (set on `.loose-tags-input`).
+
+## Accessibility
+
+- Built on Ant Select (`mode="tags"`) — combobox semantics; Enter adds, Backspace removes
+  the last pill, Arrow keys navigate suggestions.
+- ⚠️ **No visible keyboard focus indicator** ([SF-001](../../findings/SF-001-focus-visible.md)).
+- The pill remove × is Ant's control (orange); verify it exposes an accessible name.
+- The native clear is hidden (`.ant-select-selection__clear { display: none }`), so removal
+  is per-pill only in the editable mode.
+
+## Findings & Inconsistencies
+
+### F1 — `placeholder` prop ignored in the editable mode · Medium · Open
+
+The default `MSelect` branch hardcodes `placeholder="Add Tags"`; the `placeholder` prop is
+only wired to the `asDropdown` branch. Consumers setting `:placeholder` on a normal LooseTags
+see no effect. **Solution:** bind `:placeholder="placeholder"` on the `MSelect` too (default
+it to "Add Tags").
+
+### F2 — Case handling differs by mode · Low · Open
+
+Default mode **lowercases** every tag; `asDropdown` mode **preserves case**. The same
+component yields differently-cased data depending on a boolean prop. **Solution:** pick one
+normalization (or expose a `lowercase`/`normalize` prop) and apply it in both branches.
+
+### F3 — `sm` prop + `size` computed are dead · Low · Open
+
+`sm` (default true) drives a `size` computed returning `'small'`, but `size` is **never bound**
+to the `MSelect`/picker — so the input is always default size. **Solution:** bind `:size="size"`
+or remove the dead prop/computed.
+
+### F4 — Suggestion fetch has no error handling · Low · Open
+
+`getAllTagsApi(...).then(...)` has **no `.catch`** — a failed/offline request becomes an
+unhandled rejection (visible as a 404 `pageerror` in Storybook). **Solution:** add `.catch`
+to fall back to `tagOptions = []` (and optionally a non-blocking notice).
+
+## Do / Don't
+
+### Do
+
+- Use LooseTags for capturing a **list of free-form or known tags** (v-model an array).
+- Pass a `:counter` so suggestions are scoped to the relevant entity.
+- Use `disabled` for read-only display of an existing tag list.
+
+### Don't
+
+- Don't rely on the `placeholder` prop in the editable mode (F1) or on `sm` for sizing (F3).
+- Don't assume case is preserved — default mode lowercases (F2).
+- Don't use `asDropdown` expecting this spec to cover it — that path is the DropdownPicker.
+
+## Related
+
+`MTag` / `MStatusTag` (the display members), `SelectedItemPills` (its read-only render),
+`FlotoDropdownPicker` (its `asDropdown` render), `MSelect`. See the Tag family table in
+[`tag.md`](./tag.md).
+
+## Changelog
+
+- **2026-06-07** — Added. Full deep-dive: 3 render modes mapped; teal pills + JetBrains Mono
+  verified in light + dark; findings F1–F4; classified as the Tag family's input member (D12);
+  Storybook Examples + Usage/Accessibility/Changelog pages.

package/components/specs/menu.md

@@ -0,0 +1,88 @@
+# Menu — Spec, Findings & Solutions
+
+| | |
+| --- | --- |
+| **Tier** | Molecule (primitive) |
+| **Maturity** | 🟢 Stable |
+| **Source** | `@motadata/ui` `MMenu` / `MMenuItem` / `MMenuDivider` (the primitive) · `components/_base-grid-actions.vue` (`FlotoGridActions`, the context/action menu) · `MDropdown` (1× — rich-text editor table options). |
+| **Storybook** | Molecules/Menu |
+| **Registry** | [`registry/menu.json`](../registry/menu.json) |
+| **Family** | [Menu](../family-map.md) |
+
+## Why this is a family
+
+**Menu** is the shared **primitive** — a vertical list of selectable rows — that several other
+families are *built from*. It is catalogued in its own right (the building block), alongside its one
+direct **usage** that isn't already a family of its own: the **context / action menu**.
+
+## The members
+
+| Member | Source | Usage | What it is |
+| --- | --- | --- | --- |
+| **Menu** (primitive) | `MMenu` / `MMenuItem` / `MMenuDivider` | **13×** | a vertical list of selectable rows (icon + label), with dividers + danger/positive colours |
+| **Context / Action menu** | `_base-grid-actions.vue` (`FlotoGridActions`) · `MDropdown` | grid rows · 1× | a **"⋯" trigger** → an `MMenu` of **actions** (an action surface, not a value picker) |
+
+### Menu (the primitive)
+
+- A panel of `MMenuItem`s — each an **icon + label** row — with **hover** (`--neutral-lighter`),
+  **selected** (`--primary` text on `--code-tag-background-color`), `MMenuDivider` (`--border-color`),
+  and **danger** (`--secondary-red`) / **positive** (`--secondary-green`) item colours.
+- It is the building block beneath **Primary nav** & **Side menu** (Navigation), the **Dropdown picker**
+  (Organisms/DropdownPicker), and the **Context/Action menu** below. Reused — never hand-rolled.
+
+### Context / Action menu
+
+- The `FlotoGridActions` pattern: an `MPopover` (placement `bottomRight`) triggered by an
+  **ellipsis-v "⋯"** icon, opening an `MMenu` of **action** items. Items are **permission-gated**
+  (create/edit/delete keys), support **dividers**, and colour **danger** actions red / **positive**
+  green. The lone `MDropdown` usage (editor table options) is the same shape via the kit component.
+- It is an **action surface** ("do something") — distinct from a value picker and from navigation.
+
+## Which menu? (decision)
+
+1. **A list of items to render inside something** (nav, picker, dropdown)? → **Menu** primitive.
+2. **A "⋯" / button that opens a list of *actions*** on a row or object? → **Context / Action menu**.
+3. **Pick a *value* from options** (single/multi)? → **Dropdown picker** / **Select** (not here).
+4. **Go to a destination**? → **Navigation** (Primary nav / Side menu / Tabs).
+
+## Accessibility
+
+- **Verify:** the trigger has an accessible name (the "⋯" needs an `aria-label`), the open menu uses
+  **`role="menu"` / `role="menuitem"`**, **arrow-key** navigation + **Esc** to close, focus returns to
+  the trigger on close, and **danger** actions are not conveyed by colour alone (icon/label too).
+
+## Design tokens used
+
+`--page-background-color` (menu bg) · `--border-color` (border / divider) · `--neutral-lighter`
+(hover) · `--code-tag-background-color` (selected bg) · `--primary` (selected text) ·
+`--secondary-red` (danger) · `--secondary-green` (positive) · `--page-text-color`.
+
+## Findings & Inconsistencies
+
+| # | Severity | Status | Finding |
+| --- | --- | --- | --- |
+| F1 | Low | Noted | The primitive is reproduced (the live `MMenu` needs Ant menu context); built from real tokens + `MIcon`. |
+| F2 | Low (a11y) | Open | Verify `role=menu`/`menuitem`, arrow-key + Esc, trigger `aria-label`, focus return, non-colour-only danger. |
+| F3 | Info | Noted | `MDropdown` appears only **1×** (editor); the product's standard action menu is `FlotoGridActions` (MPopover + MMenu). |
+
+## Do / Don't
+
+- **Do** reuse the **Menu** primitive (and `FlotoGridActions` for row actions); colour danger actions
+  with `--secondary-red`; gate items by permission.
+- **Don't** confuse a menu of **actions** with a **value picker** (use Dropdown picker / Select) or
+  with **navigation**; don't hand-roll a `<ul>` dropdown; don't rely on colour alone for danger.
+
+## Related components
+
+**Navigation** (Primary nav / Side menu are built on `MMenu`) · **Dropdown picker** & **Select** (value
+selection, built on the same primitive) · **Popover** (the floating container) · **Toolbars** (host the
+"⋯" action menu) · **Table** (grid rows host `FlotoGridActions`).
+
+## Changelog
+
+- **2026-06-16** — Added — the **Menu** family: the **`MMenu` primitive** catalogued in its own right
+  (the building block beneath Primary nav, Side menu, the dropdown picker) **+** the **Context / Action
+  menu** (`FlotoGridActions` — a "⋯" trigger → `MMenu` of actions; the single `MDropdown` usage is the
+  same shape). Surfaced during the Navigation recheck (MMenu was "scoped out" as a primitive; the
+  context menu as an action surface) and promoted to real entries. Reproductions (real tokens + MIcon);
+  verified the primitive + the opened context menu render. Findings F1–F3.

package/components/specs/modal.md

@@ -0,0 +1,176 @@
+# Modal (`MModal`) — Spec, Findings & Solutions
+
+| | |
+| --- | --- |
+| **Tier** | Organism (overlay) |
+| **Maturity** | 🟢 Stable (core dialog) |
+| **Source** | `@motadata/ui` → `ui/components/Modal/Modal.vue` (wraps Ant `a-modal`); confirm variant `src/components/_base-confirm-modal.vue` |
+| **Storybook** | `Organisms/Modal` (Examples · Usage · Accessibility · Changelog) |
+| **Registry** | [`../registry/modal.json`](../registry/modal.json) |
+| **Family** | overlays — `MModal` (dialog) · `FlotoConfirmModal` (confirm) · **`FlotoDrawer`** (side panel, 158× — own entry) |
+| **Figma** | TODO |
+
+## Usage (product analytics)
+
+- **`MModal` 39×** · **`FlotoConfirmModal` 71×** (the confirm dialog) · **`FlotoDrawer` 158×**
+  (slide-in panel — the most-used overlay) · `FlotoDrawerForm` 59×.
+- ~40 app-specific `*Modal` / `*Drawer` composites (AnomalyModal, IncidentDetailsDrawer, …).
+
+## Overview
+
+A centered **dialog** over a dimmed backdrop. `MModal` is the base; **`FlotoConfirmModal`** is
+the confirm/destructive-action variant built on it. Open it via the **`trigger`** slot (which
+gives an `open` fn) or, for the confirm, the **`open`** prop. Mounts in a portal on `body`.
+
+## Anatomy
+
+```text
+        ┌───────────────────────────────┐
+        │  Title                         │   ← title slot (no × close — see F1)
+        │  ─────────────────────────────│
+        │  Body (default slot)           │
+        │  ─────────────────────────────│
+        │           [Cancel]  [ Save ]   │   ← footer slot (cancel + success handlers)
+        └───────────────────────────────┘
+                (dimmed backdrop / mask)
+```
+
+## Options / API
+
+**MModal:** `width` (px/%) · `centered` · `confirmLoading` (spinner on Ok during async) ·
+`preventAutoCloseOnConfirm` · `overlayClassName`. Slots: **`trigger`** (`{ open, close, toggle }`)
+· `title` · default (body) · **`footer`** (`{ cancel, success }`). Emits **`success`** / **`cancel`**.
+
+**FlotoConfirmModal:** `open` (Boolean, toggles) · `variant` (default `error`) · `width` (450) ·
+`successText` ('Yes') · `cancelText` ('No') · `hideIcon` · `iconShadow` · `disableAutoHide`.
+Slots: `icon` · `message` · `header` · `cancel-action` / `confirm-action`. Emits `confirm` / `hide`.
+
+## Header pattern (the product convention)
+
+Because MModal's built-in × is off, **real modals add their own header** in the `title` slot —
+a flex row with a **`text-primary` (navy) title** on the left and a **close ×** (`MIcon name="times"`
+wired to the modal's `hide()`) on the right. ~26 modals do this. Always include this header ×
+**or** a footer Cancel so there's a visible way out (F1).
+
+## Overlay variants (`overlay-class-name`)
+
+Real, used modal style variants (defined in `src/design/modal.less`):
+
+| Class | Effect | Usage |
+| --- | --- | --- |
+| `hide-footer` | removes the footer (read-only / detail modals) | 4× |
+| `scrollable-modal` | fixed-height **flex-column** body (top 50px, rounded header) — the body itself has **no `overflow`**, so wrap the content in a `flex:1; min-height:0; overflow-y:auto` child (else it spills out, F3) | several |
+| `scrollable-modal.restrict-width` | caps width at 1020px | — |
+| `scrollable-modal.smaller-modal` | body height 50vh | 2× |
+| `no-padding-modal` / `no-padding-confrim-modal` | strips content padding | 11× |
+
+> `readable-content-overlay` was previously listed here — it is a **Popover/Tooltip** overlay class
+> (on `MPopover` 9× / `MTooltip` 5×, defined in `popover.less`), **not** a modal variant. Removed (see
+> the correction note below).
+
+The backdrop **blurs** the page behind it (`backdrop-filter: blur(3px)`).
+
+## Dimensions (verified)
+
+| Part | Value | Notes |
+| --- | --- | --- |
+| Content corner radius | **16px** (regular) · **20px** (confirm, `@overlay-border-radius`) | confirm also has a 2px red/variant border |
+| Header corner radius | **20px** (top corners) | note the 4px mismatch vs the 16px content — a product inconsistency, kept faithful |
+| Header padding | `5px 16px` | tight — the title bar is short |
+| Body padding | `24px` (Ant default — not overridden in the kit) | a bare paragraph looks spacious; real forms fill it |
+| Footer padding | `10px 16px` (Ant default; `.widget-form-modal` uses 12px) | |
+
+All measured to match `src/design/modal.less`. The body's 24px is Ant's default — modals look
+right when filled with a real form (the demo uses a `FlotoForm`), but airy with just text.
+
+## Behaviors
+
+- **Open/close:** trigger slot (`open`) or `open` prop; closes via the header × / footer
+  **Cancel** / **Escape** (verified) / `success`. **No built-in × and no backdrop-close**
+  (`closable`/`maskClosable` hardcoded false — F1).
+- **`destroyOnClose: true`** — body content is re-created each open (fresh form state).
+- **Confirm:** Cancel (`default`) on the left, the action on the right (matches the form-field
+  placement convention); `error` variant for destructive.
+
+## Content & writing
+
+Title = a short noun/verb phrase ("Edit monitor", "Delete monitor?"). The confirm message
+states the consequence ("This can't be undone."); the action button names the verb (**Delete**),
+not "Yes/OK".
+
+## Accessibility
+
+- Ant `a-modal` traps focus and restores it on close; **Escape closes** (works even though the
+  × is hidden). Renders with `role="dialog"`.
+- ⚠️ **No visible close affordance besides the footer** (F1) — provide a footer **Cancel** (or a
+  ×) so mouse users aren't stuck relying on Escape.
+- ⚠️ No visible focus ring inside ([SF-001](../../findings/SF-001-focus-visible.md)).
+
+## Findings & Inconsistencies
+
+### F1 — No × close and no backdrop-close · Medium · Open *(UX/a11y)*
+
+`Modal.vue` hardcodes `:closable="false"` and `:maskClosable="false"`, so there's **no
+top-right ×** and clicking the backdrop doesn't close. Escape works and the footer Cancel works,
+but if a modal's footer omits a cancel, **mouse users have no discoverable way to dismiss it**.
+**Solution:** make `closable` a prop (default a visible ×), or require a footer Cancel; keep
+`maskClosable` opt-in for forms (to avoid accidental data loss).
+
+### F2 — No visible focus ring · High · Open *(a11y)* → [SF-001](../../findings/SF-001-focus-visible.md)
+
+System-wide; matters inside dialogs where focus is trapped.
+
+### F3 — `scrollable-modal` body has no overflow (content can spill) · Low · Open
+
+`scrollable-modal` sets the body to a fixed height + `display:flex; flex-direction:column`, but
+**doesn't set `overflow`** on the body itself — so long content spilling directly into the body
+**overflows the modal** instead of scrolling. The body's child must be the scroll container
+(`flex:1; min-height:0; overflow-y:auto`). **Solution:** add `overflow:auto` (or a flex-1
+scroll child) in the variant, or document the required structure (done). Caught in the catalog
+(the demo overflowed until the content was wrapped in a scroll container).
+
+## Do / Don't
+
+### Do
+
+- Use `MModal` for a focused task/dialog; **`FlotoConfirmModal`** for yes/no + destructive confirms.
+- Always include a footer **Cancel** (so there's a visible way out — F1).
+- Use a **`FlotoDrawer`** instead when the content is long, or contextual to a record (details).
+
+### Don't
+
+- Don't rely on a × or backdrop-click to close — they're disabled (F1).
+- Don't use a modal for content that's better inline or in a drawer.
+- Don't write "Yes/OK" action labels — name the verb (Delete, Save).
+
+## Related
+
+`FlotoConfirmModal` (confirm) · **`FlotoDrawer`** / `FlotoDrawerForm` (side panel — own entry) ·
+`MButton` (footer actions) · `FlotoFormItem` (fields inside).
+
+## Changelog
+
+- **2026-06-07** — Added (decision-grade Usage). Deep-dive of `Modal.vue` (39×) + the confirm
+  variant `_base-confirm-modal.vue` (71×): trigger-slot / `open`-prop opening; title/body/footer
+  slots; `width`/`centered`/`confirmLoading`. Registered `FlotoConfirmModal` in the preview;
+  verified Basic (trigger → dialog, 2 footer btns, backdrop) and Confirm (error, icon + Delete)
+  open correctly; Escape closes, no × (F1). Drawer (158×) flagged as the related own entry.
+- **2026-06-08** — Fidelity pass (owner flagged it didn't match the product). Found the real
+  modals add their **own header** (text-primary title + close ×, ~26 modals) and use **overlay
+  variants** (`hide-footer` 4×, `scrollable-modal`+`restrict-width`/`smaller-modal`,
+  `no-padding-*` 11×) — and the backdrop **blurs**. Reworked the
+  stories to the product header pattern + added **HideFooter** and **Scrollable** variant
+  stories; documented the header pattern + variants. Confirmed real usage (metric-explorer
+  Anomaly/Forecast/Outlier/Compare modals, error/detail modals; delete confirms in CRUD lists).
+- **2026-06-11** — Triple-check audit of the **whole overlay/dialog family** (owner: "make sure no
+  type of modal is missed"). Confirmed the family is complete at the **component level** — MModal
+  (39×), FlotoConfirmModal (71×), FlotoDrawer (99×), FlotoDrawerForm (59×); `MDrawer` is internal
+  (wrapped by FlotoDrawer, 0 direct app use); `FlotoFormModal` doesn't exist; no programmatic
+  `Modal.confirm`/`$confirm` service; no lightbox/viewer/fullscreen mechanisms; all 42 custom
+  `*-modal/-drawer` files build on those 4 bases. Added the two **MModal variants that existed but
+  weren't showcased**: **`no-padding`** (body → 8px, full-bleed lists/grids; verified) and **`large
+  (restrict-width)`** (content forced to **1020px**; verified). **Correction:** `readable-content-overlay`
+  is a **popover/tooltip** class (on MPopover 9× / MTooltip 5×, defined in `popover.less`), **not** a
+  modal variant — removed it from the modal variant list above. Open: the **Popover / Tooltip family**
+  (MPopover 35×, MTooltip 94×, MPopper 2×) is a separate overlay family **not yet catalogued** as its
+  own component.