mgv-backoffice 1.30.0 → 1.31.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.31.0",
   "description": "Shared Vue 3 UI component library",
   "type": "module",
   "main": "./dist/ui-lib.umd.cjs",

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

@@ -62,6 +62,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 +94,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 +108,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;

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()
+}