mgv-backoffice 1.44.0 → 1.45.0

package/dist/utils/format.d.ts

@@ -45,6 +45,14 @@ 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 a money amount with the sign BEFORE the currency symbol ("-$2.26",
+ * never "$-2.26") and locale digit grouping ("$1,234.50"). Positive values
+ * carry no sign — prefix an explicit '+' where a gain should read signed.
+ * Renders an em-dash for null/undefined/non-finite input; accepts numeric
+ * strings so BigDecimal-as-string payloads pass through.
+ */
+export declare function fmtMoney(n: number | string | null | undefined, digits?: number, currency?: string): 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

package/package.json

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

package/src/components/Pagination.test.ts

@@ -90,4 +90,43 @@ describe('Pagination', () => {
       expect(wrapper.findAll('button').map((b) => b.text()).filter((t) => /^\d+$/.test(t))).toEqual(['1'])
     }
   })
+
+  describe('controlled (page prop)', () => {
+    it('highlights the page passed in, e.g. one restored from the URL', () => {
+      const wrapper = mount(Pagination, {
+        props: { totalItems: 200, itemsPerPage: 20, page: 5 },
+      })
+      expect(wrapper.find('button.active').text()).toBe('5')
+      expect(cellLabels(wrapper)).toEqual(['1', '...', '3', '4', '5', '6', '7', '...', '10'])
+    })
+
+    it('lets the user go back to page 1 from a restored page', async () => {
+      // Regression: the uncontrolled widget always started on page 1, so with
+      // a restored ?page=3 clicking "1" was swallowed as "already active".
+      const wrapper = mount(Pagination, {
+        props: { totalItems: 200, itemsPerPage: 20, page: 3 },
+      })
+      await clickPage(wrapper, 1)
+      expect(wrapper.emitted('page-changed')).toEqual([[1]])
+    })
+
+    it('follows the prop rather than its own clicks', async () => {
+      const wrapper = mount(Pagination, {
+        props: { totalItems: 200, itemsPerPage: 20, page: 2 },
+      })
+      await clickPage(wrapper, 4)
+      expect(wrapper.emitted('page-changed')).toEqual([[4]])
+      // The parent hasn't accepted the change yet — the highlight stays put.
+      expect(wrapper.find('button.active').text()).toBe('2')
+      await wrapper.setProps({ page: 4 })
+      expect(wrapper.find('button.active').text()).toBe('4')
+    })
+
+    it('clamps an out-of-range page to the last page', () => {
+      const wrapper = mount(Pagination, {
+        props: { totalItems: 40, itemsPerPage: 20, page: 9 },
+      })
+      expect(wrapper.find('button.active').text()).toBe('2')
+    })
+  })
 })

package/src/components/Pagination.vue

