mgv-backoffice 1.33.0 → 1.35.0

package/dist/utils/format.d.ts

@@ -68,6 +68,18 @@ export declare function fmtMsAsSeconds(ms: number | null | undefined): string;
  * "2.0 MB"). Returns '' for zero/falsy input.
  */
 export declare function fmtBytes(bytes: number | null | undefined): string;
+/**
+ * Pretty-print a string that may contain JSON: parseable input is
+ * re-serialized with 2-space indentation, anything else is returned
+ * verbatim. Handy for request/response bodies of unknown content type.
+ */
+export declare function formatJson(content: string): string;
+/**
+ * Render an unknown value as a display string: strings pass through,
+ * null/undefined become '', everything else is JSON-serialized (falling
+ * back to String() for values JSON can't handle, e.g. cycles or BigInt).
+ */
+export declare function stringifyValue(value: unknown): 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/validate.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Pure, dependency-free input validators shared across back-office forms —
+ * extracted from WireMate's mock form.
+ *
+ * Semantics note: the payload validators (`isValidJson`, `isValidXml`,
+ * `isValidBase64`) treat empty/whitespace-only input as VALID — callers
+ * gate on "is there something to check" separately (required-ness is a
+ * different rule from well-formedness). `isValidAbsoluteUrl` is the
+ * opposite: it validates a value that must exist, so empty is invalid.
+ */
+/**
+ * `true` when `value` parses as an absolute http:// or https:// URL.
+ * Deliberately tightens the scheme list — backends' HTTP clients won't
+ * follow ftp:// or mailto: anyway, so a stray scheme is a typo.
+ */
+export declare function isValidAbsoluteUrl(value: string): boolean;
+/**
+ * `true` when `str` is empty or parses as JSON.
+ */
+export declare function isValidJson(str: string): boolean;
+/**
+ * `true` when `str` is empty or is well-formed XML. Runs the browser's
+ * DOMParser and checks for a `<parsererror>` node — the only reliable
+ * signal DOMParser provides, since it never throws on bad input.
+ */
+export declare function isValidXml(str: string): boolean;
+/**
+ * `true` when `str` is empty or is well-formed base64 (after stripping
+ * whitespace/newlines, which are harmless in both RFC 4648 and most
+ * real-world payloads). Rejects lengths that can't possibly decode
+ * (`length % 4 !== 0` after padding) — the common "off by a character"
+ * copy/paste issue — then defers to the native decoder as the final
+ * authority.
+ */
+export declare function isValidBase64(str: string): boolean;

package/package.json

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

package/src/components/BaseCodeBlock.test.ts

@@ -0,0 +1,70 @@
+import { describe, it, expect, beforeEach } from 'vitest'
+import { mount } from '@vue/test-utils'
+import BaseCodeBlock from './BaseCodeBlock.vue'
+import { useTheme } from '../composables/useTheme'
+
+function ensureLight() {
+  const { isDark, toggleTheme } = useTheme()
+  if (isDark.value) toggleTheme()
+}
+
+describe('BaseCodeBlock', () => {
+  beforeEach(() => {
+    ensureLight()
+  })
+
+  it('renders the code verbatim inside a <pre>', () => {
+    const code = '{\n  "a": 1\n}'
+    const wrapper = mount(BaseCodeBlock, { props: { code } })
+    const pre = wrapper.find('pre')
+    expect(pre.exists()).toBe(true)
+    expect(pre.text()).toBe(code)
+    expect(pre.classes()).toContain('font-mono')
+    expect(pre.classes()).toContain('overflow-auto')
+  })
+
+  it('defaults to the soft variant at size sm', () => {
+    const wrapper = mount(BaseCodeBlock, { props: { code: 'x' } })
+    const classes = wrapper.find('pre').classes()
+    expect(classes).toContain('bg-gray-100')
+    expect(classes).toContain('text-sm')
+    expect(classes).toContain('px-5')
+    expect(classes).not.toContain('border')
+  })
+
+  it('renders the bordered variant with a border and card fill', () => {
+    const wrapper = mount(BaseCodeBlock, {
+      props: { code: 'x', variant: 'bordered' },
+    })
+    const classes = wrapper.find('pre').classes()
+    expect(classes).toContain('border')
+    expect(classes).toContain('bg-white')
+    expect(classes).toContain('border-gray-200')
+  })
+
+  it('renders dense padding at size xs', () => {
+    const wrapper = mount(BaseCodeBlock, { props: { code: 'x', size: 'xs' } })
+    const classes = wrapper.find('pre').classes()
+    expect(classes).toContain('text-xs')
+    expect(classes).toContain('p-3')
+  })
+
+  it('applies maxHeightClass and merges fallthrough classes', () => {
+    const wrapper = mount(BaseCodeBlock, {
+      props: { code: 'x', maxHeightClass: 'max-h-96' },
+      attrs: { class: 'mx-4' },
+    })
+    const classes = wrapper.find('pre').classes()
+    expect(classes).toContain('max-h-96')
+    expect(classes).toContain('mx-4')
+  })
+
+  it('switches palette when the theme flips', async () => {
+    const wrapper = mount(BaseCodeBlock, { props: { code: 'x' } })
+    const { toggleTheme } = useTheme()
+    toggleTheme()
+    await wrapper.vm.$nextTick()
+    expect(wrapper.find('pre').classes()).toContain('bg-gray-800/70')
+    toggleTheme()
+  })
+})

