srcdev-nuxt-components 9.1.14 → 9.1.16

package/.claude/settings.json

@@ -18,7 +18,8 @@
       "Bash(git show:*)",
       "Edit(/.claude/skills/components/**)",
       "Bash(npx nuxi:*)",
-      "Bash(node -e \"const t = require\\('/Users/simoncornforth/websites/nuxt-components/node_modules/pinia-plugin-persistedstate'\\); console.log\\(Object.keys\\(t\\)\\)\")"
+      "Bash(node -e \"const t = require\\('/Users/simoncornforth/websites/nuxt-components/node_modules/pinia-plugin-persistedstate'\\); console.log\\(Object.keys\\(t\\)\\)\")",
+      "Bash(npx vue-tsc:*)"
     ],
     "additionalDirectories": [
       "/Users/simoncornforth/websites/nuxt-components/app/components/01.atoms/content-wrappers/content-width",

package/.claude/skills/composable-whatsapp.md

@@ -0,0 +1,111 @@
+# useWhatsApp Composable
+
+## Overview
+
+`useWhatsApp` opens a pre-filled WhatsApp conversation in a new tab via the `wa.me` deep-link API. It formats an array of labelled fields into a bold-label WhatsApp message and requires a phone number configured in runtime config.
+
+Composable location: `app/composables/useWhatsApp.ts`
+
+## Prerequisites
+
+- `NUXT_PUBLIC_WHATSAPP_NUMBER` env var set to the recipient number in international format, no `+` or spaces (e.g. `447700900000`).
+
+## Runtime Config
+
+`whatsappNumber` must live in `runtimeConfig.public` — **not** the private root block — because `openWhatsApp` runs client-side and private keys are server-only.
+
+```ts
+// nuxt.config.ts
+runtimeConfig: {
+  // private server-only keys (Resend, etc.)
+  public: {
+    whatsappNumber: "", // NUXT_PUBLIC_WHATSAPP_NUMBER
+  },
+},
+```
+
+Env var name follows Nuxt convention: `NUXT_PUBLIC_` prefix + SCREAMING_SNAKE of the key path.
+
+## Composable
+
+```ts
+// app/composables/useWhatsApp.ts
+export const useWhatsApp = () => {
+  const config = useRuntimeConfig(); // must be inside the function, not at module scope
+
+  const openWhatsApp = (fields: { label: string; value: string }[]) => {
+    const number = config.public.whatsappNumber;
+
+    if (!number) {
+      console.warn("[useWhatsApp] whatsappNumber is not configured");
+      return;
+    }
+
+    const message = fields
+      .filter((f) => f.value?.trim())
+      .map((f) => `*${f.label}:* ${f.value}`)
+      .join("\n");
+
+    const url = `https://wa.me/${number}?text=${encodeURIComponent(message)}`;
+    window.open(url, "_blank", "noopener,noreferrer"); // noopener prevents reverse tabnapping
+  };
+
+  return { openWhatsApp };
+};
+```
+
+### Key rules
+
+- **`useRuntimeConfig()` inside the function body** — never at module scope. Nuxt composables require an active context; module-scope calls run at import time, outside any context, and return empty values.
+- **`noopener,noreferrer`** on `window.open` — prevents the opened WhatsApp page accessing `window.opener` (reverse tabnapping).
+- **Guard for missing number** — avoids a silent `https://wa.me/?text=...` 404.
+
+## Usage in a form
+
+```ts
+// 1. Destructure the composable
+const { openWhatsApp } = useWhatsApp();
+
+// 2. Build the payload from your form state
+const buildWhatsAppPayload = () => [
+  { label: "Name",     value: state.fullName },
+  { label: "Phone",    value: state.telNumber },
+  { label: "Email",    value: state.emailAddress },
+  { label: "Services", value: state.services.join(", ") },
+  { label: "Comments", value: state.comments ?? "" },
+];
+
+// 3. Call on successful form submission
+const submitForm = async () => {
+  zodFormControl.submitAttempted = true;
+  if (!(await doZodValidate(state))) {
+    scrollToFirstError();
+    return;
+  }
+  zodFormControl.displayLoader = true;
+  try {
+    zodFormControl.submitSuccessful = true;
+    openWhatsApp(buildWhatsAppPayload());
+  } catch (error) {
+    console.warn("Contact form submission failed", error);
+  } finally {
+    zodFormControl.displayLoader = false;
+  }
+};
+```
+
+## Message format
+
+Fields with an empty/whitespace `value` are filtered out. Remaining fields render as:
+
+```
+*Name:* Jane Smith
+*Phone:* 07700 900000
+*Services:* Cut, Colour
+```
+
+## Notes
+
+- `wa.me` opens the WhatsApp desktop app if installed, otherwise falls back to web.whatsapp.com.
+- The phone number in `public` config is visible in the client bundle — acceptable for a public-facing WhatsApp business number.
+- This is a client-side-only operation; no server route or API key is needed.

