mgv-backoffice 1.29.0 → 1.31.0

package/src/composables/useFieldClasses.ts

@@ -0,0 +1,56 @@
+import { computed, type ComputedRef } from 'vue'
+import { useTheme } from './useTheme'
+
+/**
+ * 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 function useFieldClasses(): FieldClasses {
+  const { isDark } = useTheme()
+
+  const label = computed(() =>
+    isDark.value ? 'text-gray-300' : 'text-gray-600',
+  )
+
+  const input = computed(() =>
+    isDark.value
+      ? 'bg-gray-800 border-gray-600 text-gray-100 placeholder-gray-500 focus:ring-emerald-500 focus:border-emerald-500'
+      : 'bg-white border-gray-300 text-gray-800 focus:ring-emerald-500 focus:border-emerald-500',
+  )
+
+  function requiredInput(value: string | number | undefined | null): string {
+    const isEmpty = value === undefined || value === null || String(value).trim() === ''
+    if (isEmpty) {
+      return isDark.value
+        ? 'bg-gray-800 border-red-500 text-gray-100 placeholder-gray-500 focus:ring-red-500 focus:border-red-500 ring-1 ring-red-500/30'
+        : 'bg-white border-red-400 text-gray-800 focus:ring-red-500 focus:border-red-500 ring-1 ring-red-400/30'
+    }
+    return input.value
+  }
+
+  return { label, input, requiredInput }
+}

package/src/composables/useQueryParamSync.test.ts

@@ -0,0 +1,56 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+
+const replace = vi.fn()
+let query: Record<string, string> = {}
+
+vi.mock('vue-router', () => ({
+  useRoute: () => ({ query }),
+  useRouter: () => ({ replace }),
+}))
+
+import { useQueryParamSync } from './useQueryParamSync'
+
+beforeEach(() => {
+  replace.mockReset()
+  query = {}
+})
+
+describe('qparam / qenum', () => {
+  it('reads string params and returns "" for absent ones', () => {
+    query = { q: 'AMD' }
+    const { qparam } = useQueryParamSync()
+    expect(qparam('q')).toBe('AMD')
+    expect(qparam('missing')).toBe('')
+  })
+
+  it('qenum only accepts allowed values, else the fallback', () => {
+    query = { range: '7D', bogus: 'nope' }
+    const { qenum } = useQueryParamSync()
+    expect(qenum('range', ['1D', '7D', '30D'], '1D')).toBe('7D')
+    expect(qenum('bogus', ['a', 'b'], 'a')).toBe('a')
+    expect(qenum('missing', ['a', 'b'], 'b')).toBe('b')
+  })
+})
+
+describe('replaceQuery', () => {
+  it('replaces when the query differs', () => {
+    query = { q: 'old' }
+    const { replaceQuery } = useQueryParamSync()
+    replaceQuery({ q: 'new' })
+    expect(replace).toHaveBeenCalledWith({ query: { q: 'new' } })
+  })
+
+  it('no-ops when the query already matches (same keys and values)', () => {
+    query = { q: 'AMD', range: '7D' }
+    const { replaceQuery } = useQueryParamSync()
+    replaceQuery({ q: 'AMD', range: '7D' })
+    expect(replace).not.toHaveBeenCalled()
+  })
+
+  it('replaces when a key is removed (defaults omitted)', () => {
+    query = { q: 'AMD', range: '7D' }
+    const { replaceQuery } = useQueryParamSync()
+    replaceQuery({ q: 'AMD' })
+    expect(replace).toHaveBeenCalledWith({ query: { q: 'AMD' } })
+  })
+})

package/src/composables/useQueryParamSync.ts

@@ -0,0 +1,42 @@
+import { useRoute, useRouter } from 'vue-router'
+
+/**
+ * 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 function useQueryParamSync() {
+  const route = useRoute()
+  const router = useRouter()
+
+  /** String value of a query param ('' when absent or repeated). */
+  function qparam(name: string): string {
+    const v = route.query[name]
+    return typeof v === 'string' ? v : ''
+  }
+
+  /**
+   * Enum-ish param: only values from `allowed` pass; anything else in a
+   * hand-edited URL falls back to the default.
+   */
+  function qenum<T extends string>(name: string, allowed: readonly T[], fallback: T): T {
+    const v = qparam(name)
+    return (allowed as readonly string[]).includes(v) ? (v as T) : fallback
+  }
+
+  /**
+   * Mirror the given params into the URL with `router.replace` (not `push`),
+   * no-oping when nothing changed so timers/auto-refresh don't issue redundant
+   * navigations. Callers omit default values so the address stays clean.
+   */
+  function replaceQuery(next: Record<string, string>): void {
+    const current = route.query
+    const same =
+      Object.keys(next).length === Object.keys(current).length &&
+      Object.entries(next).every(([k, v]) => current[k] === v)
+    if (!same) void router.replace({ query: next })
+  }
+
+  return { qparam, qenum, replaceQuery }
+}

