@mtdt/observeops-ds-spec 0.1.0

package/components/specs/navigation.md

@@ -0,0 +1,181 @@
+# Navigation — Spec, Findings & Solutions
+
+| | |
+| --- | --- |
+| **Tier** | Molecule |
+| **Maturity** | 🟢 Stable |
+| **Source** | `layout/navbar.vue` (`FlotoNavBar`) · `settings/components/left-menu.vue` · `report/components/report-steps.vue` (`ReportSteps`) + `product-setup/components/guide-section-step.vue` + `auth/two-factor-verification.vue` (the steppers — all bespoke, no `MSteps`) · `report/components/compliance-breadcrumb.vue` · `_base-back-button.vue` (`FlotoBackButton`). |
+| **Storybook** | Molecules/Navigation |
+| **Registry** | [`registry/navigation.json`](../registry/navigation.json) |
+| **Family** | [Navigation](../family-map.md) |
+
+## Why this is a family
+
+The product's **wayfinding** components — distinct from **Toolbars** (which hold *actions*) and
+**Tabs** (sibling views of one page). Catalogued by archetype.
+
+## The archetypes
+
+| Archetype | Source | Usage | What it is |
+| --- | --- | --- | --- |
+| **Primary nav** | `FlotoNavBar` | global | left vertical **module** nav (icon + label) |
+| **Side menu** | `settings/left-menu` · Log/Topology hierarchy · Dashboard · Report/saved-views | many | the **left-panel** nav — 4 forms: section · tree · category-list · list/saved-views |
+| **Steps** | `report-steps.vue` · `product-setup` guide · 2FA | 3 flows | numbered **wizard / stepper** (bespoke, no `MSteps`) |
+| **Breadcrumb** | `compliance-breadcrumb` | — | back + **path trail** |
+| **Back button** | `FlotoBackButton` | 3× | a **chevron-left** router link |
+| **Tabs** | `MTab` | 86× | *its own family* (Molecules/Tabs) — cross-referenced |
+
+### Primary nav
+
+- The left vertical **module** sidebar (`MLayoutSider`). **Collapsed 65px** by default (brand mark +
+  module icons only); **hover-expands to 170px** (`@mouseover`/`@mouseout` → `pinned`) revealing the
+  **ObserveOps** logo + module labels. The **16 modules** come from `visibleMenuItems`
+  (role/license-gated): Dashboards, Monitors, Alerts, SLO *(BETA)*, Reports, Topology, NCCM, NetRoute,
+  Metric Explorer, Log Explorer, APM Explorer, RUM Explorer, Flow Explorer, Trap Explorer, Audits,
+  Settings — each with its registered module icon. **Active** module highlights `--primary` on
+  `--code-tag-background-color` with an inset left rule when expanded. `MMenu theme="dark"` +
+  `MMenuItem` + `FlotoLink`. **Collapsed ↔ expanded is the primary variant.**
+
+### Side menu (the left-panel — 4 forms)
+
+The product's **left-hand panel** in list/explorer views. One archetype, **four forms** (all share a
+shell: optional **tabs** + **search** + a scrollable list; selecting an item filters/navigates the main
+view). Surfaced by a per-module sweep — the original entry only covered the first.
+
+1. **Section menu** — `settings/components/left-menu.vue` (**20×**): a search atop an **`MCollapse`**
+   accordion of sections (icon + name + optional beta tag) → sub-items; active item gets a `--primary`
+   left rule. The Settings sub-nav.
+2. **Tree** — **Log Explorer** `log/components/hierarchy/*`, **Topology** `topology-hierarchy.vue`, and
+   **Inventory** (Monitors) via the shared **`@views/layouts/monitor-hierarchy-layout.vue`** — all on the
+   shared **`components/hierarchy/infinite-tree.vue`**: tabs (Type / Group / Saved Query), search, then a
+   **virtualised hierarchy** — each node a **chevron + type icon (or severity badge) + name + count
+   badge** (`57.25 M`), nested; the Saved-Query tab is a flat `MMenu` list with Create/​delete.
+3. **Category list** — **Dashboard** `dashboard/components/dashboard-dropdown.vue`: a **segmented**
+   Dashboard / NOC View toggle + round **＋**, search + layout-toggle, then `MCollapse` **categories with
+   count badges** (My Favorite 7, Server 6 …) and a **favourite star** per row.
+4. **List / Saved views** — **Report** `report/components/report-sidebar.vue` + the **`ExplorerSavedViewList`**
+   reused by **APM / RUM / Metric Explorer** (and the Log Saved-Query tab): tabs + search + a flat
+   `MMenu` list with a **Favorites (★)** row, an **active** highlight, and a per-row **pencil** to inline-rename.
+
+> **Not in this family (cross-refs):** the **faceted checkbox** left-panel (`vertical-filter/filters.vue` —
+> APM/RUM/NCM) is a **Filter** → **Molecules/Filters → Vertical filter**; the **Metric Explorer**
+> picker (`metric-picker.vue` → `counter-list.vue`, ⊕-add + drag) is a **picker** → cross-ref
+> **DropdownPicker**. The **Flow** "Result By" sidebar is a *config* panel (sortable list + dropdowns),
+> not nav.
+
+### Steps
+
+- A **count circle + label** per step: **completed** (✓ filled), **current** (filled + ring),
+  **remaining** (grey); connectors fill `--primary` up to the current step. **All steppers are bespoke**
+  (the product has no `MSteps`). Three real usages:
+  - **Report builder** (`report-steps.vue`, `ReportSteps`) — horizontal 3-step wizard:
+    *Report Properties → Visualizations & Preview → Schedule*. The reproduction models this one.
+  - **Product setup / onboarding guide** (`product-setup/guide-sections.vue` + `guide-section-step.vue`)
+    — vertical numbered step list (completed shows a green ✓) for the Log / Metric / Flow setup guides.
+  - **Two-factor auth setup** (`auth/two-factor-verification.vue`) — a *Step 1 / 2 / 3* indicator with
+    dividers.
+
+### Breadcrumb / Back button
+
+- **Breadcrumb** — a back chevron + a path (`Reports / Compliance / …`), current crumb bold. (Some are
+  a back + title/subtitle context header rather than a full trail.)
+- **Back button** (`FlotoBackButton`, 3×) — a `chevron-left` `MIcon` in a `FlotoLink`; also the Page
+  header's `back-button` slot.
+
+## App chrome & specialised navigators (from the full per-module sweep)
+
+The 2026-06-16 per-module fan-out surfaced six more wayfinding components beyond the core archetypes:
+
+| Member | Source | What it is |
+| --- | --- | --- |
+| **User account menu** | `components/layout/user-dropdown.vue` | header avatar → `MPopover`: profile, theme toggle, logout |
+| **Notification dropdown** | `components/layout/notification-dropdown.vue` | header bell + badge → **Alerts / System** tabs + View all |
+| **Global search / Omnibox** | `components/omnibox/searchbar.vue` | command/search palette (category + CodeMirror query + Execute) |
+| **NOC Player** | `dashboard/components/noc-player.vue` | wallboard **rotator** — ‹ prev/next ›, countdown, play/pause |
+| **Timeline scrollbar** | `netroute/components/timeline-scrollbar.vue` | **temporal** navigator (single ‹ › + batch ‹‹ ›› through time buckets) |
+| **Graph expansion breadcrumb** | `netroute/components/graph-view.vue` | a **Breadcrumb variant** — closable tags of expanded graph nodes |
+
+## Checked & scoped out (sweeps)
+
+Swept the product for nav variants beyond the archetypes; these were considered and deliberately placed
+elsewhere or confirmed absent:
+
+| Candidate | Usage | Verdict |
+| --- | --- | --- |
+| Topology Full/Tree switch · chart-type selector | — | **Radio (segmented)** usage, not a new nav entry — cross-ref Atoms/Radio. |
+| Topology category / APM section / Alert two-level tabs | — | **Tabs** usage (Alert adds a hover sub-menu) — cross-ref Molecules/Tabs. |
+| ViewDetailDrawer (tabs inside a drawer) | — | **Drawer + Tabs** composition — cross-ref Organisms/Drawer. |
+| Faceted checkbox sidebar (`vertical-filter/filters.vue`) | APM/RUM/NCM | A **Filter**, not nav → **Molecules/Filters → Vertical filter**. |
+| Swap/reorder control · Role-navigation form · flame-graph zoom · Layer-3 toggle · shortcuts tooltip | — | **Not navigation** (reorder control / settings form / chart-zoom / filter toggle / help legend). |
+| **Pagination** (`FlotoPaginatedCrud` / `k-pager`) | **79×** | A **page-nav** archetype, but it belongs to the **Table** family (grid footer) — cross-referenced, not duplicated here. |
+| **Menu toggle** (`menu-toggle-button`) | 7× | The Primary nav's own collapse control — folded into Primary nav's **collapsed ↔ expanded** variant, not a separate entry. |
+| `role="navigation"` landmark | 2× | An a11y attribute, not a component → tracked in **F2**. |
+| `MMenu` | 13× | The shared primitive under Primary nav / Side menu → now catalogued in its own right in the **Menu** family (Molecules/Menu). |
+| `MSubMenu` (flyout submenus) | **0×** | Confirmed **absent** — the product has no flyout/mega-menu pattern. |
+| Context / action menu (`FlotoGridActions` · `MDropdown`) | grid rows · 1× | An action surface ("do something"), not wayfinding → now homed in the **Menu** family (Molecules/Menu). |
+
+## Which navigation? (decision)
+
+1. **Top-level modules?** → **Primary nav**.
+2. **Sections within a module?** → **Side menu**.
+3. **A multi-step flow?** → **Steps**.
+4. **Location + a way up?** → **Breadcrumb**.
+5. **Just back one level?** → **Back button**.
+6. **Sibling views of one page?** → **Tabs** (Molecules/Tabs).
+
+## Accessibility
+
+- **Verify:** nav **landmarks** (`role="navigation"`), **`aria-current`** on the active item,
+  focus-visible ring (**SF-001**), and that the **stepper** conveys step state (not color-only) to
+  assistive tech.
+
+## Design tokens used
+
+`--nav-panel-bg` · `--code-tag-background-color` (active) · `--left-menu-text-color` · `--primary` ·
+`--primary-alt` · `--border-color` · `--neutral-lightest` · `--neutral-light` · `--page-text-color`.
+
+## Findings & Inconsistencies
+
+| # | Severity | Status | Finding |
+| --- | --- | --- | --- |
+| F1 | Low | Noted | Router/store-bound (`visibleMenuItems`, `FlotoLink`, `MCollapse`) → reproductions. |
+| F2 | Low (a11y) | Open | Verify nav landmarks / `aria-current` / focus ring / stepper semantics. |
+
+## Do / Don't
+
+- **Do** use Primary nav for modules, Side menu for sections, Steps for ordered flows; put the Back
+  button in the Page header slot.
+- **Don't** use Tabs for module/section nav; don't hand-roll a sidebar; don't confuse a breadcrumb
+  (location) with a toolbar (actions).
+
+## Related components
+
+**Tabs** (sibling-view nav) · **Toolbars** (Page header hosts the back button + breadcrumb) ·
+`MMenu` / `MCollapse` (the primitives) · `Input` (the side-menu search).
+
+## Changelog
+
+- **2026-06-16** — Added a **second Steps example** — **Setup guide steps** (vertical
+  `product-setup/guide-section-step.vue` pattern: 50×50 rounded index box, number → green ✓ when done,
+  title + description) alongside the existing horizontal **report-builder** wizard. Verified light +
+  dark.
+- **2026-06-16** — Fidelity pass (round 2, against a product screenshot) — corrected the Primary nav
+  logo from a square "M" to the real **ObserveOps donut mark** (coral wedge + ring + hollow centre,
+  theme-aware ring via `--nav-text-color`); changed the active item from a tinted row + left rule to a
+  **filled rounded pill** (`--primary` bg, `--nav-panel-bg` text, inset margins) matching the product;
+  made the **BETA** tag a rounded grey pill; added the bottom **MaskGroup** decoration (translucent
+  overlapping circles). Also **corrected the Steps source**: the product has **no `MSteps`** — the
+  steppers are bespoke (`report-steps.vue`, the `product-setup` guide, and `two-factor-verification`).
+- **2026-06-16** — Recheck — **rebuilt Primary nav for product fidelity** against the real
+  `FlotoNavBar`: collapsible `MLayoutSider` (**collapsed 65px → hover-expand 170px**), the **ObserveOps**
+  logo, the real **16 modules** with their registered icons, the **SLO BETA** tag, and the `--primary`
+  active highlight + inset left rule. Verified collapsed + expanded in **both light and dark** themes
+  (screenshots). Recorded the recheck sweep: **Pagination** (79×) → cross-referenced to the **Table**
+  family; **menu toggle** folded into the collapsed↔expanded variant; `MSubMenu` flyouts confirmed
+  **absent** (0×).
+- **2026-06-16** — Added — the **Navigation** family (the wayfinding archetypes): **Primary nav**
+  (`FlotoNavBar`), **Side menu** (`settings/left-menu`, 20×), **Steps** (`MSteps`), **Breadcrumb**,
+  **Back button** (`FlotoBackButton`). **Tabs** stay their own family (cross-referenced). Surfaced as a
+  separate family during the Toolbars recheck (nav ≠ toolbar). Reproductions (router/store-bound);
+  verified Primary nav + Side menu + Steps render, no console errors. Findings F1 (reproduction),
+  F2 (a11y landmarks/aria-current).

