mgv-backoffice 1.29.0 → 1.31.0

package/dist/utils/format.d.ts

@@ -25,6 +25,13 @@ export declare function fmtDateTime(ms: number): string;
  * Format an epoch-millis timestamp as a short "Mon D" calendar label.
  */
 export declare function fmtDateShort(ms: number): string;
+/**
+ * Format an ISO string / epoch-millis as a full 24-hour locale date-time WITH
+ * the millisecond fraction — for dense feeds where several rows can land in
+ * the same second and must stay distinguishable. Falls back to the raw value
+ * when the input can't be parsed.
+ */
+export declare function fmtDateTimeMs(s: string | number): string;
 /**
  * Format a price with precision that scales to magnitude: penny stocks and
  * sub-cent crypto get more decimals so the value never collapses to "0.00".
@@ -38,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/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.29.0",
+  "version": "1.31.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/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/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')
+  })
+})