@mtdt/observeops-ds-spec 0.1.0

package/components/registry/severity.json

@@ -0,0 +1,179 @@
+{
+  "name": "severity",
+  "component": "Severity",
+  "display": "Severity",
+  "tier": "atom",
+  "family": "Tag",
+  "source": "src/components/severity.vue (Severity) + severity-stripe.vue + severity-picker.vue + dashboard/severity-count-box.vue + severity-db.vue",
+  "status": "core",
+  "summary": "The severity INDICATOR — a coloured dot (+ optional label + tooltip) for a severity LEVEL (down / critical / major / warning / clear / up / maintenance / unreachable / unknown / …). Distinct from MStatusTag, which maps status STRINGS to tag-* pills. Used 80×. Renders --severity-<level>; can take `severity` directly or resolve it live from a monitor (objectId / instance / counter) via DB workers.",
+  "variants": [
+    {
+      "name": "dot",
+      "what": "2px --severity-<level> border + light --severity-<level>-dot-box centre (down = solid, 0px border)",
+      "usage": "default"
+    },
+    {
+      "name": "dot+label",
+      "what": "dot + Capitalize(level) text (displayText=true)",
+      "usage": ""
+    },
+    {
+      "name": "solid-chip",
+      "what": "filled pill: background --severity-<level> + white text (the plain mode)",
+      "usage": ""
+    },
+    {
+      "name": "text",
+      "what": "coloured numeric/value text in --severity-<level>, JetBrains Mono (.text mode)",
+      "usage": ""
+    },
+    {
+      "name": "bg-fill",
+      "what": "row/cell: --severity-<level>-lighter tint + 1px --severity-<level> border (generateSeverityBg / .bg)",
+      "usage": ""
+    },
+    {
+      "name": "stripe",
+      "what": "severity-stripe.vue — coloured left rule on a list row/card",
+      "usage": ""
+    },
+    {
+      "name": "picker",
+      "what": "severity-picker.vue / compliance-severity-picker — choose a level",
+      "usage": ""
+    },
+    {
+      "name": "count-box",
+      "what": "dashboard/severity-count-box.vue — count per severity",
+      "usage": ""
+    },
+    {
+      "name": "switch",
+      "what": "alert severity toggle — see Atoms/Radio (severity-switch)",
+      "usage": ""
+    }
+  ],
+  "sizes": [
+    {
+      "name": "default",
+      "value": "small dot",
+      "note": "single size"
+    }
+  ],
+  "states": [
+    {
+      "name": "static",
+      "what": "`severity` prop set directly"
+    },
+    {
+      "name": "live",
+      "what": "resolves from objectId / instance / counter via severityDBWorker + the live EVENT_SEVERITY_COUNTER_DB_CHANGED bus event"
+    },
+    {
+      "name": "unknown",
+      "what": "default when unresolved → --severity-unknown grey"
+    }
+  ],
+  "severityLevels": {
+    "$note": "each level -> --severity-<level> (the dot/text colour) + --severity-<level>-dot-box (the halo). Resolve via tokens/variables.json. QUIRK (mirrored from severity.less): `up` = green ring (--severity-clear) + a critical/light-red centre (--severity-critical-dot-box); `down`/`disable` have no -dot-box (down renders solid).",
+    "levels": [
+      "up",
+      "clear",
+      "critical",
+      "down",
+      "major",
+      "warning",
+      "maintenance",
+      "unreachable",
+      "suspended",
+      "disable",
+      "stop",
+      "none",
+      "unknown"
+    ]
+  },
+  "props": {
+    "severity": "String — the level (else live-resolved)",
+    "objectId": "[Number,String] — monitor id / name / IP to live-resolve from the DB worker",
+    "instance": "String — for instance-level severity",
+    "counter": "String — for counter-level severity",
+    "displayText": "Boolean (false) — show the Capitalize(severity) label beside the dot",
+    "disableTooltip": "Boolean (false)",
+    "center": "Boolean (true)",
+    "shadow": "Boolean (true) — the dot halo (severity-dot-shadow)"
+  },
+  "events": {
+    "udpate:severity": "(sic — misspelled in source) the resolved level after live lookup"
+  },
+  "decisionFlow": [
+    "Showing a monitor/alert SEVERITY level (critical/major/warning/clear/up/down/…)? -> Severity (dot).",
+    "Showing a STATUS string (up/down/running/failed/poweredoff…) as a pill? -> MStatusTag (Tag family).",
+    "Need a coloured stripe down a list row/card? -> severity-stripe.",
+    "Let the user pick a severity level (policy/condition forms)? -> severity-picker.",
+    "Show counts per severity on a dashboard? -> severity-count-box."
+  ],
+  "do": [
+    "Use Severity for severity LEVELS; MStatusTag for status STRINGS.",
+    "Pass `severity` directly when you already have it; use objectId/instance/counter only for live resolution.",
+    "Resolve colours via --severity-<level> (+ --severity-<level>-dot-box for the halo)."
+  ],
+  "dont": [
+    "Don't route alert/monitor severity through MStatusTag — its TAG_MAP lacks major/warning/clear, so they render as a grey plain tag (F7).",
+    "Don't hardcode severity colours — use the --severity-* tokens.",
+    "Don't rely on the dot colour alone for a11y — set displayText or keep the tooltip."
+  ],
+  "knownIssues": {
+    "F1": {
+      "severity": "Low",
+      "issue": "emit name is misspelled `udpate:severity` in source."
+    },
+    "F2": {
+      "severity": "Low",
+      "a11y": true,
+      "issue": "colour-dot only by default — set displayText / keep the tooltip so severity isn't colour-only (WCAG 1.4.1)."
+    }
+  },
+  "tokensUsed": [
+    "--severity-up",
+    "--severity-clear",
+    "--severity-critical",
+    "--severity-down",
+    "--severity-major",
+    "--severity-warning",
+    "--severity-maintenance",
+    "--severity-unreachable",
+    "--severity-suspended",
+    "--severity-disable",
+    "--severity-none",
+    "--severity-unknown",
+    "--severity-critical-dot-box",
+    "--severity-warning-dot-box",
+    "--severity-major-dot-box",
+    "--severity-critical-lighter",
+    "--severity-major-lighter",
+    "--severity-warning-lighter",
+    "--severity-clear-lighter",
+    "--severity-down-lighter"
+  ],
+  "related": [
+    "tag",
+    "filters",
+    "table"
+  ],
+  "storybook": "Atoms/Severity",
+  "figma": {
+    "status": "todo"
+  },
+  "renderShapesNote": "The same severity.less class set renders dot / solid-chip / text / bg-fill (mode = a class on the element). Severity is ALSO shown via the chart/graph layer using the same --severity-* tokens: topology graph-node colour, RUM apdex map markers, heatmap cells, availability segments (see data-viz-tooltips / table) — cross-referenced, not duplicated.",
+  "a11y": {
+    "summary": "Must NOT be colour-only (F2) — pair the dot with a label (displayText) or keep the tooltip; announce live changes meaningfully.",
+    "issues": [
+      "Colour-only by default (WCAG 1.4.1).",
+      "Verify dot vs halo contrast."
+    ],
+    "doc": "Atoms/Severity/Accessibility",
+    "$note": "Catalogue-wide gap SF-001 = no visible :focus-visible ring; tracked in findings/."
+  },
+  "slots": "none — presentational (renders the dot + optional label from props; no slots)"
+}

