@mtdt/observeops-ds-spec 0.1.0

package/components/registry/form-item.json

@@ -0,0 +1,281 @@
+{
+  "name": "form-item",
+  "component": "FlotoFormItem",
+  "display": "Form Field",
+  "tier": "molecule",
+  "category": "form",
+  "source": "app",
+  "sourceFile": "src/components/_base-form-item.vue",
+  "status": "core",
+  "maturity": "stable",
+  "summary": "The form field: label + validation + control + error/help. MValidationProvider (vee-validate) -> MFormItem. Most-used component (1783x). required is derived from rules.",
+  "variants": [
+    {
+      "name": "text",
+      "what": "built-in MInput text",
+      "usage": ""
+    },
+    {
+      "name": "number",
+      "what": "MInput number",
+      "usage": ""
+    },
+    {
+      "name": "textarea",
+      "what": "MInput textarea",
+      "usage": ""
+    },
+    {
+      "name": "vertical",
+      "what": "label above",
+      "usage": "13×"
+    },
+    {
+      "name": "horizontal",
+      "what": "label beside",
+      "usage": "14×"
+    },
+    {
+      "name": "custom-control",
+      "what": "slot holds any control",
+      "usage": ""
+    }
+  ],
+  "sizes": [],
+  "states": [
+    {
+      "name": "default",
+      "what": "normal"
+    },
+    {
+      "name": "required",
+      "what": "asterisk (from rules)"
+    },
+    {
+      "name": "error",
+      "what": "red border + msg (pristine-gated)"
+    },
+    {
+      "name": "valid",
+      "what": "passed validation"
+    }
+  ],
+  "family": "Form Controls",
+  "model": {
+    "prop": "value",
+    "event": "update"
+  },
+  "props": {
+    "label": {
+      "type": "string",
+      "default": "",
+      "note": "field label (+ optional info tooltip)"
+    },
+    "rules": {
+      "type": [
+        "string",
+        "object"
+      ],
+      "default": "",
+      "note": "vee-validate rules e.g. required|email|max:255; REQUIRED ASTERISK is derived from this (F1)"
+    },
+    "help": {
+      "type": "string",
+      "note": "hint text under the field"
+    },
+    "infoTooltip": {
+      "type": "string",
+      "note": "(i) icon by the label with hover help (HTML allowed)"
+    },
+    "type": {
+      "type": "string",
+      "note": "control type for the built-in MInput (text/number/textarea/...)"
+    },
+    "inputType": {
+      "type": "string",
+      "note": "overrides type for the built-in MInput"
+    },
+    "validationLabel": {
+      "type": "string"
+    },
+    "vid": {
+      "type": "string"
+    },
+    "mode": {
+      "type": "string",
+      "default": "eager"
+    },
+    "immediate": {
+      "type": "boolean",
+      "default": false,
+      "note": "validate on mount (red border; message still pristine-gated, F2)"
+    },
+    "hideErrorMessage": {
+      "type": "boolean",
+      "default": false
+    },
+    "labelCol": {
+      "type": "object",
+      "default": "{ xxl:2, xl:3, lg:4 }",
+      "note": "responsive label width (horizontal layout)"
+    },
+    "wrapperCol": {
+      "type": "object",
+      "default": "{ xxl:10, xl:9, lg:8 }",
+      "note": "responsive control width"
+    }
+  },
+  "events": [
+    "update (model)",
+    "blur"
+  ],
+  "slots": [
+    "default (the control, gets slotData)",
+    "before-input",
+    "input-children",
+    "passthrough scoped slots -> inner MInput"
+  ],
+  "methods": [
+    "validate()",
+    "setValue(v)",
+    "addError(err)",
+    "focus()"
+  ],
+  "anatomy": [
+    "label (+ required asterisk + optional info tooltip)",
+    "control (built-in MInput or slot)",
+    "help text OR error message (red when invalid)"
+  ],
+  "behaviors": {
+    "required": "asterisk shown when rules include 'required' (not required_if)",
+    "validation": "eager mode validates on interaction; error => red border + inline errors[0]; message is pristine-gated (shows after interaction, border shows immediately)",
+    "control": "no slot => built-in MInput (routed by type); slot => any control with label+validation",
+    "programmatic": "validate()/addError()/setValue()/focus() via ref"
+  },
+  "tokensUsed": [
+    "--field-border-color",
+    "--text-color-common-secondary",
+    "--secondary-red"
+  ],
+  "accessibility": {
+    "label": "associated with the control via MFormItem",
+    "required": "asterisk is visual; the rule/error conveys requirement to AT",
+    "focus": "inner controls have no visible ring (SF-001)",
+    "errors": "text messages (not color-only)"
+  },
+  "decisionFlow": [
+    "Building a form field (label + control + validation)? -> FlotoFormItem (always).",
+    "Plain text/number/textarea control? -> omit the slot, set type (built-in MInput).",
+    "Select / Radio / Checkbox / picker / tag input? -> put it in the default slot.",
+    "Needs validation? -> set rules (required|email|max:255 ...); required asterisk is automatic.",
+    "Need a persistent hint? -> help. Longer explanation? -> info-tooltip."
+  ],
+  "usageRules": {
+    "field(default)": {
+      "useWhen": "any labelled form field; omit slot for a built-in MInput",
+      "example": "Monitor name text field"
+    },
+    "required": {
+      "useWhen": "the field is mandatory",
+      "must": "put 'required' in rules (asterisk derives from it) — there is no required prop (F1)"
+    },
+    "custom-control": {
+      "useWhen": "the control is not a plain input (Select/Radio/Checkbox/picker/LooseTags)",
+      "example": "Severity as a segmented MRadioGroup in the slot"
+    },
+    "help": {
+      "useWhen": "a short persistent hint under the field",
+      "example": "In seconds. Lower values increase load."
+    },
+    "info-tooltip": {
+      "useWhen": "a longer explanation behind an (i) icon (MTooltip/VTippy, hover)",
+      "note": "needs vue-tippy VTippy registered (done in SB preview)"
+    },
+    "validation": {
+      "useWhen": "the value must be valid",
+      "note": "rules from src/validations.js; error = red border + message (pristine-gated)"
+    },
+    "layout": {
+      "useWhen": "vertical (label on top) for narrow/focused forms — drawers, modals, integration setup (Slack/Jira/ServiceNow), pickers; horizontal (label beside) for dense settings pages — Mail Server, Proxy, SNMP Trap, RADIUS, 2FA, My Profile",
+      "note": "set on the parent FlotoForm/MForm layout; drawers/modals -> vertical, full settings pages -> horizontal"
+    }
+  },
+  "notCovered": {
+    "sizes": "none — fields are one height",
+    "is-view": "lives on the inner controls, not FlotoFormItem",
+    "repeatable": "multiple-form-items is a separate related component"
+  },
+  "do": [
+    "Wrap every form control in FlotoFormItem for consistent label + validation + error.",
+    "Put validation in rules; add reusable rules in src/validations.js.",
+    "Use the default slot for non-text controls; help for hints, info-tooltip for longer guidance."
+  ],
+  "dont": [
+    "Don't pass a 'required' attribute — put required in rules (F1).",
+    "Don't hand-roll labels/validation around a bare input.",
+    "Don't rely on @input — v-model uses update."
+  ],
+  "whenToUse": "Every labelled, validated field in a form.",
+  "insteadOf": [
+    "raw a-form-item",
+    "a bare input with a hand-made label + validation"
+  ],
+  "usage": {
+    "total": 1783,
+    "label": 611,
+    "rules": 272,
+    "id": 52
+  },
+  "knownIssues": [
+    "F1 (low): required is derived from rules (regex for 'required'); there is no required prop — passing required does nothing. A convenience prop could help.",
+    "F2 (low): error message is pristine-gated — with immediate the red border shows but the message only appears after interaction (expected vee-validate behavior).",
+    "F3 (high, a11y): inner controls have no visible focus ring (SF-001)."
+  ],
+  "related": [
+    "MInput",
+    "MRadioGroup",
+    "MCheckbox",
+    "MSwitch",
+    "FlotoDropdownPicker",
+    "LooseTags",
+    "FlotoForm",
+    "MValidationObserver"
+  ],
+  "changelog": [
+    "2026-06-07: added (decision-grade) — the Form Field molecule (1783x). vee-validate provider -> MFormItem; required derived from rules; built-in MInput vs slot control; help + info-tooltip; validate/setValue/addError/focus. SB preview registers MValidationProvider/Observer + src/validations + FlotoFormItem. Verified live email error + red border. F1-F3."
+  ],
+  "storybook": "Molecules/FormItem",
+  "figma": {
+    "status": "todo",
+    "component": "Form Field"
+  },
+  "apis": {
+    "FlotoForm": {
+      "source": "src/components/_base-form.vue",
+      "what": "the form WRAPPER (MValidationObserver + MForm). Wrap FlotoFormItems in it.",
+      "props": {
+        "showNotification": "Boolean (default false) — toast on failed validate"
+      },
+      "events": {
+        "submit": "emitted only after validation passes",
+        "reset": "on reset"
+      },
+      "methods": {
+        "validate()": "Promise<true|reject> — call via ref before manual submit",
+        "resetValidation()": "clear errors"
+      },
+      "slots": "pass-through; default/named slots receive { validate, submit, reset }",
+      "usage": "<FlotoForm @submit=\"save\"><MRow><MCol :size=\"6\"><FlotoFormItem .../></MCol></MRow><template v-slot:submit=\"{ submit }\">...</template></FlotoForm>"
+    }
+  },
+  "$tokensNote": "Label = --text-color-common-secondary; error state (.has-error) = --secondary-red (#ec5b5b).",
+  "a11y": {
+    "summary": "Label associated via MFormItem (click focuses the control). Errors are text (not colour-only), pristine-gated; the required asterisk is visual — keep the required rule.",
+    "issues": [
+      "Wrapped controls have no visible focus ring (SF-001).",
+      "info-tooltip content sits behind a hover trigger."
+    ],
+    "doc": "Molecules/FormItem/Accessibility",
+    "$note": "Catalogue-wide gap SF-001 = no visible :focus-visible ring; tracked in findings/."
+  }
+}