package/src/index.ts

@@ -45,6 +45,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'
 
 // Composables
 export { useTheme, initTheme } from './composables/useTheme'
@@ -58,6 +61,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'
 
 // Enums
 export { AlertEnum } from './enums/AlertEnum'
@@ -88,19 +94,29 @@ 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 { buildSpecParams, firstInvalidNumericSpec } from './utils/specForm'
 export { computePnL } from './utils/pnl'
 export type { PnL, PnLInputs } from './utils/pnl'

package/src/types/specField.ts

@@ -11,6 +11,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). */

package/src/utils/format.test.ts

@@ -3,6 +3,7 @@ import {
   fmtNumber,
   fmtDate,
   fmtDateTime,
+  fmtDateTimeMs,
   fmtDateShort,
   fmtPrice,
   fmtPct,
@@ -10,6 +11,21 @@ import {
   fmtDuration,
 } from './format'
 
+describe('fmtDateTimeMs', () => {
+  it('keeps the millisecond fraction so same-second rows stay distinguishable', () => {
+    const out = fmtDateTimeMs('2026-06-08T14:30:51.123Z')
+    expect(out).toMatch(/51[.,:]?\d*123|123/) // ms fraction present, locale separators vary
+  })
+
+  it('accepts epoch millis', () => {
+    expect(fmtDateTimeMs(0)).toMatch(/19?70/)
+  })
+
+  it('falls back to the raw value for unparseable input', () => {
+    expect(fmtDateTimeMs('not-a-date')).toBe('Invalid Date')
+  })
+})
+
 const EM_DASH = '—'
 
 // Fraction digits are locale-stable even when the grouping/decimal
@@ -162,3 +178,58 @@ describe('fmtDuration', () => {
     expect(fmtDuration(59_000)).toBe('0m')
   })
 })
+
+import { fmtCalendarDate, fmtCalendarDateTime, fmtMsAsSeconds, fmtBytes } from './format'
+
+describe('fmtCalendarDate', () => {
+  it('renders a "Mon D, YYYY" en-US label', () => {
+    expect(fmtCalendarDate('2026-01-05T10:30:00Z')).toMatch(/^Jan \d{1,2}, 2026$/)
+  })
+  it('renders an em-dash for empty input', () => {
+    expect(fmtCalendarDate(null)).toBe(EM_DASH)
+    expect(fmtCalendarDate('')).toBe(EM_DASH)
+  })
+  it('falls back to the raw value for unparseable input', () => {
+    expect(fmtCalendarDate('not-a-date')).toBe('not-a-date')
+  })
+})
+
+describe('fmtCalendarDateTime', () => {
+  it('includes the time of day', () => {
+    expect(fmtCalendarDateTime('2026-01-05T10:30:00Z')).toMatch(/2026.*\d{1,2}:\d{2}/)
+  })
+  it('renders an em-dash for empty input', () => {
+    expect(fmtCalendarDateTime(undefined)).toBe(EM_DASH)
+  })
+})
+
+describe('fmtMsAsSeconds', () => {
+  it('renders 2 decimals at >= 1s', () => {
+    expect(fmtMsAsSeconds(1500)).toBe('= 1.50 s')
+  })
+  it('renders 3 decimals below 1s', () => {
+    expect(fmtMsAsSeconds(250)).toBe('= 0.250 s')
+  })
+  it('returns empty for zero / negative / non-finite input', () => {
+    expect(fmtMsAsSeconds(0)).toBe('')
+    expect(fmtMsAsSeconds(-5)).toBe('')
+    expect(fmtMsAsSeconds(NaN)).toBe('')
+    expect(fmtMsAsSeconds(null)).toBe('')
+  })
+})
+
+describe('fmtBytes', () => {
+  it('renders bytes below 1 KB', () => {
+    expect(fmtBytes(512)).toBe('512 B')
+  })
+  it('renders KB with one decimal', () => {
+    expect(fmtBytes(1536)).toBe('1.5 KB')
+  })
+  it('renders MB with one decimal', () => {
+    expect(fmtBytes(2 * 1024 * 1024)).toBe('2.0 MB')
+  })
+  it('returns empty for zero / falsy input', () => {
+    expect(fmtBytes(0)).toBe('')
+    expect(fmtBytes(null)).toBe('')
+  })
+})