package/components/specs/popover.md

@@ -0,0 +1,118 @@
+# Popover (`MPopover`) — Spec, Findings & Solutions
+
+| | |
+| --- | --- |
+| **Tier** | Molecule |
+| **Maturity** | 🟢 Stable |
+| **Source** | `ui/components/Popover/Popover.vue` (kit; wraps Ant `a-popover`). Positioning primitive: `src/components/_base-popper.vue` (**MPopper**, wraps `v-popover`). |
+| **Storybook** | Molecules/Popover |
+| **Registry** | [`registry/popover.json`](../registry/popover.json) |
+| **Family** | [Popover / Tooltip](../family-map.md) |
+
+## Usage analytics
+
+- **MPopover 35×** · **MPopper 2×** (direct — but MPopper also powers **FlotoDropdownPicker**'s
+  positioning, so its real footprint is much larger).
+- Patterns: **action/kebab menus** (`_base-grid-actions.vue`), **color picker**
+  (`color-picker.vue`), **date/time pickers**, rich panels, **"+N overflow" hover reveals**
+  (`tags-list.vue`). Overlay classes: `picker-action-dropdown`, `color-picker-popover`,
+  `picker-overlay`, `readable-content-overlay`.
+- **Opening behavior:** `trigger` — **click 20×**, **hover 13×** (passive reveals), explicit
+  click 2×. Transition: **`transition-name="slide-up"` 16×**.
+- **Placement (Ant names):** **`bottomLeft` 11×** (most common) · `bottomRight` 9× · `bottom` 7× ·
+  `leftTop` 4× · `top`/`right` 1×. Default `bottom`. ⚠️ Ant names — **not** the Tooltip's VTippy
+  `top-start` names.
+
+## Overview
+
+A **click-triggered floating panel** anchored to a trigger, holding **interactive** content —
+unlike a Tooltip (hover, non-interactive). `MPopover` wraps Ant `a-popover`; **`MPopper`** is the
+lower-level `v-popover` primitive used as the picker positioning engine. Use a Popover for
+anchored menus/pickers/mini-forms; for a center-interrupting task use **`MModal`**, and for
+select-from-options use **`FlotoDropdownPicker`**.
+
+## Anatomy
+
+- **Trigger** (`trigger` slot, scope `{ hide, show, toggle }`) — the anchor.
+- **Title** (optional `title` slot) — a header row.
+- **Content** (default slot, scope `{ hide, show, toggle }`) — the interactive panel.
+
+## Options (props)
+
+| Prop | Default | Notes |
+| --- | --- | --- |
+| `trigger` | `click` | `click` / `hover` / `focus` / `contextmenu` |
+| `placement` | `bottom` | `bottom` / `bottomRight` / `top` / `left` / `right` … |
+| `visible` | — | controlled mode; pair with `@visibleChange` (one-way — F1) |
+| `overlayClassName` | — | e.g. `color-picker-popover`, `picker-action-dropdown` |
+| `overlayStyle` | — | inline overlay style (width/padding/radius) |
+| `destroyTooltipOnHide` | `true` | re-creates content each open |
+| `getPopupContainer` | — | defaults to closest `.__panel` or `document.body` |
+
+## Behaviors
+
+- Opens on **click** by default; the slot scope `{ hide, show, toggle }` lets content drive
+  dismissal (an action item calls `hide()` on select).
+- `destroyTooltipOnHide` re-mounts the content each open (fresh state).
+- **MPopper** adds a ResizeObserver to keep the panel positioned as content resizes; boundary is
+  the closest `.__panel` or the viewport.
+
+## Content & writing
+
+- Title is a short noun; content is the interactive panel. Keep menus to a handful of items —
+  beyond ~7, reconsider the pattern.
+
+## Accessibility
+
+- **Disclosure semantics missing (F2):** the trigger has no `aria-haspopup`/`aria-expanded`,
+  focus is **not** moved into the panel on open, and there is **no focus trap** — keyboard/SR
+  users aren't told a panel opened or guided into it. Recommended: set `aria-haspopup` +
+  `aria-expanded` on the trigger; move focus to the first focusable on open; restore on close.
+- **Focus ring** removed on the overlay (`:focus { outline:none }` in `_base-popper.less`) —
+  **F3**, links to [SF-001](../../findings/SF-001-focus-visible.md).
+- Escape/outside-click dismissal comes from `a-popover`; verify Escape returns focus to the trigger.
+
+## Props / API
+
+See the table above and [`registry/popover.json`](../registry/popover.json).
+
+## Design tokens used
+
+`--page-background-color` · `--border-color` · `--page-text-color` (panel surface/border/text).
+
+## Findings & Inconsistencies
+
+| # | Severity | Status | Finding |
+| --- | --- | --- | --- |
+| F1 | Low | Open | `visible` is one-way — controlled mode needs an explicit `@visibleChange` handler to stay in sync. |
+| F2 | Medium (a11y) | Open | No `aria-haspopup`/`aria-expanded`, no focus move into the panel, no focus trap. |
+| F3 | Medium (a11y) | Open | No focus ring on the overlay — links to **SF-001**. |
+
+## Recommended solutions
+
+- **F1:** document/standardize the controlled pattern (`:visible` + `@visibleChange`), or expose a
+  `v-model:visible`.
+- **F2:** add disclosure ARIA + focus management (move in on open, restore on close, Escape closes).
+- **F3:** adopt the `:focus-visible` ring from SF-001.
+
+## Do / Don't
+
+- **Do** use for interactive, click-triggered content; give items a `hide()` on select; anchor row
+  actions `bottomRight`.
+- **Don't** use for plain hints (use **Tooltip**); don't use for center-interrupting tasks or
+  confirmations (use **Modal**); don't hand-roll a select dropdown (use **FlotoDropdownPicker**).
+
+## Related components
+
+`MTooltip` (hover label) · `FlotoDropdownPicker` (select; uses MPopper) · `MModal` (dialog).
+
+## Changelog
+
+- **2026-06-11 (nth-level audit)** — Documented the real opening/placement behavior: `trigger`
+  click 20× / **hover 13×** (+N overflow reveals), `transition-name="slide-up"` 16×, placement
+  **`bottomLeft` 11×** (most common) / `bottomRight` 9× / `leftTop` 4×; Ant placement names (not
+  VTippy). Added **Behavior: hover trigger** + **Placements** stories.
+- **2026-06-11** — Added (decision-grade Usage). Deep-dive of `Popover.vue` (35×, kit `a-popover`)
+  and `_base-popper.vue` (MPopper, the picker engine). Stories: Basic (title + content) · Action /
+  kebab menu · Rich panel (color picker) · Playground — verified click-open with title + items, no
+  console errors. Findings F1 (one-way `visible`), F2 (disclosure ARIA + focus), F3 (focus → SF-001).

