mgv-backoffice 1.28.0 → 1.30.0

package/dist/utils/specForm.d.ts

@@ -0,0 +1,20 @@
+import { SpecField, SpecFieldValue } from '../types/specField';
+/**
+ * Helpers for spec-driven forms (the value maps behind BaseSpecFields), so
+ * param seeding and numeric validation stay single-sourced across consumers.
+ */
+/**
+ * Build the value map for a spec set: keep any overlapping values the caller
+ * already has (e.g. a shared amount field carries across spec sets), otherwise
+ * fall back to the spec's default. No specs → empty map. A `default: null`
+ * seeds the field with null so it renders as an empty (optional) input.
+ */
+export declare function buildSpecParams(specs: readonly SpecField[] | undefined, existing: Record<string, SpecFieldValue>): Record<string, SpecFieldValue>;
+/**
+ * Label of the first blank / NaN numeric field (a cleared number input becomes
+ * '' under number coercion), or null when every numeric field holds a number.
+ * A spec whose `default` is null is OPTIONAL: blank means "knob disabled" and
+ * must pass; a non-blank value on an optional field is still validated as a
+ * number.
+ */
+export declare function firstInvalidNumericSpec(specs: readonly SpecField[] | undefined, params: Record<string, SpecFieldValue>): string | null;

package/package.json

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

package/src/components/BaseCredentialsForm.test.ts

@@ -0,0 +1,108 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { flushPromises, mount } from '@vue/test-utils'
+import BaseCredentialsForm from './BaseCredentialsForm.vue'
+import type { CredentialsView } from './BaseCredentialsForm.vue'
+
+const view = (over: Partial<CredentialsView> = {}): CredentialsView => ({
+  keyId: 'PK123',
+  baseUrl: 'https://api.example.com',
+  dataUrl: 'https://data.example.com',
+  hasSecret: true,
+  ...over,
+})
+
+const defaults = { baseUrl: 'https://default.base', dataUrl: 'https://default.data' }
+
+function mountCard(fetchFn = vi.fn().mockResolvedValue(view()), updateFn = vi.fn()) {
+  const wrapper = mount(BaseCredentialsForm, {
+    props: { title: 'Alpaca API', idPrefix: 'alpaca', fetchFn, updateFn, defaults },
+  })
+  return { wrapper, fetchFn, updateFn }
+}
+
+beforeEach(() => {
+  localStorage.clear()
+})
+
+describe('BaseCredentialsForm', () => {
+  it('loads on mount and fills the form from the fetched view', async () => {
+    const { wrapper, fetchFn } = mountCard()
+    await flushPromises()
+    expect(fetchFn).toHaveBeenCalledTimes(1)
+    expect((wrapper.get('#alpaca-key-id').element as HTMLInputElement).value).toBe('PK123')
+    expect((wrapper.get('#alpaca-base-url').element as HTMLInputElement).value).toBe(
+      'https://api.example.com',
+    )
+  })
+
+  it('falls back to the defaults when the server has no URLs stored', async () => {
+    const { wrapper } = mountCard(
+      vi.fn().mockResolvedValue(view({ keyId: null, baseUrl: '', dataUrl: '', hasSecret: false })),
+    )
+    await flushPromises()
+    expect((wrapper.get('#alpaca-base-url').element as HTMLInputElement).value).toBe(
+      defaults.baseUrl,
+    )
+    expect((wrapper.get('#alpaca-data-url').element as HTMLInputElement).value).toBe(
+      defaults.dataUrl,
+    )
+  })
+
+  it('emits load-error when the fetch rejects', async () => {
+    const { wrapper } = mountCard(vi.fn().mockRejectedValue(new Error('boom')))
+    await flushPromises()
+    expect(wrapper.emitted('load-error')).toEqual([['boom']])
+  })
+
+  it('refuses to save without a key and emits the configured message', async () => {
+    const { wrapper, updateFn } = mountCard(
+      vi.fn().mockResolvedValue(view({ keyId: null, hasSecret: false })),
+    )
+    await flushPromises()
+    await wrapper.get('button').trigger('click')
+    expect(updateFn).not.toHaveBeenCalled()
+    expect(wrapper.emitted('error')?.[0]).toEqual(['API key is required.'])
+  })
+
+  it('requires a secret only while none is stored', async () => {
+    const { wrapper, updateFn } = mountCard(
+      vi.fn().mockResolvedValue(view({ hasSecret: false })),
+    )
+    await flushPromises()
+    await wrapper.get('button').trigger('click')
+    expect(updateFn).not.toHaveBeenCalled()
+    expect(wrapper.emitted('error')?.[0]).toEqual(['Secret key is required.'])
+  })
+
+  it('saves trimmed values, omits a blank secret, and emits saved', async () => {
+    const updateFn = vi.fn().mockResolvedValue(view())
+    const { wrapper } = mountCard(vi.fn().mockResolvedValue(view()), updateFn)
+    await flushPromises()
+    await wrapper.get('#alpaca-key-id').setValue('  PK999  ')
+    await wrapper.get('button').trigger('click')
+    await flushPromises()
+    expect(updateFn).toHaveBeenCalledWith({
+      keyId: 'PK999',
+      secretKey: undefined,
+      baseUrl: 'https://api.example.com',
+      dataUrl: 'https://data.example.com',
+    })
+    expect(wrapper.emitted('saved')).toEqual([['Credentials saved.']])
+  })
+
+  it('emits error with the server message when the update rejects', async () => {
+    const updateFn = vi.fn().mockRejectedValue(new Error('validation failed'))
+    const { wrapper } = mountCard(vi.fn().mockResolvedValue(view()), updateFn)
+    await flushPromises()
+    await wrapper.get('button').trigger('click')
+    await flushPromises()
+    expect(wrapper.emitted('error')?.[0]).toEqual(['validation failed'])
+  })
+
+  it('exposes load() so a parent Reload can re-pull the card', async () => {
+    const { wrapper, fetchFn } = mountCard()
+    await flushPromises()
+    await (wrapper.vm as unknown as { load: () => Promise<void> }).load()
+    expect(fetchFn).toHaveBeenCalledTimes(2)
+  })
+})

