@mtdt/observeops-ds-spec 0.1.0

package/components/specs/button.md

@@ -0,0 +1,230 @@
+# Button (`MButton`) — Spec, Findings & Solutions
+
+| | |
+| --- | --- |
+| **Tier** | Atom |
+| **Maturity** | 🟢 Stable (core, most-used component) |
+| **Source** | `@motadata/ui` kit → `ui/components/Button/Button.vue` (wraps Ant `a-button`) |
+| **Storybook** | `Atoms/Button` |
+| **Registry** | [`../registry/button.json`](../registry/button.json) |
+| **Figma** | TODO (library not built yet) |
+
+> Documented to the [enhanced standard](../documentation-standard.md): Overview · Anatomy ·
+> Options · Behaviors · Content · Accessibility · API · Tokens · Findings · Do/Don't ·
+> Related · Changelog.
+
+## Usage (product analytics)
+
+- **`<MButton>` used 1,373× across 424 files — the most-used component in the product.**
+- **By variant** (exact): default 301, neutral-lightest 320, transparent 255, primary 91,
+  neutral 77, primary-alt 36, error 31, neutral-lighter 17, info 7, success 5, danger 3;
+  unused: dashed/ghost/warning/neutral-light/topology-overlay.
+- **By size** (approx; shared prop): `small` 76, `large` 9 — the rest default.
+- **Modifiers** (approx; shared): `outline`/ghost ~11 explicit, `rounded="false"` 273, `loading` 518, `block` 0.
+- **Icon buttons:** `shape="circle"` **218×** · `class="squared-button"` (35×35) **365×** — the
+  squared form is more common than the circular one.
+
+## Overview
+
+The primary action control. Wraps Ant `a-button` and adds the project's variant system,
+rounding, and shadow. `variant` routes two ways (`Button.vue`): values in
+`{primary, dashed, danger, ghost, default}` → Ant `type`; everything else → a
+`.button-<variant>` class (+ `type="primary"`). Renders a native `<button type="button">`.
+
+## Anatomy
+
+```text
+┌──────────────────────────────────────┐
+│  [leading icon]  Label  [trailing]    │   ← container (.ant-btn, variant class, radius)
+└──────────────────────────────────────┘
+         ▲ loading spinner replaces/precedes label when :loading
+```
+
+- **Container** — `.ant-btn` + variant class; height from `size`; radius from `rounded`.
+- **Label** — default slot (text).
+- **Icon(s)** — optional `<MIcon>` in the slot (leading/trailing).
+- **Loading spinner** — shown when `:loading`.
+
+## Options
+
+### Variants — render distinctly ✅
+
+| Variant | Applied as | Background | Usage |
+| --- | --- | --- | --- |
+| `primary` | Ant type | `#07101f` navy | 91 |
+| `primary-alt` | class | `#1d2a3e` slate | 36 |
+| `default` | Ant type | `#fff` / border `#e3e8f2` | 301 |
+| `danger` | Ant type | light `#f5f5f5` (see F2) | 3 |
+| `success` | class | `#14b053` green | 5 |
+| `error` | class | `#ec5b5b` red | 31 |
+| `neutral-lighter` | class | `#e3e8f2` | 17 |
+| `neutral-lightest` | class | `#ecf1f9` | 320 |
+| `transparent` | class | transparent | 255 |
+| `dashed` / `ghost` | Ant type | white+dashed / transparent+border | 0 |
+
+### Variants — render as navy ⚠️ (see F1)
+
+`neutral` (77×), `info` (7×), `neutral-light`, `warning` — not allow-listed → navy.
+
+### Sizes
+
+`small` (~24px) · `default` (~34px) · `large` (~34px — **same as default, see F5**).
+
+### Icon buttons (two forms — both heavily used)
+
+The product has **two** icon-only button forms, both previously undocumented:
+
+| Form | How | Usage | Notes |
+| --- | --- | --- | --- |
+| **`shape="circle"`** | Ant circular icon button | **218×** | Renders `border-radius: 4px` (not a true circle) because MButton's default `rounded` class overrides Ant's 50% — see F7. |
+| **`class="squared-button"`** | `buttons.less` 35×35 square | **365×** | Fixed `35px × 35px`, 8px padding; the most-used icon-button treatment. |
+
+Both wrap an `<MIcon>` with no text and take any `variant`. ⚠️ **They require an
+`aria-label`** (no automatic name). Other contextual icon-button classes exist
+(`.model-header-button` 3×, `.button-topology-overlay` 5×) — app-specific, not core.
+
+### States & modifiers
+
+`loading` · `disabled` · `outline` (ghost) · `block` (full width) · `rounded` (default
+true) · `shadow` (default true — **inverted, see F6**) · `shape` (`circle`).
+
+## Behaviors
+
+- **Loading:** `:loading` shows a spinner and blocks clicks — use it to prevent
+  double-submits during async actions.
+- **Block:** `:block` makes the button span its container's width.
+- **Label overflow:** buttons hug their label; no built-in truncation — keep labels short.
+- **Rounded:** `rounded` (default) gives a pill radius; `:rounded="false"` squares it (4px).
+
+## Content & writing
+
+- **Action-first, concise labels:** "Save", "Create policy", "Delete" — verb + object.
+- Avoid vague labels ("OK", "Submit") where a specific verb is clearer.
+- One word or short phrase; no sentences. *(Confirm casing convention against product —
+  appears sentence/Title case; standardize in a later content-guidelines pass.)*
+
+## Accessibility
+
+- **Semantics:** renders a native `<button type="button">` — correct role, Enter/Space
+  activate. ✅
+- **Icon-only buttons:** must have an accessible name — provide visually-hidden text or an
+  `aria-label` (no automatic label). ⚠️
+- **Target size:** default/large ≈ 34px tall, `small` ≈ 24px. Meets a ~28px pointer
+  target but is **below the 44–48px touch-target** guideline (Uber Base uses 48px tap) —
+  caution using `small` on touch surfaces. (See F4.)
+- **Focus indicator:** **appears to be removed** (`outline: none`, no focus shadow) — a
+  WCAG 2.4.7 risk. (See F3.)
+- **Contrast:** primary navy `#07101f` + white text = high contrast ✅; verify the lighter
+  variants (`neutral-lightest`, `transparent`) text contrast in both themes.
+
+## Props / API
+
+`variant` · `size` · `loading` (bool/obj) · `disabled` · `outline` · `block` ·
+`rounded` (default true) · `shadow` (default true) · `shape`. Emits `click`.
+Full machine spec: [`../registry/button.json`](../registry/button.json).
+
+## Design tokens used
+
+`--primary-button-bg` · `--primary-button-text` · `--btn-height` · `--btn-radius` ·
+`--severity-*` (success/error) · `--neutral-*` (neutral variants) · `--primary` (focus,
+proposed).
+
+## Findings & Inconsistencies
+
+### F1 — `variant` allow-list forces info/neutral/warning to navy · High · Proposed
+
+`info`/`neutral`(77×)/`neutral-light`/`warning` render navy because
+`src/design/buttons.less` only allow-lists certain variants to escape navy via a
+high-specificity `:not(...)`. **Solution options A/B/C below.**
+
+### F2 — `danger` renders light, not solid red · Low · Open
+
+Ant 1.4 `type="danger"` styling; the codebase uses `error` (31×) for destructive actions.
+**Solution:** standardize on `error`; optionally map `danger` → `error`.
+
+### F3 — No visible focus indicator · High · Open *(a11y)* → see SF-001
+
+Focused buttons show `outline: none` and no focus shadow → keyboard users can't see focus
+(WCAG 2.4.7). **This is system-wide** — tracked as
+[SF-001](../../findings/SF-001-focus-visible.md) (fix once globally with a `:focus-visible`
+ring, don't patch per component).
+
+### F4 — Small/large target sizes · Medium · Open *(new, a11y)*
+
+`small` ≈ 24px is below the 44–48px touch target; risky on touch. **Solution:** reserve
+`small` for dense desktop UIs; ensure ≥44px hit area on touch (padding) or avoid `small`.
+
+### F5 — `large` renders the same height as `default` · Low · Open *(new)*
+
+Measured `large` ≈ 34px = `default`. **Solution:** confirm intent; if `large` should be
+bigger, add a size token; else drop `large` from the documented sizes (used only 9×).
+
+### F6 — `shadow` prop is inverted/confusing · Low · Open *(new)*
+
+`shadow` defaults to **true**, but `:shadow="true"` applies the `.button-shadow` class which
+sets `box-shadow: none !important`. So the prop named "shadow" **removes** the shadow, and
+variant hover styles re-add their own shadow. **Solution:** rename to `noShadow`/`flat`, or
+invert the logic so `shadow` means what it says (document loudly meanwhile).
+
+### F7 — `shape="circle"` isn't circular · Medium · Open *(new)*
+
+Because `rounded` defaults to **true** (`.rounded { border-radius: 4px }`) and wins over Ant's
+`.ant-btn-circle` (50%), `shape="circle"` buttons render as **4px-rounded squares**, not
+circles (measured `border-radius: 4px`). **This is the real product behaviour, not a Storybook
+artifact**, and it's not an edge case: of **198** `shape="circle"` buttons, only **24** pass
+`:rounded="false"` (true circle) — **~174 render as rounded squares**. The prop name is
+misleading for ~88% of its uses. **Solution:** if a true circle is intended, pass
+`:rounded="false"` with `shape="circle"`, or have the `circle` shape override the radius (so
+"circle" means circle).
+
+## Recommended solution — F1 (the main one)
+
+- **A (recommended):** add the variants to the allow-list + token-backed styles:
+
+  ```less
+  .ant-btn.ant-btn-primary:not(
+    …existing…, .button-neutral, .button-info
+  ) { background: var(--primary-button-bg); }
+  .ant-btn.button-neutral { background: var(--neutral-button-bg); color: var(--neutral-button-text); }
+  .ant-btn.button-info    { background: var(--secondary-blue, var(--primary-alt)); color: #fff; }
+  ```
+
+- **B:** deprecate info/neutral/neutral-light/warning; migrate ~84 usages.
+- **C:** won't-fix; rename in docs (unlikely — "neutral" reading navy is confusing).
+
+## Do / Don't
+
+### Do
+
+- Use `variant="primary"` for the single main action; `primary-alt` for secondary emphasis.
+- Use `error` (not `danger`) for destructive actions, with a confirm.
+- Use `neutral-lighter` / `neutral-lightest` / `transparent` for subtle actions.
+- Give icon-only buttons an `aria-label`; show `:loading` during async work.
+
+### Don't
+
+- Don't use `neutral`/`info` expecting gray/blue — they render navy today (F1).
+- Don't put two `primary` buttons in one action group.
+- Don't rely on `small` for touch targets (F4); don't hardcode colors.
+
+## Related components
+
+`MConfirmBtn` (confirm-on-click) · `MDropdown` (menu trigger) · `FlotoGridActions` (row
+actions). **Icon buttons** (`shape="circle"` / `.squared-button`) now documented above.
+Button-*like* relatives (own families): **`FlotoLink`** (link-styled button, 67×) and the
+**segmented control** (`MRadioGroup` `as-button`, 255× — part of the Radio family). See the
+[Family Map](../family-map.md).
+
+## Changelog
+
+- **2026-06-05** — Added to Storybook. Variants corrected to the distinctly-rendering set;
+  `primary-alt` added; `info`/`neutral`/etc. moved to a flagged "navy fallback" story (F1).
+- **2026-06-05** — Light/dark verified (primary flips white-on-navy in dark).
+- **2026-06-06** — Upgraded to the enhanced doc standard; added Anatomy, Behaviors,
+  Content, Accessibility (F3 focus ring, F4 target size, F5 large-size), Related, Changelog.
+- **2026-06-07** — Thorough button audit (whole product). Added the two **icon-button** forms
+  (`shape="circle"` 218× + `.squared-button` 365×) — story + Options section + usage. New
+  findings **F6** (inverted `shadow` prop) and **F7** (`shape="circle"` not circular). Noted
+  button-like relatives `FlotoLink` (67×) and the segmented control (`MRadioGroup as-button`,
+  255×); both filed in the Family Map.
+</content>

package/components/specs/checkbox.md

@@ -0,0 +1,162 @@
+# Checkbox (`MCheckbox`) — Spec, Findings & Solutions
+
+| | |
+| --- | --- |
+| **Tier** | Atom |
+| **Maturity** | 🟢 Stable (core) — but has an open **accessibility** finding (F3) |
+| **Source** | **Floto override** → `src/components/_base-checkbox.vue` (kit's `MCheckbox` is **excluded** in `main.js`) |
+| **Storybook** | `Atoms/Checkbox` |
+| **Registry** | [`../registry/checkbox.json`](../registry/checkbox.json) |
+| **Figma** | TODO |
+
+> Documented to the [enhanced standard](../documentation-standard.md).
+
+## Usage (product analytics)
+
+- **`<MCheckbox>` used 76× across 59 files.**
+- **`<MCheckboxGroup>` 0×** (kit group unused; multi-select built ad-hoc).
+- **`indeterminate` used ~5 sites** — select-all permission groups, hierarchy/tree
+  pickers, NOC dashboard picker.
+
+## Overview
+
+A single boolean toggle, usually with a label. The product ships the Floto override
+`_base-checkbox.vue` — a **`<template functional>`**, **fully-controlled** component (no
+internal state) that renders the Ant checkbox markup and emits `change(checked)`. Bind
+with `v-model` (or `:checked` + `@change`).
+
+## Anatomy
+
+```text
+┌─ label (.ant-checkbox-wrapper) ───────────────┐
+│  ┌──┐                                          │
+│  │✔ │  Label text (default slot)               │
+│  └──┘                                          │
+│   ▲ box (.ant-checkbox-inner, 19px) + check (::after, navy) │
+└────────────────────────────────────────────────┘
+```
+
+- **Wrapper** — `<label class="ant-checkbox-wrapper">` (clicking it toggles).
+- **Box** — `.ant-checkbox-inner`, 19×19px, radius 3px.
+- **Checkmark** — `::after`, navy (`--primary`).
+- **Hidden input** — `<input type="checkbox">` (the real control for AT).
+- **Label** — default slot (optional).
+
+## Options / States
+
+`unchecked` · `checked` · `indeterminate` (dash; partial-group) · `disabled`
+(+ disabled-checked). All **controlled** — pass the state in.
+
+**Context re-check (2026-06-07):** swept all checkbox styling (`checkbox.less`, kit override,
+`table.less`, `app.less`, `general.less`) for hidden/context variants like Radio's segmented
+set. Result: **none** — the table rules (`td.checkbox` 60px column, wrapper `float`) and
+`.checkbox-label` are pure **layout**, not new looks. The only extra is an **unused
+`.checkbox-info`** variant (info-blue checked) in the kit override — **0× usage**, and not part
+of the Floto override's API (parallel to `radio-info`). So the checkbox surface is complete.
+
+## Behaviors
+
+- **Controlled only:** no internal state / no `defaultChecked`. The parent owns `checked`
+  via `v-model`; without it the box won't change on click.
+- **Indeterminate** is a parent-over-group signal (shown as a dash), not a stored value.
+
+## Content & writing
+
+- Label states the positive choice ("Send me updates", "Enable notifications").
+- Keep labels short; avoid negatives ("Don't…") which confuse the checked meaning.
+
+## Accessibility
+
+- **Label association:** the `<input>` is nested in the `<label>` (implicit association) →
+  clicking the label toggles. ✅ Provide a label (or an `aria-label` for a bare box).
+- **Keyboard:** native input → Space toggles, Tab focuses. ✅
+- **🔴 Screen-reader state is wrong (F3):** the override never binds `:checked` to the
+  `<input>`, so the input reports `checked = false` even when visually checked. AT
+  announces the wrong state.
+- **Indeterminate not exposed (F4):** the dash is CSS-only; the input has no
+  `indeterminate` property / `aria-checked="mixed"`, so AT can't announce "mixed".
+- **Target size:** 19px box is below the ~24px+ min; the wrapper label extends the hit
+  area, but a bare box (no label) is a small touch target (F5).
+
+## Props / API (the override — not the kit's)
+
+| Prop | Type | Notes |
+| --- | --- | --- |
+| `checked` | Boolean | **v-model** (`model: checked/change`) |
+| `disabled` | Boolean | |
+| `indeterminate` | Boolean | parent-over-group |
+| `value` | Boolean/String | grouping id |
+
+Event `change(checked)`; slot = label. **Not present:** `variant`, `defaultChecked`,
+`autoFocus`. Machine spec: [`../registry/checkbox.json`](../registry/checkbox.json).
+
+## Design tokens used
+
+`--checkbox-bg` (checked fill: `#fff` light / `#2b394f` dark) ·
+`--checkbox-checked-border-color` · `--primary` (checkmark) · `--neutral-lighter` (border).
+
+## Findings & Inconsistencies
+
+### F1 — Product `MCheckbox` is a functional override; kit's is excluded · Medium · Documented
+
+Two `MCheckbox` implementations; the kit's (with `variant`/`defaultChecked`) is excluded
+in `main.js` and effectively dead. Document the **override's** API. Storybook preview
+replicates the exclusion+override (fixed).
+
+### F2 — Checked state relies on the checkmark, not a colored fill · Low · Open
+
+Checked fill is `--checkbox-bg` (white in light), not a brand fill — subtler than typical.
+Confirm intent; if stronger affordance wanted, fill with `--primary` + white tick.
+
+### F3 — `<input>.checked` not bound → screen readers announce wrong state · High · Open *(a11y)*
+
+The functional template sets `:disabled` but **not `:checked`** on the input; the visual
+checked is class-driven. So AT reads the input as unchecked even when checked.
+
+**Solution:** bind the input's checked state in `_base-checkbox.vue`:
+
+```vue
+<input type="checkbox" :checked="props.checked" :disabled="props.disabled" @change="…" />
+```
+
+(and set the `indeterminate` DOM property — see F4).
+
+### F4 — Indeterminate not exposed to AT · Medium · Open *(a11y)*
+
+`indeterminate` only adds a CSS class; the input lacks the `indeterminate` property /
+`aria-checked="mixed"`. **Solution:** set `inputEl.indeterminate = props.indeterminate`
+(DOM property via a small directive/ref, since it's not a reflected attribute).
+
+### F5 — 19px box is a small touch target · Low · Open
+
+Fine with a label (extended hit area); risky as a bare box on touch. **Solution:** ensure
+≥24px hit area (padding) for label-less checkboxes.
+
+## Do / Don't
+
+### Do
+
+- Provide a label via the default slot; bind with `v-model`.
+- Use `indeterminate` for a parent over a mixed group.
+
+### Don't
+
+- Don't use `variant`/`defaultChecked` (the override has neither).
+- Don't use a checkbox for mutually-exclusive choices (`MRadio`) or instant settings (`MSwitch`).
+
+## Related components
+
+`MRadio` (mutually-exclusive) · `MSwitch` (instant on/off) · `MCheckboxGroup` (kit, unused)
+· select-all/tree-picker patterns that use `indeterminate`.
+
+## Changelog
+
+- **2026-06-05** — Added to Storybook to the real (Floto override) API; preview fixed to
+  exclude the kit's MCheckbox and register the override (F1). Light/dark verified.
+- **2026-06-06** — Documented `indeterminate` product usage. Upgraded to enhanced standard;
+  added Anatomy, Behaviors, Content, Accessibility — surfacing **F3** (SR state not bound,
+  High) and **F4** (indeterminate not exposed) with fixes; Related; Changelog.
+- **2026-06-07** — Context-variant re-check (post-Radio): swept all checkbox LESS for hidden
+  variants → none (table/label rules are layout only); noted the unused `.checkbox-info`
+  variant (0×). Surface confirmed complete.
+</content>

package/components/specs/data-viz-tooltips.md

@@ -0,0 +1,93 @@
+# Data-Viz Tooltips — Spec, Findings & Solutions
+
+| | |
+| --- | --- |
+| **Tier** | Molecule (reference patterns) |
+| **Maturity** | 🟢 Stable |
+| **Source** | `src/components/chart/options/tooltip-builder.js` (`TooltipBuilder`) + `.hc-tooltip-bg` / `.highcharts-tooltip-container-class` (Highcharts) · `heatmap-tooltip.vue` + sparkline (Vue widgets) · graph canvases (vis-network / d3, `--topology-graph-tooltip-bg`) · d3 flame graph. |
+| **Storybook** | Molecules/Data-Viz Tooltips |
+| **Registry** | [`registry/data-viz-tooltips.json`](../registry/data-viz-tooltips.json) |
+| **Family** | Tooltip family (see also [`tooltip.md`](./tooltip.md)) |
+
+## Why this is a family
+
+The product's **chart & widget hover tooltips** are a **distinct family from `MTooltip`** — they are
+**not** DS Vue components. They are owned by the **chart layer**: most are rendered by Highcharts via
+the shared **`TooltipBuilder`**, the graph tooltips by canvas libraries (vis-network / d3), and a few by
+widget Vue components (heatmap, sparkline). We catalogue them as **reference reproductions** (built from
+real tokens — `--chart-tooltip-background`, `--severity-*`, `--topology-graph-tooltip-bg`) so a designer
+or AI can map **place → tooltip** without us re-implementing chart internals.
+
+## Render mechanisms (the 4 surfaces)
+
+| Mechanism | Surface token / class | Tooltips |
+| --- | --- | --- |
+| **Highcharts `TooltipBuilder`** | `--chart-tooltip-background` + `blur(15px)` (`hc-tooltip-bg`) | series/bar, donut/pie, bubble, map/geo, radar, timeline/x-range, gauge, sankey, treemap, scatter, anomaly/forecast band, RUM waterfall, geo marker, log-pattern, sparkline |
+| **Vue widget component** | component-scoped | heatmap (`heatmap-tooltip.vue`), alert/availability segment, availability bar |
+| **Graph canvas** (vis-network / d3) | `--topology-graph-tooltip-bg` (fixed-dark both themes) | live-graph node/edge, APM service-map node, SDN tunnel edge, Cisco ACI endpoint/link, network interface edge, netroute node/edge |
+| **d3 flame graph** | `hc-tooltip-bg` surface | flame-graph span (APM / RUM traces) |
+
+## Which tooltip → where (lookup)
+
+| Tooltip | Where used | Renderer |
+| --- | --- | --- |
+| Bar / series | severity/metric stacked columns & line charts | Highcharts `TooltipBuilder` |
+| Donut / pie | status/distribution donuts | Highcharts |
+| Bubble (packed-bubble) | grouped-count bubble widgets | Highcharts |
+| Map / geo | geo-distribution maps | Highcharts |
+| Radar | multi-axis comparison | Highcharts |
+| Timeline / x-range | SLO / availability timelines | Highcharts |
+| Gauge / circular-progress | KPI gauges | Highcharts |
+| Sankey / flow | flow / traffic sankey | Highcharts |
+| Treemap | capacity / hierarchy treemaps | Highcharts |
+| Scatter (x / y) | correlation scatter | Highcharts |
+| Anomaly / forecast band | anomaly & forecast charts (actual vs expected range) | Highcharts |
+| RUM resource waterfall | RUM page resource timing | Highcharts |
+| Geo map marker (RUM apdex) | RUM geo apdex map | Highcharts |
+| Log pattern distribution | log pattern value distribution | Highcharts |
+| Sparkline | inline mini-trends (grid cells, KPIs) | Highcharts (mini) |
+| Heatmap | heatmap widgets | `heatmap-tooltip.vue` |
+| Alert / availability segment | segmented availability cells | Vue (segmented-cell) |
+| Availability bar segment | Up/Down % bars | Vue |
+| Live graph — node | topology / netroute maps | graph canvas |
+| Live graph — edge | link / interface edges | graph canvas |
+| APM service-map node | APM service map | graph canvas |
+| SDN tunnel edge | SD-WAN tunnels | graph canvas |
+| Cisco ACI endpoint | ACI endpoint edges | graph canvas |
+| Cisco ACI fabric link | ACI fabric links | graph canvas |
+| Network interface edge | interface topology | graph canvas |
+| Netroute hop node | netroute path hops | graph canvas |
+| Netroute edge (transit) | netroute transit edges | graph canvas |
+| Flame graph span | APM / RUM trace flame graphs | d3 flame graph |
+
+## Accessibility
+
+- These are **hover-only, canvas/SVG-rendered** surfaces — they are **not keyboard-reachable** and not
+  exposed to assistive tech (a known limitation of the chart libraries). Where the underlying data
+  matters for a11y, it must also be available in an adjacent **table / legend** (verify per widget).
+
+## Design tokens used
+
+`--chart-tooltip-background` · `--topology-graph-tooltip-bg` · `--tooltip-text-color` ·
+`--severity-{down,unreachable,critical,major,warning,up,…}` · `--page-text-color` · `--border-color`.
+
+## Findings & Inconsistencies
+
+| # | Severity | Status | Finding |
+| --- | --- | --- | --- |
+| F1 | Low | Noted | Owned by the chart layer (Highcharts/vis-network/d3), **not** DS components → catalogued as **reference reproductions** (real tokens), not live renders. |
+| F2 | Low (a11y) | Open | Hover-only, canvas-rendered → not keyboard-reachable / not in the a11y tree; ensure the data also exists in a table/legend. |
+
+## Related components
+
+**Tooltip** (`MTooltip` — the UI/text tooltip family) · **Table** (sparkline cells) · the chart/widget
+layer (`src/components/chart`, `src/components/widgets`).
+
+## Changelog
+
+- **2026-06-16** — Added the **registry + spec** (this page) and a **which-tooltip→where** lookup table,
+  so the family matches the "four pages move together" rule (it was previously a **story only**). No
+  story changes — the ~28 reference reproductions already cover every mechanism (Highcharts series,
+  donut, bubble, map, radar, timeline, gauge, sankey, treemap, scatter, anomaly band, waterfall, geo
+  marker, log-pattern, sparkline; heatmap & segment Vue widgets; 9 graph-canvas node/edge tooltips; the
+  d3 flame graph). Findings F1 (reproduction), F2 (a11y).

package/components/specs/date-time-pickers.md

@@ -0,0 +1,161 @@
+# Date & Time Pickers — Spec, Findings & Solutions
+
+| | |
+| --- | --- |
+| **Tier** | Molecule |
+| **Maturity** | 🟢 Stable |
+| **Source** | `src/components/widgets/time-range-picker.vue` (`TimeRangePicker`) · `ui/components/Datepicker/Datepicker.vue` (`MDatePicker`) · `ui/components/Datepicker/Timepicker.vue` (`MTimePicker`) · `src/components/common/date-time-popover.vue` (`DateTimePopover`). |
+| **Storybook** | Molecules/Date & Time Pickers |
+| **Registry** | [`registry/date-time-pickers.json`](../registry/date-time-pickers.json) |
+| **Family** | [Date & Time Pickers](../family-map.md) |
+
+## Usage analytics
+
+- **`TimeRangePicker`** — **42× / 35 files**. The dominant control; the observability time-range
+  selector. Real variants: **`hide-custom-time-range`** (24×, presets-only), `allow-clear` (7×),
+  `max-selectable-range-days` (2×), plus `bordered`, `pill-style`, `hide-selected-time`, `only-label`.
+- **`MDatePicker`** — **10× / 8 files**. **All 10 usages pass `:show-time`** → it is the **date-time**
+  field, not date-only. Often with `:min-date` (7×), `:allow-clear` (9×), `:disabled` (5×).
+- **`TimeRangeSlider`** — **2×** (dashboard view + alert correlation drawer); a timeline scrubber
+  variant of the time-range control (square handles, navy track, time-mark ticks).
+- **Standalone time pickers — `0×`.** Both the kit **`MTimePicker`** and the custom **`TimePicker`**
+  (`time-picker.vue`, a `FlotoDropdownPicker` of time options) are **0× as standalone tags**. Time is
+  entered via MDatePicker `show-time` or inside the TimeRangePicker custom view (which uses the custom
+  dropdown-based `TimePicker`, not an Ant spinner).
+- **`DateTimePopover`** — **1×** (SLO correction profile); a custom-range-only popover.
+- **Checked & scoped out:** **Scheduler / Recurrence** (`schedule-input/`, 17 files — Once/Daily/
+  Weekly/Monthly builder) is a **separate family** (future entry), not a picker; `date-remark-pairs`
+  (holiday list) is a composite; kit `DateRangePicker`/`NotifyTimePicker` are 0×; **no** week / month /
+  quarter / calendar pickers exist. `only-label` and `daily-rolling` props are **declared but 0×**.
+
+## Overview
+
+The family covers three jobs: **pick a time window** (relative or absolute) for charts/dashboards/
+logs → **`TimeRangePicker`**; **pick a date(+time) value** in a form → **`MDatePicker`** (always with
+`show-time`); **pick a time of day** → **`MTimePicker`**. `TimeRangePicker` is the hero and is unique
+to this product; the others wrap Ant `a-date-picker` / `a-time-picker`.
+
+## Anatomy
+
+### TimeRangePicker — anatomy
+
+- **Trigger (closed):** a `--timerange-background-color` **shortcut pill** (`24h`, `1h`, or a computed
+  duration like `6d 23h`) + a separator + the **range label** (`Last 24 Hours`). Empty → a
+  **calendar-alt** icon + "Select Time". `:bordered` adds a frame; `:allow-clear` a **times-circle** ×.
+- **Panel — presets:** the 15 relative options (Last 5/15/30 Mins · Last 1/6/12/24/48 Hours · Today ·
+  Last Day · Last/This Week · Last/This Month), each with its shortcut pill; active row uses
+  `--dropdown-hover-background`. **Custom** sits at the bottom (hidden by `hide-custom-time-range`).
+- **Panel — custom:** an `a-range-picker` calendar (start/end) with two `MTimePicker` (From/To,
+  seconds) and **Apply / Cancel** buttons; validates end > start.
+
+### MDatePicker / MTimePicker
+
+- `MDatePicker` = `a-date-picker` + a **calendar** suffix icon, `show-time` (12-hour `hh:mm A`),
+  `dateRender` slot for custom cells, `disabled-date` / `min-date` constraints.
+- `MTimePicker` = `a-time-picker`, **12-hour**, **clock** suffix icon, `allow-clear` default true.
+
+## Options (props)
+
+### TimeRangePicker
+
+| Prop | Default | Notes |
+| --- | --- | --- |
+| `value` | — | v-model; `{ selectedKey, startDate, endDate, startTime, endTime, dailyRollingData }` |
+| `hideCustomTimeRange` | `false` | **24×** — drop "Custom" (presets-only) |
+| `maxSelectableRangeDays` | `93` | disables dates beyond the span (365 for report export) |
+| `allowClear` | `false` | times-circle × → emits `change=undefined` |
+| `bordered` / `pillStyle` / `hideSelectedTime` / `onlyLabel` | — | trigger display variants |
+| `excludedOptions` | — | array of preset keys to drop |
+| `disabled` / `overlayClassName` / `getPopupContainer` | — | standard |
+
+### MDatePicker
+
+| Prop | Default | Notes |
+| --- | --- | --- |
+| `value` | — | moment/string/number; v-model |
+| `showTime` | `{ use12Hours:true, format:'hh:mm A' }` | **always passed in real use** |
+| `allowClear` | — | 9× |
+| `minDate` | — | 7×; earliest selectable |
+| `disabledDate` | — | function to grey out days |
+| `format` / `placeholder` | — | display format / `Select...` |
+
+### MTimePicker
+
+| Prop | Default | Notes |
+| --- | --- | --- |
+| `value` | — | moment/string/number |
+| `format` | `hh:mm A` | 12-hour |
+| `use12Hours` | `true` | |
+| `allowClear` | `true` | |
+
+## Behaviors
+
+- **TimeRangePicker emit:** relative → `{ selectedKey:'-24h', startDate, endDate, startTime, endTime }`;
+  custom → `{ selectedKey:'custom', … }`; cleared → `undefined`. Custom blocks Apply if end ≤ start.
+- **Start-time rounding:** relative ranges round the start to the nearest 5-minute boundary.
+- **MTimePicker emit:** `change(formattedString, moment)`.
+
+## Accessibility
+
+- **Provided by Ant:** `a-date-picker` / `a-time-picker` give a focusable text input + a
+  keyboard-navigable calendar/time panel; Escape closes.
+- **Verify:** focus-visible ring (**SF-001**) on the inputs and on the TimeRangePicker **preset rows**
+  (clickable `<a>`/divs — ensure they're keyboard-reachable and labelled).
+
+## Design tokens used
+
+`--timerange-background-color` · `--timerange-text-color` (pill) · `--dropdown-background` ·
+`--dropdown-hover-background` · `--left-menu-text-color-hover` (active preset) · `--border-color` ·
+`--primary` · `--calendar-selected-day-background-color` · `--tag-bg` (calendar range) ·
+`--secondary-red` (error) · `--neutral-light` / `--neutral-lightest` / `--page-text-color`.
+
+## Findings & Inconsistencies
+
+| # | Severity | Status | Finding |
+| --- | --- | --- | --- |
+| F1 | Low | Noted | `TimeRangePicker` depends on the user-preference store + `datetime` filter + moment → **reference reproduction** in Storybook (live render not feasible, like the Kendo grid). |
+| F2 | Low (a11y) | Open | Catalog-wide focus-ring removal (**SF-001**) may affect picker inputs / preset rows. |
+| N1 | Info | — | Passing an **empty string** to MTimePicker/MDatePicker `value` renders **"Invalid date"** (it parses `''` via moment) — pass `null`/`undefined` or a moment. |
+
+## Recommended solutions
+
+- **F1:** keep the reproduction; if a headless TimeRangePicker is ever extracted (Vue 3), it could
+  render live with an injected format/timezone instead of the store.
+- **F2:** adopt the shared `:focus-visible` ring (SF-001).
+- **N1:** initialize empty values to `null`, never `''`.
+
+## Do / Don't
+
+- **Do** use TimeRangePicker for chart/dashboard/log windows; `hide-custom-time-range` for
+  presets-only; `MDatePicker` **with** `show-time` for date-time form fields; constrain with
+  `max-selectable-range-days` / `min-date`.
+- **Don't** hand-roll a relative-range dropdown; don't use a bare date picker for chart windows;
+  don't pass `''` as a value (Invalid date); don't assume inline/card calendar variants (popup only).
+
+## Related components
+
+`FlotoDropdownPicker` (select) · `FlotoFormItem` (wraps date/time fields in forms) · `MPopover`
+(DateTimePopover is built on it).
+
+## Changelog
+
+- **2026-06-15 (sweep recheck — added the missed variant + corrections)** — Owner: the UI doesn't
+  match the product and a variant was missed. Full census of every `<MDatePicker>` / `<MTimePicker>` /
+  `<TimeRangePicker>` tag found: **(1)** added the **`TimeRangeSlider`** — a draggable **timeline
+  scrubber** (dashboard + alert correlation drawer, 2×) — as its own story; **(2)** corrected the
+  time-picker story: **no standalone time picker is used** (kit `MTimePicker` *and* custom `TimePicker`
+  are 0×; time comes via `show-time` or the range custom view, which uses a **dropdown-based**
+  `TimePicker`, not an Ant spinner); **(3)** `excluded-options` is a real variant (**7×**) and
+  `hide-icon` (3×), while `only-label`/`daily-rolling` are **0×** (overstated before); **(4)**
+  `MDatePicker` has **no** size/format/mode in use; **(5)** flagged **Scheduler/Recurrence**
+  (`schedule-input/`, 17 files) as a **separate family**. ⚠️ The TimeRangePicker stories are
+  reproductions — pixel-matching the product needs a reference screenshot (requested).
+- **2026-06-15** — Added (decision-grade) — the **Date & Time Pickers family** in one entry.
+  Established **`TimeRangePicker` (42×)** as the hero (the others are 10×/rare), the **presets list**
+  (15 options + Custom), the **emit shape**, and the **`hide-custom-time-range`** presets-only variant
+  (24×). Documented that **`MDatePicker` is always a date-*time* field** (all 10 usages pass
+  `show-time`). Stories: real `MDatePicker`/`MTimePicker`; **reference reproductions** of the
+  TimeRangePicker trigger, presets panel, and custom range (it depends on the store/moment). Verified
+  by render+screenshot (every shot opened): MDatePicker calendar themed correctly; caught + fixed
+  MTimePicker showing **"Invalid date"** from an empty-string value (→ `null`) and an `<a>` underline
+  on preset rows. Findings F1 (reproduction), F2 (SF-001), N1 (empty-string → Invalid date).