@@ -1,87 +1,102 @@
-<template>
-  <nav aria-label="Pagination">
-    <ul class="flex list-none p-0 m-0">
-      <li v-for="(cell, index) in cells" :key="index" class="mr-1">
-        <button
-          v-if="cell !== 0"
-          type="button"
-          :aria-current="cell === currentPage ? 'page' : undefined"
-          :aria-label="`Go to page ${cell}`"
-          @click="changePage(cell)"
-          class="inline-block min-w-[44px] border border-gray-300 dark:border-gray-600 rounded-lg p-3 text-black dark:text-gray-200 cursor-pointer transition-colors hover:bg-gray-300 dark:hover:bg-gray-700 focus:outline-none focus-visible:ring-2 focus-visible:ring-emerald-500"
-          :class="{ 'active font-bold bg-gray-200 dark:bg-gray-700': cell === currentPage }"
-        >{{ cell }}</button>
-        <span v-else aria-hidden="true" class="inline-block border border-gray-300 dark:border-gray-600 rounded-lg p-3 text-black dark:text-gray-200 cursor-not-allowed">...</span>
-      </li>
-    </ul>
-  </nav>
-</template>
-
-<script lang="ts" setup>
-import { ref, watch } from "vue";
-
-const props = defineProps({
-  totalItems: {
-    type: Number,
-    required: true
-  },
-  itemsPerPage: {
-    type: Number,
-    default: 20
-  }
-})
-
-const currentPage = ref(1);
-const totalPages = ref(0);
-const cells = ref([] as number[]);
-const emit = defineEmits(['page-changed']);
-
-// Rebuild the visible cells around `page`. A cell value of 0 renders as
-// an ellipsis. The window is the current page ± 2 neighbours, plus the
-// first/last page with an ellipsis only when pages are actually hidden.
-function buildCells(page: number) {
-  if (totalPages.value <= 5) {
-    cells.value = Array.from({ length: totalPages.value }, (_, i) => i + 1);
-    return;
-  }
-
-  const out: number[] = [];
-  const start = Math.max(1, page - 2);
-  const end = Math.min(totalPages.value, page + 2);
-
-  if (start > 1) {
-    out.push(1);
-    if (start > 2) out.push(0);
-  }
-  for (let i = start; i <= end; i++) {
-    out.push(i);
-  }
-  if (end < totalPages.value) {
-    if (end < totalPages.value - 1) out.push(0);
-    out.push(totalPages.value);
-  }
-  cells.value = out;
-}
-
-function changePage(pageNumber: number) {
-  if (pageNumber === currentPage.value || pageNumber < 1 || pageNumber > totalPages.value) {
-    return;
-  }
-  currentPage.value = pageNumber;
-  buildCells(pageNumber);
-  emit('page-changed', pageNumber);
-}
-
-watch(() => [props.totalItems, props.itemsPerPage], () => {
-  // Guard against a missing/zero page size or total (e.g. a reset form that
-  // nulled them): fall back to 20 per page / 0 items instead of rendering
-  // "Infinity" or "NaN" pages.
-  const perPage = Number(props.itemsPerPage) > 0 ? Number(props.itemsPerPage) : 20;
-  const total = Number(props.totalItems) > 0 ? Number(props.totalItems) : 0;
-  totalPages.value = Math.ceil(total / perPage);
-  if (currentPage.value > totalPages.value) {
-    currentPage.value = Math.max(1, totalPages.value);
-  }
-  buildCells(currentPage.value);
-}, { immediate: true })
-</script>
+<template>
+  <nav aria-label="Pagination">
+    <ul class="flex list-none p-0 m-0">
+      <li v-for="(cell, index) in cells" :key="index" class="mr-1">
+        <button
+          v-if="cell !== 0"
+          type="button"
+          :aria-current="cell === currentPage ? 'page' : undefined"
+          :aria-label="`Go to page ${cell}`"
+          @click="changePage(cell)"
+          class="inline-block min-w-[44px] border border-gray-300 dark:border-gray-600 rounded-lg p-3 text-black dark:text-gray-200 cursor-pointer transition-colors hover:bg-gray-300 dark:hover:bg-gray-700 focus:outline-none focus-visible:ring-2 focus-visible:ring-emerald-500"
+          :class="{ 'active font-bold bg-gray-200 dark:bg-gray-700': cell === currentPage }"
+        >{{ cell }}</button>
+        <span v-else aria-hidden="true" class="inline-block border border-gray-300 dark:border-gray-600 rounded-lg p-3 text-black dark:text-gray-200 cursor-not-allowed">...</span>
+      </li>
+    </ul>
+  </nav>
+</template>
+
+<script lang="ts" setup>
+import { computed, ref, watch } from "vue";
+
+const props = defineProps({
+  totalItems: {
+    type: Number,
+    required: true
+  },
+  itemsPerPage: {
+    type: Number,
+    default: 20
+  },
+  // Optional CONTROLLED current page (1-based). When set, the highlighted
+  // page follows this prop instead of internal state, so a page restored
+  // from the URL (?page=N) renders as N rather than 1. Clicks still emit
+  // `page-changed`; the parent is expected to feed the new page back in.
+  // Left undefined, the component keeps its own state (uncontrolled).
+  page: {
+    type: Number,
+    default: undefined
+  }
+})
+
+const emit = defineEmits(['page-changed']);
+
+// Guard against a missing/zero page size or total (e.g. a reset form that
+// nulled them): fall back to 20 per page / 0 items instead of rendering
+// "Infinity" or "NaN" pages.
+const totalPages = computed(() => {
+  const perPage = Number(props.itemsPerPage) > 0 ? Number(props.itemsPerPage) : 20;
+  const total = Number(props.totalItems) > 0 ? Number(props.totalItems) : 0;
+  return Math.ceil(total / perPage);
+});
+
+function clamp(p: number): number {
+  return Math.min(Math.max(p, 1), Math.max(totalPages.value, 1));
+}
+
+const internalPage = ref(1);
+// The total shrinking under the current page snaps it to the last page.
+watch(totalPages, () => {
+  internalPage.value = clamp(internalPage.value);
+});
+
+const currentPage = computed(() =>
+  props.page != null && Number.isFinite(props.page) ? clamp(props.page) : internalPage.value
+);
+
+// The visible cells around the current page. A cell value of 0 renders as
+// an ellipsis. The window is the current page ± 2 neighbours, plus the
+// first/last page with an ellipsis only when pages are actually hidden.
+const cells = computed(() => {
+  const total = totalPages.value;
+  if (total <= 5) {
+    return Array.from({ length: total }, (_, i) => i + 1);
+  }
+
+  const out: number[] = [];
+  const start = Math.max(1, currentPage.value - 2);
+  const end = Math.min(total, currentPage.value + 2);
+
+  if (start > 1) {
+    out.push(1);
+    if (start > 2) out.push(0);
+  }
+  for (let i = start; i <= end; i++) {
+    out.push(i);
+  }
+  if (end < total) {
+    if (end < total - 1) out.push(0);
+    out.push(total);
+  }
+  return out;
+});
+
+function changePage(pageNumber: number) {
+  if (pageNumber === currentPage.value || pageNumber < 1 || pageNumber > totalPages.value) {
+    return;
+  }
+  internalPage.value = pageNumber;
+  emit('page-changed', pageNumber);
+}
+</script>