package/src/components/BaseCodeBlock.vue

@@ -0,0 +1,74 @@
+<template>
+  <!--
+    Themed monospace <pre> for JSON payloads, request dumps and code
+    snippets — extracted from WireMate, where the same class soup was
+    hand-rolled on every stub/request detail view.
+
+    Variants:
+      • soft     — tinted fill, no border (bg-gray-800/70 / bg-gray-100).
+        The in-card look used under a section heading.
+      • bordered — bordered card fill (bg-gray-900 / bg-white). The
+        standalone look used when the block sits directly on the page.
+
+    Sizing:
+      • sm — text-sm with roomy padding, for primary content blocks.
+      • xs — text-xs with tight padding, for dense/secondary dumps.
+
+    `max-height-class` caps tall payloads (e.g. 'max-h-96'); the block
+    scrolls both axes. Extra classes (margins etc.) fall through via the
+    normal class attr merge.
+  -->
+  <pre
+    class="font-mono overflow-auto"
+    :class="[sizeClass, paletteClass, maxHeightClass]"
+  >{{ code }}</pre>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue'
+import { useTheme } from '../composables/useTheme'
+
+const props = withDefaults(
+  defineProps<{
+    /** The raw text to render. Whitespace is preserved verbatim. */
+    code: string
+    /** Visual style: tinted fill ('soft') or bordered card ('bordered'). */
+    variant?: 'soft' | 'bordered'
+    /** Text size + padding: 'sm' (roomy) or 'xs' (dense). */
+    size?: 'sm' | 'xs'
+    /** Optional Tailwind max-height utility, e.g. 'max-h-96'. */
+    maxHeightClass?: string
+  }>(),
+  {
+    variant: 'soft',
+    size: 'sm',
+    maxHeightClass: '',
+  },
+)
+
+const { isDark } = useTheme()
+
+// Full literal class strings so Tailwind detects them at build time.
+const PALETTES: Record<'soft' | 'bordered', { dark: string; light: string }> = {
+  soft: {
+    dark: 'bg-gray-800/70 text-gray-300',
+    light: 'bg-gray-100 text-gray-700',
+  },
+  bordered: {
+    dark: 'border bg-gray-900 border-gray-700 text-gray-300',
+    light: 'border bg-white border-gray-200 text-gray-700',
+  },
+}
+
+const SIZES: Record<'sm' | 'xs', string> = {
+  sm: 'text-sm px-5 py-4 rounded-lg',
+  xs: 'text-xs p-3 rounded-lg',
+}
+
+const paletteClass = computed(() => {
+  const entry = PALETTES[props.variant]
+  return isDark.value ? entry.dark : entry.light
+})
+
+const sizeClass = computed(() => SIZES[props.size])
+</script>

package/src/components/BasePillPickerModal.test.ts