package/src/utils/format.ts

@@ -55,6 +55,29 @@ export function fmtDateShort(ms: number): string {
   return new Date(ms).toLocaleDateString(undefined, { month: 'short', day: 'numeric' })
 }
 
+/**
+ * Format an ISO string / epoch-millis as a full 24-hour locale date-time WITH
+ * the millisecond fraction — for dense feeds where several rows can land in
+ * the same second and must stay distinguishable. Falls back to the raw value
+ * when the input can't be parsed.
+ */
+export function fmtDateTimeMs(s: string | number): string {
+  try {
+    return new Date(s).toLocaleString(undefined, {
+      year: 'numeric',
+      month: '2-digit',
+      day: '2-digit',
+      hour: '2-digit',
+      minute: '2-digit',
+      second: '2-digit',
+      fractionalSecondDigits: 3,
+      hour12: false,
+    })
+  } catch {
+    return String(s)
+  }
+}
+
 /**
  * Format a price with precision that scales to magnitude: penny stocks and
  * sub-cent crypto get more decimals so the value never collapses to "0.00".
@@ -88,6 +111,63 @@ export function fmtUsd(v: number): string {
   return `${sign}$${Math.abs(v).toFixed(2)}`
 }
 
+/**
+ * Format an ISO date string / epoch as a "Mon D, YYYY" calendar label
+ * (en-US, e.g. "Jan 5, 2026"). Falls back to the raw value on parse
+ * failure and an em-dash on empty input.
+ */
+export function fmtCalendarDate(s: string | number | null | undefined): string {
+  if (s === null || s === undefined || s === '') return EM_DASH
+  const d = new Date(s)
+  if (isNaN(d.getTime())) return String(s)
+  return d.toLocaleDateString('en-US', {
+    year: 'numeric',
+    month: 'short',
+    day: 'numeric',
+  })
+}
+
+/**
+ * Format an ISO date string / epoch as a "Mon D, YYYY, HH:MM" calendar
+ * label with the time of day (en-US). Same fallbacks as fmtCalendarDate.
+ */
+export function fmtCalendarDateTime(s: string | number | null | undefined): string {
+  if (s === null || s === undefined || s === '') return EM_DASH
+  const d = new Date(s)
+  if (isNaN(d.getTime())) return String(s)
+  return d.toLocaleDateString('en-US', {
+    year: 'numeric',
+    month: 'short',
+    day: 'numeric',
+    hour: '2-digit',
+    minute: '2-digit',
+  })
+}
+
+/**
+ * Render a millisecond count as a "= 1.50 s" hint so users can
+ * sanity-check magnitudes without mental math. Sub-second values get 3
+ * decimals ("= 0.250 s"), everything else 2. Returns '' for
+ * non-positive / non-finite input so callers can `v-if` it away.
+ */
+export function fmtMsAsSeconds(ms: number | null | undefined): string {
+  if (typeof ms !== 'number' || !isFinite(ms) || ms <= 0) return ''
+  const seconds = ms / 1000
+  const decimals = seconds < 1 ? 3 : 2
+  return `= ${seconds.toFixed(decimals)} s`
+}
+
+/**
+ * Pretty-print a byte count with KB/MB granularity ("512 B", "1.5 KB",
+ * "2.0 MB"). Returns '' for zero/falsy input.
+ */
+export function fmtBytes(bytes: number | null | undefined): string {
+  if (!bytes) return ''
+  if (bytes < 1024) return `${bytes} B`
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`
+}
+
 /**
  * Format a millisecond duration as compact day/hour/minute units, e.g.
  * "3d 5h", "5h 12m" or "12m". Zero-value leading units are dropped;

package/src/utils/httpColors.test.ts

@@ -60,3 +60,41 @@ describe('statusBadgeTinted', () => {
     expect(statusBadgeTinted(undefined, false)).toBe('bg-green-100 text-green-800')
   })
 })
+
+import { methodBadgeTinted, statusBadgeSoft } from './httpColors'
+
+describe('methodBadgeTinted', () => {
+  it('gives each method its own hue (dark)', () => {
+    expect(methodBadgeTinted('GET', true)).toBe('bg-blue-500/15 text-blue-400')
+    expect(methodBadgeTinted('POST', true)).toBe('bg-emerald-500/15 text-emerald-400')
+    expect(methodBadgeTinted('PUT', true)).toBe('bg-amber-500/15 text-amber-400')
+    expect(methodBadgeTinted('DELETE', true)).toBe('bg-red-500/15 text-red-400')
+    expect(methodBadgeTinted('PATCH', true)).toBe('bg-purple-500/15 text-purple-400')
+    expect(methodBadgeTinted('HEAD', true)).toBe('bg-sky-500/15 text-sky-400')
+  })
+  it('uses the light palette when isDark is false', () => {
+    expect(methodBadgeTinted('GET', false)).toBe('bg-blue-100 text-blue-700')
+  })
+  it('is case-insensitive and falls back to gray for unknown/ANY/missing', () => {
+    expect(methodBadgeTinted('get', true)).toBe('bg-blue-500/15 text-blue-400')
+    expect(methodBadgeTinted(undefined, false)).toBe('bg-gray-100 text-gray-600')
+    expect(methodBadgeTinted('OPTIONS', false)).toBe('bg-gray-100 text-gray-600')
+  })
+})
+
+describe('statusBadgeSoft', () => {
+  it('buckets by status class (light)', () => {
+    expect(statusBadgeSoft(201, false)).toBe('bg-emerald-100 text-emerald-700')
+    expect(statusBadgeSoft(302, false)).toBe('bg-sky-100 text-sky-700')
+    expect(statusBadgeSoft(404, false)).toBe('bg-amber-100 text-amber-700')
+    expect(statusBadgeSoft(503, false)).toBe('bg-red-100 text-red-700')
+  })
+  it('uses tinted surfaces in dark mode', () => {
+    expect(statusBadgeSoft(200, true)).toBe('bg-emerald-500/15 text-emerald-300')
+  })
+  it('defaults undefined to 200 and gray for out-of-range codes', () => {
+    expect(statusBadgeSoft(undefined, false)).toBe('bg-emerald-100 text-emerald-700')
+    expect(statusBadgeSoft(999, false)).toBe('bg-gray-100 text-gray-600')
+    expect(statusBadgeSoft(100, true)).toBe('bg-gray-800 text-gray-400')
+  })
+})

package/src/utils/httpColors.ts

@@ -52,6 +52,37 @@ export function statusBadgeSolid(status?: number): string {
   return 'bg-gray-600'
 }
 
+/**
+ * Dark/light-aware tinted method badge — per-method hue on a soft
+ * `*-500/15` (dark) / `*-100` (light) surface, for card-surface chips.
+ * (Extracted from WireMate's mock/stub cards; GET is blue here, unlike
+ * the green-leaning bright family above.)
+ */
+export function methodBadgeTinted(method: string | undefined, isDark: boolean): string {
+  const m = (method || 'ANY').toUpperCase()
+  if (m === 'GET') return isDark ? 'bg-blue-500/15 text-blue-400' : 'bg-blue-100 text-blue-700'
+  if (m === 'POST') return isDark ? 'bg-emerald-500/15 text-emerald-400' : 'bg-emerald-100 text-emerald-700'
+  if (m === 'PUT') return isDark ? 'bg-amber-500/15 text-amber-400' : 'bg-amber-100 text-amber-700'
+  if (m === 'DELETE') return isDark ? 'bg-red-500/15 text-red-400' : 'bg-red-100 text-red-700'
+  if (m === 'PATCH') return isDark ? 'bg-purple-500/15 text-purple-400' : 'bg-purple-100 text-purple-700'
+  if (m === 'HEAD') return isDark ? 'bg-sky-500/15 text-sky-400' : 'bg-sky-100 text-sky-700'
+  return isDark ? 'bg-gray-500/15 text-gray-400' : 'bg-gray-100 text-gray-600'
+}
+
+/**
+ * Dark/light-aware soft status badge keyed by status class — emerald 2xx,
+ * sky 3xx, amber 4xx, red 5xx, gray otherwise. Softer companion to
+ * `statusBadgeTinted` (which uses the green/blue/yellow palette).
+ */
+export function statusBadgeSoft(status: number | undefined, isDark: boolean): string {
+  const code = status ?? 200
+  if (code >= 200 && code < 300) return isDark ? 'bg-emerald-500/15 text-emerald-300' : 'bg-emerald-100 text-emerald-700'
+  if (code >= 300 && code < 400) return isDark ? 'bg-sky-500/15 text-sky-300' : 'bg-sky-100 text-sky-700'
+  if (code >= 400 && code < 500) return isDark ? 'bg-amber-500/15 text-amber-300' : 'bg-amber-100 text-amber-700'
+  if (code >= 500 && code < 600) return isDark ? 'bg-red-500/15 text-red-300' : 'bg-red-100 text-red-700'
+  return isDark ? 'bg-gray-800 text-gray-400' : 'bg-gray-100 text-gray-600'
+}
+
 /** Dark/light-aware tinted status badge. */
 export function statusBadgeTinted(status: number | undefined, isDark: boolean): string {
   const code = status ?? 200

package/src/utils/kvRows.test.ts

@@ -0,0 +1,47 @@
+import { describe, it, expect } from 'vitest'
+import { rowKeyMissing, rowValueMissing } from './kvRows'
+
+describe('rowValueMissing', () => {
+  it('is false for a fully blank row', () => {
+    expect(rowValueMissing({ key: '', value: '' })).toBe(false)
+    expect(rowValueMissing({})).toBe(false)
+  })
+
+  it('is true when the key is filled but the value is blank', () => {
+    expect(rowValueMissing({ key: 'X-Trace', value: '' })).toBe(true)
+    expect(rowValueMissing({ key: 'X-Trace', value: '   ' })).toBe(true)
+    expect(rowValueMissing({ key: 'X-Trace' })).toBe(true)
+  })
+
+  it('is false when both sides are filled', () => {
+    expect(rowValueMissing({ key: 'X-Trace', value: 'abc' })).toBe(false)
+  })
+
+  it('exempts absent matchers — they carry no value by design', () => {
+    expect(rowValueMissing({ key: 'X-Trace', value: '', matcherType: 'absent' })).toBe(false)
+  })
+
+  it('treats whitespace-only keys as blank', () => {
+    expect(rowValueMissing({ key: '   ', value: '' })).toBe(false)
+  })
+})
+
+describe('rowKeyMissing', () => {
+  it('is false for a fully blank row', () => {
+    expect(rowKeyMissing({ key: '', value: '' })).toBe(false)
+    expect(rowKeyMissing({})).toBe(false)
+  })
+
+  it('is true when the value is filled but the key is blank', () => {
+    expect(rowKeyMissing({ key: '', value: 'abc' })).toBe(true)
+    expect(rowKeyMissing({ key: '  ', value: 'abc' })).toBe(true)
+  })
+
+  it('is false when both sides are filled', () => {
+    expect(rowKeyMissing({ key: 'X-Trace', value: 'abc' })).toBe(false)
+  })
+
+  it('exempts absent matchers', () => {
+    expect(rowKeyMissing({ key: '', value: 'abc', matcherType: 'absent' })).toBe(false)
+  })
+})

package/src/utils/kvRows.ts

@@ -0,0 +1,34 @@
+/**
+ * Validators for dynamic key/value row grids (header lists, query-param
+ * lists, metadata grids, …). A row is inconsistent when one side is
+ * filled in and the other is blank:
+ *
+ *   • key present, value blank  → rowValueMissing
+ *   • value present, key blank  → rowKeyMissing
+ *
+ * Rows whose `matcherType` is `'absent'` are exempt — an absent matcher
+ * intentionally carries no value (it asserts the key is NOT present).
+ * Rows without a matcherType (plain key/value pairs) validate normally.
+ */
+
+export interface KeyValueRowLike {
+  key?: string
+  value?: string
+  matcherType?: string
+}
+
+/** True when the row has a (non-absent) key but no value. */
+export function rowValueMissing(row: KeyValueRowLike): boolean {
+  const key = (row.key ?? '').trim()
+  if (!key) return false
+  if (row.matcherType === 'absent') return false
+  return !(row.value ?? '').trim()
+}
+
+/** True when the row has a value but no key to bind it to. */
+export function rowKeyMissing(row: KeyValueRowLike): boolean {
+  if (row.matcherType === 'absent') return false
+  const hasValue = !!(row.value ?? '').trim()
+  if (!hasValue) return false
+  return !(row.key ?? '').trim()
+}

package/src/utils/specForm.test.ts

@@ -0,0 +1,53 @@
+import { describe, it, expect } from 'vitest'
+import type { SpecField } from '../types/specField'
+import { buildSpecParams, firstInvalidNumericSpec } from './specForm'
+
+// Mirrors a typical backend catalogue shape: required numerics carry a
+// default, the optional field carries `default: null` (the optionality
+// convention — blank means "knob disabled").
+const specs: SpecField[] = [
+  { key: 'amountPerSymbol', label: 'Amount per symbol ($)', type: 'decimal', default: 4, min: 1, step: 0.01, options: null, help: '' },
+  { key: 'stopLossPercent', label: 'Stop loss (%)', type: 'decimal', default: null, min: 0.1, step: 0.1, options: null, help: '' },
+]
+
+describe('firstInvalidNumericSpec', () => {
+  it('flags a blank required numeric field', () => {
+    expect(firstInvalidNumericSpec(specs, { amountPerSymbol: '', stopLossPercent: 1 }))
+      .toBe('Amount per symbol ($)')
+  })
+
+  it.each([['' as const], [null as never], [undefined as never]])(
+    'accepts a blank optional field (cleared → %j)',
+    (blank) => {
+      expect(firstInvalidNumericSpec(specs, { amountPerSymbol: 10, stopLossPercent: blank }))
+        .toBeNull()
+    },
+  )
+
+  it('still validates a non-blank value on an optional field', () => {
+    expect(firstInvalidNumericSpec(specs, { amountPerSymbol: 10, stopLossPercent: NaN }))
+      .toBe('Stop loss (%)')
+    expect(firstInvalidNumericSpec(specs, { amountPerSymbol: 10, stopLossPercent: 2.5 }))
+      .toBeNull()
+  })
+
+  it('accepts a fully valid value set and tolerates missing specs', () => {
+    expect(firstInvalidNumericSpec(specs, { amountPerSymbol: 10, stopLossPercent: 1 })).toBeNull()
+    expect(firstInvalidNumericSpec(undefined, {})).toBeNull()
+  })
+})
+
+describe('buildSpecParams', () => {
+  it('seeds from defaults, keeping caller-supplied overlaps', () => {
+    expect(buildSpecParams(specs, { amountPerSymbol: 10 }).amountPerSymbol).toBe(10)
+    expect(buildSpecParams(specs, {}).amountPerSymbol).toBe(4)
+  })
+
+  it('seeds an optional field with null (renders as an empty input)', () => {
+    expect(buildSpecParams(specs, {}).stopLossPercent).toBeNull()
+  })
+
+  it('returns an empty map when there are no specs', () => {
+    expect(buildSpecParams(undefined, { anything: 1 })).toEqual({})
+  })
+})

package/src/utils/specForm.ts

@@ -0,0 +1,48 @@
+import type { SpecField, SpecFieldValue } from '../types/specField'
+
+/**
+ * Helpers for spec-driven forms (the value maps behind BaseSpecFields), so
+ * param seeding and numeric validation stay single-sourced across consumers.
+ */
+
+/**
+ * Build the value map for a spec set: keep any overlapping values the caller
+ * already has (e.g. a shared amount field carries across spec sets), otherwise
+ * fall back to the spec's default. No specs → empty map. A `default: null`
+ * seeds the field with null so it renders as an empty (optional) input.
+ */
+export function buildSpecParams(
+  specs: readonly SpecField[] | undefined,
+  existing: Record<string, SpecFieldValue>,
+): Record<string, SpecFieldValue> {
+  const out: Record<string, SpecFieldValue> = {}
+  if (!specs) return out
+  for (const spec of specs) {
+    const prev = existing[spec.key]
+    out[spec.key] = prev !== undefined && prev !== null ? prev : (spec.default as SpecFieldValue)
+  }
+  return out
+}
+
+/**
+ * Label of the first blank / NaN numeric field (a cleared number input becomes
+ * '' under number coercion), or null when every numeric field holds a number.
+ * A spec whose `default` is null is OPTIONAL: blank means "knob disabled" and
+ * must pass; a non-blank value on an optional field is still validated as a
+ * number.
+ */
+export function firstInvalidNumericSpec(
+  specs: readonly SpecField[] | undefined,
+  params: Record<string, SpecFieldValue>,
+): string | null {
+  if (!specs) return null
+  for (const spec of specs) {
+    if (spec.type === 'decimal' || spec.type === 'integer') {
+      const v = params[spec.key]
+      const blank = v === '' || v === null || v === undefined
+      if (spec.default === null && blank) continue
+      if (typeof v !== 'number' || Number.isNaN(v)) return spec.label
+    }
+  }
+  return null
+}