@mtdt/observeops-ds-spec 0.1.0

package/components/registry/link.json

@@ -0,0 +1,186 @@
+{
+  "name": "link",
+  "component": "FlotoLink",
+  "display": "Link",
+  "tier": "atom",
+  "category": "navigation",
+  "source": "app",
+  "sourceFile": "src/components/_base-app-link.vue",
+  "status": "core",
+  "maturity": "stable",
+  "summary": "Navigation control. Default renders a RouterLink (<a>); as-button renders an MButton that pushes the route on click. Only own prop is asButton; everything else passes through.",
+  "variants": [
+    {
+      "name": "text-link",
+      "what": "RouterLink text (default)",
+      "usage": "67×"
+    },
+    {
+      "name": "as-button",
+      "what": "MButton + route push",
+      "usage": ""
+    },
+    {
+      "name": "external",
+      "what": "<a target=_blank>",
+      "usage": "147×"
+    },
+    {
+      "name": "k-link",
+      "what": "subtle grid/pagination link class",
+      "usage": "25×"
+    }
+  ],
+  "sizes": [],
+  "states": [
+    {
+      "name": "default",
+      "what": "inherits text colour"
+    },
+    {
+      "name": "hover",
+      "what": "text underline"
+    },
+    {
+      "name": "focus",
+      "what": "no visible ring (SF-001)"
+    },
+    {
+      "name": "active",
+      "what": "current route (as-button)"
+    }
+  ],
+  "family": "Link",
+  "props": {
+    "asButton": {
+      "type": "boolean",
+      "default": false,
+      "note": "button-styled navigation (MButton + $router.push) vs a plain RouterLink"
+    },
+    "to": {
+      "type": [
+        "string",
+        "object"
+      ],
+      "note": "via $attrs — route location / path"
+    },
+    "target": {
+      "type": "string",
+      "note": "via $attrs"
+    },
+    "(MButton props)": {
+      "type": "passthrough",
+      "note": "when asButton: variant/size/etc. pass through"
+    }
+  },
+  "events": [
+    "(passthrough via $listeners)"
+  ],
+  "slots": [
+    "default (link/button content)"
+  ],
+  "modes": {
+    "default": "RouterLink -> real <a> (middle-click / open-in-new-tab work)",
+    "asButton": "MButton -> navigates via $router.push on click (no href)"
+  },
+  "anatomy": [
+    "text link (<a>, inherits color)",
+    "OR button-styled link (MButton)"
+  ],
+  "accessibility": {
+    "default": "real anchor — correct link role + keyboard + new-tab",
+    "asButton": "F1 — a <button>, not an anchor: no href, no middle-click/new-tab, announced as button",
+    "focus": "no visible ring (SF-001)"
+  },
+  "decisionFlow": [
+    "Performs an action (save/delete/change state)? -> Button, not a link.",
+    "External URL / opens in a new tab? -> plain <a href target=_blank rel=noopener noreferrer> (FlotoLink is internal-only).",
+    "Internal navigation (route)? -> FlotoLink.",
+    "Internal navigation that should look like a prominent CTA/button? -> FlotoLink as-button (with a variant).",
+    "Inline internal navigation in content / menus / breadcrumbs / a clickable value? -> FlotoLink (text link).",
+    "A subtle clickable text inside a table/grid? -> class k-link."
+  ],
+  "usageRules": {
+    "text-link(default)": {
+      "useWhen": "inline INTERNAL navigation in content, menus, breadcrumbs, logos, a clickable value",
+      "dontUse": "for actions (use Button) or external URLs (use a plain anchor)",
+      "example": "go to <the inventory list>; a breadcrumb segment"
+    },
+    "as-button": {
+      "useWhen": "a prominent INTERNAL navigation call-to-action that should look like a button",
+      "dontUse": "where users expect open-in-new-tab/middle-click (F1 — it's a button, no href)",
+      "example": "Go to settings CTA"
+    },
+    "external-link": {
+      "useWhen": "an external/help/doc URL or anything that opens in a new tab",
+      "must": "plain <a href target=_blank> with rel=noopener noreferrer (FlotoLink/RouterLink can't do external; SF-004)",
+      "example": "documentation/help links"
+    },
+    "k-link(class)": {
+      "useWhen": "subtle clickable text inside a table/grid",
+      "note": "--page-text-color, hover -> pagination-active; not brand-colored (25x)"
+    }
+  },
+  "linkClasses": {
+    "k-link": 25,
+    "resource-link": "8 (mostly legacy/commented)",
+    "link-label": 5,
+    "completed-link": 3,
+    "admin-page-link": 1
+  },
+  "do": [
+    "Use for navigation (route/URL): inline links, menus, breadcrumbs, logos.",
+    "Use as-button for a prominent navigation CTA; pass a Button variant.",
+    "Name the destination in the link text; add text-primary affordance for inline links."
+  ],
+  "dont": [
+    "Don't use a link for an action (save/delete/apply) — use a Button.",
+    "Don't rely on as-button where open-in-new-tab matters (F1)."
+  ],
+  "whenToUse": "Anything that navigates the user somewhere (route, URL, anchor).",
+  "insteadOf": [
+    "raw RouterLink",
+    "a button styled as a link",
+    "an anchor for actions"
+  ],
+  "usage": {
+    "total": 67,
+    "files": 48,
+    "to": 9
+  },
+  "knownIssues": [
+    "F1 (medium, a11y/UX): as-button navigates via $router.push on an MButton (no href) — loses middle-click/open-in-new-tab and is announced as a button, not a link. Prefer a real anchor styled as a button for nav CTAs.",
+    "F2 (low): plain links inherit text color (no default link color/underline) — a bare link can look like text; most usages add text-primary. Consider a default link style.",
+    "F3 (low, security) -> SF-004: FlotoLink is internal-only (RouterLink), so external links are raw <a target=_blank> — 147x across the app, 0 with rel=noopener noreferrer (reverse tabnabbing; browser-mitigated). Add a shared external-link component + lint rule. See findings/SF-004."
+  ],
+  "related": [
+    "MButton",
+    "MDropdown",
+    "RouterLink"
+  ],
+  "changelog": [
+    "2026-06-07: added (decision-grade from the start). 67x/48 files; RouterLink default + as-button MButton route-push; only own prop asButton. Verified in SB (RouterLink + $router stubbed). F1 (as-button not a real link), F2 (no default affordance). Closes Button's navigation relative."
+  ],
+  "storybook": "Atoms/Link",
+  "figma": {
+    "status": "todo",
+    "component": "Link"
+  },
+  "tokensUsed": [
+    "--primary",
+    "--primary-alt",
+    "--page-text-color",
+    "--neutral-light",
+    "--border-color",
+    "--pagination-active-bg"
+  ],
+  "a11y": {
+    "summary": "True <a>/RouterLink — link role + keyboard focus. Use destination-naming text (not 'click here'); as-button variant announces as a button.",
+    "issues": [
+      "No visible focus ring (SF-001).",
+      "Plain links inherit text colour (F2) — add an affordance."
+    ],
+    "doc": "Atoms/Link/Accessibility",
+    "$note": "Catalogue-wide gap SF-001 = no visible :focus-visible ring; tracked in findings/."
+  }
+}