package/.claude/skills/index.md

@@ -36,6 +36,7 @@ Each skill is a single markdown file named `<area>-<task>.md`.
 ├── component-inline-action-button.md — InputButtonCore variant="inline" pattern for buttons embedded in custom input wrappers
 ├── icon-sets.md                      — icon set packages required by layer components, FOUC prevention, component→package map
 ├── robots-env-aware.md               — @nuxtjs/robots: allow crawling on prod domain only, block on preview/staging via env var
+├── composable-whatsapp.md            — useWhatsApp: open pre-filled wa.me link from form payload; runtime config, security, usage
 └── components/
     ├── accordian-core.md       — AccordianCore indexed dynamic slots (accordian-{n}-summary/icon/content), exclusive-open grouping
     ├── eyebrow-text.md         — EyebrowText props, usage patterns, styling

package/app/components/02.molecules/navigation/tab-navigation/TabNavigation.vue

@@ -5,7 +5,7 @@
     :class="[
       elementClasses,
       `tab-navigation--${navAlign}`,
-      { 'is-collapsed': isCollapsed, 'is-loaded': isLoaded, 'menu-open': isMenuOpen },
+      { 'is-collapsed': isCollapsed, 'is-loaded': isLoaded, 'menu-open': isMenuOpen, 'is-animated': isAnimated },
     ]"
     aria-label="Site navigation"
   >