package/src/components/BaseCredentialsForm.vue

@@ -0,0 +1,241 @@
+<script setup lang="ts">
+import { onMounted, reactive, ref } from 'vue'
+import BaseButton from './BaseButton.vue'
+import BaseInput from './BaseInput.vue'
+import BaseRow from './BaseRow.vue'
+import BaseSpinner from './BaseSpinner.vue'
+import { BaseButtonEnum } from '../enums/BaseButtonEnum'
+
+// One service's API-credentials card (extracted from TradeAutomation's
+// Settings page, where three venue blocks shared this exact shape). Owns the
+// form state, the has-secret handling, the save-validation ladder and the
+// template; parameterised by the service-specific bits (labels, copy,
+// endpoints, default URLs). Load/save results are EMITTED — the parent owns
+// toasts / error banners.
+
+// The non-secret credentials view the service's config endpoint returns. The
+// secret is never returned — `hasSecret` reports whether one is stored.
+export interface CredentialsView {
+  keyId: string | null
+  baseUrl: string
+  dataUrl: string
+  hasSecret: boolean
+}
+
+export interface CredentialsUpdate {
+  keyId: string
+  // Omitted when blank so the server keeps the currently-stored secret.
+  secretKey?: string
+  baseUrl: string
+  dataUrl: string
+}
+
+const props = withDefaults(
+  defineProps<{
+    // Card heading, e.g. "Alpaca API"; subtitle renders under it when set.
+    title: string
+    subtitle?: string
+    // Unique prefix for the input ids so the label/for pairs stay unambiguous
+    // when several of these cards render on one page.
+    idPrefix: string
+    // Service-specific labels / placeholders / messages.
+    keyLabel?: string
+    keyPlaceholder?: string
+    secretLabel?: string
+    // Placeholder while NO secret is stored (a stored one shows the dots).
+    secretPlaceholder?: string
+    // Help line while a secret IS stored.
+    secretSetHint?: string
+    // Help line while no secret is stored (e.g. which API permissions the key
+    // needs). Override the `no-secret-hint` slot instead when markup is needed.
+    permissionsHint?: string
+    requiredKeyMessage?: string
+    requiredSecretMessage?: string
+    savedMessage?: string
+    saveLabel?: string
+    // Service endpoints + the URLs the form falls back to when the server has
+    // none stored yet.
+    fetchFn: () => Promise<CredentialsView>
+    updateFn: (body: CredentialsUpdate) => Promise<CredentialsView>
+    defaults: { baseUrl: string; dataUrl: string }
+  }>(),
+  {
+    subtitle: '',
+    keyLabel: 'API Key',
+    keyPlaceholder: '',
+    secretLabel: 'Secret Key',
+    secretPlaceholder: 'Enter secret key',
+    secretSetHint: 'A secret is currently set. Leave blank to keep it.',
+    permissionsHint: '',
+    requiredKeyMessage: 'API key is required.',
+    requiredSecretMessage: 'Secret key is required.',
+    savedMessage: 'Credentials saved.',
+    saveLabel: 'Save credentials',
+  },
+)
+
+const emit = defineEmits<{
+  // Save outcomes → parent toasts.
+  (e: 'saved', message: string): void
+  (e: 'error', message: string): void
+  // Initial/re-load failure. Payload is the raw error message ('' when there
+  // is none) — the parent decides how loudly to surface it.
+  (e: 'load-error', message: string): void
+}>()
+
+const saving = ref(false)
+const hasSecret = ref(false)
+
+const form = reactive({
+  keyId: '',
+  secretKey: '',
+  baseUrl: props.defaults.baseUrl,
+  dataUrl: props.defaults.dataUrl,
+})
+
+async function load() {
+  try {
+    const cfg = await props.fetchFn()
+    form.keyId = cfg.keyId ?? ''
+    form.baseUrl = cfg.baseUrl || props.defaults.baseUrl
+    form.dataUrl = cfg.dataUrl || props.defaults.dataUrl
+    form.secretKey = '' // never returned by the API
+    hasSecret.value = cfg.hasSecret
+  } catch (e: unknown) {
+    emit('load-error', e instanceof Error ? e.message : '')
+  }
+}
+
+function isBlank(v: string): boolean {
+  return !v || !v.trim()
+}
+
+async function save() {
+  // Re-entrancy guard: a save may trigger a LIVE credential validation
+  // against the service, so a double-click must not fire two concurrent PUTs.
+  // Paired with the button's isDisable below — this is the belt to its braces.
+  if (saving.value) return
+  if (isBlank(form.keyId)) {
+    emit('error', props.requiredKeyMessage)
+    return
+  }
+  if (!hasSecret.value && isBlank(form.secretKey)) {
+    emit('error', props.requiredSecretMessage)
+    return
+  }
+  if (isBlank(form.baseUrl) || isBlank(form.dataUrl)) {
+    emit('error', 'Base URL and Data URL are required.')
+    return
+  }
+  saving.value = true
+  try {
+    const applied = await props.updateFn({
+      keyId: form.keyId.trim(),
+      // Omit when blank so the server keeps the stored secret.
+      secretKey: isBlank(form.secretKey) ? undefined : form.secretKey.trim(),
+      baseUrl: form.baseUrl.trim(),
+      dataUrl: form.dataUrl.trim(),
+    })
+    hasSecret.value = applied.hasSecret
+    form.secretKey = ''
+    emit('saved', props.savedMessage)
+  } catch (e: unknown) {
+    emit('error', e instanceof Error ? e.message : 'Failed to save')
+  } finally {
+    saving.value = false
+  }
+}
+
+onMounted(load)
+
+// The parent's Reload button can re-pull every card in parallel via this.
+defineExpose({ load })
+
+// One-off styling on top of BaseInput's shared field skin.
+const inputClass = 'placeholder:text-slate-400 dark:placeholder:text-slate-500 font-mono'
+</script>
+
+<template>
+  <BaseRow class="!p-6">
+    <div class="flex items-center justify-between mb-4">
+      <div>
+        <h2 class="text-lg font-semibold text-slate-900 dark:text-slate-100">{{ title }}</h2>
+        <p v-if="subtitle" class="text-xs text-slate-500 dark:text-slate-400">
+          {{ subtitle }}
+        </p>
+      </div>
+      <span v-if="saving" class="inline-flex items-center gap-2 text-xs text-slate-500">
+        <BaseSpinner class="!h-4 !w-4" />
+        Saving…
+      </span>
+    </div>
+
+    <div class="grid gap-4 md:grid-cols-2">
+      <div class="md:col-span-2">
+        <label
+          :for="`${idPrefix}-key-id`"
+          class="block text-xs uppercase tracking-wide text-slate-500 mb-1"
+        >{{ keyLabel }}</label>
+        <BaseInput
+          :id="`${idPrefix}-key-id`"
+          v-model="form.keyId"
+          type="text"
+          autocomplete="off"
+          :placeholder="keyPlaceholder"
+          :class="inputClass"
+        />
+      </div>
+
+      <div class="md:col-span-2">
+        <label
+          :for="`${idPrefix}-secret`"
+          class="block text-xs uppercase tracking-wide text-slate-500 mb-1"
+        >{{ secretLabel }}</label>
+        <BaseInput
+          :id="`${idPrefix}-secret`"
+          v-model="form.secretKey"
+          type="password"
+          autocomplete="new-password"
+          :placeholder="hasSecret ? '•••••••• (unchanged — type to replace)' : secretPlaceholder"
+          :class="inputClass"
+        />
+        <p class="text-[11px] text-slate-500 mt-1">
+          <template v-if="hasSecret">{{ secretSetHint }}</template>
+          <template v-else><slot name="no-secret-hint">{{ permissionsHint }}</slot></template>
+        </p>
+      </div>
+
+      <div class="md:col-span-2">
+        <label
+          :for="`${idPrefix}-base-url`"
+          class="block text-xs uppercase tracking-wide text-slate-500 mb-1"
+        >Base URL (trading)</label>
+        <BaseInput :id="`${idPrefix}-base-url`" v-model="form.baseUrl" type="text" :class="inputClass" />
+        <!-- Service-specific extras under the Base URL field (e.g. live/paper
+             shortcut buttons). Scoped so the parent can write into the form. -->
+        <slot name="base-url-extra" :form="form" />
+      </div>
+
+      <div class="md:col-span-2">
+        <label
+          :for="`${idPrefix}-data-url`"
+          class="block text-xs uppercase tracking-wide text-slate-500 mb-1"
+        >Data URL (market data)</label>
+        <BaseInput :id="`${idPrefix}-data-url`" v-model="form.dataUrl" type="text" :class="inputClass" />
+      </div>
+
+      <div class="md:col-span-2">
+        <BaseButton
+          :color="BaseButtonEnum.GREEN"
+          :description="saveLabel"
+          :isDisable="saving"
+          :isLoading="saving"
+          @click="save"
+        />
+      </div>
+    </div>
+
+    <!-- Service-specific extras below the credentials form. -->
+    <slot name="footer" />
+  </BaseRow>
+</template>