package/components/registry/loose-tags.json

@@ -0,0 +1,196 @@
+{
+  "name": "loose-tags",
+  "component": "LooseTags",
+  "display": "LooseTags",
+  "tier": "molecule",
+  "category": "form-input",
+  "source": "app",
+  "sourceFile": "src/components/loose-tags.vue",
+  "status": "core",
+  "maturity": "stable",
+  "summary": "Free-form tag input (type to create tags) with async suggestions. The Tag family's input member; home of the teal pills.",
+  "variants": [
+    {
+      "name": "editable",
+      "what": "mode=tags + suggestions",
+      "usage": "default"
+    },
+    {
+      "name": "disabled",
+      "what": "SelectedItemPills (read-only)",
+      "usage": ""
+    },
+    {
+      "name": "asDropdown",
+      "what": "FlotoDropdownPicker searchable multi",
+      "usage": ""
+    }
+  ],
+  "sizes": [],
+  "states": [
+    {
+      "name": "default",
+      "what": "editable"
+    },
+    {
+      "name": "disabled",
+      "what": "read-only pills"
+    }
+  ],
+  "family": "Tag",
+  "model": {
+    "prop": "value",
+    "event": "change"
+  },
+  "props": {
+    "value": {
+      "type": "array",
+      "default": [],
+      "note": "v-model — array of tag strings"
+    },
+    "disabled": {
+      "type": "boolean",
+      "default": false,
+      "note": "read-only mode → SelectedItemPills teal pills"
+    },
+    "asDropdown": {
+      "type": "boolean",
+      "default": false,
+      "note": "searchable FlotoDropdownPicker mode (covered by DropdownPicker spec)"
+    },
+    "singleSelection": {
+      "type": "boolean",
+      "default": false,
+      "note": "caps to 1 — ONLY effective in asDropdown"
+    },
+    "counter": {
+      "type": "object",
+      "default": "undefined",
+      "note": "{ key } scopes suggestion fetch; watched (refetch on change)"
+    },
+    "tagType": {
+      "type": "string",
+      "note": "filters suggestion fetch"
+    },
+    "userTagOnly": {
+      "type": "boolean",
+      "default": false,
+      "note": "filters suggestion fetch"
+    },
+    "placeholder": {
+      "type": "string",
+      "default": " ",
+      "note": "ONLY used in asDropdown (F1); editable mode hardcodes 'Add Tags'"
+    },
+    "sm": {
+      "type": "boolean",
+      "default": true,
+      "note": "DEAD — drives size computed that is never bound (F3)"
+    }
+  },
+  "events": [
+    "change"
+  ],
+  "slots": [
+    "clearIcon (set to times-circle)"
+  ],
+  "modes": {
+    "default": "MSelect mode=tags + .loose-tags-input — type-to-create + suggestions; normalizes lowercase+trim+dedupe",
+    "disabled": "SelectedItemPills teal pills (read-only, no API)",
+    "asDropdown": "FlotoDropdownPicker as-input searchable multiple (DropdownPicker spec); trims, preserves case"
+  },
+  "anatomy": [
+    "teal pills (orange ×)",
+    "free-text input",
+    "suggestions dropdown (from API)"
+  ],
+  "styling": {
+    "pill": "--main-tags-bg-color/--main-tags-text-color teal, 22px, radius 4px",
+    "removeIcon": "--secondary-orange",
+    "font": "JetBrains Mono (.loose-tags-input)"
+  },
+  "tokensUsed": [
+    "--main-tags-bg-color",
+    "--main-tags-text-color",
+    "--secondary-orange"
+  ],
+  "accessibility": {
+    "semantics": "Ant Select mode=tags (combobox); Enter add, Backspace remove last, Arrows navigate",
+    "focus": "no visible ring (SF-001)",
+    "clear": "native clear hidden via CSS (selection__clear display:none)"
+  },
+  "do": [
+    "Use to capture a list of free-form or known tags (v-model an array).",
+    "Pass :counter to scope suggestions; use disabled for read-only display."
+  ],
+  "dont": [
+    "Don't rely on placeholder in editable mode (F1) or sm for sizing (F3).",
+    "Don't assume case is preserved — default mode lowercases (F2)."
+  ],
+  "whenToUse": "Capturing a list of tags on a form (free-form or from known suggestions).",
+  "decisionFlow": [
+    "Just displaying tags (label/count/status)? -> MTag/MStatusTag, not LooseTags.",
+    "Read-only display of an existing list? -> disabled.",
+    "Pick from a known/suggested set with search? -> asDropdown.",
+    "Free-type to create new tags? -> default (editable).",
+    "Only one tag allowed? -> singleSelection (with asDropdown)."
+  ],
+  "usageRules": {
+    "editable(default)": {
+      "useWhen": "user types values + Enter to add; suggestions offered; lowercased/trimmed/deduped",
+      "example": "free-form tags on a monitor"
+    },
+    "disabled": {
+      "useWhen": "show an existing tag list read-only (view-mode forms, detail panels)"
+    },
+    "asDropdown": {
+      "useWhen": "pick from known tags (searchable picker) instead of free-typing"
+    },
+    "singleSelection": {
+      "useWhen": "only one tag may be selected (caps asDropdown to 1)",
+      "note": "no effect in default editable mode"
+    },
+    "counter": {
+      "useWhen": "scope suggestions to a specific entity (dominant real usage)"
+    }
+  },
+  "usage": {
+    "total": 94,
+    "files": 80,
+    "counter": 69,
+    "asDropdown": 10,
+    "tagType": 24,
+    "userTagOnly": 4,
+    "singleSelection": 2
+  },
+  "knownIssues": [
+    "F1 (medium): placeholder prop ignored in editable mode (hardcoded 'Add Tags'); only used in asDropdown. Bind it on MSelect too.",
+    "F2 (low): default mode lowercases tags; asDropdown preserves case — inconsistent normalization.",
+    "F3 (low): sm prop + size computed are dead (size never bound) — input always default size.",
+    "F4 (low): getAllTagsApi().then() has no .catch — failed/offline fetch is an unhandled rejection (404 pageerror in Storybook). Add .catch → tagOptions=[]."
+  ],
+  "related": [
+    "MTag",
+    "MStatusTag",
+    "SelectedItemPills",
+    "FlotoDropdownPicker",
+    "MSelect"
+  ],
+  "changelog": [
+    "2026-06-07: added — 3 render modes mapped; teal pills + JetBrains Mono verified light+dark; F1-F4; classified as Tag family input member (D12); Option B pages."
+  ],
+  "storybook": "Molecules/LooseTags",
+  "figma": {
+    "status": "todo",
+    "component": "LooseTags"
+  },
+  "a11y": {
+    "summary": "Type + Enter to add a pill; Backspace removes the last; Arrow keys navigate suggestions, Enter selects. Exposes a combobox/listbox.",
+    "issues": [
+      "No visible focus ring (SF-001).",
+      "Remove × is small — ensure hit target."
+    ],
+    "doc": "Molecules/LooseTags/Accessibility",
+    "$note": "Catalogue-wide gap SF-001 = no visible :focus-visible ring; tracked in findings/."
+  }
+}

