mgv-backoffice 1.29.0 → 1.31.0

package/README.md

@@ -636,8 +636,10 @@ import { getBaseColor, getBaseColorOf } from 'mgv-backoffice'
 import {
   methodBadgeSolid,
   methodBadgeBright,
+  methodBadgeTinted,
   statusBadgeSolid,
   statusBadgeTinted,
+  statusBadgeSoft,
 } from 'mgv-backoffice'
 ```
 
@@ -646,6 +648,27 @@ return saturated `bg-*-600` classes for use on neutral surfaces; `Bright` /
 `Tinted` variants return softer combinations suitable for cards. `statusBadgeTinted`
 takes `(status, isDark)` to adapt between themes.
 
+`methodBadgeTinted(method, isDark)` gives each method its own hue on a soft
+tinted surface (`bg-*-500/15` dark / `bg-*-100` light; GET blue, POST emerald,
+PUT amber, DELETE red, PATCH purple, HEAD sky) — the card-chip palette used by
+WireMate's mock/stub cards. `statusBadgeSoft(status, isDark)` is its status
+companion keyed by status class (emerald 2xx / sky 3xx / amber 4xx / red 5xx).
+
+### Key/value row validators
+
+```ts
+import { rowKeyMissing, rowValueMissing } from 'mgv-backoffice'
+```
+
+| Function          | Signature                                                              | Returns |
+| ----------------- | ---------------------------------------------------------------------- | ------- |
+| `rowValueMissing` | `(row: { key?, value?, matcherType? }) => boolean`                     | `true` when the row has a key but no value. |
+| `rowKeyMissing`   | `(row: { key?, value?, matcherType? }) => boolean`                     | `true` when the row has a value but no key. |
+
+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.
+
 ### HTML sanitizer
 
 ```ts
@@ -692,11 +715,31 @@ API values can be passed without pre-sanitising.
 | `fmtNumber`    | `(n: number \| string \| null \| undefined, digits = 4) => string` | Fixed-fraction number; em-dash for null/undefined/non-finite. Accepts numeric strings. |
 | `fmtDate`      | `(s: string \| number \| null \| undefined) => string`          | Locale date-time from ISO string or epoch; em-dash on empty, raw value on parse failure. |
 | `fmtDateTime`  | `(ms: number) => string`                                        | Compact `"Mon D, HH:MM"` label from epoch-millis (chart axes/tooltips). |
+| `fmtDateTimeMs`| `(s: string \| number) => string`                               | Full 24-hour locale date-time WITH the millisecond fraction — for dense feeds where same-second rows must stay distinguishable. |
 | `fmtDateShort` | `(ms: number) => string`                                        | Short `"Mon D"` calendar label from epoch-millis. |
+| `fmtCalendarDate` | `(s: string \| number \| null \| undefined) => string`       | `"Mon D, YYYY"` en-US calendar label; em-dash on empty, raw value on parse failure. |
+| `fmtCalendarDateTime` | `(s: string \| number \| null \| undefined) => string`   | `"Mon D, YYYY, HH:MM"` en-US calendar label with time of day. |
+| `fmtMsAsSeconds` | `(ms: number \| null \| undefined) => string`                 | `"= 1.50 s"` magnitude hint for millisecond inputs (3 decimals below 1 s); `''` for non-positive input. |
+| `fmtBytes`     | `(bytes: number \| null \| undefined) => string`                | `"512 B"` / `"1.5 KB"` / `"2.0 MB"`; `''` for zero/falsy input. |
 | `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"`. |
 
