mgv-backoffice 1.33.0 → 1.35.0

package/README.md

@@ -669,6 +669,24 @@ Consistency checks for dynamic key/value grids (header lists, query params,
 metadata rows). Rows with `matcherType: 'absent'` are exempt — an absent
 matcher intentionally carries no value.
 
+### Input validators
+
+```ts
+import { isValidAbsoluteUrl, isValidJson, isValidXml, isValidBase64 } from 'mgv-backoffice'
+```
+
+Pure, dependency-free form-input validators. The payload validators treat
+empty/whitespace-only input as **valid** — required-ness is a separate rule
+from well-formedness; `isValidAbsoluteUrl` validates a value that must exist,
+so empty is invalid there.
+
+| Function             | Signature                    | Returns |
+| -------------------- | ---------------------------- | ------- |
+| `isValidAbsoluteUrl` | `(value: string) => boolean` | `true` for an absolute `http://` / `https://` URL (other schemes rejected). |
+| `isValidJson`        | `(str: string) => boolean`   | `true` when empty or parseable as JSON. |
+| `isValidXml`         | `(str: string) => boolean`   | `true` when empty or well-formed XML (DOMParser `<parsererror>` check; browser-only). |
+| `isValidBase64`      | `(str: string) => boolean`   | `true` when empty or well-formed base64 (whitespace stripped, length/alphabet checked, then `atob` as the final authority). |
+
 ### HTML sanitizer
 
 ```ts
@@ -724,6 +742,8 @@ API values can be passed without pre-sanitising.
 | `fmtPrice`     | `(n: number) => string`                                         | Price with precision that scales to magnitude (more decimals for sub-cent values). |
 | `fmtPct`       | `(n: number, digits = 2) => string`                             | Percentage with explicit sign, e.g. `"+2.50%"`. |
 | `fmtUsd`       | `(v: number) => string`                                         | Signed USD amount with leading sign, e.g. `"+$5.00"`. |
+| `formatJson`   | `(content: string) => string`                                   | Pretty-prints parseable JSON with 2-space indentation; returns anything else verbatim. |
+| `stringifyValue` | `(value: unknown) => string`                                  | Display string for an unknown value: strings pass through, null/undefined → `''`, everything else JSON-serialized (`String()` fallback). |
 
 ### Spec-form helpers
 
@@ -1106,7 +1126,7 @@ a page header. Optional leading icon (via slot) plus a label.
 | Prop       | Type      | Default     | Description |
 | ---------- | --------- | ----------- | ----------- |
 | `label`    | `String`  | `''`        | Button text. Omit for an icon-only button. |
-| `variant`  | `String`  | `'neutral'` | `'neutral'` (grey) or `'danger'` (solid red). |
+| `variant`  | `String`  | `'neutral'` | `'neutral'` (grey), `'danger'` (solid red) or `'ghost'` (slate h-9 outline — toolbar/modal-footer buttons). |
 | `disabled` | `Boolean` | `false`     | Greys out and blocks the click. |
 | `title`    | `String`  | `undefined` | Native tooltip / a11y text. |
 | `type`     | `String`  | `'button'`  | Native button type. |
@@ -1304,6 +1324,26 @@ selection, so picking the same file twice still emits.
 />
 ```
 