@@ -106,6 +106,28 @@ const props = withDefaults(defineProps<Props>(), {
 const { navRef, navListRef, isCollapsed, isLoaded, isMenuOpen, isActiveItem, toggleMenu, closeMenu } =
   useNavCollapse("tab-nav-loaded");
 
+// ─── Animation gate — disables indicator transitions during route changes ────
+// Starts true: CSS anchor positioning resolves before first paint so there is
+// no previous position to animate from on initial render.
+// Uses flush:"pre" so isAnimated = false lands in the same DOM update as the
+// is-active class moving — the browser never sees the anchor shift with
+// transitions active.
+const isAnimated = ref(true);
+const route = useRoute();
+
+watch(
+  () => route.path,
+  () => {
+    isAnimated.value = false;
+    requestAnimationFrame(() => {
+      requestAnimationFrame(() => {
+        isAnimated.value = true;
+      });
+    });
+  },
+  { flush: "pre" }
+);
+
 const hoveredItemHref = ref<string | null>(null);
 const showCollapsed = computed(() => isCollapsed.value && isLoaded.value);
 
@@ -426,13 +448,16 @@ watch(
     bottom: 0;
     opacity: 0;
     pointer-events: none;
+    background: var(--tab-nav-decorator-hovered-bg, transparent);
+    border-radius: 4px;
+    z-index: 1;
+  }
+
+  .tab-navigation.is-animated .tab-nav-list .nav__hovered {
     transition:
       left 200ms ease,
       right 200ms ease,
       opacity 150ms ease;
-    background: var(--tab-nav-decorator-hovered-bg, transparent);
-    border-radius: 4px;
-    z-index: 1;
   }
 
   .tab-navigation .tab-nav-list:has(.is-hovered) .nav__hovered {
@@ -449,11 +474,14 @@ watch(
     bottom: 0;
     height: 2px;
     pointer-events: none;
+    background-color: var(--tab-nav-decorator-indicator-color, var(--slate-01, currentColor));
+    z-index: 3;
+  }
+
+  .tab-navigation.is-animated .tab-nav-list .nav__active-indicator {
     transition:
       left 200ms ease,
       right 200ms ease;
-    background-color: var(--tab-nav-decorator-indicator-color, var(--slate-01, currentColor));
-    z-index: 3;
   }
   /* } */
 }

package/app/components/02.molecules/navigation/tab-navigation/tests/__snapshots__/TabNavigation.spec.ts.snap

@@ -1,7 +1,7 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
 exports[`TabNavigation > renders correct HTML structure 1`] = `
-"<nav class="tab-navigation tab-navigation--left is-loaded" aria-label="Site navigation">
+"<nav class="tab-navigation tab-navigation--left is-loaded is-animated" aria-label="Site navigation">
   <ul class="tab-nav-list">
     <li data-href="/" class="is-active"><a href="/" class="tab-nav-link" data-nav-item="">
         <!--v-if--> Home

package/app/composables/tests/useApiRequest.spec.ts

@@ -0,0 +1,74 @@
+import { describe, it, expect } from "vitest";
+import useApiRequest from "../useApiRequest";
+
+class NetworkError extends Error {
+  override name = "NetworkError";
+}
+
+class ValidationError extends Error {
+  override name = "ValidationError";
+}
+
+describe("useApiRequest", () => {
+  // ─── Success ──────────────────────────────────────────────────────────────
+
+  describe("on success", () => {
+    it("returns [undefined, data]", async () => {
+      const [error, data] = await useApiRequest(Promise.resolve("ok"));
+      expect(error).toBeUndefined();
+      expect(data).toBe("ok");
+    });
+
+    it("passes through any resolved value type", async () => {
+      const payload = { id: 1, name: "test" };
+      const [, data] = await useApiRequest(Promise.resolve(payload));
+      expect(data).toEqual(payload);
+    });
+  });
+
+  // ─── Error — no errorsToCatch ─────────────────────────────────────────────
+
+  describe("on rejection with no errorsToCatch", () => {
+    it("returns [error] for any thrown error", async () => {
+      const err = new Error("boom");
+      const result = await useApiRequest(Promise.reject(err));
+      expect(result).toEqual([err]);
+    });
+
+    it("returns [error] for unknown error types", async () => {
+      const err = new NetworkError("network fail");
+      const result = await useApiRequest(Promise.reject(err));
+      expect(result).toEqual([err]);
+    });
+  });
+
+  // ─── Error — matching errorsToCatch ───────────────────────────────────────
+
+  describe("on rejection with matching errorsToCatch", () => {
+    it("returns [error] when the error matches the caught class", async () => {
+      const err = new NetworkError("network fail");
+      const result = await useApiRequest(Promise.reject(err), [NetworkError]);
+      expect(result).toEqual([err]);
+    });
+
+    it("returns [error] when the error matches one of multiple caught classes", async () => {
+      const err = new ValidationError("invalid");
+      const result = await useApiRequest(Promise.reject(err), [NetworkError, ValidationError]);
+      expect(result).toEqual([err]);
+    });
+  });
+
+  // ─── Error — non-matching errorsToCatch ───────────────────────────────────
+
+  describe("on rejection with non-matching errorsToCatch", () => {
+    it("re-throws when the error does not match any caught class", async () => {
+      const err = new NetworkError("network fail");
+      await expect(useApiRequest(Promise.reject(err), [ValidationError])).rejects.toThrow(err);
+    });
+
+    it("re-throws a base Error when only a subclass is caught", async () => {
+      const err = new Error("plain error");
+      await expect(useApiRequest(Promise.reject(err), [NetworkError])).rejects.toThrow(err);
+    });
+  });
+});

package/app/composables/tests/useAriaDescribedById.spec.ts

@@ -0,0 +1,134 @@
+import { describe, it, expect } from "vitest";
+import { ref } from "vue";
+import type { Slots } from "vue";
+import { mockNuxtImport } from "@nuxt/test-utils/runtime";
+import { useAriaDescribedById } from "../useAriaDescribedById";
+
+let idCounter = 0;
+const { useIdMock } = vi.hoisted(() => ({
+  useIdMock: vi.fn(() => `test-id-${++idCounter}`),
+}));
+mockNuxtImport("useId", () => useIdMock);
+
+const noSlots: Slots = {};
+const withSlot = (name: string): Slots => ({ [name]: () => [] });
+
+describe("useAriaDescribedById", () => {
+  // ─── ID structure ─────────────────────────────────────────────────────────
+
+  describe("id structure", () => {
+    it("id is prefixed with the name", () => {
+      const { id } = useAriaDescribedById("email", ref(false), noSlots);
+      expect(id).toMatch(/^email-/);
+    });
+
+    it("errorId is suffixed with -error-message", () => {
+      const { id, errorId } = useAriaDescribedById("email", ref(false), noSlots);
+      expect(errorId).toBe(`${id}-error-message`);
+    });
+
+    it("descriptionId is suffixed with -description", () => {
+      const { id, descriptionId } = useAriaDescribedById("email", ref(false), noSlots);
+      expect(descriptionId).toBe(`${id}-description`);
+    });
+  });
+
+  // ─── ariaDescribedby — no slots, no error ─────────────────────────────────
+
+  describe("ariaDescribedby", () => {
+    it("is null when no slots and no error", () => {
+      const { ariaDescribedby } = useAriaDescribedById("email", ref(false), noSlots);
+      expect(ariaDescribedby.value).toBeNull();
+    });
+
+    it("includes descriptionId when descriptionText slot is present", () => {
+      const { descriptionId, ariaDescribedby } = useAriaDescribedById(
+        "email",
+        ref(false),
+        withSlot("descriptionText")
+      );
+      expect(ariaDescribedby.value).toContain(descriptionId);
+    });
+
+    it("includes descriptionId when descriptionHtml slot is present", () => {
+      const { descriptionId, ariaDescribedby } = useAriaDescribedById(
+        "email",
+        ref(false),
+        withSlot("descriptionHtml")
+      );
+      expect(ariaDescribedby.value).toContain(descriptionId);
+    });
+
+    it("includes descriptionId when description slot is present", () => {
+      const { descriptionId, ariaDescribedby } = useAriaDescribedById(
+        "email",
+        ref(false),
+        withSlot("description")
+      );
+      expect(ariaDescribedby.value).toContain(descriptionId);
+    });
+
+    it("includes errorId when fieldHasError is true", () => {
+      const { errorId, ariaDescribedby } = useAriaDescribedById("email", ref(true), noSlots);
+      expect(ariaDescribedby.value).toContain(errorId);
+    });
+
+    it("does not include errorId when fieldHasError is false (value is null)", () => {
+      const { ariaDescribedby } = useAriaDescribedById("email", ref(false), noSlots);
+      expect(ariaDescribedby.value).toBeNull();
+    });
+
+    it("does not include errorId when slot is present but fieldHasError is false", () => {
+      const { errorId, ariaDescribedby } = useAriaDescribedById(
+        "email",
+        ref(false),
+        withSlot("descriptionText")
+      );
+      expect(ariaDescribedby.value).not.toContain(errorId);
+    });
+
+    it("includes both descriptionId and errorId when slot present and error active", () => {
+      const fieldHasError = ref(true);
+      const { descriptionId, errorId, ariaDescribedby } = useAriaDescribedById(
+        "email",
+        fieldHasError,
+        withSlot("descriptionText")
+      );
+      expect(ariaDescribedby.value).toContain(descriptionId);
+      expect(ariaDescribedby.value).toContain(errorId);
+    });
+
+    it("descriptionId appears before errorId in the combined string", () => {
+      const fieldHasError = ref(true);
+      const { descriptionId, errorId, ariaDescribedby } = useAriaDescribedById(
+        "email",
+        fieldHasError,
+        withSlot("descriptionText")
+      );
+      const value = ariaDescribedby.value!;
+      expect(value.indexOf(descriptionId)).toBeLessThan(value.indexOf(errorId));
+    });
+  });
+
+  // ─── Reactivity ───────────────────────────────────────────────────────────
+
+  describe("reactivity", () => {
+    it("ariaDescribedby updates when fieldHasError changes to true", async () => {
+      const fieldHasError = ref(false);
+      const { errorId, ariaDescribedby } = useAriaDescribedById("email", fieldHasError, noSlots);
+      expect(ariaDescribedby.value).toBeNull();
+      fieldHasError.value = true;
+      await nextTick();
+      expect(ariaDescribedby.value).toContain(errorId);
+    });
+
+    it("ariaDescribedby updates when fieldHasError changes back to false", async () => {
+      const fieldHasError = ref(true);
+      const { ariaDescribedby } = useAriaDescribedById("email", fieldHasError, noSlots);
+      expect(ariaDescribedby.value).toBeTruthy();
+      fieldHasError.value = false;
+      await nextTick();
+      expect(ariaDescribedby.value).toBeNull();
+    });
+  });
+});

package/app/composables/tests/useAriaLabelledById.spec.ts

@@ -0,0 +1,73 @@
+import { describe, it, expect } from "vitest";
+import { ref } from "vue";
+import { mockNuxtImport } from "@nuxt/test-utils/runtime";
+import { useAriaLabelledById } from "../useAriaLabelledById";
+
+let idCounter = 0;
+const { useIdMock } = vi.hoisted(() => ({
+  useIdMock: vi.fn(() => `test-id-${++idCounter}`),
+}));
+mockNuxtImport("useId", () => useIdMock);
+
+describe("useAriaLabelledById", () => {
+  // ─── headingId ────────────────────────────────────────────────────────────
+
+  describe("headingId", () => {
+    it("returns a non-empty string", () => {
+      const { headingId } = useAriaLabelledById("div");
+      expect(headingId).toBeTruthy();
+      expect(typeof headingId).toBe("string");
+    });
+
+    it("is stable — same value returned by ariaLabelledby when applicable", () => {
+      const { headingId, ariaLabelledby } = useAriaLabelledById("section");
+      expect(ariaLabelledby.value).toBe(headingId);
+    });
+  });
+
+  // ─── Labelled tags ────────────────────────────────────────────────────────
+
+  describe("labelled tags", () => {
+    it.each(["section", "main", "article", "aside"])(
+      '"%s" returns ariaLabelledby = headingId',
+      (tag) => {
+        const { headingId, ariaLabelledby } = useAriaLabelledById(tag);
+        expect(ariaLabelledby.value).toBe(headingId);
+      }
+    );
+  });
+
+  // ─── Non-labelled tags ────────────────────────────────────────────────────
+
+  describe("non-labelled tags", () => {
+    it.each(["div", "span", "h1", "p", "ul", "nav"])(
+      '"%s" returns ariaLabelledby = undefined',
+      (tag) => {
+        const { ariaLabelledby } = useAriaLabelledById(tag);
+        expect(ariaLabelledby.value).toBeUndefined();
+      }
+    );
+  });
+
+  // ─── Reactivity ───────────────────────────────────────────────────────────
+
+  describe("reactivity", () => {
+    it("updates ariaLabelledby when a ref tag changes to a labelled tag", async () => {
+      const tag = ref("div");
+      const { headingId, ariaLabelledby } = useAriaLabelledById(tag);
+      expect(ariaLabelledby.value).toBeUndefined();
+      tag.value = "section";
+      await nextTick();
+      expect(ariaLabelledby.value).toBe(headingId);
+    });
+
+    it("updates ariaLabelledby when a ref tag changes away from a labelled tag", async () => {
+      const tag = ref("section");
+      const { ariaLabelledby } = useAriaLabelledById(tag);
+      expect(ariaLabelledby.value).toBeTruthy();
+      tag.value = "div";
+      await nextTick();
+      expect(ariaLabelledby.value).toBeUndefined();
+    });
+  });
+});

package/app/composables/tests/useDialogControls.spec.ts

@@ -0,0 +1,109 @@
+import { describe, it, expect, vi } from "vitest";
+import { useDialogControls } from "../useDialogControls";
+
+describe("useDialogControls", () => {
+  // ─── initialiseDialogs ────────────────────────────────────────────────────
+
+  describe("initialiseDialogs", () => {
+    it("registers each dialog id as false", () => {
+      const { dialogsConfig, initialiseDialogs } = useDialogControls();
+      initialiseDialogs(["confirm", "delete"]);
+      expect(dialogsConfig.confirm).toBe(false);
+      expect(dialogsConfig.delete).toBe(false);
+    });
+
+    it("does not affect pre-existing dialog state", () => {
+      const { dialogsConfig, initialiseDialogs, controlDialogs } = useDialogControls();
+      initialiseDialogs(["a"]);
+      controlDialogs("a", true);
+      initialiseDialogs(["b"]);
+      expect(dialogsConfig.a).toBe(true); // unchanged
+      expect(dialogsConfig.b).toBe(false);
+    });
+  });
+
+  // ─── controlDialogs ───────────────────────────────────────────────────────
+
+  describe("controlDialogs", () => {
+    it("sets dialog state to true (open)", () => {
+      const { dialogsConfig, initialiseDialogs, controlDialogs } = useDialogControls();
+      initialiseDialogs(["modal"]);
+      controlDialogs("modal", true);
+      expect(dialogsConfig.modal).toBe(true);
+    });
+
+    it("sets dialog state to false (close)", () => {
+      const { dialogsConfig, initialiseDialogs, controlDialogs } = useDialogControls();
+      initialiseDialogs(["modal"]);
+      controlDialogs("modal", true);
+      controlDialogs("modal", false);
+      expect(dialogsConfig.modal).toBe(false);
+    });
+
+    it("multiple dialogs are independent", () => {
+      const { dialogsConfig, initialiseDialogs, controlDialogs } = useDialogControls();
+      initialiseDialogs(["a", "b"]);
+      controlDialogs("a", true);
+      expect(dialogsConfig.a).toBe(true);
+      expect(dialogsConfig.b).toBe(false);
+    });
+  });
+
+  // ─── registerDialogCallbacks + controlDialogs actions ────────────────────
+
+  describe("callbacks", () => {
+    it("fires onConfirm when closing with action='confirm'", () => {
+      const { initialiseDialogs, controlDialogs, registerDialogCallbacks } = useDialogControls();
+      initialiseDialogs(["modal"]);
+      const onConfirm = vi.fn();
+      registerDialogCallbacks("modal", { onConfirm });
+      controlDialogs("modal", false, "confirm");
+      expect(onConfirm).toHaveBeenCalledOnce();
+    });
+
+    it("fires onCancel when closing with action='cancel'", () => {
+      const { initialiseDialogs, controlDialogs, registerDialogCallbacks } = useDialogControls();
+      initialiseDialogs(["modal"]);
+      const onCancel = vi.fn();
+      registerDialogCallbacks("modal", { onCancel });
+      controlDialogs("modal", false, "cancel");
+      expect(onCancel).toHaveBeenCalledOnce();
+    });
+
+    it("does not fire onConfirm when opening (state=true)", () => {
+      const { initialiseDialogs, controlDialogs, registerDialogCallbacks } = useDialogControls();
+      initialiseDialogs(["modal"]);
+      const onConfirm = vi.fn();
+      registerDialogCallbacks("modal", { onConfirm });
+      controlDialogs("modal", true, "confirm");
+      expect(onConfirm).not.toHaveBeenCalled();
+    });
+
+    it("does not fire onCancel when opening (state=true)", () => {
+      const { initialiseDialogs, controlDialogs, registerDialogCallbacks } = useDialogControls();
+      initialiseDialogs(["modal"]);
+      const onCancel = vi.fn();
+      registerDialogCallbacks("modal", { onCancel });
+      controlDialogs("modal", true, "cancel");
+      expect(onCancel).not.toHaveBeenCalled();
+    });
+
+    it("does not fire onConfirm when closing without an action", () => {
+      const { initialiseDialogs, controlDialogs, registerDialogCallbacks } = useDialogControls();
+      initialiseDialogs(["modal"]);
+      const onConfirm = vi.fn();
+      registerDialogCallbacks("modal", { onConfirm });
+      controlDialogs("modal", false);
+      expect(onConfirm).not.toHaveBeenCalled();
+    });
+
+    it("does not fire confirm callback for a different dialog", () => {
+      const { initialiseDialogs, controlDialogs, registerDialogCallbacks } = useDialogControls();
+      initialiseDialogs(["a", "b"]);
+      const onConfirm = vi.fn();
+      registerDialogCallbacks("a", { onConfirm });
+      controlDialogs("b", false, "confirm");
+      expect(onConfirm).not.toHaveBeenCalled();
+    });
+  });
+});

package/app/composables/tests/useSleep.spec.ts

@@ -0,0 +1,33 @@
+import { describe, it, expect } from "vitest";
+import useSleep from "../useSleep";
+
+describe("useSleep", () => {
+  it("returns a Promise", () => {
+    const result = useSleep(100);
+    expect(result).toBeInstanceOf(Promise);
+  });
+
+  it("resolves with true after the given duration", async () => {
+    const promise = useSleep(500);
+    await vi.advanceTimersByTimeAsync(500);
+    await expect(promise).resolves.toBe(true);
+  });
+
+  it("does not resolve before the duration elapses", async () => {
+    let resolved = false;
+    useSleep(1000).then(() => {
+      resolved = true;
+    });
+    await vi.advanceTimersByTimeAsync(999);
+    expect(resolved).toBe(false);
+  });
+
+  it("resolves immediately after the exact duration", async () => {
+    let resolved = false;
+    useSleep(1000).then(() => {
+      resolved = true;
+    });
+    await vi.advanceTimersByTimeAsync(1000);
+    expect(resolved).toBe(true);
+  });
+});

package/app/composables/tests/useStyleClassPassthrough.spec.ts

@@ -0,0 +1,129 @@
+import { describe, it, expect } from "vitest";
+import { nextTick } from "vue";
+import { useStyleClassPassthrough } from "../useStyleClassPassthrough";
+
+describe("useStyleClassPassthrough", () => {
+  // ─── Initialisation ───────────────────────────────────────────────────────
+
+  describe("initialisation", () => {
+    it("accepts a string and normalizes to an array", () => {
+      const { elementClasses } = useStyleClassPassthrough("foo");
+      expect(elementClasses.value).toBe("foo");
+    });
+
+    it("splits a multi-word string on whitespace", () => {
+      const { elementClasses } = useStyleClassPassthrough("foo bar baz");
+      expect(elementClasses.value).toBe("foo bar baz");
+    });
+
+    it("accepts an array directly", () => {
+      const { elementClasses } = useStyleClassPassthrough(["foo", "bar"]);
+      expect(elementClasses.value).toBe("foo bar");
+    });
+
+    it("returns empty string for empty string input", () => {
+      const { elementClasses } = useStyleClassPassthrough("");
+      expect(elementClasses.value).toBe("");
+    });
+
+    it("returns empty string for empty array input", () => {
+      const { elementClasses } = useStyleClassPassthrough([]);
+      expect(elementClasses.value).toBe("");
+    });
+
+    it("strips leading and trailing whitespace from string input", () => {
+      const { elementClasses } = useStyleClassPassthrough("  foo  bar  ");
+      expect(elementClasses.value).toBe("foo bar");
+    });
+  });
+
+  // ─── elementClasses ───────────────────────────────────────────────────────
+
+  describe("elementClasses", () => {
+    it("reflects the current class list joined by spaces", () => {
+      const { elementClasses } = useStyleClassPassthrough(["a", "b", "c"]);
+      expect(elementClasses.value).toBe("a b c");
+    });
+
+    it("is reactive — updates when styleClassPassthroughRef changes", async () => {
+      const { elementClasses, styleClassPassthroughRef } = useStyleClassPassthrough(["a"]);
+      styleClassPassthroughRef.value = ["a", "b"];
+      await nextTick();
+      expect(elementClasses.value).toBe("a b");
+    });
+  });
+
+  // ─── updateElementClasses ─────────────────────────────────────────────────
+
+  describe("updateElementClasses", () => {
+    it("adds a class that is not present (string)", () => {
+      const { elementClasses, updateElementClasses } = useStyleClassPassthrough("foo");
+      updateElementClasses("bar");
+      expect(elementClasses.value).toContain("bar");
+    });
+
+    it("removes a class that is already present (toggle off)", () => {
+      const { elementClasses, updateElementClasses } = useStyleClassPassthrough("foo bar");
+      updateElementClasses("foo");
+      expect(elementClasses.value).not.toContain("foo");
+      expect(elementClasses.value).toContain("bar");
+    });
+
+    it("adds multiple classes from an array", () => {
+      const { elementClasses, updateElementClasses } = useStyleClassPassthrough([]);
+      updateElementClasses(["a", "b", "c"]);
+      expect(elementClasses.value).toBe("a b c");
+    });
+
+    it("toggles each class in an array independently", () => {
+      const { elementClasses, updateElementClasses } = useStyleClassPassthrough(["a", "b"]);
+      // "a" is present (will be removed), "c" is absent (will be added)
+      updateElementClasses(["a", "c"]);
+      expect(elementClasses.value).not.toContain("a");
+      expect(elementClasses.value).toContain("b");
+      expect(elementClasses.value).toContain("c");
+    });
+
+    it("calling twice with the same class returns to original state", () => {
+      const { elementClasses, updateElementClasses } = useStyleClassPassthrough("foo");
+      updateElementClasses("bar");
+      updateElementClasses("bar");
+      expect(elementClasses.value).toBe("foo");
+    });
+  });
+
+  // ─── resetElementClasses ──────────────────────────────────────────────────
+
+  describe("resetElementClasses", () => {
+    it("resets to a new string value", () => {
+      const { elementClasses, updateElementClasses, resetElementClasses } =
+        useStyleClassPassthrough("foo");
+      updateElementClasses("bar");
+      resetElementClasses("baz");
+      expect(elementClasses.value).toBe("baz");
+    });
+
+    it("resets to a new array value", () => {
+      const { elementClasses, updateElementClasses, resetElementClasses } =
+        useStyleClassPassthrough("foo");
+      updateElementClasses("extra");
+      resetElementClasses(["x", "y"]);
+      expect(elementClasses.value).toBe("x y");
+    });
+
+    it("clears all classes when reset with empty string", () => {
+      const { elementClasses, resetElementClasses } = useStyleClassPassthrough("foo bar");
+      resetElementClasses("");
+      expect(elementClasses.value).toBe("");
+    });
+
+    it("discards any classes added via updateElementClasses", () => {
+      const { elementClasses, updateElementClasses, resetElementClasses } =
+        useStyleClassPassthrough("original");
+      updateElementClasses("added");
+      resetElementClasses("original");
+      expect(elementClasses.value).toBe("original");
+      expect(elementClasses.value).not.toContain("added");
+    });
+  });
+});

package/app/composables/tests/useWhatsApp.spec.ts

@@ -0,0 +1,102 @@
+import { describe, it, expect, beforeEach, afterEach, vi, type MockInstance } from "vitest";
+import { mockNuxtImport } from "@nuxt/test-utils/runtime";
+import { useWhatsApp } from "../useWhatsApp";
+
+const PHONE_NUMBER = "447700900000";
+
+// mockNuxtImport intercepts Nuxt's auto-import resolution — vi.stubGlobal cannot.
+// Use vi.hoisted so the mock function is available before module evaluation.
+const { useRuntimeConfigMock } = vi.hoisted(() => ({
+  useRuntimeConfigMock: vi.fn(() => ({ public: { whatsappNumber: PHONE_NUMBER } })),
+}));
+
+mockNuxtImport("useRuntimeConfig", () => useRuntimeConfigMock);
+
+describe("useWhatsApp", () => {
+  let windowOpenSpy: MockInstance<typeof window.open>;
+
+  beforeEach(() => {
+    windowOpenSpy = vi.spyOn(window, "open").mockImplementation(() => null);
+    useRuntimeConfigMock.mockReturnValue({ public: { whatsappNumber: PHONE_NUMBER } });
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  // ─── openWhatsApp ─────────────────────────────────────────────────────────
+
+  describe("openWhatsApp", () => {
+    it("opens a wa.me URL with the configured number", () => {
+      const { openWhatsApp } = useWhatsApp();
+      openWhatsApp([{ label: "Name", value: "Jane" }]);
+      expect(windowOpenSpy).toHaveBeenCalledOnce();
+      const url = windowOpenSpy.mock.calls[0]![0] as string;
+      expect(url).toContain(`https://wa.me/${PHONE_NUMBER}`);
+    });
+
+    it("opens with _blank target and noopener,noreferrer", () => {
+      const { openWhatsApp } = useWhatsApp();
+      openWhatsApp([{ label: "Name", value: "Jane" }]);
+      expect(windowOpenSpy).toHaveBeenCalledWith(expect.any(String), "_blank", "noopener,noreferrer");
+    });
+
+    it("formats fields as bold labels in the message", () => {
+      const { openWhatsApp } = useWhatsApp();
+      openWhatsApp([
+        { label: "Name", value: "Jane Smith" },
+        { label: "Phone", value: "07700900000" },
+      ]);
+      const url = windowOpenSpy.mock.calls[0]![0] as string;
+      const message = decodeURIComponent(url.split("?text=")[1]!);
+      expect(message).toBe("*Name:* Jane Smith\n*Phone:* 07700900000");
+    });
+
+    it("URL-encodes the message", () => {
+      const { openWhatsApp } = useWhatsApp();
+      openWhatsApp([{ label: "Name", value: "Jane Smith" }]);
+      const url = windowOpenSpy.mock.calls[0]![0] as string;
+      expect(url).toContain("?text=");
+      expect(url).not.toContain(" "); // spaces must be encoded
+    });
+
+    it("filters out fields with empty values", () => {
+      const { openWhatsApp } = useWhatsApp();
+      openWhatsApp([
+        { label: "Name", value: "Jane" },
+        { label: "Comments", value: "" },
+        { label: "Phone", value: "07700900000" },
+      ]);
+      const url = windowOpenSpy.mock.calls[0]![0] as string;
+      const message = decodeURIComponent(url.split("?text=")[1]!);
+      expect(message).not.toContain("Comments");
+      expect(message).toBe("*Name:* Jane\n*Phone:* 07700900000");
+    });
+
+    it("filters out fields with whitespace-only values", () => {
+      const { openWhatsApp } = useWhatsApp();
+      openWhatsApp([
+        { label: "Name", value: "Jane" },
+        { label: "Comments", value: "   " },
+      ]);
+      const url = windowOpenSpy.mock.calls[0]![0] as string;
+      const message = decodeURIComponent(url.split("?text=")[1]!);
+      expect(message).toBe("*Name:* Jane");
+    });
+
+    it("does not call window.open when number is not configured", () => {
+      useRuntimeConfigMock.mockReturnValue({ public: { whatsappNumber: "" } });
+      const { openWhatsApp } = useWhatsApp();
+      openWhatsApp([{ label: "Name", value: "Jane" }]);
+      expect(windowOpenSpy).not.toHaveBeenCalled();
+    });
+
+    it("logs a warning when number is not configured", () => {
+      useRuntimeConfigMock.mockReturnValue({ public: { whatsappNumber: "" } });
+      const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+      const { openWhatsApp } = useWhatsApp();
+      openWhatsApp([{ label: "Name", value: "Jane" }]);
+      expect(warnSpy).toHaveBeenCalledWith("[useWhatsApp] whatsappNumber is not configured");
+    });
+  });
+});