+### Spec-form helpers
+
+```ts
+import { buildSpecParams, firstInvalidNumericSpec } from 'mgv-backoffice'
+```
+
+Value-map helpers for spec-driven forms (the state behind `BaseSpecFields`).
+A spec whose `default` is `null` is treated as OPTIONAL — blank means "knob
+disabled" and passes validation.
+
+| Function                 | Signature | Returns |
+| ------------------------ | --------- | ------- |
+| `buildSpecParams`        | `(specs: SpecField[] \| undefined, existing: Record<string, SpecFieldValue>) => Record<string, SpecFieldValue>` | Value map seeded from each spec's `default`, keeping overlapping values the caller already has. |
+| `firstInvalidNumericSpec`| `(specs: SpecField[] \| undefined, params: Record<string, SpecFieldValue>) => string \| null` | Label of the first blank / NaN numeric field, or `null` when all numerics are valid. |
+
 ### Profit & loss
 
 ```ts
@@ -1388,6 +1431,72 @@ validation can catch it.
   @update="(key, value) => (form.params[key] = value)" />
 ```
 
+### BaseFilterChip
+
+Colour-coded toggleable filter chip — one-click event/category filters above
+a data feed. Idle renders a tinted border/background in the semantic colour;
+active renders a solid fill with white text (`aria-pressed` reflects the
+state). Layout classes (`h-9 flex-1`, …) pass through the class attribute;
+click handlers bind natively on the component.
+
+**Props:**
+
+| Prop       | Type      | Default   | Description |
+| ---------- | --------- | --------- | ----------- |
+| `label`    | `String`  | `''`      | Chip text; the default slot overrides it. |
+| `color`    | `'emerald' \| 'sky' \| 'amber' \| 'red' \| 'slate'` | `'slate'` | Semantic colour of the idle tint and active fill. |
+| `active`   | `Boolean` | `false`   | Whether the chip's filter is applied (solid fill). |
+| `disabled` | `Boolean` | `false`   | Greys out + blocks the click. |
+| `title`    | `String`  | —         | Native tooltip. |
+
+```vue
+<BaseFilterChip
+  v-for="f in filters"
+  :key="f.key"
+  class="h-9 flex-1"
+  :color="f.color"
+  :active="isActive(f)"
+  :title="f.title"
+  @click="toggle(f)"
+>{{ f.label }}</BaseFilterChip>
+```
+
+### BaseCredentialsForm
+
+One service's API-credentials card: key id + secret + base/data URLs, with
+the has-secret handling (placeholder dots, blank-keeps-stored-secret), the
+save-validation ladder and a saving spinner. Load/save results are EMITTED —
+the parent owns toasts / error banners. Exposes `load()` so a parent Reload
+button can re-pull several cards in parallel.
+
+**Props:** `title` + `idPrefix` + `fetchFn: () => Promise<CredentialsView>` +
+`updateFn: (body: CredentialsUpdate) => Promise<CredentialsView>` +
+`defaults: { baseUrl, dataUrl }` (required); `subtitle`, `keyLabel`,
+`keyPlaceholder`, `secretLabel`, `secretPlaceholder`, `secretSetHint`,
+`permissionsHint`, `requiredKeyMessage`, `requiredSecretMessage`,
+`savedMessage`, `saveLabel` (optional copy overrides).
+
+**Slots:** `no-secret-hint` — rich help while no secret is stored;
+`base-url-extra` (`{ form }`) — extras under the Base URL field (e.g.
+live/paper shortcut buttons that write into the form); `footer` — extra
+content at the card's bottom.
+
+**Emits:** `saved(message)`, `error(message)`, `load-error(message)`.
+
+```vue
+<BaseCredentialsForm
+  ref="card"
+  title="Alpaca API"
+  id-prefix="alpaca"
+  :fetch-fn="fetchAlpaca"
+  :update-fn="updateAlpaca"
+  :defaults="{ baseUrl: LIVE_BASE, dataUrl: DATA_URL }"
+  @saved="onSaved"
+  @error="onError"
+  @load-error="onLoadError"
+/>
+```
+
 ---
 
 ## Composables
@@ -1403,6 +1512,8 @@ import {
   useMobileSidebar,
   useSidebarCollapse,
   useNotifications,
+  useQueryParamSync,
+  useFieldClasses,
 } from 'mgv-backoffice'
 ```
 
@@ -1417,6 +1528,8 @@ import {
 | `useMobileSidebar()` | Singleton state shared between `BaseSidebar` and `BaseAppLayout` for the off-canvas open/closed flag. |
 | `useSidebarCollapse({ storageKey? })` | Singleton collapsed/expanded state for the desktop sidebar rail, shared between `BaseSidebar` and `BaseAppLayout` and persisted to localStorage (default key `'mgv-sidebar-collapsed'`). |
 | `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. |
 
 ---
 

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