@@ -0,0 +1,95 @@
+import { describe, it, expect } from 'vitest'
+import { mount } from '@vue/test-utils'
+import BasePillPickerModal from './BasePillPickerModal.vue'
+import type { PillPickerItem } from '../types/pillPicker'
+
+const items: PillPickerItem[] = [
+  { id: 'STOCK:AAPL', label: 'AAPL', group: 'STOCK' },
+  { id: 'STOCK:MSFT', label: 'MSFT', group: 'STOCK', title: 'Microsoft' },
+  { id: 'CRYPTO:BTC/USD', label: 'BTC/USD', group: 'CRYPTO' },
+]
+
+const groups = [
+  { value: 'STOCK', label: 'Stock' },
+  { value: 'CRYPTO', label: 'Crypto' },
+]
+
+function mountPicker(props: Record<string, unknown> = {}) {
+  return mount(BasePillPickerModal, {
+    props: { title: 'Pick one', items, ...props },
+    global: { stubs: { teleport: true } },
+  })
+}
+
+// Pills are the buttons inside the flex-wrap grid — not the segmented
+// control's buttons and not the footer Close.
+function pillLabels(wrapper: ReturnType<typeof mountPicker>): string[] {
+  return wrapper
+    .findAll('.flex.flex-wrap.gap-2 > button')
+    .map((b) => b.text())
+}
+
+describe('BasePillPickerModal', () => {
+  it('renders one pill per item and emits pick with the clicked item', async () => {
+    const wrapper = mountPicker()
+    expect(pillLabels(wrapper)).toEqual(['AAPL', 'MSFT', 'BTC/USD'])
+    await wrapper.findAll('.flex.flex-wrap.gap-2 > button')[1].trigger('click')
+    expect(wrapper.emitted('pick')).toEqual([[items[1]]])
+  })
+
+  it('narrows by free text, case-insensitively, and shows the no-match message', async () => {
+    const wrapper = mountPicker({ noMatchMessage: 'nothing here' })
+    await wrapper.find('input').setValue('btc')
+    expect(pillLabels(wrapper)).toEqual(['BTC/USD'])
+    await wrapper.find('input').setValue('zzz')
+    expect(wrapper.text()).toContain('nothing here')
+  })
+
+  it('renders the group toggle with All prepended and narrows by group', async () => {
+    const wrapper = mountPicker({ groups })
+    // Re-query before each click — the grid re-render replaces the buttons,
+    // so a wrapper captured before a click goes stale.
+    const seg = () => wrapper.findAll('[role="group"] button')
+    expect(seg().map((b) => b.text())).toEqual(['All', 'Stock', 'Crypto'])
+    await seg()[2].trigger('click')
+    expect(pillLabels(wrapper)).toEqual(['BTC/USD'])
+    await seg()[0].trigger('click')
+    expect(pillLabels(wrapper)).toEqual(['AAPL', 'MSFT', 'BTC/USD'])
+  })
+
+  it('hides the group toggle when no groups are passed', () => {
+    const wrapper = mountPicker()
+    expect(wrapper.find('[role="group"]').exists()).toBe(false)
+  })
+
+  it('shows the empty message instead of the filter row when there are no items', () => {
+    const wrapper = mountPicker({ items: [], emptyMessage: 'nothing configured' })
+    expect(wrapper.text()).toContain('nothing configured')
+    expect(wrapper.find('input').exists()).toBe(false)
+  })
+
+  it('applies the mono font to the input and pills only when asked', () => {
+    const mono = mountPicker({ mono: true })
+    expect(mono.find('input').classes()).toContain('font-mono')
+    expect(mono.findAll('.flex.flex-wrap.gap-2 > button')[0].classes()).toContain('font-mono')
+
+    const plain = mountPicker()
+    expect(plain.find('input').classes()).not.toContain('font-mono')
+  })
+
+  it('forwards an item title to the pill tooltip', () => {
+    const wrapper = mountPicker()
+    expect(
+      wrapper.findAll('.flex.flex-wrap.gap-2 > button')[1].attributes('title'),
+    ).toBe('Microsoft')
+  })
+
+  it('emits close from the footer button', async () => {
+    const wrapper = mountPicker({ closeText: 'Dismiss' })
+    const buttons = wrapper.findAll('button')
+    const closeBtn = buttons[buttons.length - 1]
+    expect(closeBtn.text()).toBe('Dismiss')
+    await closeBtn.trigger('click')
+    expect(wrapper.emitted('close')).toHaveLength(1)
+  })
+})

package/src/components/BaseToolbarButton.test.ts

