@mtdt/observeops-ds-spec 0.1.0

package/components/registry/date-time-pickers.json

@@ -0,0 +1,296 @@
+{
+  "name": "date-time-pickers",
+  "display": "Date & Time Pickers",
+  "tier": "molecule",
+  "family": "Date & Time Pickers",
+  "status": "stable",
+  "summary": "The product's date/time selection family. The hero is TimeRangePicker (42×) — the observability time-range control (relative presets + absolute custom range). MDatePicker (10×, wraps a-date-picker) is the form date-time field, in practice ALWAYS used with show-time. MTimePicker wraps a-time-picker (12-hour) but is rarely used standalone. DateTimePopover is a lighter custom-range-only popover.",
+  "variants": [
+    {
+      "name": "TimeRangePicker",
+      "what": "presets + custom range",
+      "usage": "42×"
+    },
+    {
+      "name": "presets-only",
+      "what": "hide-custom-time-range",
+      "usage": "24×"
+    },
+    {
+      "name": "excluded-options",
+      "what": "exclude preset keys",
+      "usage": "7×"
+    },
+    {
+      "name": "MDatePicker",
+      "what": "date-time (show-time)",
+      "usage": "10×"
+    },
+    {
+      "name": "MTimePicker",
+      "what": "12h time",
+      "usage": "ref"
+    },
+    {
+      "name": "TimeRangeSlider",
+      "what": "draggable scrubber",
+      "usage": "2×"
+    },
+    {
+      "name": "DateTimePopover",
+      "what": "custom-range-only popover",
+      "usage": "1×"
+    }
+  ],
+  "sizes": [],
+  "states": [
+    {
+      "name": "default",
+      "what": "pill + label"
+    },
+    {
+      "name": "empty",
+      "what": "'Select Time' placeholder"
+    },
+    {
+      "name": "open",
+      "what": "panel/calendar visible"
+    },
+    {
+      "name": "disabled",
+      "what": "not interactive"
+    }
+  ],
+  "members": {
+    "TimeRangePicker": {
+      "source": "src/components/widgets/time-range-picker.vue (name TimeRangePicker)",
+      "usage": "42x / 35 files — the dominant date/time control",
+      "renders": "REFERENCE REPRODUCTION in Storybook (depends on the Vuex user-preference store + the `datetime` filter + moment, so it can't render live — like the Kendo grid).",
+      "presets": [
+        "Last 5 Mins (5m)",
+        "Last 15 Mins (15m)",
+        "Last 30 Mins (30m)",
+        "Last 1 Hour (1h)",
+        "Last 6 Hours (6h)",
+        "Last 12 Hours (12h)",
+        "Last 24 Hours (24h)",
+        "Last 48 Hours (48h)",
+        "Today (today)",
+        "Last Day (1d)",
+        "Last Week (1w)",
+        "Last Month (1mo)",
+        "This Week (week)",
+        "This Month (month)",
+        "Custom ('')"
+      ],
+      "props": {
+        "value": "v-model — object { selectedKey, startDate, endDate, startTime, endTime, dailyRollingData }",
+        "hideCustomTimeRange": "bool, 24× — drop the 'Custom' option (presets-only mode); the dominant variant",
+        "excludedOptions": "array, 7× — drop specific preset keys (e.g. ['today']); a real, common variant",
+        "allowClear": "bool, 7× — show a times-circle × to reset (emits change=undefined)",
+        "hideIcon": "bool, 3× — passed by consumers",
+        "maxSelectableRangeDays": "number, default 93 (365 for report export) — disables dates beyond the span in the custom calendar (2×)",
+        "disabled": "bool, 3×",
+        "getPopupContainer": "function, 2×",
+        "bordered": "bool, 1× — add a --border-color frame to the trigger",
+        "pillStyle": "object, 1× — inline style for the shortcut pill",
+        "hideSelectedTime": "bool, 1× — hide the absolute from/to shown beside the trigger",
+        "overlayClassName": "string, 1×",
+        "onlyLabel": "bool — DECLARED BUT UNUSED (0×); dailyRolling also 0×"
+      },
+      "emit": "change/v-model -> { selectedKey:'-24h'|'today'|'custom'|…, startDate:<ms>, endDate:<ms>, startTime:'HH:mm:ss', endTime:'HH:mm:ss', dailyRollingData:false }. Custom range validates end > start or blocks the emit.",
+      "trigger": "a --timerange-background-color shortcut pill (e.g. '24h' or a computed duration '6d 23h') + separator + the range label ('Last 24 Hours'); empty state shows a calendar-alt icon + 'Select Time'."
+    },
+    "MDatePicker": {
+      "source": "ui/components/Datepicker/Datepicker.vue (wraps a-date-picker)",
+      "usage": "10x / 8 files",
+      "renders": "REAL kit component (no store deps)",
+      "props": {
+        "value": "moment | string | number; v-model (model event=change)",
+        "showTime": "bool|object, default { use12Hours:true, format:'hh:mm A' } — ALL 10 real usages pass :show-time, so MDatePicker is the date-TIME field",
+        "allowClear": "9×",
+        "minDate": "7× — earliest selectable date",
+        "disabled": "5×",
+        "disabledDate": "function — grey out days",
+        "format": "display format",
+        "placeholder": "default 'Select...'"
+      },
+      "icon": "calendar suffix icon; slot dateRender for custom day cells"
+    },
+    "MTimePicker": {
+      "source": "ui/components/Datepicker/Timepicker.vue (wraps a-time-picker)",
+      "usage": "0× standalone — NOT used as a standalone tag anywhere in src. Time-of-day is entered via MDatePicker show-time or inside the TimeRangePicker custom view.",
+      "renders": "REAL kit component (shown for reference)",
+      "props": {
+        "format": "default 'hh:mm A'",
+        "use12Hours": "default true",
+        "allowClear": "default true",
+        "placeholder": "default 'Select...'"
+      },
+      "emit": "change(formattedString, moment)",
+      "icon": "clock suffix icon"
+    },
+    "TimePicker (custom)": {
+      "source": "src/components/time-picker.vue (name TimePicker)",
+      "usage": "0× standalone; used INSIDE TimeRangePicker's custom view (From/To time)",
+      "renders": "internal — wraps FlotoDropdownPicker (a DROPDOWN of time options + clock icon), NOT an Ant spinner",
+      "props": {
+        "value": "Array|Object|String",
+        "multiple": "bool",
+        "useSeconds": "bool (seconds granularity)",
+        "usePopover": "bool",
+        "...$attrs": "passed through to FlotoDropdownPicker"
+      }
+    },
+    "TimeRangeSlider": {
+      "source": "src/components/widgets/time-range-picker/time-range-slider.vue (name TimeRangeSlider)",
+      "usage": "2× — dashboard view + alert correlation drawer",
+      "renders": "REFERENCE REPRODUCTION (Ant range Slider styled as a timeline; needs moment/helper/datetime filter)",
+      "anatomy": "hidden rail; tick dots (2x14px) with time-mark labels every 10th (HH:mm / DD/MM / MMM by span); two 10x10 square handles; a --primary track for the selected window. min/max auto-expand to ~4x the current duration so dragging widens the window.",
+      "emit": "change -> { selectedKey:'custom', startDate, endDate, startTime, endTime } (same shape as TimeRangePicker)"
+    },
+    "DateTimePopover": {
+      "source": "src/components/common/date-time-popover.vue",
+      "usage": "1× (SLO correction profile) — a lighter CUSTOM-RANGE-ONLY popover (no presets)",
+      "renders": "documented (MPopover + FlotoFormItem + store deps)",
+      "emit": "{ startDate, endDate, startTime, endTime }"
+    }
+  },
+  "decisionFlow": [
+    "Selecting a TIME WINDOW for charts/dashboards/logs (relative or absolute)? -> TimeRangePicker (the 42× hero).",
+    "Want presets only (no absolute calendar)? -> TimeRangePicker :hide-custom-time-range (24×).",
+    "A single date or date+time value in a FORM field? -> MDatePicker with :show-time (the product default).",
+    "Just a time of day (e.g. a schedule)? -> MTimePicker (12-hour).",
+    "A custom absolute from/to with NO presets, as a form field? -> DateTimePopover.",
+    "Constrain how far back/forward? -> :max-selectable-range-days (TimeRangePicker) or :min-date / :disabled-date (MDatePicker)."
+  ],
+  "usageRules": {
+    "timeWindow": {
+      "useWhen": "pick a chart/dashboard/log time window",
+      "how": "<TimeRangePicker v-model>",
+      "example": "metric explorer, dashboards, log search"
+    },
+    "presetsOnly": {
+      "useWhen": "absolute ranges shouldn't be allowed",
+      "how": ":hide-custom-time-range",
+      "example": "widgets where only relative windows make sense"
+    },
+    "dateTimeField": {
+      "useWhen": "a date+time value in a form",
+      "how": "<MDatePicker :show-time v-model>",
+      "example": "maintenance window start, schedule"
+    },
+    "timeField": {
+      "useWhen": "a time of day",
+      "how": "<MTimePicker v-model>",
+      "example": "daily run time"
+    }
+  },
+  "tokensUsed": [
+    "--timerange-background-color",
+    "--timerange-text-color",
+    "--dropdown-background",
+    "--dropdown-hover-background",
+    "--left-menu-text-color-hover",
+    "--border-color",
+    "--primary",
+    "--calendar-selected-day-background-color",
+    "--tag-bg",
+    "--secondary-red",
+    "--neutral-light",
+    "--neutral-lightest",
+    "--page-text-color"
+  ],
+  "do": [
+    "Use TimeRangePicker for chart/dashboard/log time windows.",
+    "Use :hide-custom-time-range when only relative windows are valid.",
+    "Use MDatePicker WITH :show-time for date-time form fields (the product norm).",
+    "Constrain selection with :max-selectable-range-days / :min-date where it matters."
+  ],
+  "dont": [
+    "Don't hand-roll a relative-range dropdown — use TimeRangePicker.",
+    "Don't use a bare date picker for chart windows — that's TimeRangePicker's job.",
+    "Don't pass an empty string '' to MTimePicker/MDatePicker value (parses to an Invalid date) — pass null/undefined or a moment.",
+    "Don't assume card/inline calendar variants — the product uses the popup pickers only."
+  ],
+  "knownIssues": {
+    "F1": {
+      "severity": "Low",
+      "issue": "TimeRangePicker depends on the user-preference store + datetime filter, so it is reproduced (not rendered live) in Storybook."
+    },
+    "F2": {
+      "severity": "Low",
+      "a11y": true,
+      "issue": "Catalog-wide focus-ring removal (SF-001) may affect the picker inputs/preset rows; verify keyboard focus visibility."
+    }
+  },
+  "accessibility": {
+    "providedByAnt": "a-date-picker / a-time-picker expose a text input + a keyboard-navigable calendar/time panel; Escape closes; the input is focusable and typeable.",
+    "verify": "Focus-visible ring (SF-001) on inputs and on the TimeRangePicker preset rows (which are <a>/clickable divs — ensure they're keyboard-reachable and labelled)."
+  },
+  "scopedOut": {
+    "Scheduler / Recurrence (schedule-input/)": "17 files — a Once/Daily/Weekly/Monthly RECURRENCE builder (MRadioGroup + Once/Weekly/Monthly inputs). Date/time-adjacent but a DISTINCT component family — candidate for its own future entry, not part of date/time pickers.",
+    "DateTimePopover": "covered above (custom-range-only popover).",
+    "date-remark-pairs.vue": "a date + remark list (holidays / special days) — a composite, not a picker primitive.",
+    "TimeRangeSlider text-input shorthand (time-range-picker/text-input.vue)": "internal — typed shorthand ('5m','7d') with autocomplete inside TimeRangePicker.",
+    "kit DateRangePicker / NotifyTimePicker": "0× / niche — not used as standalone product patterns.",
+    "no week/month/quarter/calendar pickers": "confirmed absent — no MWeekPicker/MMonthPicker/MRangePicker/a-calendar usage."
+  },
+  "storybook": "Molecules/Date & Time Pickers",
+  "related": [
+    "dropdown-picker",
+    "form-item",
+    "popover"
+  ],
+  "figma": {
+    "status": "todo"
+  },
+  "apis": {
+    "TimeRangePicker": {
+      "source": "src/components/widgets/time-range-picker.vue",
+      "props": {
+        "value": "Object — selected range (.sync via change)",
+        "hideCustomTimeRange": "Boolean (false) — presets only",
+        "excludedOptions": "Array — preset keys to hide",
+        "allowClear": "Boolean (false)",
+        "bordered": "Boolean (false)",
+        "onlyLabel": "Boolean (false)",
+        "hideIcon": "Boolean (false)",
+        "hideSelectedTime": "Boolean (false)",
+        "disabled": "Boolean (false)",
+        "getPopupContainer": "Function"
+      },
+      "events": {
+        "change": "(range) — selection changed"
+      }
+    },
+    "MDatePicker": {
+      "source": "ui/components/Datepicker/Datepicker.vue (kit)",
+      "props": {
+        "value": "[String,Number,Object]",
+        "format": "String — display format",
+        "showTime": "[Boolean,Object] (default 12h hh:mm A) — date-time vs date-only",
+        "minDate": "[String,Number,Object]",
+        "maxDate": "[String,Number,Object]",
+        "disabledTime": "Function",
+        "placeholder": "('Select...')",
+        "getPopupContainer": "Function"
+      },
+      "events": {
+        "change": "(date)",
+        "update": "(date)",
+        "handleCalendarChange": "(date)"
+      }
+    }
+  },
+  "a11y": {
+    "summary": "Focusable text input + keyboard-navigable calendar; disabled via the disabled input. The trigger pill should expose its current selection to AT.",
+    "issues": [
+      "Preset rows are <a>/<div> — verify keyboard-reachable.",
+      "SF-001 focus ring.",
+      "Range error is shown as text."
+    ],
+    "doc": "Molecules/Date & Time Pickers/Accessibility",
+    "$note": "Catalogue-wide gap SF-001 = no visible :focus-visible ring; tracked in findings/."
+  }
+}