package/src/components/BaseDropdown.test.ts

@@ -61,4 +61,27 @@ describe('BaseDropdown', () => {
     expect(rows[1].attributes('aria-selected')).toBe('false')
     expect(rows[0].get('button').classes()).toContain('bg-emerald-500')
   })
+
+  it('replaces the default trigger skin when triggerClass is set', () => {
+    const wrapper = mount(BaseDropdown, {
+      props: { options, modelValue: '1', triggerClass: 'rounded border bg-red-100 text-red-700 px-1.5 py-0.5' },
+    })
+    const classes = wrapper.get('button').classes()
+    // Custom skin applied…
+    expect(classes).toContain('bg-red-100')
+    expect(classes).toContain('text-red-700')
+    // …and the default slate skin dropped (layout/focus classes remain).
+    expect(classes).not.toContain('border-slate-300')
+    expect(classes).not.toContain('bg-white')
+    expect(classes).toContain('cursor-pointer')
+  })
+
+  it('sizes the chevron via chevronClass', () => {
+    const wrapper = mount(BaseDropdown, {
+      props: { options, modelValue: '1', chevronClass: 'w-3 h-3' },
+    })
+    const chevron = wrapper.get('button svg')
+    expect(chevron.classes()).toContain('w-3')
+    expect(chevron.classes()).not.toContain('w-5')
+  })
 })

