@mtdt/observeops-ds-spec 0.1.0

package/components/specs/drawer.md

@@ -0,0 +1,162 @@
+# Drawer (`FlotoDrawer`) — Spec, Findings & Solutions
+
+| | |
+| --- | --- |
+| **Tier** | Organism (overlay) |
+| **Maturity** | 🟢 Stable — the product's most-used overlay |
+| **Source** | `src/components/_base-drawer.vue` (global `FlotoDrawer`, wraps kit `MDrawer` → Ant `a-drawer`); form variant `src/components/crud/_base-drawer-form.vue` |
+| **Storybook** | `Organisms/Drawer` (Examples · Usage · Accessibility · Changelog) |
+| **Registry** | [`../registry/drawer.json`](../registry/drawer.json) |
+| **Family** | overlays — sibling of [Modal](./modal.md); `FlotoDrawerForm` is the form variant |
+| **Figma** | TODO |
+
+## Usage (product analytics)
+
+- **`FlotoDrawer` 99×** + **`FlotoDrawerForm` 59×** = **158×** — the **most-used overlay**
+  (more than `MModal` 39 + `FlotoConfirmModal` 71 combined).
+- `open` 27× · `width` 14× (default 40%).
+- Dozens of app-specific `*Drawer` composites (IncidentDetails, SyncApproval, RunbookApproval,
+  FirmwareUpgradeApproval, CredentialSelection, CatalogSelection, AttachRules, ViewDetail, …).
+
+## Overview
+
+A **slide-in side panel** (from the right) over a backdrop. Use it for **detail views, edit
+forms, and record-contextual content** that's too long or too rich for a centered modal. Open
+via the **`open`** prop (toggles) or a **`trigger`** slot. `FlotoDrawerForm` = `FlotoForm`
+(vertical) + `FlotoDrawer` for the common Add/Edit-in-a-drawer flow.
+
+## Anatomy
+
+```text
+                              ┌──────────────────────────┐
+                              │  Title              [×]   │  ← title slot (text-primary) + built-in ×
+                              │  ───────────────────────  │
+   (dimmed backdrop)          │  Body (scrollable —       │  ← default slot, scrolls via FlotoScrollView
+                              │  FlotoScrollView)         │
+                              │  ───────────────────────  │
+                              │            [Cancel][Save] │  ← actions slot (fixed footer; gets `hide`)
+                              └──────────────────────────┘
+```
+
+## Widths / sizes (the full range)
+
+`width` (default **40%**) spans a real range in the product:
+
+| Width | Use |
+| --- | --- |
+| `360`px / 40% | simple detail / form panels (default) |
+| 50–70% | richer content / editors |
+| **85–96%** (`width="90%"` ~24×, plus `96%` / `85%` / `100%`) | **large / full-screen drawers** for complex **multi-pane** flows — a left nav + main scrollable form + a right reference panel (e.g. **APM Application Registration** at `width="96%"`). Use a wide drawer (not a modal) for rich config/registration wizards. See the **Large / full-screen** story. |
+
+## Options / API
+
+**FlotoDrawer:** `open` (Boolean, toggles) · `width` (px/%, default **40%**) ·
+`scrolledContent` (default **true** → wraps the body in `FlotoScrollView`) · `usePadding` ·
+plus Ant `a-drawer` attrs via `$attrs` (e.g. `placement`). Slots: **`trigger`**
+(`{ open, close, toggle }`) · **`title`** / `title-row` · default (body) · **`actions`**
+(`{ hide }`, a fixed footer). Emits **`show`** / **`hide`**.
+
+**FlotoDrawerForm:** `open` · `width` (40%) · `scrolledContent`. Slots: `trigger` · `header` /
+`header-row` · default (body, gets `submit`) · `actions` (`{ hide, submit }`). It wraps a
+vertical `FlotoForm` and **suppresses `MForm`'s default Submit** (`<template #submit><span/>`),
+so only the footer submits.
+
+## Behaviors
+
+- **Open/close:** `open` prop / `trigger` slot; the drawer has a **built-in close ×** (Ant
+  `a-drawer`, unlike `MModal`), plus the actions footer. **`maskClosable: false`** — clicking
+  the backdrop doesn't close (avoids losing form input).
+- **Scroll:** the body scrolls inside the panel (`scrolledContent` → `FlotoScrollView`); the
+  title and actions footer stay pinned. With an `actions` slot, the body reserves ~65px at the
+  bottom for the footer.
+- **`@hide`** fires ~500ms after close (after the slide-out animation).
+
+## Accessibility
+
+- Ant `a-drawer` — `role="dialog"`, focus trap, **built-in close ×** (a real, discoverable
+  dismiss — better than `MModal`, which has none). Escape closes.
+- ⚠️ No visible focus ring inside ([SF-001](../../findings/SF-001-focus-visible.md)).
+- Give the drawer a clear **title** describing the record/task.
+
+## Findings & Inconsistencies
+
+### F1 — `@hide` is delayed ~500ms · Low · Documented
+
+`handlevisibleChange` emits `hide` after a 500ms `setTimeout` (to let the slide-out animation
+finish). Parents toggling `open` off should account for the delay (the panel lingers briefly).
+Not a bug — document so consumers don't double-handle.
+
+### F2 — No visible focus ring · High · Open *(a11y)* → [SF-001](../../findings/SF-001-focus-visible.md)
+
+System-wide; matters in a focus-trapped panel.
+
+### F3 — `.actions` footer has no inter-button gap · Low · Open
+
+The `.actions` bar is `display:flex; justify-content:flex-end` but sets **no gap**, so adjacent
+footer buttons **touch** (measured 0px) unless you add **`mr-2`** to the non-last button (the
+product convention, e.g. `instance-grid`). **Solution:** add `gap: 8px` (or `& > * + * { margin-left }`)
+to `.actions` in `drawer.less`; until then, put `class="mr-2"` on every button except the last.
+
+## Footer actions — button layout (2 / 3 / 4)
+
+The footer/`actions` bar is **right-aligned** (`justify-content: flex-end`), buttons spaced
+with **`mr-2`** (8px) on the non-last. Layout by count:
+
+| Count | Layout |
+| --- | --- |
+| **2** | `[ … Cancel  Save ]` — Cancel `mr-2`, primary far-right |
+| **3** | all right-aligned (`Reset · Cancel · Save`, `mr-2` gaps) — **or** split: a **destructive** action (Delete) on the **left**, the confirm group (Cancel + Save) on the right (`justify-between`) |
+| **4** | **split** — a tertiary action or a "* mandatory" note on the **left**, the confirm group on the right; beyond this, move rarely-used actions into a menu |
+
+Rules: **primary far-right**, **Cancel** immediately to its left; **destructive / tertiary /
+notes go left** (separated from the confirm group). See the **Footer actions** story.
+
+## Do / Don't
+
+### Do
+
+- Use a Drawer for **detail views, edit forms, and long/record-contextual content**.
+- Use **`FlotoDrawerForm`** for Add/Edit forms (vertical form + validation + footer submit).
+- Put primary/secondary actions in the **`actions`** footer (Cancel left, Save right).
+
+### Don't
+
+- Don't use a Drawer for a **short confirmation** — use **`FlotoConfirmModal`**.
+- Don't rely on backdrop-click to close (disabled) — use the × or a footer Cancel.
+- Don't add an `MForm` inside without suppressing its default Submit (two submit buttons).
+
+## Related
+
+[Modal](./modal.md) (`MModal` / `FlotoConfirmModal`) · `FlotoDrawerForm` (form variant) ·
+`FlotoForm` / `FlotoFormItem` (fields inside) · `MButton` (footer actions).
+
+## Changelog
+
+- **2026-06-08** — Added (decision-grade Usage) — the **Drawer**, the product's most-used
+  overlay (158×). Deep-dive of `_base-drawer.vue` (99×) + `FlotoDrawerForm` (59×): `open`-prop /
+  `trigger` opening; `title` / body (scrollable via `FlotoScrollView`) / `actions` (fixed
+  footer) slots; `width` default 40%; built-in × with `maskClosable:false`. Registered
+  `FlotoDrawer` and `FlotoScrollView` in the preview; verified Basic (slide-in, title, actions,
+  backdrop) and a Form drawer (2 fields, Cancel/Save). Findings F1 (delayed `@hide`), F2
+  (focus → SF-001).
+- **2026-06-11** — Reworked the **Large / full-screen** story for real fidelity. Read the actual
+  `apm-application-registration-drawer.vue` end-to-end: it's `width="96%"` `:scrolled-content="false"`
+  with a **2 : 6 : 4 `MRow`** body — a tinted deployment **nav** (`--drawer-sidebar-background`,
+  selected on `--code-tag-background-color`), a **sectioned form** column (`--dashboard-background`,
+  `section-heading`+`helper-text` split by **dividers**, ending in an *Apply Configuration* button),
+  and a **right info** column (`vertical-line` headings + supported-tech **data tables** + a bordered
+  **Verification** box, each column scrolling independently). The prior story was a loose 3-div
+  approximation; replaced it with a faithful reproduction. Verified headless: drawer = 1382px (96%
+  of 1440), columns render 230 / 691 / 461px (17 / 50 / 33%) side-by-side, no console errors. The
+  left-nav uses the **real brand icons** (`vm` / `docker` / `kubernetes`, prefix `fal`) — already
+  in `src/assets/icons/icons.js` and registered via the preview's `@assets/icons` import (verified
+  each resolves to a real SVG path).
+- **2026-06-11** — Replaced the story's inline one-off styles with **shared DS primitive classes**
+  (`.ds-section-heading` / `.ds-helper-text` / `.ds-divider` / `.ds-accent-bar` / `.ds-panel` /
+  `.ds-panel-heading` / `.ds-nav-item` / `.ds-spec-table`) — new file
+  [`storybook/ds-primitives.less`](../../storybook/ds-primitives.less), loaded in the preview, mapped
+  1:1 from the product's scoped classes. See [`ds-primitives.md`](../ds-primitives.md). Verified
+  headless that each class resolves to the **same** token-derived computed value as the prior inline
+  style (14px/600, `--primary` accent, `--border-color` divider, `--help-card-bg-color` panel, etc.)
+  — zero visual change, now real reuse. Interactive pieces remain the real components (FlotoDrawer,
+  MRow/MCol, MRadioGroup, FlotoFormItem, MButton, MIcon).