package/components/registry/switch.json

@@ -0,0 +1,177 @@
+{
+  "name": "switch",
+  "component": "MSwitch",
+  "display": "Switch",
+  "tier": "atom",
+  "family": "Selection Controls",
+  "source": "mkit",
+  "sourceFile": "ui/components/Switch/Switch.vue",
+  "status": "core",
+  "maturity": "stable",
+  "summary": "Instant on/off toggle for a setting that applies immediately. Controlled.",
+  "variants": [],
+  "sizes": [
+    {
+      "name": "small",
+      "value": "~20x44px",
+      "note": ""
+    },
+    {
+      "name": "default",
+      "value": "22x44px",
+      "note": ""
+    }
+  ],
+  "states": [
+    {
+      "name": "off",
+      "what": "gray knob"
+    },
+    {
+      "name": "on",
+      "what": "green knob"
+    },
+    {
+      "name": "disabled",
+      "what": "no toggle"
+    },
+    {
+      "name": "loading",
+      "what": "spinner in knob"
+    }
+  ],
+  "model": {
+    "prop": "checked",
+    "event": "change"
+  },
+  "props": {
+    "checked": {
+      "type": "boolean",
+      "default": false,
+      "note": "v-model"
+    },
+    "size": {
+      "type": "string",
+      "default": "default",
+      "enum": [
+        "small",
+        "default"
+      ]
+    },
+    "disabled": {
+      "type": "boolean",
+      "default": false
+    },
+    "loading": {
+      "type": "boolean",
+      "default": false
+    },
+    "defaultChecked": {
+      "type": "boolean",
+      "note": "NO-OP (F1) — overridden by :checked"
+    },
+    "autoFocus": {
+      "type": "boolean",
+      "default": false
+    }
+  },
+  "events": [
+    "change"
+  ],
+  "slots": [
+    "checked (on label, unused)",
+    "unchecked (off label, unused)"
+  ],
+  "anatomy": [
+    "track",
+    "knob (gray off → green on)",
+    "optional on/off label slots"
+  ],
+  "styling": {
+    "trackOff": "#fff light / #172336 dark",
+    "trackOn": "same as off (no change)",
+    "knobOff": "#a5bad0 (neutral-light)",
+    "knobOn": "#14b053 (green)",
+    "size": "22x44px default"
+  },
+  "accessibility": {
+    "role": "switch",
+    "keyboard": "Space/Enter toggle",
+    "ariaChecked": "true when on; MISSING when off (F4)",
+    "focus": "no visible ring (F3)",
+    "targetSize": "~22px (F5)"
+  },
+  "do": [
+    "Use for immediate on/off settings; show :loading while persisting.",
+    "Control via v-model / :checked."
+  ],
+  "dont": [
+    "Using a switch in a form that needs explicit Save (use MCheckbox).",
+    "Relying on :defaultChecked (no-op, F1)."
+  ],
+  "whenToUse": "Immediate on/off settings (enable feature, toggle status).",
+  "decisionFlow": [
+    "Mutually-exclusive options? -> MRadio.",
+    "Applies immediately (no Save)? -> Switch.",
+    "Committed only on form Save (opt-in/consent/multi-select)? -> MCheckbox."
+  ],
+  "usageRules": {
+    "switch": {
+      "useWhen": "single binary setting that applies the moment you toggle it",
+      "dontUse": "if saved with a form (use checkbox) or one-of-many (use radio)",
+      "example": "Enable notifications; monitor on/off"
+    },
+    "loading": {
+      "useWhen": "the toggle triggers an async persist; block re-toggle until resolved"
+    },
+    "disabled": {
+      "useWhen": "setting exists but can't change in current state/permission"
+    },
+    "size=small": {
+      "useWhen": "dense rows/tables"
+    }
+  },
+  "insteadOf": [
+    "raw a-switch"
+  ],
+  "tokensUsed": [
+    "--white-regular",
+    "--neutral-light",
+    "--secondary-green"
+  ],
+  "usage": {
+    "total": 136,
+    "files": 88,
+    "labelSlots": 0
+  },
+  "knownIssues": [
+    "F1 (medium): defaultChecked is a no-op — MSwitch always passes :checked (default false) which overrides it. Use :checked/v-model.",
+    "F2 (medium): on/off changes only the knob color (gray→green) + position; the track color never changes — subtler, color-leaning signal.",
+    "F3 (high, a11y): no visible focus ring (outline:none) — WCAG 2.4.7. Add :focus-visible.",
+    "F4 (medium, a11y): aria-checked is set when on but missing when off — AT may not announce off. Ensure aria-checked=false.",
+    "F5 (low, a11y): ~22px height below the 44px touch target."
+  ],
+  "related": [
+    "MCheckbox",
+    "MRadio"
+  ],
+  "changelog": [
+    "2026-06-05: added (Playground/States/Sizes).",
+    "2026-06-06: full deep-dive — examples fixed to :checked (F1); on/off measured; enhanced standard + Option B pages; a11y F3/F4/F5."
+  ],
+  "storybook": "Atoms/Switch",
+  "figma": {
+    "status": "todo",
+    "component": "Switch"
+  },
+  "a11y": {
+    "summary": "role=switch; Space/Enter toggle; aria-checked=true when on. ~22×44px (sub-44 target).",
+    "issues": [
+      "No visible focus ring.",
+      "aria-checked missing in the OFF state.",
+      "On/off signalled mainly by knob colour — add a non-colour cue."
+    ],
+    "doc": "Atoms/Switch/Accessibility",
+    "$note": "Catalogue-wide gap SF-001 = no visible :focus-visible ring; tracked in findings/."
+  }
+}