package/src/components/BaseDropdown.vue

@@ -31,8 +31,8 @@
         {{ selectedOption ? selectedOption.label : placeholder }}
       </span>
       <ChevronDownIcon
-        class="w-5 h-5 shrink-0 text-slate-500 dark:text-slate-400 transition-transform"
-        :class="open ? 'rotate-180' : ''"
+        class="shrink-0 transition-transform"
+        :class="[chevronClass, open ? 'rotate-180' : '']"
         aria-hidden="true"
       />
     </button>
@@ -85,6 +85,15 @@ interface Props {
   disabled?: boolean
   /** Accessible name for the trigger/listbox when there is no visible label. */
   ariaLabel?: string
+  /**
+   * Replaces the trigger's default slate skin (border/background/text/padding)
+   * with the given classes — layout, focus ring and disabled classes are kept.
+   * Lets a consumer render the trigger as e.g. a coloured status pill while
+   * keeping the shared menu behaviour. `size` is ignored when this is set.
+   */
+  triggerClass?: string
+  /** Chevron sizing/colour classes; shrink for compact triggers. */
+  chevronClass?: string
 }
 
 const props = withDefaults(defineProps<Props>(), {
@@ -94,6 +103,8 @@ const props = withDefaults(defineProps<Props>(), {
   block: true,
   disabled: false,
   ariaLabel: '',
+  triggerClass: '',
+  chevronClass: 'w-5 h-5 text-slate-500 dark:text-slate-400',
 })
 
 const emit = defineEmits<{
@@ -109,12 +120,17 @@ const selectedOption = computed(() =>
 )
 
 const triggerClass = computed(() => {
+  const layout =
+    'flex items-center justify-between gap-2 text-left transition-colors ' +
+    'focus:outline-none focus-visible:ring-2 focus-visible:ring-emerald-500 ' +
+    'cursor-pointer disabled:opacity-50 disabled:cursor-not-allowed '
+  if (props.triggerClass) return layout + props.triggerClass
   const padding = props.size === 'sm' ? 'px-3 py-2' : 'px-4 py-2.5'
   return (
-    'flex items-center justify-between gap-2 rounded-lg border text-left text-sm transition-colors ' +
+    layout +
+    'rounded-lg border text-sm ' +
     'border-slate-300 dark:border-slate-600 bg-white dark:bg-slate-900 text-slate-700 dark:text-slate-100 ' +
-    'hover:bg-slate-50 dark:hover:bg-slate-800 focus:outline-none focus-visible:ring-2 focus-visible:ring-emerald-500 ' +
-    'cursor-pointer disabled:opacity-50 disabled:cursor-not-allowed ' +
+    'hover:bg-slate-50 dark:hover:bg-slate-800 ' +
     padding
   )
 })

package/src/components/BaseFilterChip.test.ts

@@ -0,0 +1,44 @@
+import { describe, it, expect } from 'vitest'
+import { mount } from '@vue/test-utils'
+import BaseFilterChip from './BaseFilterChip.vue'
+
+describe('BaseFilterChip', () => {
+  it('renders the label prop, overridden by the default slot', () => {
+    expect(mount(BaseFilterChip, { props: { label: 'Buy' } }).text()).toBe('Buy')
+    expect(
+      mount(BaseFilterChip, { props: { label: 'x' }, slots: { default: 'Sell' } }).text(),
+    ).toBe('Sell')
+  })
+
+  it('switches from the tinted idle skin to the solid active fill', () => {
+    const idle = mount(BaseFilterChip, { props: { color: 'sky', active: false } })
+    expect(idle.get('button').classes()).toContain('bg-sky-50')
+    expect(idle.get('button').attributes('aria-pressed')).toBe('false')
+
+    const active = mount(BaseFilterChip, { props: { color: 'sky', active: true } })
+    expect(active.get('button').classes()).toContain('bg-sky-500')
+    expect(active.get('button').classes()).toContain('text-white')
+    expect(active.get('button').attributes('aria-pressed')).toBe('true')
+  })
+
+  it('lets native click listeners through, blocked when disabled', async () => {
+    let clicks = 0
+    const chip = mount(BaseFilterChip, {
+      props: { label: 'Buy' },
+      attrs: { onClick: () => clicks++ },
+    })
+    await chip.get('button').trigger('click')
+    expect(clicks).toBe(1)
+
+    const off = mount(BaseFilterChip, {
+      props: { label: 'Buy', disabled: true },
+      attrs: { onClick: () => clicks++ },
+    })
+    expect(off.get('button').attributes('disabled')).toBeDefined()
+  })
+
+  it('forwards the title tooltip', () => {
+    const chip = mount(BaseFilterChip, { props: { label: 'Buy', title: 'Show buys' } })
+    expect(chip.get('button').attributes('title')).toBe('Show buys')
+  })
+})

package/src/components/BaseFilterChip.vue

@@ -0,0 +1,67 @@
+<template>
+  <!--
+    Colour-coded toggleable filter chip — the one-click event/category filter
+    buttons above a data feed (extracted from TradeAutomation's Trade Log).
+    Idle: tinted border/background in the semantic colour. Active: solid fill
+    with white text. `aria-pressed` reflects the toggle state.
+
+    Layout (height, flex sizing) is the caller's: pass classes like
+    `h-9 flex-1` through the class attribute.
+
+    The click handler falls through natively to the root <button> — bind
+    @click on the component as usual; a disabled chip blocks it.
+  -->
+  <button
+    type="button"
+    :disabled="disabled"
+    :title="title"
+    :aria-pressed="active"
+    class="whitespace-nowrap rounded-md border px-3 text-sm font-semibold text-center transition-colors focus:outline-none focus-visible:ring-2 disabled:opacity-50 disabled:cursor-not-allowed"
+    :class="active ? ACTIVE[color] : IDLE[color]"
+  >
+    <slot>{{ label }}</slot>
+  </button>
+</template>
+
+<script setup lang="ts">
+type FilterChipColor = 'emerald' | 'sky' | 'amber' | 'red' | 'slate'
+
+withDefaults(
+  defineProps<{
+    /** Chip text; the default slot overrides it. */
+    label?: string
+    /** Semantic colour of both the idle tint and the active solid fill. */
+    color?: FilterChipColor
+    /** Whether the chip's filter is currently applied (solid fill). */
+    active?: boolean
+    disabled?: boolean
+    /** Native tooltip. */
+    title?: string
+  }>(),
+  { label: '', color: 'slate', active: false, disabled: false, title: undefined },
+)
+
+// Full literal class strings (no dynamic concatenation) so Tailwind detects
+// them at build time. Idle: tinted; active: solid with white text.
+const IDLE: Record<FilterChipColor, string> = {
+  emerald:
+    'border-emerald-300 dark:border-emerald-700/60 bg-emerald-50 dark:bg-emerald-900/20 text-emerald-700 dark:text-emerald-400 hover:bg-emerald-100 dark:hover:bg-emerald-900/30 focus-visible:ring-emerald-500',
+  sky:
+    'border-sky-300 dark:border-sky-700/60 bg-sky-50 dark:bg-sky-900/20 text-sky-700 dark:text-sky-400 hover:bg-sky-100 dark:hover:bg-sky-900/30 focus-visible:ring-sky-500',
+  amber:
+    'border-amber-300 dark:border-amber-700/60 bg-amber-50 dark:bg-amber-900/20 text-amber-700 dark:text-amber-400 hover:bg-amber-100 dark:hover:bg-amber-900/30 focus-visible:ring-amber-500',
+  red:
+    'border-red-300 dark:border-red-700/60 bg-red-50 dark:bg-red-900/20 text-red-700 dark:text-red-400 hover:bg-red-100 dark:hover:bg-red-900/30 focus-visible:ring-red-500',
+  slate:
+    'border-slate-300 dark:border-slate-600 bg-slate-50 dark:bg-slate-900 text-slate-600 dark:text-slate-300 hover:bg-slate-100 dark:hover:bg-slate-800 focus-visible:ring-emerald-500',
+}
+
+const ACTIVE: Record<FilterChipColor, string> = {
+  emerald:
+    'border-emerald-500 bg-emerald-500 text-white hover:bg-emerald-600 focus-visible:ring-emerald-500',
+  sky: 'border-sky-500 bg-sky-500 text-white hover:bg-sky-600 focus-visible:ring-sky-500',
+  amber: 'border-amber-500 bg-amber-500 text-white hover:bg-amber-600 focus-visible:ring-amber-500',
+  red: 'border-red-500 bg-red-500 text-white hover:bg-red-600 focus-visible:ring-red-500',
+  slate: 'border-slate-600 bg-slate-600 text-white hover:bg-slate-700 focus-visible:ring-emerald-500',
+}
+</script>

package/src/composables/useQueryParamSync.test.ts

@@ -0,0 +1,56 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+
+const replace = vi.fn()
+let query: Record<string, string> = {}
+
+vi.mock('vue-router', () => ({
+  useRoute: () => ({ query }),
+  useRouter: () => ({ replace }),
+}))
+
+import { useQueryParamSync } from './useQueryParamSync'
+
+beforeEach(() => {
+  replace.mockReset()
+  query = {}
+})
+
+describe('qparam / qenum', () => {
+  it('reads string params and returns "" for absent ones', () => {
+    query = { q: 'AMD' }
+    const { qparam } = useQueryParamSync()
+    expect(qparam('q')).toBe('AMD')
+    expect(qparam('missing')).toBe('')
+  })
+
+  it('qenum only accepts allowed values, else the fallback', () => {
+    query = { range: '7D', bogus: 'nope' }
+    const { qenum } = useQueryParamSync()
+    expect(qenum('range', ['1D', '7D', '30D'], '1D')).toBe('7D')
+    expect(qenum('bogus', ['a', 'b'], 'a')).toBe('a')
+    expect(qenum('missing', ['a', 'b'], 'b')).toBe('b')
+  })
+})
+
+describe('replaceQuery', () => {
+  it('replaces when the query differs', () => {
+    query = { q: 'old' }
+    const { replaceQuery } = useQueryParamSync()
+    replaceQuery({ q: 'new' })
+    expect(replace).toHaveBeenCalledWith({ query: { q: 'new' } })
+  })
+
+  it('no-ops when the query already matches (same keys and values)', () => {
+    query = { q: 'AMD', range: '7D' }
+    const { replaceQuery } = useQueryParamSync()
+    replaceQuery({ q: 'AMD', range: '7D' })
+    expect(replace).not.toHaveBeenCalled()
+  })
+
+  it('replaces when a key is removed (defaults omitted)', () => {
+    query = { q: 'AMD', range: '7D' }
+    const { replaceQuery } = useQueryParamSync()
+    replaceQuery({ q: 'AMD' })
+    expect(replace).toHaveBeenCalledWith({ query: { q: 'AMD' } })
+  })
+})

package/src/composables/useQueryParamSync.ts

@@ -0,0 +1,42 @@
+import { useRoute, useRouter } from 'vue-router'
+
+/**
+ * URL-query mirroring helpers for filterable views: read a filter's initial
+ * state from the query string once on setup, then write changes back with
+ * `replaceQuery` so a filtered view can be copied, shared and bookmarked
+ * without filter tweaks piling up in the browser history.
+ */
+export function useQueryParamSync() {
+  const route = useRoute()
+  const router = useRouter()
+
+  /** String value of a query param ('' when absent or repeated). */
+  function qparam(name: string): string {
+    const v = route.query[name]
+    return typeof v === 'string' ? v : ''
+  }
+
+  /**
+   * Enum-ish param: only values from `allowed` pass; anything else in a
+   * hand-edited URL falls back to the default.
+   */
+  function qenum<T extends string>(name: string, allowed: readonly T[], fallback: T): T {
+    const v = qparam(name)
+    return (allowed as readonly string[]).includes(v) ? (v as T) : fallback
+  }
+
+  /**
+   * Mirror the given params into the URL with `router.replace` (not `push`),
+   * no-oping when nothing changed so timers/auto-refresh don't issue redundant
+   * navigations. Callers omit default values so the address stays clean.
+   */
+  function replaceQuery(next: Record<string, string>): void {
+    const current = route.query
+    const same =
+      Object.keys(next).length === Object.keys(current).length &&
+      Object.entries(next).every(([k, v]) => current[k] === v)
+    if (!same) void router.replace({ query: next })
+  }
+
+  return { qparam, qenum, replaceQuery }
+}