mgv-backoffice 1.30.0 → 1.32.0

package/dist/utils/format.d.ts

@@ -45,6 +45,29 @@ export declare function fmtPct(n: number, digits?: number): string;
  * Format a signed USD amount with an explicit leading sign (e.g. "+$5.00").
  */
 export declare function fmtUsd(v: number): string;
+/**
+ * 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 declare function fmtCalendarDate(s: string | number | null | undefined): string;
+/**
+ * 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 declare function fmtCalendarDateTime(s: string | number | null | undefined): string;
+/**
+ * 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 declare function fmtMsAsSeconds(ms: number | null | undefined): string;
+/**
+ * Pretty-print a byte count with KB/MB granularity ("512 B", "1.5 KB",
+ * "2.0 MB"). Returns '' for zero/falsy input.
+ */
+export declare function fmtBytes(bytes: number | null | undefined): 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/httpColors.d.ts

@@ -15,5 +15,18 @@ export declare function methodBadgeSolid(method?: string): string;
 export declare function methodBadgeBright(method?: string): string;
 /** Solid 600-weight status badge with white text. */
 export declare function statusBadgeSolid(status?: number): string;
+/**
+ * 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 declare function methodBadgeTinted(method: string | undefined, isDark: boolean): string;
+/**
+ * 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 declare function statusBadgeSoft(status: number | undefined, isDark: boolean): string;
 /** Dark/light-aware tinted status badge. */
 export declare function statusBadgeTinted(status: number | undefined, isDark: boolean): string;

package/dist/utils/kvRows.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 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 declare function rowValueMissing(row: KeyValueRowLike): boolean;
+/** True when the row has a value but no key to bind it to. */
+export declare function rowKeyMissing(row: KeyValueRowLike): boolean;

package/package.json

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

package/src/components/BaseConfirmModal.vue

@@ -1,26 +1,14 @@
 <template>
   <BaseModalShell
     :title="title"
+    :icon="ExclamationTriangleIcon"
+    :icon-bg-class="variant === 'danger'
+      ? isDark ? 'bg-red-900/30' : 'bg-red-50'
+      : isDark ? 'bg-amber-900/30' : 'bg-amber-50'"
+    :icon-class="variant === 'danger' ? 'text-red-600' : 'text-amber-600'"
     :manual-close="submitting"
     @cancel="handleCancel"
   >
-    <template #icon>
-      <div
-        class="flex-shrink-0 flex h-12 w-12 items-center justify-center rounded-full"
-        :class="[
-          variant === 'danger'
-            ? isDark ? 'bg-red-900/30' : 'bg-red-50'
-            : isDark ? 'bg-amber-900/30' : 'bg-amber-50'
-        ]"
-      >
-        <ExclamationTriangleIcon
-          class="h-6 w-6"
-          :class="variant === 'danger' ? 'text-red-600' : 'text-amber-600'"
-          aria-hidden="true"
-        />
-      </div>
-    </template>
-
     <!--
       Default renders the plain `message` string. Callers that need rich
       text (bold names, inline code, etc.) can override the `message` slot

package/src/components/BaseEntityPickerModal.vue

@@ -1,18 +1,16 @@
 <template>
   <BaseModalShell
     :title="title"
+    :icon="FolderIcon"
+    :icon-bg-class="palette.iconBg"
+    :icon-class="palette.iconText"
     :manual-close="submitting"
     @cancel="handleCancel"
   >
-    <template #icon>
-      <slot name="icon">
-        <div
-          class="flex-shrink-0 flex h-12 w-12 items-center justify-center rounded-full"
-          :class="palette.iconBg"
-        >
-          <FolderIcon class="h-6 w-6" :class="palette.iconText" aria-hidden="true" />
-        </div>
-      </slot>
+    <!-- Forward a caller-supplied icon override; otherwise the shell
+         renders the default folder icon in the palette-tinted chip. -->
+    <template v-if="$slots.icon" #icon>
+      <slot name="icon" />
     </template>
 
     <p v-if="message" class="text-sm" :class="isDark ? 'text-gray-300' : 'text-gray-600'">