package/components/specs/radio.md

@@ -0,0 +1,144 @@
+# Radio (`MRadioGroup`) — Spec, Findings & Solutions
+
+| | |
+| --- | --- |
+| **Tier** | Atom (selection control) |
+| **Maturity** | 🟢 Stable (core selection control) |
+| **Source** | `@motadata/ui` → `ui/components/Radio/RadioGroup.vue` (+ `Radio.vue`); wraps Ant `a-radio-group` |
+| **Storybook** | `Atoms/Radio` (Examples · Usage · Accessibility · Changelog) |
+| **Registry** | [`../registry/radio.json`](../registry/radio.json) |
+| **Family** | selection controls — sibling of [Checkbox](./checkbox.md) & [Switch](./switch.md); the `as-button` segmented control is the Button family's "segmented" relative |
+| **Figma** | TODO |
+
+## Usage (product analytics)
+
+- **`<MRadioGroup>` used 225× across 136 files.**
+- **Standalone `<MRadio>` is used 0×** — radios are always rendered through the **group** with
+  an `:options` array.
+- **`as-button` (segmented control) used 255×** — the segmented form is at least as common as
+  the plain radio list. `buttonStyle` is never overridden (always `solid`).
+
+## Overview
+
+A **one-of-many** selection control. Use `MRadioGroup` with an `:options` array
+(`{ value, text }`) and v-model the selected `value` (`model: { event: 'change' }`). Set
+`as-button` to render a **segmented control** (joined buttons) instead of a radio list. An
+`option` slot allows custom row rendering.
+
+## Anatomy
+
+```text
+Radio list:        ◉ Low   ○ Medium   ○ High        ← a-radio per option
+Segmented:        ┌──────┬──────┬─────┬─────┐
+(as-button)       │ 1h   │ 24h* │ 7d  │ 30d │        ← a-radio-button; selected fills navy
+                  └──────┴──────┴─────┴─────┘
+```
+
+## Options / API
+
+- **`options`** (Array) — `{ value, text | label | title, disabled? }`; the selectable set.
+- **`value`** (v-model) — the selected `value`.
+- **`asButton`** (Boolean) — segmented control vs radio list.
+- **`size`** (`small` · `default` · `large`) — mainly affects the segmented buttons.
+- **`disabled`** (Boolean) — disable the whole group (per-option via `option.disabled`).
+- **`buttonStyle`** (`solid` · `outline`, default `solid`) — never changed in the product.
+- **`name`**, **`defaultValue`**.
+- Slots: default (custom `a-radio`/`a-radio-button` children) · `option` (custom row).
+- Emits **`change`**.
+
+## Behaviors
+
+- **Single selection** — picking one option deselects the others.
+- **Segmented** (`as-button`): the selected button fills the brand color; the rest are
+  outlined/joined. **The selected fill is context-dependent (see F4).**
+- **Keyboard:** native radio behavior — Arrow keys move selection within the group, Space
+  selects.
+
+## Segmented variants (all real in the product)
+
+- **Plain segmented** (`as-button`) — kit default; selected = navy `#111c2c` @ 0.8 opacity.
+- **With icons** — an icon per option via the `option` slot (the `without-icon-margin`
+  context, **14×**) — view/mode toggles.
+- **Severity switch** — `class="radio-toggle-shadow alert-severity-buttons"` (the real
+  `severity-switch.vue` combo): borderless segments with thin separators; selected = a tinted
+  rounded chip. (`radio-toggle-shadow` 2×, `alert-severity-buttons` 2×.)
+- **Radio dot color** (list) = cyan `#099dd9` (Ant `@primary-color`) — matches the product.
+- `buttonStyle="outline"` exists but is **unused** (always `solid`).
+
+## Design tokens used
+
+Selected segment fill = primary/brand (measured `#111c2c` light → `#e3e8f2` dark); inherits
+Ant radio tokens for the dot and borders.
+
+## Accessibility
+
+- Built on native `<input type="radio">` grouped by `name` — correct role and arrow-key
+  navigation. ✅
+- ⚠️ **No visible keyboard focus indicator** ([SF-001](../../findings/SF-001-focus-visible.md)).
+- Ensure the group has a label (a field label or `aria-label`) describing what's being chosen.
+
+## Findings & Inconsistencies
+
+### F1 — Standalone `MRadio` + `variant`/`type` are effectively dead · Low · Open
+
+`MRadio` is never used directly (0×); its `variant="info"` (→ `.radio-info`) and
+`type="button"` paths are unexercised. The group is the real API. **Solution:** document the
+group as the entry point; treat `MRadio` as an internal building block.
+
+### F2 — `buttonStyle` outline unused · Low · Open
+
+`buttonStyle` defaults to `solid` and is never set to `outline` (0×). **Solution:** document
+`solid` as the de-facto style; keep `outline` only if a real need appears.
+
+### F3 — No visible focus indicator · High · Open *(a11y)* → see [SF-001](../../findings/SF-001-focus-visible.md)
+
+Same system-wide focus-ring gap as other controls.
+
+### F4 — Segmented selected style is context-dependent · Medium · Open
+
+The selected segment renders differently depending on the **ancestor**: standalone it uses the
+kit's `.ant-radio-group-solid` (navy `#111c2c` **@ 0.8 opacity**), but inside form/panel
+contexts `src/design/form.less` overrides it to a **solid `--primary` fill (`!important`),
+11px padding, and icon spacing**. So the *same* `as-button` group looks slightly different
+(opacity + padding) inside a form vs standalone. Storybook (loading the same stylesheets)
+matches the product **for the same markup**; the divergence is purely the missing form
+ancestor. **Solution:** decide on one canonical segmented appearance and move it out of the
+form-scoped selectors into the component (kit) styles so it's consistent everywhere; meanwhile
+the catalog shows the standalone look + documents the in-form override here.
+
+## Do / Don't
+
+### Do
+
+- Use `MRadioGroup` with `:options` for one-of-many; v-model the value.
+- Use `as-button` for a small set of always-visible, mutually-exclusive choices.
+- Disable individual options with `option.disabled`.
+
+### Don't
+
+- Don't use a radio group for multi-select (use `Checkbox`) or an instant on/off (use `Switch`).
+- Don't use radios for **many** options or when space is tight (use `DropdownPicker`).
+- Don't render standalone `MRadio` — go through the group.
+
+## Related
+
+`Checkbox` (multi-select) · `Switch` (instant on/off) · `DropdownPicker` (many options) ·
+Button's **segmented control** is this component with `as-button`.
+
+## Changelog
+
+- **2026-06-07** — Added (first authored to the decision-grade Usage standard). Deep-dive of
+  `RadioGroup.vue`/`Radio.vue` (225×; standalone radio 0×; `as-button` 255×). Verified radio
+  list + segmented in light/dark. Findings F1 (dead standalone/variants), F2 (`outline`
+  unused), F3 (focus → SF-001). Closes the Button family's "segmented control" relative.
+- **2026-06-07** — Fidelity deep-dive (owner flagged the segmented didn't match the product).
+  Confirmed radio-list dots = cyan `#099dd9` (matches). Found the full segmented variant set
+  and added stories: **with icons** (14×) and the **severity switch** combo
+  (`radio-toggle-shadow` + `alert-severity-buttons`, the real `severity-switch.vue`). New
+  finding **F4**: segmented selected style is context-dependent (kit navy @0.8 standalone vs
+  solid `--primary` inside forms). Storybook matches the product for identical markup.
+- **2026-06-07** — Fixed the icon-segmented story: the icon was wrapped in a `flex` span, whose
+  baseline offset the selected segment by 7px (stair-step). Switched to the product's inline
+  icon pattern (`.without-icon-margin`, icon `mr-1`) — segments now align (all `top: 40`).
+  Authoring note: don't `flex`-wrap content inside Ant `vertical-align: baseline` radio
+  buttons; keep it inline.

package/components/specs/scheduler.md

@@ -0,0 +1,133 @@
+# Scheduler / Recurrence (`ScheduleInput`) — Spec, Findings & Solutions
+
+| | |
+| --- | --- |
+| **Tier** | Molecule |
+| **Maturity** | 🟢 Stable |
+| **Source** | `src/components/schedule-input/index.vue` (`ScheduleInput`) + `once-input.vue` · `weekly-input.vue` · `monthly-input.vue` (sub-forms). |
+| **Storybook** | Molecules/Scheduler |
+| **Registry** | [`registry/scheduler.json`](../registry/scheduler.json) |
+| **Family** | [Scheduler / Recurrence](../family-map.md) |
+
+## Usage analytics
+
+- **16×** across settings & reports: **backups** (`backup-profile-form`,
+  `device-inventory-schedule-backup`), **network discovery** (`discovery-schedules`), **compliance
+  audits** (`compliance-audit-schedules`), **monitor (re)discovery** (`monitor-schedule-form`,
+  `rediscover/custom-schedule-form`, `topology-scanner/schedule-form`), **runbooks**
+  (`runbook-schedules`), **reports** (`report-form`), **policies** (`policy-form/basic-info`).
+- Built entirely from already-catalogued primitives — it's a **composition**, not a new control.
+
+## Overview
+
+A **recurrence builder**: pick *how often* a job runs and *when*. A **"Scheduler Type"** segmented
+control (`MRadioGroup as-button`) — **Once · Daily · Weekly · Monthly** — swaps in a sub-form. This is
+distinct from the **Date & Time Pickers** family (which picks a *value* or a *window*); the Scheduler
+produces a **recurrence rule**.
+
+## Anatomy
+
+- **Scheduler Type** — segmented `MRadioGroup as-button` (Once/Daily/Weekly/Monthly).
+- **Sub-form** (swaps on type):
+  - **Once / Daily** → **Start Date** (`MDatePicker`, date-only, `min-date` = today) + **Hours** (the
+    custom dropdown `TimePicker` — a `FlotoDropdownPicker` of times, multi-select).
+  - **Weekly** → **Days** (`FlotoDropdownPicker`, Mon–Sun multi) + Start Date + Hours.
+  - **Monthly** → **Months** (Jan–Dec multi) + **Dates** (1–31 multi) + Start Date + Hours.
+- Each field is a **`FlotoFormItem`** with `rules="required"`.
+
+## Options (props)
+
+### ScheduleInput
+
+| Prop | Default | Notes |
+| --- | --- | --- |
+| `value` | — | v-model; `{ scheduleType, scheduleInfo }` |
+| `excludedScheduleOptions` | `[]` | drop types from the control (e.g. `['Weekly','Monthly']`) (1×) |
+| `showOnlyOnce` | `false` | collapse to **Once** only (no recurrence) (1×) |
+| `disabled` (passthrough) | — | via `$attrs` — disables the fields (2×) |
+| `$attrs` → sub-form | — | `disabled` (2×), `time-options` (2×), `use-single-selection` (1×), `hide-date-time` (1×), `multiple` |
+
+### Sub-forms (once / weekly / monthly)
+
+| Prop | Default | Notes |
+| --- | --- | --- |
+| `value` | — | the `scheduleInfo` object |
+| `hideDateTime` | `false` | hide Start Date + Hours |
+| `timeOptions` | — | override the Hours options |
+| `multiple` | `false` | allow multiple Hours (`use-single-selection` caps to 1) |
+
+## Behaviors
+
+- **Emit:** `{ scheduleType, scheduleInfo: { startDate:<ms>, times:[…], days:[…] (weekly),
+  months:[…] + dates:[…] (monthly) } }`. Changing the **type resets** `scheduleInfo` to
+  `{ startDate: now }`. Start Date defaults to **today** if unset.
+- **`Daily` reuses the `Once` sub-form** (Start Date + Hours) — the difference is the `scheduleType`
+  value, not the fields.
+
+## Content & writing
+
+- Field labels are fixed (Scheduler Type, Start Date, Hours, Days, Months, Dates) — keep them.
+
+## Accessibility
+
+- **Provided by** the composed primitives: `MRadioGroup` (radio semantics + arrow-key type selection),
+  `MDatePicker` / `FlotoDropdownPicker` (their own a11y), `FlotoFormItem` (labels + required state).
+- **Verify:** focus-visible ring (**SF-001**) on the segmented buttons and the selects.
+
+## Design tokens used
+
+Inherits from its primitives — segmented control `--primary` (selected), `--neutral-lightest`
+(unselected); fields use `--border-color`, `--page-text-color`, `--neutral-light`. No new tokens.
+
+## Findings & Inconsistencies
+
+| # | Severity | Status | Finding |
+| --- | --- | --- | --- |
+| F1 | Low | Open | All three sub-forms declare `name: 'OnceForm'` (copy-paste leftover) — should be `WeeklyForm` / `MonthlyForm`. Harmless but confusing. |
+| F2 | Low | Noted | `ScheduleInput` pulls the local DB (**lokijs → Node `fs`**) transitively, so it can't render live in Storybook — **reference reproduction** built from the real primitives. |
+
+## Recommended solutions
+
+- **F1:** rename each sub-form's `name` to match its file (`WeeklyForm`, `MonthlyForm`).
+- **F2:** if a headless schedule builder is extracted (Vue 3), drop the DB import so it can render
+  standalone.
+
+## Do / Don't
+
+- **Do** use for recurring jobs; drop unsupported recurrences with `excluded-schedule-options`; use
+  `show-only-once` for a single run.
+- **Don't** use it for a plain date/time value (→ `MDatePicker`) or a chart time window
+  (→ `TimeRangePicker`); don't hand-roll the Once/Daily/Weekly/Monthly switcher.
+
+## Related components
+
+`MRadioGroup` (segmented type control) · **Date & Time Pickers** (`MDatePicker` / the custom
+`TimePicker` it embeds) · `FlotoDropdownPicker` (Days/Months/Dates) · `FlotoFormItem`.
+
+## Checked & scoped out (sweep recheck)
+
+A census of every `<ScheduleInput>` (16×) confirmed the **types are Once/Daily/Weekly/Monthly only**
+and accounted for every prop. Deliberately *separate* (not ScheduleInput variants):
+
+- **`MetricPollTime` / `metric-collection-time/*`** — metric **polling-frequency** config (a distinct
+  monitoring sub-system) → candidate for a future *Monitoring-config* entry, not job recurrence.
+- **`MonitoringHourPicker`** — a monitoring-hours selector.
+- **`monitor-schedules.vue`** (`MonitorSchedule`) — a CRUD **list** of schedules (on/off windows) that
+  edits via `monitor-schedule-form` → which *uses* `ScheduleInput`; a consumer, not a new component.
+- **`'Hourly'`** — a **granularity** option in policy anomaly/forecast conditions (aggregation period),
+  **not** a recurrence type.
+
+## Changelog
+
+- **2026-06-16 (sweep recheck)** — Full census of `<ScheduleInput>` (16×): types are **Once/Daily/
+  Weekly/Monthly only** (the `'Hourly'` elsewhere is a policy-condition *granularity* dropdown, not a
+  recurrence type). Added the missed **`:disabled`** passthrough (2×). Confirmed `MetricPollTime` /
+  `MonitoringHourPicker` / `monitor-schedules` (CRUD list) are **separate**, not variants — documented
+  in **Checked & scoped out**. No new types/variants missed.
+- **2026-06-16** — Added (decision-grade) — the **Scheduler / Recurrence** family (`ScheduleInput`,
+  16×). Documented the **Once/Daily/Weekly/Monthly** segmented switcher and each sub-form's fields,
+  the **emit shape**, and the `excluded-schedule-options` / `show-only-once` props. Stories built as a
+  **reference reproduction** from the real primitives (`MRadioGroup as-button` + `MDatePicker` +
+  `FlotoDropdownPicker`) because the live `ScheduleInput` pulls the local DB (lokijs). Verified the
+  type-switch swaps the sub-form (Monthly → Months + Dates) and the `scheduleInfo` shape, no console
+  errors. Findings F1 (sub-forms all named `OnceForm`), F2 (lokijs → reproduction).