package/app/composables/useWhatsApp.ts

@@ -0,0 +1,24 @@
+// composables/useWhatsApp.ts
+
+export const useWhatsApp = () => {
+  const config = useRuntimeConfig();
+
+  const openWhatsApp = (fields: { label: string; value: string }[]) => {
+    const number = config.public.whatsappNumber;
+
+    if (!number) {
+      console.warn("[useWhatsApp] whatsappNumber is not configured");
+      return;
+    }
+
+    const message = fields
+      .filter((f) => f.value?.trim())
+      .map((f) => `*${f.label}:* ${f.value}`)
+      .join("\n");
+
+    const url = `https://wa.me/${number}?text=${encodeURIComponent(message)}`;
+    window.open(url, "_blank", "noopener,noreferrer");
+  };
+
+  return { openWhatsApp };
+};

package/nuxt.config.ts

@@ -17,6 +17,7 @@ export default defineNuxtConfig({
     contactEmailTo: "", // NUXT_CONTACT_EMAIL_TO   — inbox that receives enquiries
     contactEmailFrom: "", // NUXT_CONTACT_EMAIL_FROM — must be a verified Resend domain
     public: {
+      whatsappNumber: "", // NUXT_PUBLIC_WHATSAPP_NUMBER — in international format, no + or spaces, e.g. 447700900000
       // Consumer apps that don't support dark/light mode can opt out entirely:
       // set NUXT_PUBLIC_COLOUR_SCHEME_ENABLED=false (env var) or override in their nuxt.config.ts
       colourScheme: {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "srcdev-nuxt-components",
   "type": "module",
-  "version": "9.1.14",
+  "version": "9.1.16",
   "main": "nuxt.config.ts",
   "types": "types.d.ts",
   "license": "MIT",