package/src/composables/useLatestRequest.test.ts

@@ -0,0 +1,61 @@
+import { describe, it, expect } from 'vitest'
+import { defineComponent, h } from 'vue'
+import { mount } from '@vue/test-utils'
+import { useLatestRequest, isAbortError, type LatestRequestToken } from './useLatestRequest'
+
+describe('useLatestRequest', () => {
+  it('aborts and invalidates the previous request when a new one begins', () => {
+    const latest = useLatestRequest()
+    const a = latest.begin()
+    expect(a.isLatest()).toBe(true)
+    expect(a.signal.aborted).toBe(false)
+
+    const b = latest.begin()
+    expect(a.signal.aborted).toBe(true)
+    expect(a.isLatest()).toBe(false)
+    expect(b.isLatest()).toBe(true)
+    expect(b.signal.aborted).toBe(false)
+  })
+
+  it('cancel() aborts the in-flight request without starting another', () => {
+    const latest = useLatestRequest()
+    const a = latest.begin()
+    latest.cancel()
+    expect(a.signal.aborted).toBe(true)
+    expect(a.isLatest()).toBe(false)
+    // A later begin() works normally.
+    expect(latest.begin().isLatest()).toBe(true)
+  })
+
+  it('cancels the in-flight request when the owning component unmounts', () => {
+    let token!: LatestRequestToken
+    const wrapper = mount(
+      defineComponent({
+        setup() {
+          token = useLatestRequest().begin()
+          return () => h('div')
+        },
+      }),
+    )
+    expect(token.signal.aborted).toBe(false)
+    wrapper.unmount()
+    expect(token.signal.aborted).toBe(true)
+    expect(token.isLatest()).toBe(false)
+  })
+})
+
+describe('isAbortError', () => {
+  it('recognises DOMException and Error abort rejections', () => {
+    expect(isAbortError(new DOMException('aborted', 'AbortError'))).toBe(true)
+    const e = new Error('aborted')
+    e.name = 'AbortError'
+    expect(isAbortError(e)).toBe(true)
+  })
+
+  it('rejects everything else', () => {
+    expect(isAbortError(new Error('boom'))).toBe(false)
+    expect(isAbortError(new DOMException('x', 'TimeoutError'))).toBe(false)
+    expect(isAbortError('AbortError')).toBe(false)
+    expect(isAbortError(null)).toBe(false)
+  })
+})

package/src/composables/useLatestRequest.ts

@@ -0,0 +1,81 @@
+import { getCurrentScope, onScopeDispose } from 'vue'
+
+/** One begun request: its abort signal and whether it is still the latest. */
+export interface LatestRequestToken {
+  /** Pass to fetch(); aborted as soon as a newer request begins (or on cancel). */
+  signal: AbortSignal
+  /**
+   * True while no newer begin() / cancel() has happened. Check it after every
+   * await before writing state, so a superseded response can never clobber
+   * the newer one's — and only the latest call clears its loading flag.
+   */
+  isLatest: () => boolean
+}
+
+/**
+ * "Latest request wins" guard for views that refetch on every filter change,
+ * poll, or Refresh click. Each `begin()` aborts the previous in-flight request
+ * on the wire and hands back a fresh AbortSignal plus an `isLatest()` check
+ * (a monotonic request id), so a slow, stale response that still lands can be
+ * dropped instead of racing the fresh one.
+ *
+ * `cancel()` aborts the in-flight request and invalidates it without starting
+ * a new one (e.g. the selection was cleared). When called inside a component
+ * setup / effect scope, the in-flight request is cancelled automatically on
+ * unmount.
+ *
+ * ```ts
+ * const latest = useLatestRequest()
+ * async function load() {
+ *   const req = latest.begin()
+ *   loading.value = true
+ *   try {
+ *     const res = await fetchThings(req.signal)
+ *     if (!req.isLatest()) return
+ *     rows.value = res
+ *   } catch (e) {
+ *     if (!req.isLatest() || isAbortError(e)) return
+ *     error.value = String(e)
+ *   } finally {
+ *     if (req.isLatest()) loading.value = false
+ *   }
+ * }
+ * ```
+ */
+export function useLatestRequest(): {
+  begin: () => LatestRequestToken
+  cancel: () => void
+} {
+  let seq = 0
+  let ctrl: AbortController | null = null
+
+  function begin(): LatestRequestToken {
+    const mine = ++seq
+    ctrl?.abort()
+    const c = new AbortController()
+    ctrl = c
+    return { signal: c.signal, isLatest: () => mine === seq }
+  }
+
+  function cancel(): void {
+    ++seq
+    ctrl?.abort()
+    ctrl = null
+  }
+
+  if (getCurrentScope()) onScopeDispose(cancel)
+
+  return { begin, cancel }
+}
+
+/**
+ * True for the rejection an aborted fetch() produces (a DOMException — or, in
+ * some runtimes, a plain Error — named "AbortError"). Superseded / cancelled
+ * requests should be swallowed silently rather than shown as an error.
+ */
+export function isAbortError(e: unknown): boolean {
+  return (
+    (typeof DOMException !== 'undefined' && e instanceof DOMException && e.name === 'AbortError') ||
+    (e instanceof Error && e.name === 'AbortError')
+  )
+}

