mgv-backoffice 1.32.0 → 1.34.0

package/dist/utils/format.d.ts

@@ -68,6 +68,18 @@ export declare function fmtMsAsSeconds(ms: number | null | undefined): string;
  * "2.0 MB"). Returns '' for zero/falsy input.
  */
 export declare function fmtBytes(bytes: number | null | undefined): string;
+/**
+ * Pretty-print a string that may contain JSON: parseable input is
+ * re-serialized with 2-space indentation, anything else is returned
+ * verbatim. Handy for request/response bodies of unknown content type.
+ */
+export declare function formatJson(content: string): string;
+/**
+ * Render an unknown value as a display string: strings pass through,
+ * null/undefined become '', everything else is JSON-serialized (falling
+ * back to String() for values JSON can't handle, e.g. cycles or BigInt).
+ */
+export declare function stringifyValue(value: unknown): string;
 /**
  * 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/dist/utils/validate.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Pure, dependency-free input validators shared across back-office forms —
+ * extracted from WireMate's mock form.
+ *
+ * Semantics note: the payload validators (`isValidJson`, `isValidXml`,
+ * `isValidBase64`) treat empty/whitespace-only input as VALID — callers
+ * gate on "is there something to check" separately (required-ness is a
+ * different rule from well-formedness). `isValidAbsoluteUrl` is the
+ * opposite: it validates a value that must exist, so empty is invalid.
+ */
+/**
+ * `true` when `value` parses as an absolute http:// or https:// URL.
+ * Deliberately tightens the scheme list — backends' HTTP clients won't
+ * follow ftp:// or mailto: anyway, so a stray scheme is a typo.
+ */
+export declare function isValidAbsoluteUrl(value: string): boolean;
+/**
+ * `true` when `str` is empty or parses as JSON.
+ */
+export declare function isValidJson(str: string): boolean;
+/**
+ * `true` when `str` is empty or is well-formed XML. Runs the browser's
+ * DOMParser and checks for a `<parsererror>` node — the only reliable
+ * signal DOMParser provides, since it never throws on bad input.
+ */
+export declare function isValidXml(str: string): boolean;
+/**
+ * `true` when `str` is empty or is well-formed base64 (after stripping
+ * whitespace/newlines, which are harmless in both RFC 4648 and most
+ * real-world payloads). Rejects lengths that can't possibly decode
+ * (`length % 4 !== 0` after padding) — the common "off by a character"
+ * copy/paste issue — then defers to the native decoder as the final
+ * authority.
+ */
+export declare function isValidBase64(str: string): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mgv-backoffice",
-  "version": "1.32.0",
+  "version": "1.34.0",
   "description": "Shared Vue 3 UI component library",
   "type": "module",
   "main": "./dist/ui-lib.umd.cjs",

package/src/components/BaseCodeBlock.test.ts