@@ -0,0 +1,80 @@
+export interface CredentialsView {
+    keyId: string | null;
+    baseUrl: string;
+    dataUrl: string;
+    hasSecret: boolean;
+}
+export interface CredentialsUpdate {
+    keyId: string;
+    secretKey?: string;
+    baseUrl: string;
+    dataUrl: string;
+}
+type __VLS_Props = {
+    title: string;
+    subtitle?: string;
+    idPrefix: string;
+    keyLabel?: string;
+    keyPlaceholder?: string;
+    secretLabel?: string;
+    secretPlaceholder?: string;
+    secretSetHint?: string;
+    permissionsHint?: string;
+    requiredKeyMessage?: string;
+    requiredSecretMessage?: string;
+    savedMessage?: string;
+    saveLabel?: string;
+    fetchFn: () => Promise<CredentialsView>;
+    updateFn: (body: CredentialsUpdate) => Promise<CredentialsView>;
+    defaults: {
+        baseUrl: string;
+        dataUrl: string;
+    };
+};
+declare function load(): Promise<void>;
+declare var __VLS_23: {}, __VLS_30: {
+    form: {
+        keyId: string;
+        secretKey: string;
+        baseUrl: string;
+        dataUrl: string;
+    };
+}, __VLS_44: {};
+type __VLS_Slots = {} & {
+    'no-secret-hint'?: (props: typeof __VLS_23) => any;
+} & {
+    'base-url-extra'?: (props: typeof __VLS_30) => any;
+} & {
+    footer?: (props: typeof __VLS_44) => any;
+};
+declare const __VLS_base: import('vue').DefineComponent<__VLS_Props, {
+    load: typeof load;
+}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {} & {
+    error: (message: string) => any;
+    saved: (message: string) => any;
+    "load-error": (message: string) => any;
+}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onError?: ((message: string) => any) | undefined;
+    onSaved?: ((message: string) => any) | undefined;
+    "onLoad-error"?: ((message: string) => any) | undefined;
+}>, {
+    subtitle: string;
+    keyLabel: string;
+    keyPlaceholder: string;
+    secretLabel: string;
+    secretPlaceholder: string;
+    secretSetHint: string;
+    permissionsHint: string;
+    requiredKeyMessage: string;
+    requiredSecretMessage: string;
+    savedMessage: string;
+    saveLabel: string;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

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

@@ -0,0 +1,31 @@
+type FilterChipColor = 'emerald' | 'sky' | 'amber' | 'red' | 'slate';
+type __VLS_Props = {
+    /** Chip text; the default slot overrides it. */
+    label?: string;
+    /** Semantic colour of both the idle tint and the active solid fill. */
+    color?: FilterChipColor;
+    /** Whether the chip's filter is currently applied (solid fill). */
+    active?: boolean;
+    disabled?: boolean;
+    /** Native tooltip. */
+    title?: string;
+};
+declare var __VLS_1: {};
+type __VLS_Slots = {} & {
+    default?: (props: typeof __VLS_1) => any;
+};
+declare const __VLS_base: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    title: string;
+    color: FilterChipColor;
+    label: string;
+    disabled: boolean;
+    active: boolean;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/composables/useFieldClasses.d.ts

@@ -0,0 +1,29 @@
+import { ComputedRef } from 'vue';
+/**
+ * Shared form-field class strings for the gray/emerald form skin
+ * (the WireMate mock-form family). Extracted because the exact same
+ * `labelClasses` / `inputClasses` / `requiredInputClasses` trio was
+ * copy-pasted across every form section component.
+ *
+ * Usage:
+ *
+ *   const f = useFieldClasses()
+ *   <label :class="f.label">Name</label>
+ *   <input :class="f.input" />
+ *   <input :class="f.requiredInput(value)" />   // red skin while empty
+ *
+ * Vue auto-unwraps the computed refs in template bindings; `requiredInput`
+ * is a plain function and is called with the current field value.
+ */
+export interface FieldClasses {
+    /** Form label: gray-300 / gray-600. */
+    label: ComputedRef<string>;
+    /** Standard input skin: gray-800 dark surface / white light surface, emerald focus. */
+    input: ComputedRef<string>;
+    /**
+     * Input skin for required fields: red border + ring while the value is
+     * empty (undefined / null / blank after trim), the standard skin otherwise.
+     */
+    requiredInput: (value: string | number | undefined | null) => string;
+}
+export declare function useFieldClasses(): FieldClasses;

package/dist/composables/useQueryParamSync.d.ts

@@ -0,0 +1,11 @@
+/**
+ * URL-query mirroring helpers for filterable views: read a filter's initial
+ * state from the query string once on setup, then write changes back with
+ * `replaceQuery` so a filtered view can be copied, shared and bookmarked
+ * without filter tweaks piling up in the browser history.
+ */
+export declare function useQueryParamSync(): {
+    qparam: (name: string) => string;
+    qenum: <T extends string>(name: string, allowed: readonly T[], fallback: T) => T;
+    replaceQuery: (next: Record<string, string>) => void;
+};

package/dist/index.d.ts

@@ -38,6 +38,9 @@ export { default as BaseSegmentedControl } from './components/BaseSegmentedContr
 export { default as BaseTable } from './components/BaseTable.vue';
 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 type { CredentialsView, CredentialsUpdate } from './components/BaseCredentialsForm.vue';
 export { useTheme, initTheme } from './composables/useTheme';
 export type { UseThemeOptions } from './composables/useTheme';
 export { useThemeClasses } from './composables/useThemeClasses';
@@ -49,6 +52,9 @@ export { useMobileSidebar } from './composables/useMobileSidebar';
 export { useSidebarCollapse } from './composables/useSidebarCollapse';
 export type { UseSidebarCollapseOptions } from './composables/useSidebarCollapse';
 export { useNotifications } from './composables/useNotifications';
+export { useQueryParamSync } from './composables/useQueryParamSync';
+export { useFieldClasses } from './composables/useFieldClasses';
+export type { FieldClasses } from './composables/useFieldClasses';
 export { AlertEnum } from './enums/AlertEnum';
 export { BaseBadgeEnum } from './enums/BaseBadgeEnum';
 export { BaseButtonEnum } from './enums/BaseButtonEnum';
@@ -70,8 +76,11 @@ export type { TableColumn } from './types/table';
 export type { SpecField, SpecFieldType, SpecFieldValue } from './types/specField';
 export type { StatBreakdownItem } from './types/statBreakdown';
 export { getBaseColor, getBaseColorOf } from './utils/util';
-export { methodBadgeSolid, methodBadgeBright, statusBadgeSolid, statusBadgeTinted, } from './utils/httpColors';
+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, fmtDateShort, fmtPrice, fmtPct, fmtUsd, fmtDuration, } from './utils/format';
+export { fmtNumber, fmtDate, fmtDateTime, fmtDateTimeMs, fmtDateShort, fmtCalendarDate, fmtCalendarDateTime, fmtMsAsSeconds, fmtBytes, fmtPrice, fmtPct, fmtUsd, fmtDuration, } from './utils/format';
+export { buildSpecParams, firstInvalidNumericSpec } from './utils/specForm';
 export { computePnL } from './utils/pnl';
 export type { PnL, PnLInputs } from './utils/pnl';

package/dist/types/specField.d.ts

@@ -10,6 +10,11 @@ export interface SpecField {
     key: string;
     label: string;
     type: SpecFieldType;
+    /**
+     * Default value the form seeds the field with. `null` marks the field as
+     * OPTIONAL for `firstInvalidNumericSpec` (blank = "knob disabled").
+     */
+    default?: SpecFieldValue | null;
     /** Choices for `type: 'select'`. */
     options?: string[] | null;
     /** Step for numeric inputs; defaults to 1 (integer) / 0.01 (decimal). */