package/components/registry/menu.json

@@ -0,0 +1,145 @@
+{
+  "name": "menu",
+  "display": "Menu",
+  "tier": "molecule",
+  "family": "Menu",
+  "status": "stable",
+  "summary": "The MMenu primitive (a vertical list of selectable icon+label rows, with dividers and danger/positive colours) catalogued in its own right, plus its action-surface usage: the Context/Action menu (FlotoGridActions — a '...' trigger opening an MMenu of actions).",
+  "variants": [
+    {
+      "name": "menu-primitive",
+      "what": "MMenu list of rows",
+      "usage": "13×"
+    },
+    {
+      "name": "context-menu",
+      "what": "⋯ → MMenu of actions",
+      "usage": "grid rows"
+    }
+  ],
+  "sizes": [],
+  "states": [
+    {
+      "name": "hover",
+      "what": "--neutral-lighter"
+    },
+    {
+      "name": "selected",
+      "what": "--primary on tint"
+    },
+    {
+      "name": "danger",
+      "what": "--secondary-red"
+    },
+    {
+      "name": "positive",
+      "what": "--secondary-green"
+    },
+    {
+      "name": "disabled",
+      "what": "not interactive"
+    }
+  ],
+  "renders": "REFERENCE REPRODUCTIONS — the live MMenu needs Ant menu context/theme. Built with real tokens + MIcon.",
+  "members": {
+    "Menu": {
+      "source": "@motadata/ui MMenu / MMenuItem / MMenuDivider",
+      "usage": "13x",
+      "what": "the primitive — a vertical list of selectable rows (icon + label); states: hover (--neutral-lighter), selected (--primary on --code-tag-background-color); MMenuDivider (--border-color); danger (--secondary-red) / positive (--secondary-green) item colours",
+      "buildingBlockFor": [
+        "navigation (Primary nav, Side menu)",
+        "dropdownpicker",
+        "menu (Context/Action menu)"
+      ]
+    },
+    "ContextMenu": {
+      "source": "components/_base-grid-actions.vue (FlotoGridActions) + MDropdown (1x, rich-text editor table options)",
+      "usage": "grid rows + 1x MDropdown",
+      "what": "an action surface — an MPopover (placement bottomRight) triggered by an ellipsis-v '...' icon, opening an MMenu of ACTION items (icon + label); permission-gated (create/edit/delete keys), supports dividers, danger=red / positive=green",
+      "isActionSurface": true
+    }
+  },
+  "decisionFlow": [
+    "A list of items to render inside something (nav, picker, dropdown)? -> Menu primitive.",
+    "A '...' or button that opens a list of ACTIONS on a row/object? -> Context / Action menu.",
+    "Pick a VALUE from options (single/multi)? -> Dropdown picker / Select (not this family).",
+    "Go to a destination? -> Navigation (Primary nav / Side menu / Tabs)."
+  ],
+  "do": [
+    "Reuse the Menu primitive; use FlotoGridActions for row actions.",
+    "Colour danger actions with --secondary-red, positive with --secondary-green.",
+    "Gate menu items by permission (create/edit/delete keys)."
+  ],
+  "dont": [
+    "Don't confuse an actions menu with a value picker (use Dropdown picker / Select).",
+    "Don't confuse it with navigation (go somewhere).",
+    "Don't hand-roll a <ul> dropdown; don't rely on colour alone for danger."
+  ],
+  "knownIssues": {
+    "F1": {
+      "severity": "Low",
+      "issue": "Primitive reproduced (live MMenu needs Ant menu context) -> real tokens + MIcon."
+    },
+    "F2": {
+      "severity": "Low",
+      "a11y": true,
+      "issue": "Verify role=menu/menuitem, arrow-key + Esc, trigger aria-label, focus return, non-colour-only danger."
+    },
+    "F3": {
+      "severity": "Info",
+      "issue": "MDropdown appears only 1x (editor); the standard action menu is FlotoGridActions (MPopover + MMenu)."
+    }
+  },
+  "tokensUsed": [
+    "--page-background-color",
+    "--border-color",
+    "--neutral-lighter",
+    "--code-tag-background-color",
+    "--primary",
+    "--secondary-red",
+    "--secondary-green",
+    "--page-text-color"
+  ],
+  "storybook": "Molecules/Menu",
+  "related": [
+    "navigation",
+    "dropdownpicker",
+    "select",
+    "popover",
+    "toolbars",
+    "table"
+  ],
+  "figma": {
+    "status": "todo"
+  },
+  "apis": {
+    "ContextMenu": {
+      "source": "src/components/_base-grid-actions.vue (FlotoGridActions)",
+      "props": {
+        "actions": "Array<{key,name,icon?,isDanger?|redAction?,greenAction?,type?:'divider'}>",
+        "resource": "Object (the row, required)",
+        "createPermissionKeys/editPermissionKeys/deletePermissionKeys": "Array of action keys gated by the matching *PermissionName",
+        "createPermissionName/editPermissionName/deletePermissionName": "String permission const",
+        "overlayClassName": "String (default 'picker-action-dropdown')",
+        "textClassName": "String (default 'text-neutral-light')",
+        "useDelayedHide": "Boolean"
+      },
+      "events": {
+        "selected": "(action) on any pick",
+        "<actionKey>": "also emitted by the action's key (e.g. @delete)"
+      },
+      "slots": {
+        "trigger": "{ toggle } — default is the ⋯ ellipsis-v"
+      },
+      "actionItem": "{ key, name, icon, isDanger|redAction (red), greenAction (green), type:'divider' }"
+    }
+  },
+  "a11y": {
+    "summary": "role=menu + menuitem; ↑/↓ move, Enter/Space activate, Esc closes + restores focus (trapped while open); not colour-only (danger/positive carry icon+label).",
+    "issues": [
+      "The ellipsis-v ⋯ trigger is icon-only — needs an aria-label."
+    ],
+    "doc": "Molecules/Menu/Accessibility",
+    "$note": "Catalogue-wide gap SF-001 = no visible :focus-visible ring; tracked in findings/."
+  }
+}