package/components/registry/input.json

@@ -0,0 +1,277 @@
+{
+  "name": "input",
+  "component": "MInput",
+  "display": "Input",
+  "tier": "atom",
+  "category": "form-control",
+  "source": "mkit",
+  "sourceFile": "ui/components/Input/Input.vue",
+  "status": "core",
+  "maturity": "stable",
+  "summary": "Text input. A type-router (text/password/number/search/textarea/datetime). v-model is value+update. Almost always wrapped by FlotoFormItem for label+validation.",
+  "variants": [
+    {
+      "name": "text",
+      "what": "single-line (default)",
+      "usage": ""
+    },
+    {
+      "name": "password",
+      "what": "masked",
+      "usage": ""
+    },
+    {
+      "name": "number",
+      "what": "MInputNumber steppers",
+      "usage": "70×"
+    },
+    {
+      "name": "search",
+      "what": "MInputSearch + enter",
+      "usage": ""
+    },
+    {
+      "name": "textarea",
+      "what": "multi-line",
+      "usage": ""
+    },
+    {
+      "name": "material-input",
+      "what": "bottom-border underline",
+      "usage": "62×"
+    },
+    {
+      "name": "no-border-input",
+      "what": "borderless inline edit",
+      "usage": "3×"
+    }
+  ],
+  "sizes": [],
+  "states": [
+    {
+      "name": "default",
+      "what": "resting"
+    },
+    {
+      "name": "hover",
+      "what": "border lightens"
+    },
+    {
+      "name": "focus",
+      "what": "border → primary"
+    },
+    {
+      "name": "disabled",
+      "what": "muted, no caret"
+    },
+    {
+      "name": "read-only",
+      "what": "selectable not editable"
+    },
+    {
+      "name": "error",
+      "what": "red border (validation)"
+    }
+  ],
+  "family": "Form Controls",
+  "model": {
+    "prop": "value",
+    "event": "update",
+    "note": "event is 'update', not 'input' (F1)"
+  },
+  "props": {
+    "type": {
+      "type": "string",
+      "default": "text",
+      "enum": [
+        "text",
+        "password",
+        "number",
+        "search",
+        "textarea",
+        "datetime"
+      ],
+      "note": "routes to a-input / a-input[type=password] / MInputNumber / MInputSearch / a-textarea / date-picker"
+    },
+    "value": {
+      "type": "any",
+      "note": "v-model"
+    },
+    "defaultValue": {
+      "type": "string"
+    },
+    "allowClear": {
+      "type": "boolean",
+      "note": "shows an x to clear when there's a value (218x incl. pickers)"
+    },
+    "maxlength": {
+      "type": "number",
+      "note": "native char cap (7x); no built-in counter — show-count NOT supported by Ant 1.4 kit"
+    },
+    "(a-input attrs)": {
+      "type": "passthrough",
+      "note": "disabled, readOnly, maxLength via $attrs. size (small/default/large) exists but EFFECTIVELY UNUSED — one height (32px; search 36px)"
+    }
+  },
+  "events": [
+    "update (model)",
+    "search",
+    "enterKey"
+  ],
+  "slots": [
+    "prefix",
+    "suffix",
+    "addonBefore",
+    "addonAfter",
+    "enterButton (search)"
+  ],
+  "typeRouting": {
+    "text": "a-input",
+    "password": "a-input[type=password] (no show/hide toggle, F2)",
+    "number": "MInputNumber (steppers)",
+    "search": "MInputSearch (enter button, emits search)",
+    "textarea": "a-textarea",
+    "datetime": "date picker (separate concern)"
+  },
+  "styleClasses": {
+    "material-input": {
+      "usage": 62,
+      "note": "bottom-border-only Material underline (border 0/0/1/0)"
+    },
+    "full-border-text-area": 17,
+    "full-bordered-addon-input": 6,
+    "no-border-input": 3,
+    "auto-height-input": 2,
+    "text-lg-input": 2
+  },
+  "anatomy": [
+    "optional prefix/suffix (inside field)",
+    "input control",
+    "optional addonBefore/addonAfter segments"
+  ],
+  "tokensUsed": [
+    "--field-border-color",
+    "--input-text-color",
+    "--text-input-bg",
+    "--input-placeholder-color",
+    "--input-suffix-bg",
+    "--input-suffix-text",
+    "--input-addon-color"
+  ],
+  "accessibility": {
+    "semantics": "native input/textarea; label via FlotoFormItem or aria-label",
+    "focus": "no visible ring (SF-001)",
+    "placeholder": "~50% color (--input-placeholder-color) — verify contrast; not a label substitute"
+  },
+  "decisionFlow": [
+    "Multi-line text? -> type=textarea (or FlotoFormItem type=textarea).",
+    "Numeric value (with steppers)? -> type=number (MInputNumber).",
+    "Secret/password? -> type=password (PasswordInput for show/hide).",
+    "Search box (enter/clear, emits search)? -> type=search (MInputSearch).",
+    "A date/time? -> date picker, not a text input.",
+    "Otherwise single-line text -> type=text (default).",
+    "[Field] In a form with a label/validation? -> wrap in FlotoFormItem (the norm).",
+    "[Style] Dense/inline underline look? -> .material-input. Unit/protocol attached? -> addonBefore/addonAfter. Context icon? -> prefix/suffix."
+  ],
+  "usageRules": {
+    "text": {
+      "useWhen": "single-line free text (name, label, value)",
+      "example": "monitor name"
+    },
+    "password": {
+      "useWhen": "secret entry",
+      "dontUse": "when a show/hide toggle is needed (use PasswordInput) — type=password has none (F2)"
+    },
+    "number": {
+      "useWhen": "numeric input with steppers",
+      "example": "port, threshold, interval"
+    },
+    "search": {
+      "useWhen": "a search box (Enter emits search, has an enter button)",
+      "example": "filter/search a list"
+    },
+    "textarea": {
+      "useWhen": "multi-line text",
+      "note": "in forms use FlotoFormItem type=textarea",
+      "example": "description, notes"
+    },
+    "prefix/suffix": {
+      "useWhen": "a context icon inside the field (search glass, unit)",
+      "example": "search prefix, $ suffix"
+    },
+    "addonBefore/addonAfter": {
+      "useWhen": "attached fixed segments (protocol/unit)",
+      "example": "https:// … .com"
+    },
+    "material-input": {
+      "useWhen": "a dense/inline Material underline look (bottom border only)",
+      "example": "inline filters/toolbars (62x)"
+    },
+    "allow-clear": {
+      "useWhen": "an optional field/search where clearing to empty is valid",
+      "example": "filter/search inputs (x to clear)"
+    },
+    "error-state": {
+      "useWhen": "a field fails validation",
+      "note": ".has-error red border applied by FlotoFormItem; always pair with an inline message"
+    },
+    "disabled-vs-readonly": {
+      "useWhen": "disabled = can't interact (greyed); read-only = selectable/copyable but not editable (view mode)"
+    },
+    "FlotoFormItem": {
+      "useWhen": "any input in a form — adds the label + validation (the standard pattern, 1783x)"
+    }
+  },
+  "do": [
+    "Wrap inputs in FlotoFormItem for label + validation (standard form pattern).",
+    "Pick the type for the data; bind with v-model.",
+    "Use prefix/suffix for context icons; addonBefore/addonAfter for units/protocols."
+  ],
+  "dont": [
+    "Don't rely on @input to update the model — it's @update (F1).",
+    "Don't use the placeholder as the only label.",
+    "Don't expect a password show/hide toggle from type=password (F2)."
+  ],
+  "whenToUse": "Capturing typed input (text/number/search/multi-line) on a form or toolbar.",
+  "insteadOf": [
+    "raw a-input/a-textarea",
+    "native input"
+  ],
+  "usage": {
+    "MInput": 293,
+    "FlotoFormItem": 1783,
+    "material-input": 62,
+    "full-border-text-area": 17
+  },
+  "knownIssues": [
+    "F1 (low): v-model event is 'update' not 'input' — @input won't update the model; use @update or v-model. Align to input/update:value in a future API pass.",
+    "F2 (low): type=password has no show/hide toggle (falls to a-input[type=password]); a separate PasswordInput exists. Route to a-input-password or point to PasswordInput.",
+    "F3 (high, a11y): inputs strip the focus outline — no visible focus ring (SF-001)."
+  ],
+  "related": [
+    "FlotoFormItem",
+    "MInputNumber",
+    "MInputSearch",
+    "MInputGroup",
+    "LooseTags",
+    "date picker"
+  ],
+  "changelog": [
+    "2026-06-07: added (decision-grade from the start). 293x; type-router; v-model value/update; prefix/suffix/addon slots; .material-input 62x (bottom-border) verified. F1-F3. FlotoFormItem (1783x) noted as the field wrapper (own entry next)."
+  ],
+  "storybook": "Atoms/Input",
+  "figma": {
+    "status": "todo",
+    "component": "Input"
+  },
+  "a11y": {
+    "summary": "Native <input>/<textarea>, correct roles + text-editing keys. Always label (FlotoFormItem or aria-label). type=search adds Enter→search.",
+    "issues": [
+      "No visible focus ring (SF-001).",
+      "Placeholder contrast ~50% — verify.",
+      "type=password has no show/hide (F2) — use PasswordInput."
+    ],
+    "doc": "Atoms/Input/Accessibility",
+    "$note": "Catalogue-wide gap SF-001 = no visible :focus-visible ring; tracked in findings/."
+  }
+}