@@ -0,0 +1,48 @@
+import { describe, it, expect } from 'vitest'
+import { mount } from '@vue/test-utils'
+import BaseToolbarButton from './BaseToolbarButton.vue'
+
+describe('BaseToolbarButton', () => {
+  it('renders the neutral pill shape by default', () => {
+    const wrapper = mount(BaseToolbarButton, { props: { label: 'Refresh' } })
+    const cls = wrapper.find('button').classes()
+    expect(cls).toContain('rounded-lg')
+    expect(cls).toContain('py-2')
+    expect(cls).toContain('font-medium')
+    expect(cls).toContain('disabled:opacity-50')
+    expect(wrapper.text()).toBe('Refresh')
+  })
+
+  it('keeps the danger variant on the pill shape with the red palette', () => {
+    const wrapper = mount(BaseToolbarButton, {
+      props: { label: 'Delete', variant: 'danger' },
+    })
+    const cls = wrapper.find('button').classes()
+    expect(cls).toContain('rounded-lg')
+    expect(cls).toContain('bg-red-600')
+  })
+
+  it('renders the ghost variant as the slate h-9 rounded-md outline button', () => {
+    const wrapper = mount(BaseToolbarButton, {
+      props: { label: 'Close', variant: 'ghost' },
+    })
+    const cls = wrapper.find('button').classes()
+    expect(cls).toContain('h-9')
+    expect(cls).toContain('rounded-md')
+    expect(cls).toContain('px-4')
+    expect(cls).toContain('font-semibold')
+    expect(cls).toContain('border-slate-300')
+    expect(cls).toContain('disabled:opacity-40')
+    expect(cls).not.toContain('rounded-lg')
+    expect(cls).not.toContain('py-2')
+  })
+
+  it('emits click and honours disabled', async () => {
+    const wrapper = mount(BaseToolbarButton, { props: { label: 'Go' } })
+    await wrapper.find('button').trigger('click')
+    expect(wrapper.emitted('click')).toHaveLength(1)
+
+    const disabled = mount(BaseToolbarButton, { props: { label: 'Go', disabled: true } })
+    expect(disabled.find('button').attributes('disabled')).toBeDefined()
+  })
+})

package/src/components/BaseToolbarButton.vue

@@ -11,7 +11,8 @@
     Props:
       • label    — button text (rendered in a <span>). Optional so an
         icon-only toolbar button is possible.