package/components/registry/table.json

@@ -0,0 +1,275 @@
+{
+  "name": "table",
+  "display": "Table (Grid)",
+  "tier": "organism",
+  "family": "Table",
+  "source": "src/components/crud/_base-grid.vue (MGrid) — wraps the Kendo Vue Grid (@progress/kendo-vue-grid) + gridWorker/arrayWorker. Usually driven by FlotoPaginatedCrud.",
+  "status": "stable",
+  "summary": "The product's primary data table. Resizable/reorderable/sortable columns, client + server paging, grouping, selection (with bulk-action bar), expandable detail rows, per-column cell slots. MGrid is the grid; FlotoPaginatedCrud is the fetch+paginate wrapper around it.",
+  "variants": [
+    {
+      "name": "basic",
+      "what": "columns + rows, sortable",
+      "usage": ""
+    },
+    {
+      "name": "selectable",
+      "what": "checkboxes + bulk bar",
+      "usage": ""
+    },
+    {
+      "name": "expandable",
+      "what": "detail rows",
+      "usage": ""
+    },
+    {
+      "name": "grouping",
+      "what": "grouped rows + counts",
+      "usage": ""
+    },
+    {
+      "name": "cell-types",
+      "what": "per-column cell slots",
+      "usage": ""
+    },
+    {
+      "name": "pagination",
+      "what": "client/server paging",
+      "usage": ""
+    },
+    {
+      "name": "tree",
+      "what": "hierarchical",
+      "usage": ""
+    },
+    {
+      "name": "pivot",
+      "what": "pivot/report grid",
+      "usage": ""
+    }
+  ],
+  "sizes": [],
+  "states": [
+    {
+      "name": "default",
+      "what": "normal"
+    },
+    {
+      "name": "hover",
+      "what": "row highlight"
+    },
+    {
+      "name": "selected",
+      "what": "checked + accent bar"
+    },
+    {
+      "name": "expanded",
+      "what": "detail row open"
+    },
+    {
+      "name": "empty",
+      "what": "no records"
+    },
+    {
+      "name": "loading",
+      "what": "content loader"
+    }
+  ],
+  "usage": {
+    "MGrid": 75,
+    "FlotoPaginatedCrud": 76,
+    "topModules": [
+      "settings",
+      "apm",
+      "ncm",
+      "slo",
+      "alert"
+    ]
+  },
+  "props": {
+    "columns": {
+      "type": "Array",
+      "required": true,
+      "note": "column defs (field, title, width, cell template, sortable)"
+    },
+    "data": {
+      "type": "Array",
+      "note": "the rows (client mode)"
+    },
+    "selectable": {
+      "type": "Boolean",
+      "default": false,
+      "note": "checkbox column + selection"
+    },
+    "expandable": {
+      "type": "Boolean",
+      "default": false,
+      "note": "chevron column + detailRow slot"
+    },
+    "paging": {
+      "type": "Boolean",
+      "default": false
+    },
+    "defaultPageSize": {
+      "type": "Number",
+      "default": 50
+    },
+    "defaultSort": {
+      "type": "Object/Array",
+      "note": "initial sort"
+    },
+    "defaultGroup": {
+      "type": "String/Array",
+      "note": "grouping column(s)"
+    },
+    "filters": {
+      "type": "Object/Array"
+    },
+    "searchTerm": {
+      "type": "String",
+      "note": "external search; with use-search-term-loading shows a spinner"
+    },
+    "maxAllowedSelection": {
+      "type": "Number",
+      "note": "cap selection count (0 = unlimited)"
+    },
+    "preSelectedItems": {
+      "type": "Array"
+    },
+    "selectionDisabledItems": {
+      "type": "Array"
+    },
+    "disablePreSelectedItem": {
+      "type": "Boolean",
+      "default": false
+    },
+    "hideSelectionInfo": {
+      "type": "Boolean",
+      "default": false,
+      "note": "hide the 'N selected' tag"
+    },
+    "rowHeight": {
+      "type": "Number",
+      "note": "virtualization row height (non-paging mode)"
+    },
+    "totalCount": {
+      "type": "Number",
+      "note": "server total"
+    },
+    "externalSkip": {
+      "type": "Number",
+      "note": "server paging offset"
+    },
+    "externalTake": {
+      "type": "Number",
+      "note": "server page size"
+    },
+    "useExpandKey": {
+      "type": "Boolean",
+      "default": false
+    },
+    "useSearchTermLoading": {
+      "type": "Boolean",
+      "default": false
+    }
+  },
+  "slots": {
+    "perColumn": "a slot per column field renders that cell (status, name, tags, severity, value, duration, action, monitorType, timestamp, count, …)",
+    "detailRow": "expanded row content (when expandable)"
+  },
+  "events": {
+    "selection-change": "selection set changed",
+    "selection-change-single": "single-select changed",
+    "column-change": "columns reordered/resized/toggled",
+    "data-state-change": "sort/filter/page changed (server mode)",
+    "loaded": "data loaded"
+  },
+  "consumerClasses": [
+    "hide-expand-column",
+    "hide-header",
+    "hide-grouping",
+    "tabular-content-grid",
+    "service-grid",
+    "rum-grid",
+    "mgrid-container"
+  ],
+  "tokensUsed": [
+    "--grid-header-bg",
+    "--border-color",
+    "--neutral-lightest",
+    "--neutral-lighter",
+    "--primary",
+    "--neutral-dark",
+    "--page-background-color"
+  ],
+  "decisionFlow": [
+    "Need to fetch + paginate a list with CRUD? -> FlotoPaginatedCrud (wraps MGrid; handles fetch/paging/search/filters).",
+    "Have data already in memory to show in a table? -> MGrid with :data + :columns.",
+    "Large/server dataset? -> MGrid server paging (external-take/external-skip + total-count + @data-state-change).",
+    "Rows need actions? -> a row-actions kebab cell (FlotoGridActions); multi-select -> selectable + the bulk-action bar.",
+    "Rows have drill-down detail? -> expandable + the detailRow slot.",
+    "Just a few static key/values, not a dataset? -> a definition list / cards, NOT a grid."
+  ],
+  "usageRules": {
+    "crudList": {
+      "useWhen": "a fetched, paginated, searchable list (the default)",
+      "how": "FlotoPaginatedCrud + columns",
+      "example": "settings list views, inventory"
+    },
+    "inMemory": {
+      "useWhen": "data already loaded",
+      "how": "MGrid :data :columns",
+      "example": "drill-down sub-tables, preview grids"
+    },
+    "selectable": {
+      "useWhen": "bulk operations on rows",
+      "how": "selectable + selection-change + the bulk-action bar",
+      "example": "monitor bulk enable/disable/delete"
+    },
+    "expandable": {
+      "useWhen": "each row has detail",
+      "how": "expandable + detailRow slot",
+      "example": "discovered services, trace spans, interface details"
+    }
+  },
+  "do": [
+    "Use FlotoPaginatedCrud for fetched lists",
+    "Server-page large datasets",
+    "Put row actions in a kebab cell; multi-select via the bulk bar",
+    "Keep the header visible in empty/loading states"
+  ],
+  "dont": [
+    "Don't use a grid for a handful of static key/values (use a list/cards)",
+    "Don't client-load huge datasets (server-page)",
+    "Don't hand-roll selection/paging — MGrid/FlotoPaginatedCrud own it"
+  ],
+  "knownIssues": {
+    "F1": {
+      "severity": "Low",
+      "issue": "Heavy: Kendo grid + 2 web workers (gridWorker/arrayWorker) — not trivially renderable outside the app (Storybook shows reproductions)."
+    },
+    "F2": {
+      "severity": "Medium",
+      "a11y": true,
+      "issue": "Kendo grid semantics — verify rows/cells expose proper table roles, sort state (aria-sort), and selection (aria-selected); the custom cell slots can lose them."
+    }
+  },
+  "storybook": "Organisms/Table",
+  "related": [
+    "popover (row-actions kebab + bulk-action bar)",
+    "tag (status cells)",
+    "checkbox (selection)",
+    "dropdown-picker (column filters)"
+  ],
+  "figma": {
+    "status": "todo"
+  },
+  "a11y": {
+    "summary": "Expose grid semantics (role=grid/table, row, columnheader); sortable headers → aria-sort; selectable rows → aria-selected (header = select-all); arrow-key cell nav; announce 'No records'/loading via a live region.",
+    "issues": [
+      "Verify the Kendo grid actually exposes the above (semantics / aria-sort / live region)."
+    ],
+    "doc": "Organisms/Table/Accessibility",
+    "$note": "Catalogue-wide gap SF-001 = no visible :focus-visible ring; tracked in findings/."
+  }
+}