@mtdt/observeops-ds-spec 0.1.0

package/components/registry/modal.json

@@ -0,0 +1,265 @@
+{
+  "name": "modal",
+  "component": "MModal",
+  "display": "Modal",
+  "tier": "organism",
+  "category": "overlay",
+  "source": "mkit",
+  "sourceFile": "ui/components/Modal/Modal.vue",
+  "status": "core",
+  "maturity": "stable",
+  "summary": "Centered dialog over a dimmed backdrop. MModal (39x) is the base; FlotoConfirmModal (71x) is the confirm variant. Open via trigger slot or open prop. No x/backdrop-close (footer/Escape only).",
+  "variants": [
+    {
+      "name": "MModal",
+      "what": "centered dialog",
+      "usage": "39×"
+    },
+    {
+      "name": "FlotoConfirmModal",
+      "what": "confirm yes/no",
+      "usage": "71×"
+    },
+    {
+      "name": "hide-footer",
+      "what": "read-only/detail",
+      "usage": "4×"
+    },
+    {
+      "name": "scrollable-modal",
+      "what": "fixed-height scroll body",
+      "usage": ""
+    },
+    {
+      "name": "restrict-width",
+      "what": "capped 1020px",
+      "usage": ""
+    },
+    {
+      "name": "no-padding-modal",
+      "what": "full-bleed content",
+      "usage": "11×"
+    }
+  ],
+  "sizes": [
+    {
+      "name": "default",
+      "value": "560px",
+      "note": ""
+    },
+    {
+      "name": "confirm",
+      "value": "450px",
+      "note": ""
+    },
+    {
+      "name": "restrict-width",
+      "value": "1020px",
+      "note": ""
+    }
+  ],
+  "states": [
+    {
+      "name": "closed",
+      "what": "hidden"
+    },
+    {
+      "name": "open",
+      "what": "over backdrop"
+    },
+    {
+      "name": "loading",
+      "what": "confirmLoading"
+    }
+  ],
+  "family": "Overlay",
+  "components": {
+    "MModal": {
+      "usage": 39,
+      "open": "trigger slot { open }",
+      "props": [
+        "width",
+        "centered",
+        "confirmLoading",
+        "preventAutoCloseOnConfirm",
+        "overlayClassName"
+      ],
+      "slots": [
+        "trigger { open, close, toggle }",
+        "title",
+        "default (body)",
+        "footer { cancel, success }"
+      ],
+      "events": [
+        "success",
+        "cancel"
+      ]
+    },
+    "FlotoConfirmModal": {
+      "usage": 71,
+      "open": "open prop (Boolean)",
+      "props": [
+        "open",
+        "variant(default error)",
+        "width(450)",
+        "successText(Yes)",
+        "cancelText(No)",
+        "hideIcon",
+        "iconShadow",
+        "disableAutoHide"
+      ],
+      "slots": [
+        "icon",
+        "message",
+        "header",
+        "cancel-action",
+        "confirm-action"
+      ],
+      "events": [
+        "confirm",
+        "hide"
+      ]
+    }
+  },
+  "anatomy": [
+    "title (no x close)",
+    "body (default slot)",
+    "footer (cancel + success)",
+    "dimmed backdrop/mask"
+  ],
+  "behaviors": {
+    "open": "trigger slot (open fn) or open prop",
+    "close": "header x / footer Cancel / Escape (verified) / success — NO built-in x, NO backdrop-close (closable/maskClosable hardcoded false)",
+    "destroyOnClose": true,
+    "confirm": "Cancel(default) left, action right; error variant for destructive"
+  },
+  "headerPattern": "built-in x is off, so real modals (~26) add their own header in the title slot: flex row with a text-primary title + a close x (MIcon times wired to hide())",
+  "overlayVariants": {
+    "hide-footer": "removes footer (read-only/detail) — 4x",
+    "scrollable-modal": "fixed-height scrollable body, top 50px, rounded header; modifiers restrict-width (1020px), smaller-modal (50vh)",
+    "no-padding-modal / no-padding-confrim-modal": "strip content padding — 11x",
+    "backdrop": "blurred (backdrop-filter: blur(3px))"
+  },
+  "tokensUsed": [
+    "--page-background-color",
+    "--border-color",
+    "--page-text-color"
+  ],
+  "accessibility": {
+    "semantics": "role=dialog; Ant traps + restores focus; Escape closes (even with x hidden)",
+    "gaps": "F1 no visible close besides footer; SF-001 no focus ring inside"
+  },
+  "decisionFlow": [
+    "Yes/no or destructive confirmation? -> FlotoConfirmModal (variant=error for destructive).",
+    "A focused short task/form that must interrupt? -> MModal (dialog).",
+    "Long/complex content, or contextual to a record (details/edit in place)? -> FlotoDrawer (side panel), not a modal.",
+    "Just a brief message? -> consider a notification instead of a modal."
+  ],
+  "usageRules": {
+    "dialog(MModal)": {
+      "useWhen": "a focused task/form that interrupts the flow; short content",
+      "must": "include a footer Cancel (only visible way out — F1)",
+      "example": "Edit/Filter/Note dialogs"
+    },
+    "confirm(FlotoConfirmModal)": {
+      "useWhen": "confirm a yes/no or destructive action",
+      "example": "Delete monitor? (error variant, Cancel/Delete); delete in CRUD lists, inline-name-edit, trap-profile"
+    },
+    "hide-footer": {
+      "useWhen": "view-only content (no Save/Cancel); header x is the way out",
+      "example": "metric-explorer Compare/Anomaly/Arithmetic/Outlier modals"
+    },
+    "scrollable-modal": {
+      "useWhen": "long body that must scroll (lists/editors); wrap content in flex:1;min-height:0;overflow-y:auto (F3)",
+      "example": "Compare metric, linked-records detail, widget JSON editor, column configurator"
+    },
+    "no-padding": {
+      "useWhen": "content manages its own padding (editor/full-bleed)",
+      "example": "log-collection profile list, view-query, LAMA integration, activation-code modal"
+    },
+    "drawer-instead": {
+      "useWhen": "content is long or contextual to a record -> use FlotoDrawer (158x), not a modal",
+      "example": "incident details, approval drawers"
+    }
+  },
+  "inProduct": {
+    "MModal": "Anomaly/Forecast/Outlier modals, Filter modal, Note modal, Compare modal",
+    "FlotoConfirmModal": "delete/abort confirmations across the app",
+    "FlotoDrawer": "detail/view drawers, form drawers (incident details, approval drawers)"
+  },
+  "do": [
+    "Use MModal for a focused dialog; FlotoConfirmModal for confirms.",
+    "Always include a footer Cancel (visible way out).",
+    "Use FlotoDrawer for long or record-contextual content."
+  ],
+  "dont": [
+    "Don't rely on a x or backdrop-click to close (disabled, F1).",
+    "Don't use a modal for content better inline or in a drawer.",
+    "Don't label actions Yes/OK — name the verb (Delete, Save)."
+  ],
+  "whenToUse": "A focused task, dialog, or confirmation that must interrupt the flow.",
+  "insteadOf": [
+    "raw a-modal",
+    "a hand-built overlay"
+  ],
+  "usage": {
+    "MModal": 39,
+    "FlotoConfirmModal": 71,
+    "FlotoDrawer": 158,
+    "FlotoDrawerForm": 59
+  },
+  "knownIssues": [
+    "F1 (medium, UX/a11y): no top-right x and no backdrop-close (closable/maskClosable hardcoded false). Escape + footer Cancel work, but a modal whose footer omits Cancel has no discoverable dismiss for mouse users. Make closable a prop (visible x) or require a footer Cancel.",
+    "F2 (high, a11y): no visible focus ring inside the dialog (SF-001).",
+    "F3 (low): scrollable-modal sets a fixed-height flex-column body but NO overflow on the body — long content spills out unless wrapped in a flex:1;min-height:0;overflow-y:auto child. Add overflow to the variant or document the required structure."
+  ],
+  "related": [
+    "FlotoConfirmModal",
+    "FlotoDrawer",
+    "FlotoDrawerForm",
+    "MButton",
+    "FlotoFormItem"
+  ],
+  "changelog": [
+    "2026-06-07: added (decision-grade). MModal (39x) + FlotoConfirmModal (71x). Trigger-slot / open-prop; title/body/footer slots; width/centered/confirmLoading. Verified Basic + Confirm open; Escape closes, no x (F1). Drawer (158x) = related own entry."
+  ],
+  "storybook": "Organisms/Modal",
+  "figma": {
+    "status": "todo",
+    "component": "Modal"
+  },
+  "$tokensNote": "Backdrop scrim is a blurred Ant literal rgba(0,0,0,.45) + blur(3px) — not tokenized; Ant Modal internals follow the kit.",
+  "apis": {
+    "MModal": {
+      "source": "ui/components/Modal/Modal.vue (kit)",
+      "props": {
+        "width": "[Number,String] — modal width",
+        "centered": "Boolean — vertically centre",
+        "confirmLoading": "Boolean — spinner on the confirm button",
+        "preventAutoCloseOnConfirm": "Boolean (false) — keep open after confirm",
+        "overlayClassName": "String — class on the backdrop mask"
+      },
+      "events": {
+        "success": "() — confirm / OK",
+        "cancel": "() — cancel / close"
+      },
+      "slots": {
+        "title": "header title",
+        "default": "modal body"
+      }
+    },
+    "FlotoConfirmModal": {
+      "source": "src/components/_base-confirm-modal.vue",
+      "note": "Confirm/alert wrapper — variant=error for destructive; commonly hosts a FlotoForm (form-in-modal)."
+    }
+  },
+  "a11y": {
+    "summary": "role=dialog; Ant traps + restores focus; Esc closes. No top-right × and no backdrop-close (closable/maskClosable hardcoded false). Give a clear title; state the consequence for confirms.",
+    "issues": [
+      "No visible focus ring inside the dialog.",
+      "Esc is the only dismiss (no × / backdrop-close)."
+    ],
+    "doc": "Organisms/Modal/Accessibility",
+    "$note": "Catalogue-wide gap SF-001 = no visible :focus-visible ring; tracked in findings/."
+  }
+}