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

package/src/components/BaseGroupedChecklist.test.ts

@@ -0,0 +1,73 @@
+import { describe, it, expect } from 'vitest'
+import { mount } from '@vue/test-utils'
+import BaseGroupedChecklist from './BaseGroupedChecklist.vue'
+
+const GROUPS = [
+  { key: 'STOCK', label: 'Stocks', items: ['AMD', 'NVDA'] },
+  { key: 'ETF', label: 'ETFs', items: [] },
+  { key: 'CRYPTO', label: 'Crypto', items: ['BTC/USD'] },
+]
+
+function mountList(modelValue: string[] = []) {
+  return mount(BaseGroupedChecklist, {
+    props: {
+      groups: GROUPS,
+      modelValue,
+      allAriaLabel: 'Select all symbols',
+      itemAriaLabel: (s: string) => `Pick ${s}`,
+      'onUpdate:modelValue': () => {},
+    },
+  })
+}
+
+const box = (w: ReturnType<typeof mountList>, label: string) =>
+  w.find<HTMLInputElement>(`input[aria-label="${label}"]`)
+
+const lastEmit = (w: ReturnType<typeof mountList>) =>
+  (w.emitted('update:modelValue') as string[][][]).at(-1)![0]
+
+describe('BaseGroupedChecklist', () => {
+  it('renders non-empty groups with counts and reflects the model', () => {
+    const w = mountList(['AMD'])
+    expect(w.text()).toContain('Select all (3)')
+    expect(w.text()).toContain('Stocks (2)')
+    expect(w.text()).not.toContain('ETFs')
+    expect(box(w, 'Pick AMD').element.checked).toBe(true)
+    expect(box(w, 'Pick NVDA').element.checked).toBe(false)
+    expect(box(w, 'Select all Stocks').element.checked).toBe(false)
+    expect(box(w, 'Select all symbols').element.checked).toBe(false)
+  })
+
+  it('toggles one item', async () => {
+    const w = mountList(['AMD'])
+    await box(w, 'Pick BTC/USD').trigger('change')
+    expect(lastEmit(w)).toEqual(['AMD', 'BTC/USD'])
+    await box(w, 'Pick AMD').trigger('change')
+    expect(lastEmit(w)).toEqual([])
+  })
+
+  it('selects and clears a whole group, leaving others alone', async () => {
+    const w = mountList(['BTC/USD'])
+    await box(w, 'Select all Stocks').trigger('change')
+    expect(lastEmit(w)).toEqual(['AMD', 'NVDA', 'BTC/USD'])
+    await w.setProps({ modelValue: ['AMD', 'NVDA', 'BTC/USD'] })
+    await box(w, 'Select all Stocks').trigger('change')
+    expect(lastEmit(w)).toEqual(['BTC/USD'])
+  })
+
+  it('master checkbox selects everything, then clears everything', async () => {
+    const w = mountList([])
+    await box(w, 'Select all symbols').trigger('change')
+    expect(lastEmit(w)).toEqual(['AMD', 'NVDA', 'BTC/USD'])
+    await w.setProps({ modelValue: ['AMD', 'NVDA', 'BTC/USD'] })
+    expect(box(w, 'Select all symbols').element.checked).toBe(true)
+    await box(w, 'Select all symbols').trigger('change')
+    expect(lastEmit(w)).toEqual([])
+  })
+
+  it('emits in group order regardless of click order', async () => {
+    const w = mountList(['BTC/USD'])
+    await box(w, 'Pick AMD').trigger('change')
+    expect(lastEmit(w)).toEqual(['AMD', 'BTC/USD'])
+  })
+})

package/src/components/BaseGroupedChecklist.vue