package/src/index.ts

@@ -85,6 +85,8 @@ export { useFieldClasses } from './composables/useFieldClasses'
 export type { FieldClasses } from './composables/useFieldClasses'
 export { usePolling } from './composables/usePolling'
 export type { UsePollingOptions } from './composables/usePolling'
+export { useLatestRequest, isAbortError } from './composables/useLatestRequest'
+export type { LatestRequestToken } from './composables/useLatestRequest'
 
 // Enums
 export { AlertEnum } from './enums/AlertEnum'
@@ -138,6 +140,7 @@ export {
   fmtPrice,
   fmtPct,
   fmtUsd,
+  fmtMoney,
   fmtDuration,
   formatJson,
   stringifyValue,

package/src/utils/format.test.ts

@@ -8,6 +8,7 @@ import {
   fmtPrice,
   fmtPct,
   fmtUsd,
+  fmtMoney,
   fmtDuration,
   formatJson,
   stringifyValue,
@@ -262,3 +263,28 @@ describe('stringifyValue', () => {
     expect(stringifyValue(1n)).toBe('1')
   })
 })
+
+describe('fmtMoney', () => {
+  it('puts the minus before the currency and groups digits', () => {
+    expect(fmtMoney(-2.26)).toBe('-$2.26')
+    expect(fmtMoney(1234.5)).toBe(`$${(1234.5).toLocaleString(undefined, { minimumFractionDigits: 2 })}`)
+    expect(fmtMoney(0)).toBe('$0.00')
+  })
+
+  it('honours digits and currency', () => {
+    expect(fmtMoney(1.5, 3)).toBe('$1.500')
+    expect(fmtMoney(-3, 2, '€')).toBe('-€3.00')
+  })
+
+  it('does not sign a value that rounds to zero', () => {
+    expect(fmtMoney(-0.001)).toBe('$0.00')
+  })
+
+  it('renders an em-dash for missing input and accepts numeric strings', () => {
+    expect(fmtMoney(null)).toBe('—')
+    expect(fmtMoney(undefined)).toBe('—')
+    expect(fmtMoney('')).toBe('—')
+    expect(fmtMoney(NaN)).toBe('—')
+    expect(fmtMoney('-4.5')).toBe('-$4.50')
+  })
+})

package/src/utils/format.ts

@@ -111,6 +111,31 @@ export function fmtUsd(v: number): string {
   return `${sign}$${Math.abs(v).toFixed(2)}`
 }
 
+/**
+ * Format a money amount with the sign BEFORE the currency symbol ("-$2.26",
+ * never "$-2.26") and locale digit grouping ("$1,234.50"). Positive values
+ * carry no sign — prefix an explicit '+' where a gain should read signed.
+ * Renders an em-dash for null/undefined/non-finite input; accepts numeric
+ * strings so BigDecimal-as-string payloads pass through.
+ */
+export function fmtMoney(
+  n: number | string | null | undefined,
+  digits = 2,
+  currency = '$',
+): string {
+  if (n === null || n === undefined) return EM_DASH
+  if (typeof n === 'string' && n.trim() === '') return EM_DASH
+  const v = typeof n === 'string' ? Number(n) : n
+  if (!isFinite(v)) return EM_DASH
+  const abs = Math.abs(v).toLocaleString(undefined, {
+    minimumFractionDigits: digits,
+    maximumFractionDigits: digits,
+  })
+  // A value that rounds to zero ("-0.00") reads unsigned.
+  const negative = v < 0 && Number(Math.abs(v).toFixed(digits)) !== 0
+  return `${negative ? '-' : ''}${currency}${abs}`
+}
+
 /**
  * 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