package/src/components/BaseFileDropzone.vue

@@ -0,0 +1,94 @@
+<template>
+  <!--
+    Dashed "click to select a file" upload zone — extracted from WireMate's
+    ImportPostmanModal file picker. Also accepts drag-and-drop.
+
+    The hidden input is reset after every selection so choosing the same
+    file twice still fires `files` — callers don't need their own reset.
+  -->
+  <label
+    class="flex flex-col items-center justify-center gap-2 rounded-lg border-2 border-dashed px-6 py-10 text-center transition-colors"
+    :class="[
+      disabled ? 'opacity-50 cursor-not-allowed' : 'cursor-pointer',
+      dragging
+        ? (isDark ? 'border-emerald-500 text-emerald-400' : 'border-emerald-500 text-emerald-600')
+        : (isDark
+          ? 'border-gray-700 hover:border-emerald-500 text-gray-400 hover:text-emerald-400'
+          : 'border-gray-300 hover:border-emerald-500 text-gray-500 hover:text-emerald-600'),
+    ]"
+    @dragover.prevent="onDragOver"
+    @dragleave.prevent="dragging = false"
+    @drop.prevent="onDrop"
+  >
+    <slot name="icon">
+      <svg class="w-10 h-10" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="1.5" aria-hidden="true">
+        <path
+          stroke-linecap="round"
+          stroke-linejoin="round"
+          d="M19.5 14.25v-2.625a3.375 3.375 0 0 0-3.375-3.375h-1.5A1.125 1.125 0 0 1 13.5 7.125v-1.5a3.375 3.375 0 0 0-3.375-3.375H8.25m6.75 12-3-3m0 0-3 3m3-3v6m-1.5-15H5.625c-.621 0-1.125.504-1.125 1.125v17.25c0 .621.504 1.125 1.125 1.125h12.75c.621 0 1.125-.504 1.125-1.125V11.25a9 9 0 0 0-9-9Z"
+        />
+      </svg>
+    </slot>
+    <p class="text-sm font-medium">{{ label }}</p>
+    <p v-if="hint" class="text-xs" :class="isDark ? 'text-gray-500' : 'text-gray-400'">
+      {{ hint }}
+    </p>
+    <input
+      type="file"
+      class="hidden"
+      :accept="accept"
+      :multiple="multiple"
+      :disabled="disabled"
+      @change="onChange"
+    />
+  </label>
+</template>
+
+<script lang="ts" setup>
+import { ref } from 'vue'
+import { useTheme } from '../composables/useTheme'
+
+interface Props {
+  /** Main line, e.g. "Click to select a Postman collection (.json)". */
+  label: string
+  /** Optional dimmed helper line below the label. */
+  hint?: string
+  /** Forwarded to the hidden input's `accept`. Dropped files are NOT filtered by it. */
+  accept?: string
+  multiple?: boolean
+  disabled?: boolean
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  hint: '',
+  accept: '',
+  multiple: false,
+  disabled: false,
+})
+
+const emit = defineEmits<{ files: [files: File[]] }>()
+
+const { isDark } = useTheme()
+
+const dragging = ref(false)
+
+function onChange(e: Event) {
+  const input = e.target as HTMLInputElement
+  const files = Array.from(input.files ?? [])
+  // Reset so re-selecting the same file re-triggers change.
+  input.value = ''
+  if (files.length) emit('files', files)
+}
+
+function onDragOver() {
+  if (!props.disabled) dragging.value = true
+}
+
+function onDrop(e: DragEvent) {
+  dragging.value = false
+  if (props.disabled) return
+  const dropped = Array.from(e.dataTransfer?.files ?? [])
+  if (!dropped.length) return
+  emit('files', props.multiple ? dropped : dropped.slice(0, 1))
+}
+</script>

