@mtdt/observeops-ds-spec 0.1.0

package/components/registry/dropdown-picker.json

@@ -0,0 +1,388 @@
+{
+  "name": "dropdown-picker",
+  "component": "FlotoDropdownPicker",
+  "display": "DropdownPicker",
+  "tier": "organism",
+  "source": "app",
+  "sourceFile": "src/components/_base-dropdown-picker.vue",
+  "status": "core",
+  "maturity": "stable-but-flawed",
+  "summary": "The product's custom select: popover-anchored, virtualized, searchable, single/multi-select, keyboard nav, optional inline-add. Not a native/Ant select.",
+  "variants": [
+    {
+      "name": "single",
+      "what": "pick one (default)",
+      "usage": ""
+    },
+    {
+      "name": "multiple",
+      "what": "checkboxes + Select All",
+      "usage": ""
+    },
+    {
+      "name": "not-searchable",
+      "what": "no search box",
+      "usage": "119×"
+    },
+    {
+      "name": "allow-clear",
+      "what": "× clear on hover",
+      "usage": "218×"
+    },
+    {
+      "name": "text-only",
+      "what": "plain-text trigger",
+      "usage": "15×"
+    },
+    {
+      "name": "read-only-pills",
+      "what": "multi+disabled → pills",
+      "usage": ""
+    },
+    {
+      "name": "inline-add",
+      "what": "add new option",
+      "usage": ""
+    },
+    {
+      "name": "two-pane",
+      "what": "menu + hovered description",
+      "usage": ""
+    },
+    {
+      "name": "use-popover",
+      "what": "MPopover trigger",
+      "usage": "26×"
+    }
+  ],
+  "sizes": [],
+  "states": [
+    {
+      "name": "closed",
+      "what": "trigger only"
+    },
+    {
+      "name": "open",
+      "what": "menu + search"
+    },
+    {
+      "name": "disabled",
+      "what": "read-only pills"
+    },
+    {
+      "name": "empty",
+      "what": "placeholder"
+    },
+    {
+      "name": "selected",
+      "what": "value(s) in trigger"
+    }
+  ],
+  "family": "Form Controls",
+  "model": {
+    "prop": "value",
+    "event": "change"
+  },
+  "optionShape": {
+    "label": "text || name || label",
+    "value": "key || id || value",
+    "canonical": "{ key, text }",
+    "extra": [
+      "id",
+      "disable",
+      "status"
+    ]
+  },
+  "props": {
+    "value": {
+      "type": [
+        "number",
+        "string",
+        "object",
+        "array",
+        "boolean"
+      ],
+      "note": "v-model; key (single) or array of keys (multiple)"
+    },
+    "options": {
+      "type": "array",
+      "note": "passed via $attrs; { key, text } objects"
+    },
+    "externalOptions": {
+      "type": "array",
+      "default": []
+    },
+    "disabledOptions": {
+      "type": "array",
+      "default": []
+    },
+    "multiple": {
+      "type": "boolean",
+      "default": false
+    },
+    "allowSelectAll": {
+      "type": "boolean",
+      "default": false
+    },
+    "allowClear": {
+      "type": "boolean",
+      "default": false,
+      "note": "218x"
+    },
+    "searchable": {
+      "type": "boolean",
+      "default": true,
+      "note": "defaults TRUE (F3); :searchable=false used 119x"
+    },
+    "asInput": {
+      "type": "boolean",
+      "default": true,
+      "note": "defaults TRUE (F3); trigger looks like an input"
+    },
+    "wrap": {
+      "type": "boolean",
+      "default": true,
+      "note": "defaults TRUE (F3)"
+    },
+    "textOnly": {
+      "type": "boolean",
+      "default": false
+    },
+    "placeholder": {
+      "type": "string",
+      "default": "Select"
+    },
+    "usePopover": {
+      "type": "boolean",
+      "default": false,
+      "note": "false=MPopper (v-tooltip), true=MPopover (kit); 26x"
+    },
+    "placement": {
+      "type": "string",
+      "default": "bottom-start"
+    },
+    "maxValues": {
+      "type": "number",
+      "default": 0,
+      "note": "the REAL selection cap (sliced in handleChange)"
+    },
+    "maxAllowedSelection": {
+      "type": "number",
+      "default": 0,
+      "note": "DEAD — declared but never used (F2); use maxValues"
+    },
+    "itemSize": {
+      "type": "number",
+      "default": 32
+    },
+    "itemsToShow": {
+      "type": "number",
+      "default": 10,
+      "note": "with hideAllDropdownOptions, caps rendered count"
+    },
+    "hideAllDropdownOptions": {
+      "type": "boolean",
+      "default": false
+    },
+    "canUserAddOptions": {
+      "type": "boolean",
+      "default": false,
+      "note": "inline add; emits add"
+    },
+    "addLabel": {
+      "type": "string",
+      "default": ""
+    },
+    "useAfterMenuDescription": {
+      "type": "boolean",
+      "default": false,
+      "note": "two-pane: menu + hovered description"
+    },
+    "showHelp": {
+      "type": "boolean",
+      "default": false
+    },
+    "defaultOpen": {
+      "type": "boolean",
+      "default": false,
+      "note": "opens on mount"
+    },
+    "avoidKeyboardNavigation": {
+      "type": "boolean",
+      "default": false
+    },
+    "overlayClassName": {
+      "type": "string",
+      "default": "picker-overlay"
+    },
+    "overlayStyle": {
+      "type": "object",
+      "default": {}
+    },
+    "minWidth": {
+      "type": "number",
+      "default": 0
+    },
+    "removeClearBtn": {
+      "type": "boolean",
+      "default": false
+    },
+    "fixedPosition": {
+      "type": "boolean",
+      "default": false
+    },
+    "disabled": {
+      "type": "boolean",
+      "default": false
+    }
+  },
+  "events": [
+    "change",
+    "show",
+    "hide",
+    "search",
+    "add",
+    "active-item-index-change"
+  ],
+  "slots": [
+    "default (menu)",
+    "menu-item",
+    "before-menu-text",
+    "after-menu-text",
+    "after-menu",
+    "helpbox",
+    "hovered-menu-description",
+    "trigger"
+  ],
+  "triggers": {
+    "SingleTrigger": "single mode; asInput=MInput readonly + chevron/clear; textOnly=plain text; else a tag-style chip",
+    "MultipleTrigger": "multi mode; enabled=MInput 'First (+N)'; disabled=SelectedItemPills teal pills"
+  },
+  "dependencies": [
+    "MPopper (v-tooltip) or MPopover",
+    "RecycleScroller (vue-virtual-scroller)",
+    "arrayWorker (web worker search)",
+    "MInput",
+    "MMenu/MMenuItem",
+    "MCheckbox",
+    "MDivider",
+    "MButton",
+    "MIcon"
+  ],
+  "anatomy": [
+    "trigger (input/text/chip/pills)",
+    "search box (+ optional add)",
+    "Select All header (multi)",
+    "virtualized option rows",
+    "Clear footer (multi)",
+    "no-data illustration"
+  ],
+  "tokensUsed": [
+    "--dropdown-hover-background",
+    "--left-menu-text-color-hover",
+    "--main-tags-bg-color",
+    "--main-tags-text-color"
+  ],
+  "accessibility": {
+    "keyboardOpen": "ArrowUp/Down/Enter/Escape work only once open (window keydown)",
+    "gaps": "F1 — no combobox ARIA, not keyboard-openable (click-only), no focus ring (SF-001)"
+  },
+  "do": [
+    "Use as the standard select; options as { key, text }; v-model the key(s).",
+    "multiple + allow-select-all for multi; :searchable=false for short lists; trigger slot for custom triggers."
+  ],
+  "dont": [
+    "Don't rely on maxAllowedSelection to cap (F2 — use maxValues).",
+    "Don't assume keyboard/AT users can operate it today (F1). Don't forget searchable/asInput/wrap default true (F3)."
+  ],
+  "whenToUse": "The default select control anywhere in the product (single or multi).",
+  "decisionFlow": [
+    "Free-form typed tags? -> LooseTags, not the picker.",
+    "2-3 always-visible exclusive options? -> MRadio (segmented).",
+    "Simple on/off? -> MSwitch.",
+    "Choosing one/many from a list? -> DropdownPicker.",
+    "Choosing several? -> multiple (+ allow-select-all).",
+    "Short fixed list? -> :searchable=false.",
+    "Clearable/none valid? -> allow-clear.",
+    "User can add missing options? -> can-user-add-options + add-label.",
+    "Non-default trigger (button/chips)? -> trigger slot."
+  ],
+  "usageRules": {
+    "single(default)": {
+      "useWhen": "pick one value from a list (most common)",
+      "example": "monitor type, template, owner"
+    },
+    "multiple": {
+      "useWhen": "pick several values (checkboxes + Select-All + Clear); add allow-select-all",
+      "example": "filter by several tags/groups"
+    },
+    "searchable=false": {
+      "useWhen": "short fixed list where search is noise (119x)"
+    },
+    "allow-clear": {
+      "useWhen": "an empty/none state is valid and resettable (218x)"
+    },
+    "as-input": {
+      "useWhen": "trigger should look like a form field (default true); false for chip/inline trigger"
+    },
+    "can-user-add-options": {
+      "useWhen": "user may need a value not in the list (inline add -> emits add)"
+    },
+    "trigger-slot": {
+      "useWhen": "default input trigger doesn't fit (button, avatar, pills)"
+    },
+    "cap-selection": {
+      "useWhen": "limit count -> use maxValues, NOT maxAllowedSelection (dead, F2)"
+    }
+  },
+  "insteadOf": [
+    "native select",
+    "a-select",
+    "MSelect (for non-tag selects)"
+  ],
+  "usage": {
+    "total": 510,
+    "files": 241,
+    "allowClear": 218,
+    "searchableFalse": 119,
+    "multiple": 66,
+    "textOnly": 15,
+    "usePopover": 26
+  },
+  "knownIssues": [
+    "F1 (high, a11y) -> promoted to SF-003: not an accessible combobox — no role/aria-expanded/activedescendant, click-only open (not keyboard-openable), no focus ring (SF-001). Highest-impact a11y gap (510x). See findings/SF-003.",
+    "F2 (medium): maxAllowedSelection declared but never used; real cap is maxValues. Consumers (LooseTags asDropdown) pass it expecting a limit.",
+    "F3 (low): searchable/asInput/wrap default to true (against vue/no-boolean-default).",
+    "F4 (low): loose option schema (text||name||label, key||id||value). Document canonical { key, text }.",
+    "SB caveat (tooling): search needs the arrayWorker web worker (no-op in Storybook); no-data SVG needs an svg-component loader (absent in SB)."
+  ],
+  "related": [
+    "SingleTrigger",
+    "MultipleTrigger",
+    "SelectedItemPills",
+    "LooseTags",
+    "MSelect",
+    "MPopover",
+    "MPopper",
+    "MMenu",
+    "MCheckbox"
+  ],
+  "changelog": [
+    "2026-06-07: added — full deep-dive of _base-dropdown-picker + dropdown-trigger family (510x/241 files); rendered real default mode in SB via v-tooltip/MPopper/RecycleScroller registration; F1-F4 + SB caveats."
+  ],
+  "storybook": "Organisms/DropdownPicker",
+  "figma": {
+    "status": "todo",
+    "component": "DropdownPicker"
+  },
+  "a11y": {
+    "summary": "Once open: ↑/↓ move the active row, Enter selects, Esc closes.",
+    "issues": [
+      "Opens on click only — no Enter/Space/↓ on the trigger.",
+      "No combobox/listbox/option semantics.",
+      "No visible focus ring (SF-001)."
+    ],
+    "doc": "Organisms/DropdownPicker/Accessibility",
+    "$note": "Catalogue-wide gap SF-001 = no visible :focus-visible ring; tracked in findings/."
+  }
+}

