mgv-backoffice 1.36.0 → 1.36.2

package/src/utils/httpColors.ts

@@ -1,99 +1,99 @@
-/**
- * HTTP method / status code → Tailwind class helpers.
- *
- * Two visual families:
- *
- *   Solid family (600 weight, white text): bold saturated badges for
- *   inline rows (e.g. request logs / detail modals).
- *
- *   Bright/tinted family (500 weight + tinted backgrounds): softer
- *   badges for use on card surfaces, adapts to dark/light themes.
- */
-
-type MethodColorMap = Readonly<Record<string, string>>
-
-const SOLID_METHOD_COLORS: MethodColorMap = {
-  GET: 'bg-blue-600',
-  POST: 'bg-emerald-600',
-  PUT: 'bg-amber-600',
-  DELETE: 'bg-red-600',
-  PATCH: 'bg-purple-600',
-  HEAD: 'bg-gray-600',
-}
-
-const BRIGHT_METHOD_COLORS: MethodColorMap = {
-  GET: 'bg-blue-500',
-  POST: 'bg-green-500',
-  PUT: 'bg-yellow-500',
-  DELETE: 'bg-red-500',
-  PATCH: 'bg-purple-500',
-  HEAD: 'bg-gray-500',
-}
-
-/** Solid 600-weight method badge. */
-export function methodBadgeSolid(method?: string): string {
-  if (!method) return 'bg-gray-600'
-  return SOLID_METHOD_COLORS[method.toUpperCase()] ?? 'bg-gray-600'
-}
-
-/** Bright 500-weight method badge. */
-export function methodBadgeBright(method?: string): string {
-  if (!method) return 'bg-gray-500'
-  return BRIGHT_METHOD_COLORS[method.toUpperCase()] ?? 'bg-gray-500'
-}
-
-/** Solid 600-weight status badge with white text. */
-export function statusBadgeSolid(status?: number): string {
-  const code = status ?? 0
-  if (code >= 200 && code < 300) return 'bg-emerald-600'
-  if (code >= 300 && code < 400) return 'bg-blue-600'
-  if (code >= 400 && code < 500) return 'bg-amber-600'
-  if (code >= 500) return 'bg-red-600'
-  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
-  if (isDark) {
-    if (code >= 200 && code < 300) return 'bg-green-500/15 text-green-400'
-    if (code >= 300 && code < 400) return 'bg-blue-500/15 text-blue-400'
-    if (code >= 400 && code < 500) return 'bg-yellow-500/15 text-yellow-400'
-    return 'bg-red-500/15 text-red-400'
-  }
-  if (code >= 200 && code < 300) return 'bg-green-100 text-green-800'
-  if (code >= 300 && code < 400) return 'bg-blue-100 text-blue-800'
-  if (code >= 400 && code < 500) return 'bg-yellow-100 text-yellow-800'
-  return 'bg-red-100 text-red-800'
-}
+/**
+ * HTTP method / status code → Tailwind class helpers.
+ *
+ * Two visual families:
+ *
+ *   Solid family (600 weight, white text): bold saturated badges for
+ *   inline rows (e.g. request logs / detail modals).
+ *
+ *   Bright/tinted family (500 weight + tinted backgrounds): softer
+ *   badges for use on card surfaces, adapts to dark/light themes.
+ */
+
+type MethodColorMap = Readonly<Record<string, string>>
+
+const SOLID_METHOD_COLORS: MethodColorMap = {
+  GET: 'bg-blue-600',
+  POST: 'bg-emerald-600',
+  PUT: 'bg-amber-600',
+  DELETE: 'bg-red-600',
+  PATCH: 'bg-purple-600',
+  HEAD: 'bg-gray-600',
+}
+
+const BRIGHT_METHOD_COLORS: MethodColorMap = {
+  GET: 'bg-blue-500',
+  POST: 'bg-green-500',
+  PUT: 'bg-yellow-500',
+  DELETE: 'bg-red-500',
+  PATCH: 'bg-purple-500',
+  HEAD: 'bg-gray-500',
+}
+
+/** Solid 600-weight method badge. */
+export function methodBadgeSolid(method?: string): string {
+  if (!method) return 'bg-gray-600'
+  return SOLID_METHOD_COLORS[method.toUpperCase()] ?? 'bg-gray-600'
+}
+
+/** Bright 500-weight method badge. */
+export function methodBadgeBright(method?: string): string {
+  if (!method) return 'bg-gray-500'
+  return BRIGHT_METHOD_COLORS[method.toUpperCase()] ?? 'bg-gray-500'
+}
+
+/** Solid 600-weight status badge with white text. */
+export function statusBadgeSolid(status?: number): string {
+  const code = status ?? 0
+  if (code >= 200 && code < 300) return 'bg-emerald-600'
+  if (code >= 300 && code < 400) return 'bg-blue-600'
+  if (code >= 400 && code < 500) return 'bg-amber-600'
+  if (code >= 500) return 'bg-red-600'
+  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
+  if (isDark) {
+    if (code >= 200 && code < 300) return 'bg-green-500/15 text-green-400'
+    if (code >= 300 && code < 400) return 'bg-blue-500/15 text-blue-400'
+    if (code >= 400 && code < 500) return 'bg-yellow-500/15 text-yellow-400'
+    return 'bg-red-500/15 text-red-400'
+  }
+  if (code >= 200 && code < 300) return 'bg-green-100 text-green-800'
+  if (code >= 300 && code < 400) return 'bg-blue-100 text-blue-800'
+  if (code >= 400 && code < 500) return 'bg-yellow-100 text-yellow-800'
+  return 'bg-red-100 text-red-800'
+}

package/src/utils/kvRows.test.ts

@@ -1,47 +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)
-  })
-})
+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

@@ -1,34 +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()
-}
+/**
+ * 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

@@ -1,53 +1,64 @@
-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({})
-  })
-})
+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('flags a fractional value on an integer field', () => {
+    const withInt: SpecField[] = [
+      ...specs,
+      { key: 'quantityPerSymbol', label: 'Quantity per symbol (shares)', type: 'integer', default: 0, min: 0, step: 1, options: null, help: '' },
+    ]
+    const base = { amountPerSymbol: 10, stopLossPercent: 1 }
+    expect(firstInvalidNumericSpec(withInt, { ...base, quantityPerSymbol: 0.1 }))
+      .toBe('Quantity per symbol (shares)')
+    expect(firstInvalidNumericSpec(withInt, { ...base, quantityPerSymbol: 2 })).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

@@ -1,48 +1,49 @@
-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
-}
+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. Integer specs additionally reject fractional values.
+ */
+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
+      if (spec.type === 'integer' && !Number.isInteger(v)) return spec.label
+    }
+  }
+  return null
+}