@@ -0,0 +1,70 @@
+import { describe, it, expect, beforeEach } from 'vitest'
+import { mount } from '@vue/test-utils'
+import BaseCodeBlock from './BaseCodeBlock.vue'
+import { useTheme } from '../composables/useTheme'
+
+function ensureLight() {
+  const { isDark, toggleTheme } = useTheme()
+  if (isDark.value) toggleTheme()
+}
+
+describe('BaseCodeBlock', () => {
+  beforeEach(() => {
+    ensureLight()
+  })
+
+  it('renders the code verbatim inside a <pre>', () => {
+    const code = '{\n  "a": 1\n}'
+    const wrapper = mount(BaseCodeBlock, { props: { code } })
+    const pre = wrapper.find('pre')
+    expect(pre.exists()).toBe(true)
+    expect(pre.text()).toBe(code)
+    expect(pre.classes()).toContain('font-mono')
+    expect(pre.classes()).toContain('overflow-auto')
+  })
+
+  it('defaults to the soft variant at size sm', () => {
+    const wrapper = mount(BaseCodeBlock, { props: { code: 'x' } })
+    const classes = wrapper.find('pre').classes()
+    expect(classes).toContain('bg-gray-100')
+    expect(classes).toContain('text-sm')
+    expect(classes).toContain('px-5')
+    expect(classes).not.toContain('border')
+  })
+
+  it('renders the bordered variant with a border and card fill', () => {
+    const wrapper = mount(BaseCodeBlock, {
+      props: { code: 'x', variant: 'bordered' },
+    })
+    const classes = wrapper.find('pre').classes()
+    expect(classes).toContain('border')
+    expect(classes).toContain('bg-white')
+    expect(classes).toContain('border-gray-200')
+  })
+
+  it('renders dense padding at size xs', () => {
+    const wrapper = mount(BaseCodeBlock, { props: { code: 'x', size: 'xs' } })
+    const classes = wrapper.find('pre').classes()
+    expect(classes).toContain('text-xs')
+    expect(classes).toContain('p-3')
+  })
+
+  it('applies maxHeightClass and merges fallthrough classes', () => {
+    const wrapper = mount(BaseCodeBlock, {
+      props: { code: 'x', maxHeightClass: 'max-h-96' },
+      attrs: { class: 'mx-4' },
+    })
+    const classes = wrapper.find('pre').classes()
+    expect(classes).toContain('max-h-96')
+    expect(classes).toContain('mx-4')
+  })
+
+  it('switches palette when the theme flips', async () => {
+    const wrapper = mount(BaseCodeBlock, { props: { code: 'x' } })
+    const { toggleTheme } = useTheme()
+    toggleTheme()
+    await wrapper.vm.$nextTick()
+    expect(wrapper.find('pre').classes()).toContain('bg-gray-800/70')
+    toggleTheme()
+  })
+})

package/src/components/BaseCodeBlock.vue