package/components/registry/filters.json

@@ -0,0 +1,155 @@
+{
+  "name": "filters",
+  "display": "Filters",
+  "tier": "molecule",
+  "family": "Filters",
+  "status": "stable",
+  "summary": "The product's filtering components, grouped by ARCHETYPE (not by the screen they sit in). Four distinct kinds: the Expression builder (nested AND/OR query builder), the Filter bar (inline chips), Quick filters (preset menu), and the Filter row (multi-selects + Reset/Apply). These are molecules; the Toolbars (organisms) compose them.",
+  "variants": [
+    {
+      "name": "expression-builder",
+      "what": "nested AND/OR popover",
+      "usage": "32×"
+    },
+    {
+      "name": "filter-bar",
+      "what": "inline chip bar + Match All/Any",
+      "usage": "50×"
+    },
+    {
+      "name": "quick-filters",
+      "what": "preset one-click menu",
+      "usage": ""
+    },
+    {
+      "name": "filter-row",
+      "what": "multi-selects + Reset/Apply",
+      "usage": ""
+    },
+    {
+      "name": "vertical-filter",
+      "what": "faceted left-panel (checkbox+count)",
+      "usage": "APM/RUM/NCM"
+    }
+  ],
+  "sizes": [],
+  "states": [
+    {
+      "name": "default",
+      "what": "resting"
+    },
+    {
+      "name": "applied",
+      "what": "active conditions"
+    },
+    {
+      "name": "open",
+      "what": "popover/panel visible"
+    },
+    {
+      "name": "disabled",
+      "what": "not interactive"
+    }
+  ],
+  "props": "Filters is MULTI-ARCHETYPE — there is no single component prop list. Per-archetype prop/event contracts are in `apis` (e.g. apis.FilterBar = value/fieldSchema/defaultChips + change) and the `archetypes` block.",
+  "renders": "REFERENCE REPRODUCTIONS — the live filters are store-bound (FilterCondition is 500+ lines). The Filter bar reproduction is fully interactive.",
+  "archetypes": {
+    "ExpressionBuilder": {
+      "source": "src/components/filters/ — FiltersContainer (filters-container.vue) + Filters (filters.vue) + FilterGroup + FilterCondition (516 ln) + FilterTrigger",
+      "usage": "FiltersContainer 32× — the most-used filter",
+      "presentation": "an MPopover (placement bottomLeft, has-arrow) opened from a FilterTrigger input (renders the applied query, or a 'Search' placeholder) — NOT an inline panel. Popover has a close x, Pre Filters / Post Filters tabs (MTab), the builder, and a Reset / Clear / Apply footer. Apply emits the query (trigger shows it) and closes; Clear empties; Reset reverts.",
+      "what": "a nested AND/OR query builder: 'Group(s) matching All/Any' -> one or more groups (3 pre / 1 post), each 'Include/Exclude -> Group matching All/Any -> Criteria' -> conditions (counter · operator · value; Between -> From/To). Add Condition (max 3) / Add New Group.",
+      "props": "MultipleFormItems drive the group/condition lists; FilterCondition is type-aware (operator + value picker by field type)",
+      "storybook": "fully functional reproduction (open/close, tabs, add/remove conditions+groups, Include/Exclude + All/Any, Between, Apply renders the query into the trigger)"
+    },
+    "FilterBar": {
+      "source": "src/components/filter-bar/_base-filter-bar.vue + filter-chip.vue",
+      "usage": "~50×",
+      "what": "an inline CHIP bar — field·operator·value chips (default-chips have no ×) + '+ Filter' + a Match All/Any toggle + Clear All. Chips scroll horizontally; the segment picker floats position:fixed.",
+      "note": "moved here from the former Grid Toolbar entry"
+    },
+    "QuickFilters": {
+      "source": "src/components/filter-bar/filter-quick-menu.vue",
+      "what": "a thumbs-up button opening a panel of PRESET one-click filters ({ key, label, condition }); picking one applies that condition",
+      "note": "moved here from the former Grid Toolbar entry"
+    },
+    "FilterRow": {
+      "source": "pattern (e.g. metric-collection-filters.vue)",
+      "what": "the simplest filter — a few multi-selects (Groups/Severity/Tags) + Reset/Apply + close ×, as a slide-in over a list",
+      "note": "re-homed from the retired Monitoring Config (Collection Filters)"
+    },
+    "VerticalFilter": {
+      "source": "components/filters/vertical-filter/filters.vue (shared: APM Explorer, APM Error Tracker, RUM Sessions) + ncm/components/explorer-grid-virtical-filter.vue (richer NCM variant)",
+      "usage": "APM/RUM/NCM",
+      "what": "the FACETED left-panel sidebar — a search atop collapsible groups (MCollapse), each row a checkbox + optional status/type icon + label + count; checking rows filters the grid",
+      "note": "looks like a Navigation side menu but it FILTERS (not navigates) -> lives in Filters; cross-referenced from Navigation -> Side menu. Surfaced by the 2026-06-16 left-panel sweep."
+    }
+  },
+  "decisionFlow": [
+    "Complex AND/OR conditions across multiple groups? -> Expression builder (FiltersContainer, 32×).",
+    "A compact inline chip bar over a grid? -> Filter bar.",
+    "One-click saved/preset filters? -> Quick filters.",
+    "A few simple multi-selects + Apply/Reset? -> Filter row.",
+    "Plain text search of a list? -> the Input 'search' type (181×), not a Filter."
+  ],
+  "do": [
+    "Use the Expression builder for real query logic (groups + AND/OR + typed operators).",
+    "Use the Filter bar for a compact chip filter over a grid.",
+    "Use Quick filters for common one-click presets.",
+    "Use a Filter row for a small fixed set of facets."
+  ],
+  "dont": [
+    "Don't hand-roll a condition builder — use FiltersContainer.",
+    "Don't put plain search here — that's the Input search type.",
+    "Don't duplicate a filter across screens — it's one molecule; compose it in a Toolbar."
+  ],
+  "knownIssues": {
+    "F1": {
+      "severity": "Low",
+      "issue": "Store-bound / FilterCondition is 500+ lines, so these render as reproductions (the Filter bar reproduction is fully interactive)."
+    }
+  },
+  "tokensUsed": [
+    "--code-tag-background-color",
+    "--border-color",
+    "--page-background-color",
+    "--page-text-color",
+    "--neutral-light",
+    "--neutral-button-text",
+    "--primary",
+    "--dropdown-background"
+  ],
+  "storybook": "Molecules/Filters",
+  "related": [
+    "dropdown-picker",
+    "input",
+    "tag",
+    "table"
+  ],
+  "figma": {
+    "status": "todo"
+  },
+  "apis": {
+    "FilterBar": {
+      "source": "src/components/filter-bar/_base-filter-bar.vue (FlotoFilterBar)",
+      "props": {
+        "value": "Object (model, event 'change')",
+        "fieldSchema": "Array (required) — the filterable fields + their operator/value types",
+        "defaultChips": "Array — leading non-removable chips declared by the consuming module (e.g. Groups/Types/Severity)"
+      },
+      "events": {
+        "change": "(next) emitted as chips change"
+      },
+      "note": "PITFALL: the leading default-chips come from the MODULE via defaultChips, not the base bar — read a real consumer to reproduce faithfully."
+    }
+  },
+  "a11y": {
+    "summary": "Field/operator/value selects (FlotoDropdownPicker) + real buttons (+Filter, Add, Reset/Apply); convey the nested Group→Condition structure to AT.",
+    "issues": [
+      "SF-001 focus ring on chips/selects/buttons.",
+      "Icon-only triggers (thumbs-up, chip ×, row ×) need accessible names."
+    ],
+    "doc": "Molecules/Filters/Accessibility",
+    "$note": "Catalogue-wide gap SF-001 = no visible :focus-visible ring; tracked in findings/."
+  }
+}