+### BaseCodeBlock
+
+Themed monospace `<pre>` for JSON payloads, request dumps and code snippets
+(extracted from WireMate's stub/request detail views). Preserves whitespace
+verbatim, scrolls both axes, and adapts to the theme. Extra classes (margins
+etc.) fall through via the normal class merge.
+
+**Props:**
+
+| Prop             | Type     | Default  | Description |
+| ---------------- | -------- | -------- | ----------- |
+| `code`           | `String` | **required** | The raw text to render. |
+| `variant`        | `String` | `'soft'` | `'soft'` = tinted fill, no border (in-card look); `'bordered'` = bordered card fill (standalone look). |
+| `size`           | `String` | `'sm'`   | `'sm'` = `text-sm px-5 py-4`; `'xs'` = dense `text-xs p-3`. |
+| `maxHeightClass` | `String` | `''`     | Optional Tailwind max-height utility, e.g. `max-h-96`. |
+
+```vue
+<BaseCodeBlock :code="formatJson(response.body)" size="xs" max-height-class="max-h-64" />
+```
+
 ---
 
 ## Forms & tables
@@ -1533,6 +1573,46 @@ content at the card's bottom.
 
 ---
 
+### BasePillPickerModal
+
+"Pick one of many" modal: every item rendered as a clickable pill, narrowed
+by a free-text filter and an optional segmented group toggle. Clicking a pill
+emits `pick` with the item; backdrop / Escape / the footer Close emit `close`.
+Narrowing state lives inside, so a `v-if`-mounted instance always opens fresh.
+
+**Props:** `title` + `items: PillPickerItem[]` (required);
+`groups?: SegmentedOption<string>[]` (renders the group toggle with an
+`allLabel` option prepended, narrowing by each item's `group`); `icon?`
+(defaults to the magnifying glass), `subtitle?`, `searchPlaceholder`,
+`emptyMessage`, `noMatchMessage`, `mono` (mono font for the filter input and
+pills — symbols, codes, ids), `maxWidthClass` (default `max-w-2xl`),
+`closeText`, `groupAriaLabel`, `allLabel`.
+
+**Emits:** `pick(item: PillPickerItem)`, `close`.
+
+```ts
+interface PillPickerItem {
+  id: string      // unique key; identifies the pick
+  label: string   // pill text; what the filter matches
+  group?: string  // segmented-toggle bucket
+  title?: string  // pill tooltip
+}
+```
+
+```vue
+<BasePillPickerModal
+  v-if="open"
+  title="Symbols"
+  :items="symbols.map(s => ({ id: s.id, label: s.symbol, group: s.assetClass }))"
+  :groups="[{ value: 'STOCK', label: 'STOCK' }, { value: 'CRYPTO', label: 'CRYPTO' }]"
+  mono
+  @pick="apply"
+  @close="open = false"
+/>
+```
+
+---
+
 ## Composables
 
 ```ts
@@ -1548,6 +1628,7 @@ import {
   useNotifications,
   useQueryParamSync,
   useFieldClasses,
+  usePolling,
 } from 'mgv-backoffice'
 ```
 
@@ -1555,7 +1636,7 @@ import {
 | ---------- | ------- |
 | `initTheme({ storageKey? })` | Explicitly initialize the theme singleton. Call in your app entry point **before mounting** when you need a custom storage key — library components call `useTheme()` internally, so a component mounting first would otherwise lock in the default key (a dev-mode warning fires if that happens). |
 | `useTheme({ storageKey? })` | Singleton dark/light controller. Toggles `<html class="dark">` and persists via localStorage (default key `'mgv-theme'`). Prefer `initTheme` at app entry for custom keys. |
-| `useThemeClasses()` | Named Tailwind class roles for dark/light (card, border, primaryText, mutedText, dimText, input, ghostButton, emeraldText, redText, …). Returns computed refs auto-unwrapped in templates. |
+| `useThemeClasses()` | Named Tailwind class roles for dark/light (card, border, primaryText, mutedText, dimText, input, ghostButton, emeraldText, redText, …). Since 1.34.0 returns a `reactive` object of plain strings — bind `t.card` directly, never `t.card.value` (the old ComputedRef shape leaked ref internals into `:class` bindings). |
 | `useEscapeKey(handler)` | Component-scoped Escape key listener. |
 | `useDebouncedRef(source, delay?)` | Debounced mirror of a ref. Timer cleared on scope dispose. |
 | `useToast(durationMs?)` | Per-component toast state: `{ showToast, toastMessage, toastType, showToastMessage }`. |
@@ -1564,6 +1645,7 @@ import {
 | `useNotifications()` | Singleton notification state shared by the sidebar bell and `BaseNotificationPanel`: `{ notifications, unreadCount, open, openPanel, closePanel, togglePanel, setNotifications, add, remove, markRead, markAllRead, clear }`. |
 | `useQueryParamSync()` | URL-query mirroring for filterable views: `{ qparam(name), qenum(name, allowed, fallback), replaceQuery(next) }`. Read filters from the query string once on setup, write changes back with `router.replace` (no-op when unchanged) so filtered views stay shareable without polluting history. |
 | `useFieldClasses()` | Shared form-field class strings for the gray/emerald form skin: `{ label, input, requiredInput(value) }`. `requiredInput` returns a red border+ring skin while the value is empty and the standard skin otherwise. |
+| `usePolling(fn, intervalMs, { immediate?, pauseWhenHidden? })` | Visibility-gated polling loop bound to the component lifecycle: starts on mount, stops on unmount, pauses while the tab is hidden and refreshes + resumes on return to visible (both default on). Pass `intervalMs: null` for refresh-only mode (run on mount + each return-to-visible, no timer). Returns `{ start, stop, active }`. Catch errors inside `fn` — the loop never swallows rejections. |
 
 ---
 

package/dist/components/BaseCodeBlock.vue.d.ts

@@ -0,0 +1,17 @@
+type __VLS_Props = {
+    /** The raw text to render. Whitespace is preserved verbatim. */
+    code: string;
+    /** Visual style: tinted fill ('soft') or bordered card ('bordered'). */
+    variant?: 'soft' | 'bordered';
+    /** Text size + padding: 'sm' (roomy) or 'xs' (dense). */
+    size?: 'sm' | 'xs';
+    /** Optional Tailwind max-height utility, e.g. 'max-h-96'. */
+    maxHeightClass?: string;
+};
+declare const __VLS_export: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    size: "sm" | "xs";
+    variant: "soft" | "bordered";
+    maxHeightClass: string;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/components/BasePillPickerModal.vue.d.ts

@@ -0,0 +1,43 @@
+import { Component } from 'vue';
+import { PillPickerItem } from '../types/pillPicker';
+import { SegmentedOption } from '../types/segmented';
+interface Props {
+    title: string;
+    items: PillPickerItem[];
+    /**
+     * Group toggle rendered next to the text filter. When set, an "All"
+     * option is prepended and pills are narrowed by their `group` field.
+     */
+    groups?: SegmentedOption<string>[];
+    /** Icon for the modal shell. Defaults to the magnifying glass. */
+    icon?: Component;
+    subtitle?: string;
+    searchPlaceholder?: string;
+    emptyMessage?: string;
+    noMatchMessage?: string;
+    /** Render the filter input and pill labels in the mono font (symbols, codes, ids). */
+    mono?: boolean;
+    maxWidthClass?: string;
+    closeText?: string;
+    /** aria-label of the group toggle. */
+    groupAriaLabel?: string;
+    allLabel?: string;
+}
+declare const __VLS_export: import('vue').DefineComponent<Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {} & {
+    close: () => any;
+    pick: (item: PillPickerItem) => any;
+}, string, import('vue').PublicProps, Readonly<Props> & Readonly<{
+    onClose?: (() => any) | undefined;
+    onPick?: ((item: PillPickerItem) => any) | undefined;
+}>, {
+    maxWidthClass: string;
+    searchPlaceholder: string;
+    emptyMessage: string;
+    noMatchMessage: string;
+    mono: boolean;
+    closeText: string;
+    groupAriaLabel: string;
+    allLabel: string;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/components/BaseToolbarButton.vue.d.ts

@@ -1,4 +1,4 @@
-type ToolbarVariant = 'neutral' | 'danger';
+type ToolbarVariant = 'neutral' | 'danger' | 'ghost';
 type __VLS_Props = {
     label?: string;
     variant?: ToolbarVariant;

package/dist/composables/usePolling.d.ts

@@ -0,0 +1,31 @@
+import { Ref } from 'vue';
+export interface UsePollingOptions {
+    /** Run `fn` immediately when polling starts (mount / resume). Default true. */
+    immediate?: boolean;
+    /**
+     * Pause the interval while the tab is hidden and refresh + resume when it
+     * becomes visible again — a hidden tab has no reason to keep waking the
+     * backend. Default true.
+     */
+    pauseWhenHidden?: boolean;
+}
+/**
+ * Visibility-gated polling loop bound to the component lifecycle.
+ *
+ * Starts on mount, stops on unmount. With `pauseWhenHidden` (the default)
+ * the interval is torn down on `document.visibilitychange` → hidden and
+ * re-armed — with an immediate refresh — when the tab is shown again.
+ *
+ * Pass `intervalMs: null` for a refresh-only mode: `fn` runs on mount and
+ * on every return-to-visible, but no interval is scheduled. Useful for
+ * "reload this badge when the user comes back" data that doesn't warrant
+ * a timer.
+ *
+ * Rejections from an async `fn` are the caller's to handle — catch inside
+ * `fn`; the loop itself never swallows or reports them.
+ */
+export declare function usePolling(fn: () => void | Promise<void>, intervalMs: number | null, options?: UsePollingOptions): {
+    start: () => void;
+    stop: () => void;
+    active: Readonly<Ref<boolean>>;
+};

package/dist/composables/useThemeClasses.d.ts

@@ -1,4 +1,3 @@
-import { ComputedRef } from 'vue';
 /**
  * Centralized dark/light Tailwind class strings.
  *
@@ -12,51 +11,55 @@ import { ComputedRef } from 'vue';
  *     <p :class="t.mutedText">...</p>
  *   </div>
  *
- * Vue auto-unwraps the computed refs inside template `:class` bindings,
- * so callers do not write `.value`.
+ * The returned object is `reactive()`, so property access yields the
+ * plain class string while staying reactive to theme flips. (It used to
+ * be a plain object of ComputedRefs — Vue does NOT unwrap refs nested in
+ * plain objects inside template bindings, so `:class="t.card"` rendered
+ * the ref's own keys — `fn dep __v_isRef …` — instead of the classes.)
+ * Property access is string-valued now: do not append `.value`.
  */
 export interface ThemeClasses {
     /** Card surface: bg-gray-800 / bg-white, with border. */
-    card: ComputedRef<string>;
+    card: string;
     /** Slightly darker card surface: bg-gray-900 / bg-white, with border. */
-    cardAlt: ComputedRef<string>;
+    cardAlt: string;
     /** Page background. */
-    pageBg: ComputedRef<string>;
+    pageBg: string;
     /** Standard border between cards/sections. */
-    border: ComputedRef<string>;
+    border: string;
     /** Subtle divider (lighter than border). */
-    divider: ComputedRef<string>;
+    divider: string;
     /** Page headings: white / gray-900. */
-    primaryText: ComputedRef<string>;
+    primaryText: string;
     /** Softer headings: gray-100 / gray-800. */
-    primaryTextSoft: ComputedRef<string>;
+    primaryTextSoft: string;
     /** Body copy on cards: gray-200 / gray-700. */
-    bodyText: ComputedRef<string>;
+    bodyText: string;
     /** Form labels: gray-300 / gray-700. */
-    label: ComputedRef<string>;
+    label: string;
     /** Secondary text: gray-400 / gray-600. */
-    mutedText: ComputedRef<string>;
+    mutedText: string;
     /** Tertiary text: gray-500 / gray-600. */
-    subtleText: ComputedRef<string>;
+    subtleText: string;
     /** Dimmest text: gray-500 in dark / gray-400 in light. */
-    dimText: ComputedRef<string>;
+    dimText: string;
     /** Slightly more contrast than dimText: gray-400 / gray-500. */
-    dimTextAlt: ComputedRef<string>;
+    dimTextAlt: string;
     /** Big illustration / empty-state icon: gray-600 / gray-300. */
-    illustration: ComputedRef<string>;
+    illustration: string;
     /** Standard text input. */
-    input: ComputedRef<string>;
+    input: string;
     /** Input + placeholder colour. */
-    inputWithPlaceholder: ComputedRef<string>;
+    inputWithPlaceholder: string;
     /** Ghost / Cancel button. */
-    ghostButton: ComputedRef<string>;
+    ghostButton: string;
     /** Emerald accent text: emerald-400 / emerald-600. */
-    emeraldText: ComputedRef<string>;
+    emeraldText: string;
     /** Amber accent text: amber-400 / amber-600. */
-    amberText: ComputedRef<string>;
+    amberText: string;
     /** Amber heading-weight: amber-300 / amber-700. */
-    amberTextStrong: ComputedRef<string>;
+    amberTextStrong: string;
     /** Red accent text: red-400 / red-500. */
-    redText: ComputedRef<string>;
+    redText: string;
 }
 export declare function useThemeClasses(): ThemeClasses;

package/dist/index.d.ts

@@ -32,6 +32,7 @@ export { default as BaseChipButton } from './components/BaseChipButton.vue';
 export { default as BaseRemoveButton } from './components/BaseRemoveButton.vue';
 export { default as BaseStatusPill } from './components/BaseStatusPill.vue';
 export { default as BaseFileDropzone } from './components/BaseFileDropzone.vue';
+export { default as BaseCodeBlock } from './components/BaseCodeBlock.vue';
 export { default as BaseInput } from './components/BaseInput.vue';
 export { default as BaseSelect } from './components/BaseSelect.vue';
 export { default as BaseDropdown } from './components/BaseDropdown.vue';
@@ -41,6 +42,7 @@ export { default as BaseSpecFields } from './components/BaseSpecFields.vue';
 export { default as BaseStatBreakdown } from './components/BaseStatBreakdown.vue';
 export { default as BaseFilterChip } from './components/BaseFilterChip.vue';
 export { default as BaseCredentialsForm } from './components/BaseCredentialsForm.vue';
+export { default as BasePillPickerModal } from './components/BasePillPickerModal.vue';
 export type { CredentialsView, CredentialsUpdate } from './components/BaseCredentialsForm.vue';
 export { useTheme, initTheme } from './composables/useTheme';
 export type { UseThemeOptions } from './composables/useTheme';
@@ -56,6 +58,8 @@ export { useNotifications } from './composables/useNotifications';
 export { useQueryParamSync } from './composables/useQueryParamSync';
 export { useFieldClasses } from './composables/useFieldClasses';
 export type { FieldClasses } from './composables/useFieldClasses';
+export { usePolling } from './composables/usePolling';
+export type { UsePollingOptions } from './composables/usePolling';
 export { AlertEnum } from './enums/AlertEnum';
 export { BaseBadgeEnum } from './enums/BaseBadgeEnum';
 export { BaseButtonEnum } from './enums/BaseButtonEnum';
@@ -76,12 +80,14 @@ export type { DropdownOption } from './types/dropdown';
 export type { TableColumn } from './types/table';
 export type { SpecField, SpecFieldType, SpecFieldValue } from './types/specField';
 export type { StatBreakdownItem } from './types/statBreakdown';
+export type { PillPickerItem } from './types/pillPicker';
 export { getBaseColor, getBaseColorOf } from './utils/util';
 export { methodBadgeSolid, methodBadgeBright, methodBadgeTinted, statusBadgeSolid, statusBadgeTinted, statusBadgeSoft, } from './utils/httpColors';
 export { rowKeyMissing, rowValueMissing } from './utils/kvRows';
 export type { KeyValueRowLike } from './utils/kvRows';
 export { sanitizeHtml, isSafeHref } from './utils/sanitizeHtml';
-export { fmtNumber, fmtDate, fmtDateTime, fmtDateTimeMs, fmtDateShort, fmtCalendarDate, fmtCalendarDateTime, fmtMsAsSeconds, fmtBytes, fmtPrice, fmtPct, fmtUsd, fmtDuration, } from './utils/format';
+export { fmtNumber, fmtDate, fmtDateTime, fmtDateTimeMs, fmtDateShort, fmtCalendarDate, fmtCalendarDateTime, fmtMsAsSeconds, fmtBytes, fmtPrice, fmtPct, fmtUsd, fmtDuration, formatJson, stringifyValue, } from './utils/format';
+export { isValidAbsoluteUrl, isValidJson, isValidXml, isValidBase64, } from './utils/validate';
 export { buildSpecParams, firstInvalidNumericSpec } from './utils/specForm';
 export { computePnL } from './utils/pnl';
 export type { PnL, PnLInputs } from './utils/pnl';

package/dist/types/pillPicker.d.ts

@@ -0,0 +1,14 @@
+/**
+ * One clickable pill in a BasePillPickerModal.
+ *
+ * `id` must be unique (it keys the pill and identifies the pick),
+ * `label` is what the pill shows and what the free-text filter matches,
+ * `group` assigns the pill to one of the modal's segmented-filter groups,
+ * `title` becomes the pill's tooltip.
+ */
+export interface PillPickerItem {
+    id: string;
+    label: string;
+    group?: string;
+    title?: string;
+}