@@ -0,0 +1,74 @@
+<template>
+  <!--
+    Themed monospace <pre> for JSON payloads, request dumps and code
+    snippets — extracted from WireMate, where the same class soup was
+    hand-rolled on every stub/request detail view.
+
+    Variants:
+      • soft     — tinted fill, no border (bg-gray-800/70 / bg-gray-100).
+        The in-card look used under a section heading.
+      • bordered — bordered card fill (bg-gray-900 / bg-white). The
+        standalone look used when the block sits directly on the page.
+
+    Sizing:
+      • sm — text-sm with roomy padding, for primary content blocks.
+      • xs — text-xs with tight padding, for dense/secondary dumps.
+
+    `max-height-class` caps tall payloads (e.g. 'max-h-96'); the block
+    scrolls both axes. Extra classes (margins etc.) fall through via the
+    normal class attr merge.
+  -->
+  <pre
+    class="font-mono overflow-auto"
+    :class="[sizeClass, paletteClass, maxHeightClass]"
+  >{{ code }}</pre>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue'
+import { useTheme } from '../composables/useTheme'
+
+const props = withDefaults(
+  defineProps<{
+    /** 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
+  }>(),
+  {
+    variant: 'soft',
+    size: 'sm',
+    maxHeightClass: '',
+  },
+)
+
+const { isDark } = useTheme()
+
+// Full literal class strings so Tailwind detects them at build time.
+const PALETTES: Record<'soft' | 'bordered', { dark: string; light: string }> = {
+  soft: {
+    dark: 'bg-gray-800/70 text-gray-300',
+    light: 'bg-gray-100 text-gray-700',
+  },
+  bordered: {
+    dark: 'border bg-gray-900 border-gray-700 text-gray-300',
+    light: 'border bg-white border-gray-200 text-gray-700',
+  },
+}
+
+const SIZES: Record<'sm' | 'xs', string> = {
+  sm: 'text-sm px-5 py-4 rounded-lg',
+  xs: 'text-xs p-3 rounded-lg',
+}
+
+const paletteClass = computed(() => {
+  const entry = PALETTES[props.variant]
+  return isDark.value ? entry.dark : entry.light
+})
+
+const sizeClass = computed(() => SIZES[props.size])
+</script>

package/src/composables/usePolling.test.ts

@@ -0,0 +1,112 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { defineComponent, h, nextTick } from 'vue'
+import { mount } from '@vue/test-utils'
+import { usePolling, type UsePollingOptions } from './usePolling'
+
+function mountWithPolling(
+  fn: () => void,
+  intervalMs: number | null,
+  options?: UsePollingOptions,
+) {
+  let api!: ReturnType<typeof usePolling>
+  const wrapper = mount(
+    defineComponent({
+      setup() {
+        api = usePolling(fn, intervalMs, options)
+        return () => h('div')
+      },
+    }),
+  )
+  return { wrapper, api }
+}
+
+function setVisibility(state: 'visible' | 'hidden') {
+  Object.defineProperty(document, 'visibilityState', {
+    configurable: true,
+    get: () => state,
+  })
+  document.dispatchEvent(new Event('visibilitychange'))
+}
+
+describe('usePolling', () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+    setVisibility('visible')
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  it('runs immediately on mount and then on each interval', () => {
+    const fn = vi.fn()
+    mountWithPolling(fn, 1000)
+    expect(fn).toHaveBeenCalledTimes(1)
+    vi.advanceTimersByTime(3000)
+    expect(fn).toHaveBeenCalledTimes(4)
+  })
+
+  it('skips the initial call when immediate is false', () => {
+    const fn = vi.fn()
+    mountWithPolling(fn, 1000, { immediate: false })
+    expect(fn).not.toHaveBeenCalled()
+    vi.advanceTimersByTime(1000)
+    expect(fn).toHaveBeenCalledTimes(1)
+  })
+
+  it('pauses while hidden and refreshes + resumes on return to visible', async () => {
+    const fn = vi.fn()
+    mountWithPolling(fn, 1000)
+    expect(fn).toHaveBeenCalledTimes(1)
+
+    setVisibility('hidden')
+    await nextTick()
+    vi.advanceTimersByTime(5000)
+    expect(fn).toHaveBeenCalledTimes(1) // no ticks while hidden
+
+    setVisibility('visible')
+    expect(fn).toHaveBeenCalledTimes(2) // immediate refresh on resume
+    vi.advanceTimersByTime(1000)
+    expect(fn).toHaveBeenCalledTimes(3) // interval re-armed
+  })
+
+  it('with intervalMs null, runs on mount and on visibility resume only', () => {
+    const fn = vi.fn()
+    mountWithPolling(fn, null)
+    expect(fn).toHaveBeenCalledTimes(1)
+    vi.advanceTimersByTime(60000)
+    expect(fn).toHaveBeenCalledTimes(1)
+
+    setVisibility('hidden')
+    setVisibility('visible')
+    expect(fn).toHaveBeenCalledTimes(2)
+    vi.advanceTimersByTime(60000)
+    expect(fn).toHaveBeenCalledTimes(2)
+  })
+
+  it('stops on unmount', () => {
+    const fn = vi.fn()
+    const { wrapper } = mountWithPolling(fn, 1000)
+    wrapper.unmount()
+    vi.advanceTimersByTime(5000)
+    expect(fn).toHaveBeenCalledTimes(1)
+    // and the visibility listener is gone too
+    setVisibility('hidden')
+    setVisibility('visible')
+    expect(fn).toHaveBeenCalledTimes(1)
+  })
+
+  it('exposes manual start/stop and an active flag', () => {
+    const fn = vi.fn()
+    const { api } = mountWithPolling(fn, 1000)
+    expect(api.active.value).toBe(true)
+    api.stop()
+    expect(api.active.value).toBe(false)
+    vi.advanceTimersByTime(3000)
+    expect(fn).toHaveBeenCalledTimes(1)
+    api.start()
+    expect(fn).toHaveBeenCalledTimes(2)
+    vi.advanceTimersByTime(1000)
+    expect(fn).toHaveBeenCalledTimes(3)
+  })
+})

package/src/composables/usePolling.ts

@@ -0,0 +1,90 @@
+import { onMounted, onUnmounted, readonly, ref, type 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 function usePolling(
+  fn: () => void | Promise<void>,
+  intervalMs: number | null,
+  options: UsePollingOptions = {},
+): { start: () => void; stop: () => void; active: Readonly<Ref<boolean>> } {
+  const { immediate = true, pauseWhenHidden = true } = options
+
+  let timer: ReturnType<typeof setInterval> | null = null
+  const active = ref(false)
+
+  function startTimer() {
+    if (timer !== null || intervalMs === null) return
+    timer = setInterval(() => void fn(), intervalMs)
+  }
+
+  function stopTimer() {
+    if (timer !== null) {
+      clearInterval(timer)
+      timer = null
+    }
+  }
+
+  function start() {
+    if (active.value) return
+    active.value = true
+    if (immediate) void fn()
+    startTimer()
+  }
+
+  function stop() {
+    active.value = false
+    stopTimer()
+  }
+
+  function onVisibilityChange() {
+    if (document.visibilityState === 'visible') {
+      // Refresh right away so stale data doesn't linger for a full
+      // interval after the user returns, then re-arm the timer.
+      active.value = true
+      void fn()
+      startTimer()
+    } else {
+      stop()
+    }
+  }
+
+  onMounted(() => {
+    start()
+    if (pauseWhenHidden) {
+      document.addEventListener('visibilitychange', onVisibilityChange)
+    }
+  })
+
+  onUnmounted(() => {
+    stop()
+    if (pauseWhenHidden) {
+      document.removeEventListener('visibilitychange', onVisibilityChange)
+    }
+  })
+
+  return { start, stop, active: readonly(active) }
+}

package/src/composables/useThemeClasses.test.ts

@@ -0,0 +1,34 @@
+import { describe, it, expect } from 'vitest'
+import { isReactive } from 'vue'
+import { normalizeClass } from '@vue/shared'
+import { useThemeClasses } from './useThemeClasses'
+import { useTheme } from './useTheme'
+
+describe('useThemeClasses', () => {
+  it('returns a reactive object whose properties are plain class strings', () => {
+    const t = useThemeClasses()
+    expect(isReactive(t)).toBe(true)
+    expect(typeof t.primaryText).toBe('string')
+    expect(t.primaryText).toMatch(/^text-/)
+  })
+
+  it('survives normalizeClass — the regression that leaked ref internals into class attrs', () => {
+    // Before the reactive() fix, `:class="t.primaryText"` handed a raw
+    // ComputedRef to normalizeClass, which rendered the ref's own keys
+    // ("fn dep __v_isRef …") instead of the theme classes.
+    const t = useThemeClasses()
+    const normalized = normalizeClass(t.primaryText)
+    expect(normalized).not.toContain('__v_isRef')
+    expect(normalized).toBe(t.primaryText)
+  })
+
+  it('tracks theme flips', () => {
+    const { isDark, toggleTheme } = useTheme()
+    const t = useThemeClasses()
+    const before = t.primaryText
+    toggleTheme()
+    expect(t.primaryText).not.toBe(before)
+    expect(t.primaryText).toBe(isDark.value ? 'text-white' : 'text-gray-900')
+    toggleTheme() // restore for other tests sharing the singleton theme
+  })
+})

package/src/composables/useThemeClasses.ts

@@ -1,4 +1,4 @@
-import { computed, type ComputedRef } from 'vue'
+import { computed, reactive } from 'vue'
 import { useTheme } from './useTheme'
 
 /**
@@ -14,69 +14,73 @@ import { useTheme } from './useTheme'
  *     <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 {
   // -- Surfaces --
   /** 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
 
   // -- Borders --
   /** Standard border between cards/sections. */
-  border: ComputedRef<string>
+  border: string
   /** Subtle divider (lighter than border). */
-  divider: ComputedRef<string>
+  divider: string
 
   // -- Text hierarchy --
   /** 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
 
   // -- Inputs --
   /** Standard text input. */
-  input: ComputedRef<string>
+  input: string
   /** Input + placeholder colour. */
-  inputWithPlaceholder: ComputedRef<string>
+  inputWithPlaceholder: string
 
   // -- Buttons --
   /** Ghost / Cancel button. */
-  ghostButton: ComputedRef<string>
+  ghostButton: string
 
   // -- Accent text colours --
   /** 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 function useThemeClasses(): ThemeClasses {
   const { isDark } = useTheme()
 
-  return {
+  return reactive({
     card: computed(() =>
       isDark.value
         ? 'bg-gray-800 border-gray-700'
@@ -129,5 +133,5 @@ export function useThemeClasses(): ThemeClasses {
       isDark.value ? 'text-amber-300' : 'text-amber-700',
     ),
     redText: computed(() => (isDark.value ? 'text-red-400' : 'text-red-500')),
-  }
+  })
 }

package/src/index.ts

@@ -37,6 +37,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'
 
 // Components — extracted from TradeAutomation
 export { default as BaseInput } from './components/BaseInput.vue'
@@ -65,6 +66,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'
 
 // Enums
 export { AlertEnum } from './enums/AlertEnum'
@@ -117,7 +120,15 @@ export {
   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/src/style.css

@@ -1,5 +1,21 @@
+/* Brand typography, shipped by the library so every consumer renders the same:
+   Fira Sans for UI text, Fira Code for numerals/data. External @import (kept
+   first — CSS ignores @import after any other rule); consumers should add
+   <link rel="preconnect"> hints for fonts.googleapis.com / fonts.gstatic.com
+   in their index.html for faster first paint. */
+@import url('https://fonts.googleapis.com/css2?family=Fira+Code:wght@400;500;600;700&family=Fira+Sans:wght@300;400;500;600;700&display=swap');
+
 @import "tailwindcss";
 
+/* Register the fonts as the Tailwind theme defaults. The compiled stylesheet
+   re-declares theme variables in its :root, so in consumers that import this
+   file after their own `@import "tailwindcss"` these values win the cascade
+   for font-sans/font-mono utilities AND the body rule below. */
+@theme {
+  --font-sans: 'Fira Sans', ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif;
+  --font-mono: 'Fira Code', ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+}
+
 /* Compile `dark:` variants against the `.dark` class that useTheme()/initTheme()
    toggle on <html> — NOT the OS-level prefers-color-scheme media query
    (Tailwind v4's default). Both consumers (TradeAutomation, WireMate) switch
@@ -8,3 +24,9 @@
    Use a specificity-bearing selector (:is, not :where) so dark: utilities win
    over plain base utilities like bg-slate-50 on a cascade tie. */
 @custom-variant dark (&:is(.dark, .dark *));
+
+/* Apply the brand font app-wide. Plain body rule (not preflight-dependent) so
+   it also styles consumers whose own Tailwind preflight came earlier. */
+body {
+  font-family: var(--font-sans);
+}

package/src/utils/format.test.ts

@@ -9,6 +9,8 @@ import {
   fmtPct,
   fmtUsd,
   fmtDuration,
+  formatJson,
+  stringifyValue,
 } from './format'
 
 describe('fmtDateTimeMs', () => {
@@ -233,3 +235,30 @@ describe('fmtBytes', () => {
     expect(fmtBytes(null)).toBe('')
   })
 })
+
+describe('formatJson', () => {
+  it('pretty-prints parseable JSON with 2-space indentation', () => {
+    expect(formatJson('{"a":1,"b":[2,3]}')).toBe('{\n  "a": 1,\n  "b": [\n    2,\n    3\n  ]\n}')
+  })
+  it('returns non-JSON input verbatim', () => {
+    expect(formatJson('plain text')).toBe('plain text')
+    expect(formatJson('<xml/>')).toBe('<xml/>')
+    expect(formatJson('')).toBe('')
+  })
+})
+
+describe('stringifyValue', () => {
+  it('passes strings through and blanks null/undefined', () => {
+    expect(stringifyValue('abc')).toBe('abc')
+    expect(stringifyValue(null)).toBe('')
+    expect(stringifyValue(undefined)).toBe('')
+  })
+  it('JSON-serializes objects, arrays and numbers', () => {
+    expect(stringifyValue({ a: 1 })).toBe('{"a":1}')
+    expect(stringifyValue([1, 2])).toBe('[1,2]')
+    expect(stringifyValue(42)).toBe('42')
+  })
+  it('falls back to String() when JSON.stringify throws', () => {
+    expect(stringifyValue(1n)).toBe('1')
+  })
+})