@@ -0,0 +1,122 @@
+<template>
+  <div>
+    <label class="flex items-center gap-2 border-b border-slate-200 dark:border-slate-700 pb-2">
+      <input
+        type="checkbox"
+        class="h-4 w-4"
+        :checked="allSelected"
+        :aria-label="allAriaLabel"
+        @change="toggleAll"
+      />
+      <span class="text-sm font-medium text-slate-700 dark:text-slate-200">
+        {{ allLabel }} ({{ allItems.length }})
+      </span>
+    </label>
+    <div class="overflow-y-auto space-y-3 mt-3" :class="maxHeightClass">
+      <div v-for="g in visibleGroups" :key="g.key">
+        <label class="flex items-center gap-2 pb-1.5">
+          <input
+            type="checkbox"
+            class="h-4 w-4"
+            :checked="groupSelected(g)"
+            :aria-label="`${allLabel} ${g.label}`"
+            @change="toggleGroup(g)"
+          />
+          <span class="text-xs font-semibold uppercase tracking-wide text-slate-500 dark:text-slate-400">
+            {{ g.label }} ({{ g.items.length }})
+          </span>
+        </label>
+        <div class="grid grid-cols-[repeat(2,minmax(0,1fr))] sm:grid-cols-[repeat(3,minmax(0,1fr))] gap-x-3 gap-y-1.5">
+          <label v-for="item in g.items" :key="item" class="flex items-center gap-2">
+            <input
+              type="checkbox"
+              class="h-4 w-4"
+              :checked="selected.has(item)"
+              :aria-label="itemAriaLabel ? itemAriaLabel(item) : item"
+              @change="toggleItem(item)"
+            />
+            <span
+              class="text-sm text-slate-700 dark:text-slate-200"
+              :class="{ 'font-mono': mono }"
+            >{{ item }}</span>
+          </label>
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+/**
+ * Multi-select checklist in groups: a master "Select all (N)" checkbox, a
+ * per-group select-all, and one checkbox per item. `v-model` is the array of
+ * selected item ids (order follows the groups). Items are plain strings and
+ * must be unique across groups; empty groups are not rendered.
+ *
+ * Typical use: "pick which symbols / users / records an action applies to"
+ * inside a confirmation modal.
+ */
+import { computed } from 'vue'
+import type { ChecklistGroup } from '../types/checklist'
+
+interface Props {
+  groups: ChecklistGroup[]
+  modelValue: string[]
+  /** Text of the master checkbox; group checkboxes read "<allLabel> <group>". */
+  allLabel?: string
+  allAriaLabel?: string
+  /** Accessible name per item checkbox (defaults to the item itself). */
+  itemAriaLabel?: (item: string) => string
+  /** Render item labels in a monospace font (tickers, ids). */
+  mono?: boolean
+  maxHeightClass?: string
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  allLabel: 'Select all',
+  allAriaLabel: 'Select all items',
+  itemAriaLabel: undefined,
+  mono: false,
+  maxHeightClass: 'max-h-72',
+})
+
+const emit = defineEmits<{ (e: 'update:modelValue', value: string[]): void }>()
+
+const visibleGroups = computed(() => props.groups.filter((g) => g.items.length > 0))
+const allItems = computed(() => visibleGroups.value.flatMap((g) => g.items))
+const selected = computed(() => new Set(props.modelValue))
+
+const allSelected = computed(
+  () => allItems.value.length > 0 && allItems.value.every((i) => selected.value.has(i)),
+)
+
+function groupSelected(g: ChecklistGroup): boolean {
+  return g.items.every((i) => selected.value.has(i))
+}
+
+// Emit in group order so the model is stable regardless of click order.
+function commit(next: Set<string>) {
+  emit('update:modelValue', allItems.value.filter((i) => next.has(i)))
+}
+
+function toggleAll() {
+  commit(allSelected.value ? new Set() : new Set(allItems.value))
+}
+
+function toggleGroup(g: ChecklistGroup) {
+  const next = new Set(selected.value)
+  const on = !groupSelected(g)
+  for (const i of g.items) {
+    if (on) next.add(i)
+    else next.delete(i)
+  }
+  commit(next)
+}
+
+function toggleItem(item: string) {
+  const next = new Set(selected.value)
+  if (next.has(item)) next.delete(item)
+  else next.add(item)
+  commit(next)
+}
+</script>

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/useDirtyState.test.ts

@@ -0,0 +1,38 @@
+import { describe, it, expect } from 'vitest'
+import { reactive } from 'vue'
+import { stableStringify, useDirtyState } from './useDirtyState'
+
+describe('stableStringify', () => {
+  it('ignores key order at every depth but keeps array order', () => {
+    expect(stableStringify({ b: 1, a: { d: 2, c: 3 } })).toBe(stableStringify({ a: { c: 3, d: 2 }, b: 1 }))
+    expect(stableStringify([1, 2])).not.toBe(stableStringify([2, 1]))
+  })
+})
+
+describe('useDirtyState', () => {
+  it('starts clean, turns dirty on an edit and clean again when reverted', () => {
+    const form = reactive({ name: 'a', params: { x: 1 } as Record<string, number> })
+    const { dirty } = useDirtyState(() => form)
+    expect(dirty.value).toBe(false)
+    form.params.x = 2
+    expect(dirty.value).toBe(true)
+    form.params.x = 1
+    expect(dirty.value).toBe(false)
+  })
+
+  it('markClean() adopts the current state as the baseline', () => {
+    const form = reactive({ name: 'a' })
+    const { dirty, markClean } = useDirtyState(() => form)
+    form.name = 'b'
+    expect(dirty.value).toBe(true)
+    markClean()
+    expect(dirty.value).toBe(false)
+  })
+
+  it('a reordered but equal object is not an edit', () => {
+    const form = reactive<{ params: Record<string, number> }>({ params: { a: 1, b: 2 } })
+    const { dirty } = useDirtyState(() => form)
+    form.params = { b: 2, a: 1 }
+    expect(dirty.value).toBe(false)
+  })
+})

package/src/composables/useDirtyState.ts

@@ -0,0 +1,44 @@
+import { computed, ref, type ComputedRef } from 'vue'
+
+/**
+ * JSON-serialise a value with object keys sorted at every depth, so two
+ * structurally equal values always produce the same string regardless of
+ * key insertion order (arrays keep their order).
+ */
+export function stableStringify(value: unknown): string {
+  return JSON.stringify(value, (_key, v: unknown) => {
+    if (v !== null && typeof v === 'object' && !Array.isArray(v)) {
+      const sorted: Record<string, unknown> = {}
+      for (const k of Object.keys(v as Record<string, unknown>).sort()) {
+        sorted[k] = (v as Record<string, unknown>)[k]
+      }
+      return sorted
+    }
+    return v
+  })
+}
+
+/**
+ * Unsaved-changes tracking for an edit form. `snapshot` returns the form's
+ * current state (read reactively); `dirty` is true whenever it differs from
+ * the last clean baseline. Call `markClean()` after loading or saving to make
+ * the current state the new baseline. Comparison is structural (key order is
+ * ignored), so a server echo that reorders keys never reads as an edit.
+ *
+ * ```ts
+ * const form = reactive({ name: '', params: {} })
+ * const { dirty, markClean } = useDirtyState(() => form)
+ * // …load → assign form → markClean(); Save enabled while dirty.value
+ * ```
+ */
+export function useDirtyState(snapshot: () => unknown): {
+  dirty: ComputedRef<boolean>
+  markClean: () => void
+} {
+  const baseline = ref(stableStringify(snapshot()))
+  const dirty = computed(() => stableStringify(snapshot()) !== baseline.value)
+  function markClean() {
+    baseline.value = stableStringify(snapshot())
+  }
+  return { dirty, markClean }
+}

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