-      • variant  — 'neutral' (default grey) or 'danger' (solid red).
+      • variant  — 'neutral' (default grey), 'danger' (solid red) or
+        'ghost' (slate outline — TradeAutomation's toolbar/footer idiom).
       • disabled — greys out + blocks the click.
       • title    — native tooltip / accessibility text.
       • type     — native button type. Defaults to 'button' so the
@@ -21,7 +22,7 @@
     :type="type"
     :disabled="disabled"
     :title="title"
-    class="inline-flex shrink-0 items-center gap-2 px-3 py-2 rounded-lg text-sm font-medium border transition-colors cursor-pointer disabled:opacity-50 disabled:cursor-not-allowed whitespace-nowrap focus:outline-none focus-visible:ring-2 focus-visible:ring-emerald-500"
+    class="inline-flex shrink-0 items-center gap-2 text-sm border transition-colors cursor-pointer disabled:cursor-not-allowed whitespace-nowrap focus:outline-none focus-visible:ring-2 focus-visible:ring-emerald-500"
     :class="variantClass"
     @click="$emit('click', $event)"
   >
@@ -34,7 +35,7 @@
 import { computed } from 'vue'
 import { useTheme } from '../composables/useTheme'
 
-type ToolbarVariant = 'neutral' | 'danger'
+type ToolbarVariant = 'neutral' | 'danger' | 'ghost'
 
 const props = withDefaults(
   defineProps<{
@@ -59,9 +60,19 @@ defineEmits<{
 
 const { isDark } = useTheme()
 
-// Resolves the variant + theme into the colour classes. The danger
+// Resolves the variant + theme into shape and colour classes. The danger
 // style is normalised here so every destructive toolbar button reads
-// identically (red-500 hover in dark, red-700 hover in light).
+// identically (red-500 hover in dark, red-700 hover in light). Shape lives
+// per-variant because 'ghost' — the slate outline button extracted from
+// TradeAutomation's toolbars and modal footers — is a fixed-height
+// rounded-md button, not the neutral/danger pill; it themes via dark:
+// utilities so it renders the same markup in both themes.
+const SHAPE: Record<ToolbarVariant, string> = {
+  neutral: 'px-3 py-2 rounded-lg font-medium disabled:opacity-50',
+  danger: 'px-3 py-2 rounded-lg font-medium disabled:opacity-50',
+  ghost: 'h-9 px-4 rounded-md font-semibold disabled:opacity-40 disabled:hover:bg-slate-50 dark:disabled:hover:bg-slate-900',
+}
+
 const variantClass = computed(() => {
   const palette: Record<ToolbarVariant, { dark: string; light: string }> = {
     neutral: {
@@ -72,8 +83,12 @@ const variantClass = computed(() => {
       dark: 'bg-red-600 text-white border-red-600 hover:bg-red-500',
       light: 'bg-red-600 text-white border-red-600 hover:bg-red-700',
     },
+    ghost: {
+      dark: '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',
+      light: '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',
+    },
   }
   const entry = palette[props.variant]
-  return isDark.value ? entry.dark : entry.light
+  return [SHAPE[props.variant], isDark.value ? entry.dark : entry.light]
 })
 </script>

package/src/composables/usePolling.test.ts

@@ -0,0 +1,112 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { defineComponent, h, nextTick } from 'vue'
+import { mount } from '@vue/test-utils'
+import { usePolling, type UsePollingOptions } from './usePolling'
+
+function mountWithPolling(
+  fn: () => void,
+  intervalMs: number | null,
+  options?: UsePollingOptions,
+) {
+  let api!: ReturnType<typeof usePolling>
+  const wrapper = mount(
+    defineComponent({
+      setup() {
+        api = usePolling(fn, intervalMs, options)
+        return () => h('div')
+      },
+    }),
+  )
+  return { wrapper, api }
+}
+
+function setVisibility(state: 'visible' | 'hidden') {
+  Object.defineProperty(document, 'visibilityState', {
+    configurable: true,
+    get: () => state,
+  })
+  document.dispatchEvent(new Event('visibilitychange'))
+}
+
+describe('usePolling', () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+    setVisibility('visible')
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  it('runs immediately on mount and then on each interval', () => {
+    const fn = vi.fn()
+    mountWithPolling(fn, 1000)
+    expect(fn).toHaveBeenCalledTimes(1)
+    vi.advanceTimersByTime(3000)
+    expect(fn).toHaveBeenCalledTimes(4)
+  })
+
+  it('skips the initial call when immediate is false', () => {
+    const fn = vi.fn()
+    mountWithPolling(fn, 1000, { immediate: false })
+    expect(fn).not.toHaveBeenCalled()
+    vi.advanceTimersByTime(1000)
+    expect(fn).toHaveBeenCalledTimes(1)
+  })
+
+  it('pauses while hidden and refreshes + resumes on return to visible', async () => {
+    const fn = vi.fn()
+    mountWithPolling(fn, 1000)
+    expect(fn).toHaveBeenCalledTimes(1)
+
+    setVisibility('hidden')
+    await nextTick()
+    vi.advanceTimersByTime(5000)
+    expect(fn).toHaveBeenCalledTimes(1) // no ticks while hidden
+
+    setVisibility('visible')
+    expect(fn).toHaveBeenCalledTimes(2) // immediate refresh on resume
+    vi.advanceTimersByTime(1000)
+    expect(fn).toHaveBeenCalledTimes(3) // interval re-armed
+  })
+
+  it('with intervalMs null, runs on mount and on visibility resume only', () => {
+    const fn = vi.fn()
+    mountWithPolling(fn, null)
+    expect(fn).toHaveBeenCalledTimes(1)
+    vi.advanceTimersByTime(60000)
+    expect(fn).toHaveBeenCalledTimes(1)
+
+    setVisibility('hidden')
+    setVisibility('visible')
+    expect(fn).toHaveBeenCalledTimes(2)
+    vi.advanceTimersByTime(60000)
+    expect(fn).toHaveBeenCalledTimes(2)
+  })
+
+  it('stops on unmount', () => {
+    const fn = vi.fn()
+    const { wrapper } = mountWithPolling(fn, 1000)
+    wrapper.unmount()
+    vi.advanceTimersByTime(5000)
+    expect(fn).toHaveBeenCalledTimes(1)
+    // and the visibility listener is gone too
+    setVisibility('hidden')
+    setVisibility('visible')
+    expect(fn).toHaveBeenCalledTimes(1)
+  })
+
+  it('exposes manual start/stop and an active flag', () => {
+    const fn = vi.fn()
+    const { api } = mountWithPolling(fn, 1000)
+    expect(api.active.value).toBe(true)
+    api.stop()
+    expect(api.active.value).toBe(false)
+    vi.advanceTimersByTime(3000)
+    expect(fn).toHaveBeenCalledTimes(1)
+    api.start()
+    expect(fn).toHaveBeenCalledTimes(2)
+    vi.advanceTimersByTime(1000)
+    expect(fn).toHaveBeenCalledTimes(3)
+  })
+})

package/src/composables/usePolling.ts

@@ -0,0 +1,90 @@
+import { onMounted, onUnmounted, readonly, ref, type Ref } from 'vue'
+
+export interface UsePollingOptions {
+  /** Run `fn` immediately when polling starts (mount / resume). Default true. */
+  immediate?: boolean
+  /**
+   * Pause the interval while the tab is hidden and refresh + resume when it
+   * becomes visible again — a hidden tab has no reason to keep waking the
+   * backend. Default true.
+   */
+  pauseWhenHidden?: boolean
+}
+
+/**
+ * Visibility-gated polling loop bound to the component lifecycle.
+ *
+ * Starts on mount, stops on unmount. With `pauseWhenHidden` (the default)
+ * the interval is torn down on `document.visibilitychange` → hidden and
+ * re-armed — with an immediate refresh — when the tab is shown again.
+ *
+ * Pass `intervalMs: null` for a refresh-only mode: `fn` runs on mount and
+ * on every return-to-visible, but no interval is scheduled. Useful for
+ * "reload this badge when the user comes back" data that doesn't warrant
+ * a timer.
+ *
+ * Rejections from an async `fn` are the caller's to handle — catch inside
+ * `fn`; the loop itself never swallows or reports them.
+ */
+export function usePolling(
+  fn: () => void | Promise<void>,
+  intervalMs: number | null,
+  options: UsePollingOptions = {},
+): { start: () => void; stop: () => void; active: Readonly<Ref<boolean>> } {
+  const { immediate = true, pauseWhenHidden = true } = options
+
+  let timer: ReturnType<typeof setInterval> | null = null
+  const active = ref(false)
+
+  function startTimer() {
+    if (timer !== null || intervalMs === null) return
+    timer = setInterval(() => void fn(), intervalMs)
+  }
+
+  function stopTimer() {
+    if (timer !== null) {
+      clearInterval(timer)
+      timer = null
+    }
+  }
+
+  function start() {
+    if (active.value) return
+    active.value = true
+    if (immediate) void fn()
+    startTimer()
+  }
+
+  function stop() {
+    active.value = false
+    stopTimer()
+  }
+
+  function onVisibilityChange() {
+    if (document.visibilityState === 'visible') {
+      // Refresh right away so stale data doesn't linger for a full
+      // interval after the user returns, then re-arm the timer.
+      active.value = true
+      void fn()
+      startTimer()
+    } else {
+      stop()
+    }
+  }
+
+  onMounted(() => {
+    start()
+    if (pauseWhenHidden) {
+      document.addEventListener('visibilitychange', onVisibilityChange)
+    }
+  })
+
+  onUnmounted(() => {
+    stop()
+    if (pauseWhenHidden) {
+      document.removeEventListener('visibilitychange', onVisibilityChange)
+    }
+  })
+
+  return { start, stop, active: readonly(active) }
+}

package/src/composables/useThemeClasses.test.ts

@@ -0,0 +1,34 @@
+import { describe, it, expect } from 'vitest'
+import { isReactive } from 'vue'
+import { normalizeClass } from '@vue/shared'
+import { useThemeClasses } from './useThemeClasses'
+import { useTheme } from './useTheme'
+
+describe('useThemeClasses', () => {
+  it('returns a reactive object whose properties are plain class strings', () => {
+    const t = useThemeClasses()
+    expect(isReactive(t)).toBe(true)
+    expect(typeof t.primaryText).toBe('string')
+    expect(t.primaryText).toMatch(/^text-/)
+  })
+
+  it('survives normalizeClass — the regression that leaked ref internals into class attrs', () => {
+    // Before the reactive() fix, `:class="t.primaryText"` handed a raw
+    // ComputedRef to normalizeClass, which rendered the ref's own keys
+    // ("fn dep __v_isRef …") instead of the theme classes.
+    const t = useThemeClasses()
+    const normalized = normalizeClass(t.primaryText)
+    expect(normalized).not.toContain('__v_isRef')
+    expect(normalized).toBe(t.primaryText)
+  })
+
+  it('tracks theme flips', () => {
+    const { isDark, toggleTheme } = useTheme()
+    const t = useThemeClasses()
+    const before = t.primaryText
+    toggleTheme()
+    expect(t.primaryText).not.toBe(before)
+    expect(t.primaryText).toBe(isDark.value ? 'text-white' : 'text-gray-900')
+    toggleTheme() // restore for other tests sharing the singleton theme
+  })
+})