package/components/registry/drawer.json

@@ -0,0 +1,222 @@
+{
+  "name": "drawer",
+  "component": "FlotoDrawer",
+  "display": "Drawer",
+  "tier": "organism",
+  "category": "overlay",
+  "source": "app",
+  "sourceFile": "src/components/_base-drawer.vue",
+  "status": "core",
+  "maturity": "stable",
+  "summary": "Slide-in side panel (from the right) for detail views, edit forms, and record-contextual content. The product's MOST-used overlay (FlotoDrawer 99x + FlotoDrawerForm 59x = 158x). Open via open prop or trigger slot.",
+  "variants": [
+    {
+      "name": "FlotoDrawer",
+      "what": "detail side panel",
+      "usage": "99×"
+    },
+    {
+      "name": "FlotoDrawerForm",
+      "what": "form + drawer (Add/Edit)",
+      "usage": "59×"
+    }
+  ],
+  "sizes": [
+    {
+      "name": "360px",
+      "value": "360px",
+      "note": "simple"
+    },
+    {
+      "name": "40%",
+      "value": "40%",
+      "note": "default"
+    },
+    {
+      "name": "50-70%",
+      "value": "50-70%",
+      "note": "richer"
+    },
+    {
+      "name": "85-96%",
+      "value": "85-96%",
+      "note": "large multi-pane"
+    }
+  ],
+  "states": [
+    {
+      "name": "open",
+      "what": "slid in from right"
+    },
+    {
+      "name": "closed",
+      "what": "hidden"
+    },
+    {
+      "name": "scrolling",
+      "what": "body scrolls, title/footer pinned"
+    }
+  ],
+  "family": "Overlay",
+  "components": {
+    "FlotoDrawer": {
+      "usage": 99,
+      "props": [
+        "open(toggles)",
+        "width(px/%, default 40%)",
+        "scrolledContent(default true -> FlotoScrollView)",
+        "usePadding",
+        "(a-drawer attrs: placement, ...)"
+      ],
+      "slots": [
+        "trigger {open,close,toggle}",
+        "title / title-row",
+        "default (body, scrollable)",
+        "actions {hide} (fixed footer)"
+      ],
+      "events": [
+        "show",
+        "hide"
+      ]
+    },
+    "FlotoDrawerForm": {
+      "usage": 59,
+      "summary": "FlotoForm (vertical) + FlotoDrawer; suppresses MForm default Submit so only the footer submits",
+      "slots": [
+        "trigger",
+        "header / header-row",
+        "default {submit}",
+        "actions {hide, submit}"
+      ]
+    }
+  },
+  "anatomy": [
+    "title (text-primary) + built-in close x",
+    "scrollable body (FlotoScrollView)",
+    "actions fixed footer (Cancel/Save)",
+    "dimmed backdrop"
+  ],
+  "behaviors": {
+    "open": "open prop (toggles) or trigger slot",
+    "close": "built-in x (Ant a-drawer) + actions footer + Escape — maskClosable:false (no backdrop-close)",
+    "scroll": "body scrolls (FlotoScrollView); title/footer pinned; ~65px reserved at bottom when actions slot present",
+    "hide-delay": "@hide fires ~500ms after close (slide-out animation)"
+  },
+  "tokensUsed": [
+    "--page-background-color",
+    "--border-color",
+    "--page-text-color"
+  ],
+  "accessibility": {
+    "semantics": "role=dialog, focus trap, BUILT-IN close x (better than MModal which has none), Escape closes",
+    "focus": "no visible ring inside (SF-001)"
+  },
+  "decisionFlow": [
+    "Short yes/no or destructive confirmation? -> FlotoConfirmModal, not a drawer.",
+    "Long content, a detail view, or a form contextual to a record? -> FlotoDrawer.",
+    "An Add/Edit FORM in a panel? -> FlotoDrawerForm (vertical form + validation + footer submit).",
+    "A short focused task that must center-interrupt? -> MModal (dialog)."
+  ],
+  "usageRules": {
+    "detail(FlotoDrawer)": {
+      "useWhen": "view details / long content contextual to a record",
+      "example": "incident details, view-detail/view-more drawers, gauge/compliance drilldown"
+    },
+    "form(FlotoDrawerForm)": {
+      "useWhen": "Add/Edit form in a panel (vertical form + validation; footer Save submits)",
+      "example": "most Add/Edit flows; approval drawers (sync/runbook/firmware), email-dispatch form"
+    },
+    "width": {
+      "useWhen": "default 40%; narrower (px) for simple panels, wider (%) for rich content",
+      "example": "360px detail, 60% rich editor"
+    },
+    "large-fullscreen(85-96%)": {
+      "useWhen": "complex MULTI-PANE flows (left nav + main form + right reference panel) — config/registration wizards",
+      "example": "APM Application Registration (width=96%); used ~30x at 90%/96%/85%/100%. Use a wide drawer, not a modal."
+    }
+  },
+  "inProduct": {
+    "FlotoDrawer": "IncidentDetails, ViewDetail/ViewMore, Gauge/Compliance drilldown, Credential/Catalog selection drawers",
+    "FlotoDrawerForm": "Add/Edit forms, SyncApproval/RunbookApproval/FirmwareUpgradeApproval, AttachRules/AttachStorage, EmailDispatch form"
+  },
+  "do": [
+    "Use a Drawer for detail views, edit forms, long/record-contextual content.",
+    "Use FlotoDrawerForm for Add/Edit forms (vertical form + footer submit).",
+    "Put actions in the footer (Cancel left, Save right)."
+  ],
+  "dont": [
+    "Don't use a Drawer for a short confirmation (use FlotoConfirmModal).",
+    "Don't rely on backdrop-click to close (disabled) — use the x or footer Cancel.",
+    "Don't add an MForm inside without suppressing its default Submit (two submit buttons)."
+  ],
+  "whenToUse": "Detail views, edit forms, and long/record-contextual content that doesn't fit a centered modal.",
+  "insteadOf": [
+    "raw a-drawer",
+    "a modal for long/record-contextual content"
+  ],
+  "usage": {
+    "FlotoDrawer": 99,
+    "FlotoDrawerForm": 59,
+    "total": 158,
+    "open": 27,
+    "width": 14
+  },
+  "knownIssues": [
+    "F1 (low): @hide emits ~500ms after close (setTimeout for the slide-out animation) — parents should account for the delay.",
+    "F2 (high, a11y): no visible focus ring inside the panel (SF-001).",
+    "F3 (low): .actions footer is justify-end with NO gap -> adjacent buttons touch (0px). Product convention is mr-2 on the non-last button. Fix: add gap:8px to .actions in drawer.less. Footer layout: 2=Cancel(mr-2)+Save right; 3=Reset/Cancel/Save right OR destructive left + confirm group right (justify-between); 4=tertiary/note left + confirm group right; primary far-right, Cancel just left of it, destructive/tertiary on the left."
+  ],
+  "related": [
+    "MModal",
+    "FlotoConfirmModal",
+    "FlotoDrawerForm",
+    "FlotoForm",
+    "FlotoFormItem",
+    "MButton"
+  ],
+  "changelog": [
+    "2026-06-08: added (decision-grade). FlotoDrawer (99x) + FlotoDrawerForm (59x) = 158x, the most-used overlay. open-prop/trigger; title/body(scrollable)/actions(fixed footer) slots; width 40%; built-in x + maskClosable:false. Verified Basic + Form drawer render. F1 (delayed hide), F2 (focus)."
+  ],
+  "storybook": "Organisms/Drawer",
+  "figma": {
+    "status": "todo",
+    "component": "Drawer"
+  },
+  "$tokensNote": "Title text = --page-text-color. Backdrop scrim is Ant's literal rgba(0,0,0,.45) — not tokenized; Ant Drawer internals follow the kit.",
+  "apis": {
+    "FlotoDrawer": {
+      "source": "src/components/_base-drawer.vue",
+      "props": {
+        "open": "Boolean (false) — visibility (use .sync)",
+        "width": "[String,Number] ('40%') — drawer width",
+        "usePadding": "Boolean (false) — pad the body",
+        "scrolledContent": "Boolean (true) — wrap the body in a scroll view"
+      },
+      "events": {
+        "show": "() — opened",
+        "hide": "() — closed (backdrop / ESC / close)"
+      },
+      "slots": {
+        "default": "drawer body"
+      }
+    },
+    "FlotoDrawerForm": {
+      "source": "src/components/crud/_base-drawer-form.vue",
+      "note": "Form-in-drawer variant — same open / width / scrolledContent props.",
+      "slots": {
+        "trigger": "element that opens the drawer",
+        "header": "custom header",
+        "header-row": "header action row",
+        "default": "form body"
+      }
+    }
+  },
+  "a11y": {
+    "summary": "Ant a-drawer → role=dialog; focus trapped + restored on close; built-in close ×; Esc closes; backdrop-click doesn't close (maskClosable:false). Give a clear title.",
+    "issues": [
+      "No visible focus ring inside the panel."
+    ],
+    "doc": "Organisms/Drawer/Accessibility",
+    "$note": "Catalogue-wide gap SF-001 = no visible :focus-visible ring; tracked in findings/."
+  }
+}