package/src/components/BaseModalShell.vue

@@ -4,8 +4,14 @@
     backdrop, dark-mode card, escape key, aria-modal). Concrete modals
     should compose this rather than re-implementing the chrome.
 
+    Every modal shows an icon left of the title: the REQUIRED `icon`
+    prop (a component, e.g. a heroicon) renders inside a tinted
+    circular chip. Tint via `icon-bg-class` / `icon-class`; the `icon`
+    slot remains as a full-markup override for callers that need
+    something richer than the standard chip.
+
     Slots:
-      • icon    — small circular icon shown next to the title
+      • icon    — override the standard icon chip next to the title
       • default — body content
       • footer  — action buttons (cancel / confirm / etc.)
 
@@ -37,7 +43,14 @@
       >
         <div class="flex items-start justify-between gap-4 p-6 border-b shrink-0" :class="t.border">
           <div class="flex items-start gap-4 min-w-0">
-            <slot name="icon" />
+            <slot name="icon">
+              <div
+                class="flex-shrink-0 flex h-12 w-12 items-center justify-center rounded-full"
+                :class="iconChipBg"
+              >
+                <component :is="icon" class="h-6 w-6" :class="iconClass" aria-hidden="true" />
+              </div>
+            </slot>
             <div class="flex-1 min-w-0">
               <h3 :id="titleId" class="text-lg font-medium" :class="t.primaryText">
                 {{ title }}
@@ -69,7 +82,14 @@
         <div class="p-6">
           <!-- Title row -->
           <div class="flex items-start gap-4">
-            <slot name="icon" />
+            <slot name="icon">
+              <div
+                class="flex-shrink-0 flex h-12 w-12 items-center justify-center rounded-full"
+                :class="iconChipBg"
+              >
+                <component :is="icon" class="h-6 w-6" :class="iconClass" aria-hidden="true" />
+              </div>
+            </slot>
             <div class="flex-1">
               <h3
                 :id="titleId"
@@ -98,12 +118,26 @@
 
 <script setup lang="ts">
 import { computed } from 'vue'