package/components/specs/dropdown-picker.md

@@ -0,0 +1,161 @@
+# DropdownPicker (`FlotoDropdownPicker`) — Spec, Findings & Solutions
+
+| | |
+| --- | --- |
+| **Tier** | Organism |
+| **Maturity** | 🟡 Stable-but-flawed (the product's core select — heavily used; significant a11y gaps) |
+| **Source** | `src/components/_base-dropdown-picker.vue` (global `FlotoDropdownPicker`); triggers in `src/components/dropdown-trigger/` |
+| **Storybook** | `Organisms/DropdownPicker` (Examples · Usage · Accessibility · Changelog) |
+| **Registry** | [`../registry/dropdown-picker.json`](../registry/dropdown-picker.json) |
+| **Family** | Tag family's host — renders `SelectedItemPills` (the teal `+N` pills) in read-only/multi modes |
+| **Figma** | TODO |
+
+## Usage (product analytics)
+
+- **`<FlotoDropdownPicker>` used 510× across 241 files** — one of the most-used components
+  in the product (the de-facto select).
+- **`allow-clear` 218×** · **`:searchable="false"` 119×** · **`multiple` ~66×** ·
+  `text-only` 15× · `use-popover` 26× · `:as-input="false"` 7×.
+
+## Overview
+
+The product's **custom select**: a popover-anchored, **virtualized** option menu with a
+built-in search box, single or multi-select, keyboard navigation, and an optional inline
+"add new option" affordance. It does **not** use a native `<select>` or Ant `a-select` — it
+is composed from a popover (`MPopper` by default, `MPopover` when `use-popover`), an `MInput`
+trigger, an `MMenu` + `RecycleScroller` list, and `MCheckbox` rows.
+
+**Options** are objects: `{ key, text }` (label is resolved as `text || name || label`;
+value/identity as `key || id || value`). **v-model** is the selected `key` (single) or an
+**array of keys** (`multiple`); `model: { event: 'change' }`.
+
+## Anatomy
+
+```text
+Trigger (asInput):  ┌─────────────────────────────┐
+                    │ Web Server               ⌄ │   ← MInput (readonly) + chevron / clear ×
+                    └─────────────────────────────┘
+Open overlay:       ┌─────────────────────────────┐
+                    │ 🔍 Search…              [+] │   ← search box (+ optional add button)
+                    │ ──────────────────────────  │
+                    │ ☑ Web Server                │   ← virtualized rows (RecycleScroller)
+                    │ ☐ Database                  │     (checkboxes when multiple)
+                    │ …                           │
+                    │ ──────────────────────────  │
+                    │                  [× Clear]  │   ← multi-select footer
+                    └─────────────────────────────┘
+```
+
+## Options / API (selected — full list in the registry)
+
+**Selection & data:** `value` (v-model) · `options` (via `$attrs`) · `externalOptions` ·
+`disabledOptions` · `multiple` · `allowSelectAll` · `maxValues` (real cap) ·
+`maxAllowedSelection` (**dead — F2**).
+
+**Trigger & display:** `asInput` (default **true**) · `textOnly` · `placeholder`
+(default "Select") · `allowClear` · `wrap` (default **true**).
+
+**Menu behavior:** `searchable` (default **true**) · `itemSize` (32) · `itemsToShow` (10) ·
+`hideAllDropdownOptions` · `useAfterMenuDescription` (two-pane) · `showHelp` ·
+`canUserAddOptions` + `addLabel` (inline add) · `defaultOpen` · `avoidKeyboardNavigation`.
+
+**Popover:** `usePopover` (MPopover vs MPopper) · `placement` · `overlayClassName`
+(default "picker-overlay") · `overlayStyle` · `minWidth` · `fixedPosition`.
+
+**Emits:** `change` (model) · `show` · `hide` · `search` · `add` · `active-item-index-change`.
+
+**Slots:** default (custom menu) · `menu-item` · `before-menu-text` · `after-menu-text` ·
+`after-menu` · `helpbox` · `hovered-menu-description` · `trigger` (full trigger override).
+
+## Behaviors
+
+- **Search** filters on `text`/`name`/`label` via a **web worker** (`arrayWorker.search`),
+  debounced through a watcher; emits `search`.
+- **Virtualization:** the list renders through `RecycleScroller` (`itemSize` px rows) — long
+  option sets stay performant.
+- **Keyboard (when open):** ↑/↓ move the active row, **Enter** selects, **Escape** closes
+  (a `window` keydown listener bound on open). `avoidKeyboardNavigation` disables this.
+- **Multi-select:** checkboxes per row, optional **Select All** header, **Clear** footer; the
+  trigger shows `First item (+N)`. Read-only/`disabled` multi renders teal `SelectedItemPills`.
+- **Inline add:** with `canUserAddOptions`, a `+` reveals an input; confirming emits `add`.
+- **No data:** shows a themed illustration (light/dark SVG).
+
+## Design tokens used
+
+`--dropdown-hover-background` / `--left-menu-text-color-hover` (active/hover row) · the menu
+inherits dropdown surface tokens (dark menu bg verified `#1d2a3e`) · trigger uses input
+tokens. Pills (multi read-only) use the teal `--main-tags-*` (see [`tag.md`](./tag.md)).
+
+## Accessibility
+
+- **Keyboard (open):** ↑/↓/Enter/Escape work once the menu is open.
+- ⚠️ See findings **F1** — this is the product's biggest a11y gap (no combobox semantics,
+  not keyboard-openable, no focus ring).
+
+## Findings & Inconsistencies
+
+### F1 — Not an accessible combobox · High · Open *(a11y)* → promoted to [SF-003](../../findings/SF-003-combobox-a11y.md)
+
+It re-implements a select with `div`/`span` + a **readonly `MInput`** trigger and an `MMenu`,
+but exposes **no combobox semantics**: no `role="combobox"`/`listbox"`/`option`, no
+`aria-expanded`, no `aria-activedescendant`, no labelled relationship. The trigger opens
+**only on click** (no Enter/Space handler), so **keyboard users may be unable to open it**;
+and there's no visible focus ring ([SF-001](../../findings/SF-001-focus-visible.md)). For a
+control used **510×**, this is the highest-impact a11y issue in the system — **promoted to the
+system register as [SF-003](../../findings/SF-003-combobox-a11y.md)** (full evidence + the
+combobox-ARIA + keyboard-open + focus solution there).
+
+### F2 — `maxAllowedSelection` prop is dead · Medium · Open
+
+`maxAllowedSelection` is declared but **never referenced** in the logic; the actual cap is
+`maxValues` (sliced in `handleChange`). Consumers pass `:max-allowed-selection` (e.g.
+`LooseTags` `asDropdown` uses it for `singleSelection`) expecting a limit that **never
+applies**. **Solution:** implement `maxAllowedSelection` (or alias it to `maxValues`) and
+document the canonical prop.
+
+### F3 — Three boolean props default to `true` · Low · Open
+
+`searchable`, `asInput`, and `wrap` all default to **true** (each `eslint-disable`'d against
+the project's `vue/no-boolean-default`). Consumers must remember to pass `:searchable="false"`
+etc. **Solution:** keep but document loudly; revisit if a future API cleanup is done.
+
+### F4 — Loose option schema · Low · Open
+
+Labels resolve as `text || name || label` and identity as `key || id || value` in different
+spots — three accepted shapes for the same concept. **Solution:** document a canonical
+`{ key, text }` contract and normalize inputs.
+
+## Storybook fidelity caveats
+
+Two behaviors depend on the product runtime and **don't fully work in Storybook** (not
+product bugs): **search filtering** needs the `arrayWorker` web worker (absent in SB, so the
+list doesn't filter), and the **no-data illustration** needs an SVG-as-component loader
+(absent in SB). Stories therefore use non-empty option sets; the search box renders but won't
+filter. The preview registers `v-tooltip` (→ `MPopper`), `RecycleScroller`, and the picker
+itself to render its real default mode.
+
+## Do / Don't
+
+### Do
+
+- Use it as the standard select; pass `options` as `{ key, text }`, v-model the `key`(s).
+- Use `multiple` + `allow-select-all` for multi-select; `:searchable="false"` for short lists.
+- Use the `trigger` slot when you need a custom trigger (e.g. a button or pills).
+
+### Don't
+
+- Don't rely on `maxAllowedSelection` to cap selection (F2 — use `maxValues`).
+- Don't assume keyboard/AT users can operate it today (F1).
+- Don't forget `searchable`/`asInput`/`wrap` default to **true** (F3).
+
+## Related
+
+`SingleTrigger` / `MultipleTrigger` / `SelectedItemPills` (its triggers) · `LooseTags`
+(uses it via `asDropdown`) · `MSelect` · `MPopover` / `MPopper` · `MMenu` · `MCheckbox`.
+
+## Changelog
+
+- **2026-06-07** — Added. Full deep-dive of `_base-dropdown-picker.vue` + the
+  `dropdown-trigger/` family (510×/241 files). Verified live (trigger, open menu, virtualized
+  list, multi-select + Select All + Clear, dark theme) by registering `v-tooltip`/`MPopper`/
+  `RecycleScroller` in the preview. Findings F1 (a11y, High) – F4; Storybook caveats noted.

package/components/specs/filters.md

@@ -0,0 +1,118 @@
+# Filters — Spec, Findings & Solutions
+
+| | |
+| --- | --- |
+| **Tier** | Molecule |
+| **Maturity** | 🟢 Stable |
+| **Source** | `filters/filters-container.vue` (`FiltersContainer`) + `FilterGroup` + `FilterCondition` + `FilterTrigger` · `filter-bar/_base-filter-bar.vue` (`FlotoFilterBar`) · `filter-bar/filter-quick-menu.vue` · the filter-row pattern. |
+| **Storybook** | Molecules/Filters |
+| **Registry** | [`registry/filters.json`](../registry/filters.json) |
+| **Family** | [Filters](../family-map.md) |
+
+## Why this is a family
+
+The product's filtering UIs were scattered across screens (Grid Toolbar, Monitoring config). They're
+really **four filter archetypes** — catalogued here by *what they are*, regardless of where they sit.
+The **Toolbars** (organisms) *compose* these molecules.
+
+## The five archetypes
+
+| Archetype | Source | Usage | What it is |
+| --- | --- | --- | --- |
+| **Expression builder** | `FiltersContainer` | **32×** | a nested **AND/OR** query builder |
+| **Filter bar** | `FlotoFilterBar` | ~50× | an inline **chip** bar + Match All/Any |
+| **Quick filters** | `filter-quick-menu` | — | a **preset** one-click menu |
+| **Filter row** | pattern | — | a few **multi-selects** + Reset/Apply |
+| **Vertical filter** | `vertical-filter/filters.vue` · NCM | APM/RUM/NCM | the **faceted left-panel** (checkbox + count groups) |
+
+### Vertical filter (the faceted left-panel sidebar)
+
+- The left-hand **faceted filter** panel — a **search** atop **collapsible groups** (`MCollapse`), each
+  row a **checkbox + optional status/type icon + label + count** (right-aligned); checking rows filters
+  the grid. The shared component is **`components/filters/vertical-filter/filters.vue`** (used by **APM
+  Explorer**, **APM Error Tracker**, **RUM Sessions**); **NCM**'s `explorer-grid-virtical-filter.vue` is
+  a richer variant adding **status icons** (backup) and **device-type icons** (switch/router).
+- It **looks like a Navigation side menu but it filters, it doesn't navigate** — so it lives here, not in
+  Navigation (cross-referenced from **Navigation → Side menu**). Surfaced by the 2026-06-16 left-panel
+  sweep.
+
+### Expression builder (the 32× one)
+
+- **Presentation:** it is an **`MPopover`** (placement `bottomLeft`, `has-arrow`) opened from a
+  **`FilterTrigger`** input (a filter-icon box that renders the applied query, or a "Search"
+  placeholder) — **not** an inline panel. The popover has a **close ×**, **Pre Filters / Post Filters**
+  tabs (`MTab`), the builder, and a **Reset / Clear / Apply** footer. **Apply** emits the query (the
+  trigger then shows it) and closes; **Clear** empties; **Reset** reverts to the applied state.
+- **"Group(s) matching All/Any"** wraps one or more **groups** (Pre allows up to 3 groups, Post 1).
+- Each group: **"Include/Exclude → Group matching All/Any → Criteria"** + a list of **conditions**.
+- Each condition: **counter · operator · value** (type-aware — `FilterCondition` picks the operator set
+  and value control from the field type; **Between** → From/To). **Add Condition** (max 3) /
+  **Add New Group** extend it; **×** removes.
+
+### Filter bar (~50×) — *moved here from Grid Toolbar*
+
+- An inline **chip** bar: `default-chips` (no ×) + completed chips (`Type = … (+N) ×`) + a stub.
+- **+ Filter** adds · **×** removes · **Match All/Any** toggle + **Clear All** (once a filter applies).
+- Chips scroll horizontally; the segment picker floats `position:fixed` so the row never clips it.
+
+### Quick filters — *moved here from Grid Toolbar*
+
+- A **thumbs-up** button → a panel of **preset** filters (`{ key, label, condition }`); picking one
+  applies that condition.
+
+### Filter row — *re-homed from the retired Monitoring Config (Collection Filters)*
+
+- A small set of multi-selects (**Groups · Severity · Tags**) + **Reset / Apply** + close **×**.
+
+## Which filter? (decision)
+
+1. **Complex AND/OR across groups?** → **Expression builder**.
+2. **Compact chip bar over a grid?** → **Filter bar**.
+3. **One-click presets?** → **Quick filters**.
+4. **A few simple facets?** → **Filter row**.
+5. **Plain text search?** → the **Input** `search` type (181×), **not** a filter.
+
+## Accessibility
+
+- Inherits from the composed controls (`FlotoDropdownPicker`, chips, `MButton`). **Verify**
+  focus-visible ring (**SF-001**) on the chips/selects, and an `aria-label` on icon-only triggers
+  (thumbs-up, ×).
+
+## Design tokens used
+
+`--code-tag-background-color` (chips) · `--border-color` · `--page-background-color` ·
+`--page-text-color` · `--neutral-light` · `--neutral-button-text` · `--primary` · `--dropdown-background`.
+
+## Findings & Inconsistencies
+
+| # | Severity | Status | Finding |
+| --- | --- | --- | --- |
+| F1 | Low | Noted | Store-bound; `FilterCondition` is 500+ lines — catalogued as reproductions (the Filter bar reproduction is fully interactive). |
+| N1 | Info | — | **Taxonomy:** this family was created (2026-06-16) to gather filters by archetype, moving Filter bar + Quick filters out of "Grid Toolbar" and re-homing "Collection Filters" from the retired "Monitoring Config." |
+
+## Do / Don't
+
+- **Do** use the Expression builder for real query logic; the Filter bar for a compact chip filter;
+  Quick filters for presets; a Filter row for a few facets.
+- **Don't** hand-roll a condition builder; don't put plain search here (→ Input); don't duplicate a
+  filter across screens — compose the one molecule in a Toolbar.
+
+## Related components
+
+`FlotoDropdownPicker` (the selects inside) · **Input** (`search` type) · `Tag` (the chips) · **Table**
+(filters sit above grids) · **Toolbars** (compose these).
+
+## Changelog
+
+- **2026-06-16** — Expression builder — corrected the **presentation** to match the product: it now
+  lives inside an **`MPopover`** opened from a **`FilterTrigger`** input (it was an inline panel before),
+  with **Pre / Post Filters** tabs, a close ×, and a **Reset / Clear / Apply** footer. Made it **fully
+  functional** — open/close, switch tabs, add/remove conditions (max 3) and groups (3 pre / 1 post),
+  Include/Exclude + All/Any selects, **Between** → From/To, and **Apply** renders the query back into the
+  trigger. Verified interaction (add/edit/apply/clear) + light + dark.
+- **2026-06-16** — Added — the **Filters** family, by component archetype. Catalogued the **missing**
+  **Expression builder** (`FiltersContainer`, **32×** — a nested AND/OR query builder), **moved** the
+  **Filter bar** (~50×) and **Quick filters** out of the context-shaped "Grid Toolbar," and **re-homed**
+  the **Filter row** from the retired "Monitoring config." Stories: Expression builder · Filter bar
+  (interactive) · Quick filters · Filter row. Reproductions (store-bound); verified render + the moved
+  Filter bar still interactive, no console errors.

package/components/specs/form-item.md

@@ -0,0 +1,130 @@
+# Form Field (`FlotoFormItem`) — Spec, Findings & Solutions
+
+| | |
+| --- | --- |
+| **Tier** | Molecule (form field) |
+| **Maturity** | 🟢 Stable — the backbone of every form |
+| **Source** | `src/components/_base-form-item.vue` (global `FlotoFormItem`) — `MValidationProvider` (vee-validate) → `MFormItem` → label + control |
+| **Storybook** | `Molecules/FormItem` (Examples · Usage · Accessibility · Changelog) |
+| **Registry** | [`../registry/form-item.json`](../registry/form-item.json) |
+| **Family** | the form-controls host — wraps `Input` / `Select` / `Radio` / `Checkbox` / `LooseTags` / `DropdownPicker` |
+| **Figma** | TODO |
+
+## Usage (product analytics)
+
+- **`<FlotoFormItem>` used 1783×** — the **most-used component** in the product (every field).
+- `label` 611× · `rules` 272× · `id` 52× · `help`/`info-tooltip` a few. Wrapped by `FlotoForm`
+  (`layout="horizontal"` or `"vertical"`).
+
+## Overview
+
+The **Form Field**: a label + validation + control + error/help message, in one wrapper. It
+binds a vee-validate `MValidationProvider` to a `MFormItem` (Ant form-item). v-model binds
+`value` + `update`. With **no default slot** it renders its own `MInput` (routed by `type`/
+`inputType`); otherwise the **default slot is the control** (any input component).
+
+## Anatomy
+
+```text
+Label *  ⓘ                         ← label · required asterisk (from rules) · optional info (i) tooltip
+┌───────────────────────────────┐
+│ control (MInput or slot)       │
+└───────────────────────────────┘
+  Help text  /  Error message      ← help (hint) OR the validation error (red) when invalid
+```
+
+## Options / API
+
+- **`label`** — field label (renders the `<label>` + optional info tooltip).
+- **`rules`** (String|Object) — vee-validate rules (`required|email|max:255` …). **`required`
+  is derived from `rules`** — the asterisk shows when rules include `required` (no separate prop).
+- **`help`** — hint text under the field.
+- **`info-tooltip`** — an **(i)** icon by the label with hover help (HTML allowed).
+- **`type`/`inputType`** — control type for the built-in `MInput` (text/number/textarea/…).
+- **`validationLabel`**, **`vid`**, **`mode`** (`eager`), **`immediate`**, **`hideErrorMessage`**.
+- **Layout** (from the parent `FlotoForm`/`MForm` `layout`): **vertical** (label above the
+  control, 13×) or **horizontal** (label beside, via `labelCol`/`wrapperCol`, 14×) — both common.
+- **`labelCol`/`wrapperCol`** — responsive grid split for label vs control (horizontal layout).
+- **Sizes:** none — fields are one height (the control's). **`is-view`** read-only mode lives on
+  the *inner controls*, not on `FlotoFormItem`.
+- **Slots:** default (the control, gets `slotData`) · `before-input` · `input-children` · plus
+  passthrough scoped slots to the inner `MInput`.
+- **Methods:** `validate()` · `setValue(v)` · `addError(err)` · `focus()`.
+- v-model: `value` + `update`. Emits `blur`.
+
+## Behaviors
+
+- **Required asterisk** appears when `rules` contain `required` (not `required_if`).
+- **Validation:** on `eager` mode the field validates on interaction; **error** sets a red
+  border + an inline message (`errors[0]`); **success** sets a valid status. The message is
+  **pristine-gated** — it appears after the user interacts (type/blur), not on first paint.
+- **Built-in vs custom control:** omit the slot for a plain `MInput`; use the slot to wrap a
+  Select/Radio/Checkbox/picker and still get the label + validation.
+- **Programmatic:** parents call `validate()` / `addError()` / `setValue()` / `focus()` via a ref.
+
+## Content & writing
+
+- Labels: short noun phrases, Title Case ("Polling Interval"). Don't repeat the label in the
+  placeholder. Use `help` for a persistent hint, `info-tooltip` for a longer explanation.
+
+## Accessibility
+
+- The label is associated with the control via `MFormItem`; the required asterisk is visual —
+  ensure the rule also conveys requirement to AT (the error message does).
+- ⚠️ Inner controls have **no visible focus ring** ([SF-001](../../findings/SF-001-focus-visible.md)).
+- Error messages are text (not color-only) — good; keep them specific.
+
+## Findings & Inconsistencies
+
+### F1 — `required` is derived, not explicit · Low · Documented
+
+There's no `required` prop — the asterisk comes from parsing `rules` for `required`. Passing a
+`required` attribute does nothing. **Solution:** document (done); a `required` convenience prop
+that injects the rule could reduce confusion.
+
+### F2 — Error message is pristine-gated · Low · Documented
+
+Even with `immediate`, the inline message only shows after interaction (the red border shows
+immediately). Expected vee-validate behavior; document so it's not mistaken for a bug.
+
+### F3 — No visible focus ring on controls · High · Open *(a11y)* → [SF-001](../../findings/SF-001-focus-visible.md)
+
+System-wide (the wrapped inputs strip `outline`).
+
+## Do / Don't
+
+### Do
+
+- Wrap **every** form control in `FlotoFormItem` for a consistent label + validation + error.
+- Put validation in `rules` (`required|email|max:255`); add reusable rules in `src/validations.js`.
+- Use the default slot to wrap non-text controls (Select/Radio/Checkbox/picker).
+- Use `help` for hints, `info-tooltip` for longer guidance.
+
+### Don't
+
+- Don't pass a `required` attribute expecting an asterisk — put `required` in `rules` (F1).
+- Don't hand-roll labels/validation around a bare input — use this wrapper.
+- Don't rely on `@input` — v-model uses `update`.
+
+## Related
+
+`Input` (the default control) · `Radio` / `Checkbox` / `Switch` / `DropdownPicker` / `LooseTags`
+(slot controls) · `FlotoForm` (the form + layout) · `MValidationObserver` (form-level validate).
+
+## Changelog
+
+- **2026-06-07** — Added (decision-grade Usage from the start) — the Form Field molecule
+  (1783×). Deep-dive of `_base-form-item.vue`: vee-validate provider → MFormItem → label +
+  control + error; `required` derived from `rules`; built-in MInput vs slot control; help +
+  info-tooltip; `validate()`/`setValue()`/`addError()`/`focus()`. Storybook: registered
+  `MValidationProvider`/`Observer` + `src/validations` rules + FlotoFormItem in the preview;
+  stories Basic · Required · Help · Info tooltip · Custom control · Validation error (verified
+  the live email error message + red border). Findings F1 (derived required), F2 (pristine-gated
+  message), F3 (focus → SF-001).
+- **2026-06-07** — Fixed a Storybook-wide tooltip bug + coverage. Root cause: `MTooltip`
+  renders `<VTippy>` (vue-tippy), which wasn't registered in the preview — so the info-tooltip
+  dumped its content inline (always-on dark box, no (i) icon, no hover). Registered
+  `VTippy` (vue-tippy `TippyComponent`) → **all `MTooltip`s now work** (icon trigger + hover
+  popup; verified). Added a **Layout** story (vertical vs horizontal). Confirmed coverage: no
+  size variants (one height); `is-view` is on the inner controls, not the field; the repeatable
+  `multiple-form-items` pattern is a separate (related) component.