+import type { Component } from 'vue'
 import { useTheme } from '../composables/useTheme'
 import { useThemeClasses } from '../composables/useThemeClasses'
 import { useEscapeKey } from '../composables/useEscapeKey'
 
 interface Props {
   title: string
+  /**
+   * Icon component (e.g. a heroicon) rendered in a tinted circular
+   * chip left of the title. REQUIRED — every modal must name itself
+   * with an icon. The `icon` slot can override the whole chip.
+   */
+  icon: Component
+  /**
+   * Background classes of the icon chip. Defaults to the emerald
+   * tint (dark-mode aware).
+   */
+  iconBgClass?: string
+  /** Classes applied to the icon itself. Defaults to emerald. */
+  iconClass?: string
   /**
    * Max-width of the dialog card. Defaults to `max-w-md`. Pass any
    * Tailwind max-w utility, or empty string to opt out.
@@ -135,6 +169,8 @@ const props = withDefaults(defineProps<Props>(), {
   manualClose: false,
   scrollable: false,
   subtitle: '',
+  iconBgClass: '',
+  iconClass: 'text-emerald-600',
 })
 
 const emit = defineEmits<{
@@ -156,6 +192,12 @@ const shellClass = computed(() =>
     : 'bg-white border border-gray-200',
 )
 
+// The icon chip's background: an explicit `icon-bg-class` wins, else the
+// standard emerald tint in the current theme.
+const iconChipBg = computed(() =>
+  props.iconBgClass || (isDark.value ? 'bg-emerald-900/30' : 'bg-emerald-50'),
+)
+
 function onBackdrop() {
   emit('backdrop')
   if (!props.manualClose) emit('cancel')

package/src/components/BaseTextInputModal.vue

@@ -12,18 +12,14 @@
   -->
   <BaseModalShell
     :title="title"
+    :icon="DocumentDuplicateIcon"
     manual-close
     @backdrop="handleBackdropClick"
   >
-    <template #icon>
-      <slot name="icon">
-        <div
-          class="flex-shrink-0 flex h-12 w-12 items-center justify-center rounded-full"
-          :class="isDark ? 'bg-emerald-900/30' : 'bg-emerald-50'"
-        >
-          <DocumentDuplicateIcon class="h-6 w-6 text-emerald-600" aria-hidden="true" />
-        </div>
-      </slot>
+    <!-- Forward a caller-supplied icon override; otherwise the shell
+         renders the default document icon in the standard emerald chip. -->
+    <template v-if="$slots.icon" #icon>
+      <slot name="icon" />
     </template>
 
     <p class="text-sm" :class="isDark ? 'text-gray-300' : 'text-gray-600'">

package/src/composables/useFieldClasses.test.ts

@@ -0,0 +1,55 @@
+import { describe, it, expect, beforeEach } from 'vitest'
+import { useFieldClasses } from './useFieldClasses'
+import { useTheme } from './useTheme'
+
+// useTheme is a module-level singleton — grab its ref once and flip it
+// per test. localStorage is cleared so a previous test's persisted theme
+// can't leak into the initial value.
+beforeEach(() => {
+  localStorage.clear()
+})
+
+describe('useFieldClasses', () => {
+  it('returns the light-mode strings when isDark is false', () => {
+    const { isDark } = useTheme()
+    isDark.value = false
+    const f = useFieldClasses()
+    expect(f.label.value).toBe('text-gray-600')
+    expect(f.input.value).toContain('bg-white')
+    expect(f.input.value).toContain('focus:ring-emerald-500')
+  })
+
+  it('returns the dark-mode strings when isDark is true', () => {
+    const { isDark } = useTheme()
+    isDark.value = true
+    const f = useFieldClasses()
+    expect(f.label.value).toBe('text-gray-300')
+    expect(f.input.value).toContain('bg-gray-800')
+  })
+
+  it('requiredInput flags empty values with the red skin', () => {
+    const { isDark } = useTheme()
+    isDark.value = false
+    const f = useFieldClasses()
+    expect(f.requiredInput('')).toContain('border-red-400')
+    expect(f.requiredInput('   ')).toContain('border-red-400')
+    expect(f.requiredInput(undefined)).toContain('border-red-400')
+    expect(f.requiredInput(null)).toContain('border-red-400')
+  })
+
+  it('requiredInput falls back to the standard skin for filled values', () => {
+    const { isDark } = useTheme()
+    isDark.value = false
+    const f = useFieldClasses()
+    expect(f.requiredInput('hello')).toBe(f.input.value)
+    expect(f.requiredInput(0)).toBe(f.input.value) // 0 is a real value, not empty
+  })
+
+  it('requiredInput follows the active theme', () => {
+    const { isDark } = useTheme()
+    isDark.value = true
+    const f = useFieldClasses()
+    expect(f.requiredInput('')).toContain('bg-gray-800')
+    expect(f.requiredInput('')).toContain('border-red-500')
+  })
+})

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/index.ts

@@ -36,6 +36,7 @@ export { default as BaseNotificationPanel } from './components/BaseNotificationP
 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'
 
 // Components — extracted from TradeAutomation
 export { default as BaseInput } from './components/BaseInput.vue'
@@ -62,6 +63,8 @@ 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'
@@ -92,9 +95,13 @@ 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,
@@ -102,6 +109,10 @@ export {
   fmtDateTime,
   fmtDateTimeMs,
   fmtDateShort,
+  fmtCalendarDate,
+  fmtCalendarDateTime,
+  fmtMsAsSeconds,
+  fmtBytes,
   fmtPrice,
   fmtPct,
   fmtUsd,

package/src/utils/format.test.ts

@@ -178,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

@@ -111,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;