@devopsplaybook.io/common-web 0.6.0 → 0.7.0-beta.14.f2476ab

package/CHANGELOG.md

@@ -5,6 +5,65 @@ All notable changes to this project are documented here.
 This project follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 and [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.7.0] - 2026-10-24
+
+### Added
+
+- Pre-paint theme script: the layer injects a small inline `<head>` script that
+  applies `data-theme` from `localStorage` and `prefers-color-scheme` before
+  first paint, removing the flash of the light theme for users with a stored
+  dark preference. Applications with a strict CSP must allow this inline script
+  (nonce or `unsafe-inline`); without it the existing `prefers-color-scheme`
+  CSS path still applies.
+- Per-status foreground tokens `--color-on-success`, `--color-on-error` and
+  `--color-on-warning` so status backgrounds and their text meet WCAG AA in
+  both themes, with an automated contrast test over the shipped tokens.
+- `AppNavigation` accepts a `linkComponent` prop (default `"a"`) so Nuxt apps
+  can opt into SPA navigation with `resolveComponent("NuxtLink")` instead of
+  full page reloads.
+- `OfflineBanner` accepts a `message` prop (default `"You are offline."`) and
+  keeps its `role="status"` live region mounted at all times, so the offline
+  announcement is not missed by screen readers; while online the region is
+  visually hidden.
+- `AlertMessages` supports sticky alerts with `durationMs: 0`, deduplicates
+  identical `type` + `text` pairs, and caps the queue at five messages (oldest
+  dropped first).
+- Respect `prefers-reduced-motion`: the loading spinner, `dpb-fade-in` and
+  `dpb-blink` animations are disabled under reduced motion.
+
+### Changed
+
+- `useTheme().isDark` is now the effective theme: under the default `system`
+  preference it follows `prefers-color-scheme` (including live media changes),
+  and `toggleTheme()` toggles from the effective value instead of only an
+  explicit `dark` preference.
+- Alert styles are prefixed: `.message*` selectors are renamed to
+  `.alert-message*` (`.alert-message`, `.alert-message-text`,
+  `.alert-message-{type}`) so they no longer collide with consumer styles.
+  This is the only consumer-facing class change.
+- `useAppHeight()` coalesces resize updates with `requestAnimationFrame`, so
+  repeated resize events and multiple component instances write the CSS custom
+  property at most once per frame.
+- `useOfflineStatus()` initialises `isOnline` from `navigator.onLine`, so a
+  page loaded offline no longer briefly renders as online.
+- `AlertMessage.type` is narrowed to `"info" | "success" | "warning" | "error"`
+  instead of collapsing to `string`, and the mitt compatibility index
+  signatures are documented.
+- `AuthService.removeToken()` documents that its optional argument is accepted
+  for API compatibility and ignored.
+
+### Fixed
+
+- Dark-mode status colors failed WCAG AA against white text (warning 1.86:1,
+  success/info 3.30:1, error 4.23:1). Dark backgrounds now use `#171717` text
+  through the new `--color-on-*` tokens, and dark `--color-error` changed from
+  `#e53935` to `#ef5350` because the old value cannot reach 4.5:1 with either
+  white or `#171717` text. Light mode is unchanged and passes.
+- The playground theme button showed "Switch to dark" on an already-dark page
+  under the `system` preference; `toggleTheme()` now toggles correctly.
+- The offline banner no longer claims "showing cached data"; the layer provides
+  no cache and the default copy is now neutral.
+
 ## [0.6.0] - 2026-10-24
 
 ### Added

package/README.md

@@ -25,23 +25,61 @@ required. The `playground/` directory demonstrates a consuming app.
 
 | Component | Purpose |
 | --- | --- |
-| `<Loading size="small" />` | Accessible loading indicator; `size` is `small` or `large`. |
+| `<Loading size="small" />` | Accessible loading indicator; `size` is `small` or `large`. The animation is disabled under `prefers-reduced-motion: reduce`. |
 | `<AlertMessages />` | Accessible live region displaying messages emitted on `EventBus`. |
-| `<AppNavigation :links="links" />` | Navigation shell with a named `brand` slot and configurable links (`label`, `to`, optional `icon` and `active`). |
-| `<OfflineBanner />` | Announces offline status and accepts replacement content through its default slot. |
+| `<AppNavigation :links="links" :link-component="NuxtLink" />` | Navigation shell with a named `brand` slot and configurable links (`label`, `to`, optional `icon` and `active`). |
+| `<OfflineBanner message="You are offline." />` | Announces offline status and accepts replacement content through its default slot. |
 
 `AlertMessages` listens for `EventTypes.ALERT_MESSAGE` events. Its payload is
-`{ text, type?, durationMs? }`; the default display duration is five seconds.
-`handleError(error)` logs the error and emits a corresponding error alert.
+`{ text, type?, durationMs? }` with `type` limited to `info`, `success`,
+`warning` or `error`. The default display duration is five seconds;
+`durationMs: 0` keeps the message until it is dismissed from the queue.
+Identical `type` + `text` pairs are deduplicated and the queue keeps at most
+five messages, dropping the oldest first. Alert styles use the prefixed
+`.alert-message*` classes, so consumer stylesheets are not affected by the
+layer's global styles. `handleError(error)` logs the error and emits a
+corresponding error alert.
+
+`AppNavigation` renders plain `<a href>` links by default, which keeps
+non-Nuxt deep imports and raw-source usage working. Nuxt applications should
+pass their link component to keep SPA state on navigation:
+
+```vue
+<script setup lang="ts">
+import { resolveComponent } from "vue";
+
+const NuxtLink = resolveComponent("NuxtLink");
+</script>
+
+<template>
+  <AppNavigation :links="links" :link-component="NuxtLink" />
+</template>
+```
+
+`OfflineBanner` keeps its `role="status"` live region mounted at all times so
+screen readers announce the transition; while online the region is visually
+hidden. The default copy is the neutral `You are offline.`; replace it with
+the `message` prop or the default slot.
 
 ## Composables and services
 
 - `useTheme()` persists `light`/`dark` preferences in `localStorage` and applies
-  `data-theme` to the document root. Use `setTheme("system")` to return to the
-  operating-system preference.
+  `data-theme` to the document root. `isDark` reflects the effective theme: the
+  default `system` preference follows `prefers-color-scheme`, including live
+  operating-system changes, and `toggleTheme()` toggles from that effective
+  value. Use `setTheme("system")` to return to the operating-system preference.
+  The layer also injects a small pre-paint `<head>` script that applies
+  `data-theme` from `localStorage` and `prefers-color-scheme` before first
+  paint, so a stored dark preference no longer flashes the light theme during
+  load. Applications with a strict CSP must allow this inline script (nonce or
+  `unsafe-inline`); without it, the `prefers-color-scheme` CSS path still
+  applies and the theme resolves after hydration.
 - `useAppHeight()` updates `--app-height` from `visualViewport` when available
-  and cleans up resize listeners on unmount.
-- `useOfflineStatus()` returns a reactive `isOnline` ref.
+  and cleans up resize listeners on unmount. Resize updates are coalesced with
+  `requestAnimationFrame`, so repeated resize events and multiple component
+  instances write the custom property at most once per frame.
+- `useOfflineStatus()` returns a reactive `isOnline` ref, initialised from
+  `navigator.onLine` so a page loaded offline renders offline immediately.
 - Services are browser-only and available through package deep imports, for
   example `@devopsplaybook.io/common-web/services/AuthService`. `AuthService`
   guards every `localStorage` access, so during SSR `getToken()` resolves
@@ -139,10 +177,15 @@ missing or malformed; `set()` normalises valid non-negative integer strings
 ## Tokens and app-shell styles
 
 The layer loads `assets/css/tokens.css` and `assets/css/app-shell.css`.
-Tokens include `--color-*`, `--space-*`, `--text-*`, `--radius-*`,
-`--shadow-*`, `--header-height`, and `--app-height`. Dark mode can be selected
-with `data-theme="dark"` or comes from `prefers-color-scheme` when no explicit
-light preference is set.
+Tokens include `--color-*` (including the per-status foreground tokens
+`--color-on-success`, `--color-on-error` and `--color-on-warning` used with
+`--color-success`, `--color-error` and `--color-warning`),
+`--space-*`, `--text-*`, `--radius-*`, `--shadow-*`, `--header-height`, and
+`--app-height`. Dark mode can be selected with `data-theme="dark"` or comes
+from `prefers-color-scheme` when no explicit light preference is set. Status
+colors meet WCAG AA against their `--color-on-*` foreground tokens in both
+themes. The `dpb-fade-in` and `dpb-blink` helper classes are disabled under
+`prefers-reduced-motion: reduce`.
 
 Load app-specific CSS after the layer and redefine only the values you need:
 

package/assets/css/app-shell.css

@@ -27,10 +27,12 @@
   }
 }
 
-.dpb-fade-in {
-  animation: dpb-fade 180ms ease-out;
-}
+@media (prefers-reduced-motion: no-preference) {
+  .dpb-fade-in {
+    animation: dpb-fade 180ms ease-out;
+  }
 
-.dpb-blink {
-  animation: dpb-blink 1s ease-in-out infinite;
+  .dpb-blink {
+    animation: dpb-blink 1s ease-in-out infinite;
+  }
 }

package/assets/css/tokens.css

@@ -13,6 +13,9 @@
   --color-success: #2e7d32;
   --color-error: #c62828;
   --color-warning: #8a5a00;
+  --color-on-success: #ffffff;
+  --color-on-error: #ffffff;
+  --color-on-warning: #ffffff;
 
   --space-xs: 0.25rem;
   --space-sm: 0.5rem;
@@ -53,8 +56,11 @@
   --color-surface-message-info: #1c3a1d;
   --color-border: #44445a;
   --color-success: #43a047;
-  --color-error: #e53935;
+  --color-error: #ef5350;
   --color-warning: #f0b429;
+  --color-on-success: #171717;
+  --color-on-error: #171717;
+  --color-on-warning: #171717;
   --shadow-sm: 0 1px 2px rgb(0 0 0 / 30%);
   --shadow-md: 0 4px 12px rgb(0 0 0 / 40%);
   --shadow-lg: 0 8px 24px rgb(0 0 0 / 50%);
@@ -72,8 +78,11 @@
     --color-surface-message-info: #1c3a1d;
     --color-border: #44445a;
     --color-success: #43a047;
-    --color-error: #e53935;
+    --color-error: #ef5350;
     --color-warning: #f0b429;
+    --color-on-success: #171717;
+    --color-on-error: #171717;
+    --color-on-warning: #171717;
     --shadow-sm: 0 1px 2px rgb(0 0 0 / 30%);
     --shadow-md: 0 4px 12px rgb(0 0 0 / 40%);
     --shadow-lg: 0 8px 24px rgb(0 0 0 / 50%);

package/components/AlertMessages.vue

@@ -2,9 +2,13 @@
   <div role="status" aria-live="polite" class="alert-messages">
     <div v-for="message in messages" :key="message.id">
       <div
-        :class="message.type ? `message message-${message.type}` : 'message'"
+        :class="
+          message.type
+            ? `alert-message alert-message-${message.type}`
+            : 'alert-message'
+        "
       >
-        <span class="message-text">
+        <span class="alert-message-text">
           <b v-if="message.type">{{ message.type }}</b>
           {{ message.text }}
         </span>
@@ -21,35 +25,54 @@ interface DisplayMessage extends AlertMessage {
   id: number;
 }
 
+const DEFAULT_DURATION_MS = 5000;
+const MAX_MESSAGES = 5;
+
 const messages = ref<DisplayMessage[]>([]);
-const timers = new Set<ReturnType<typeof setTimeout>>();
+const timers = new Map<number, ReturnType<typeof setTimeout>>();
 let nextId = 1;
 
 function dismiss(id: number): void {
+  const timer = timers.get(id);
+  if (timer) {
+    clearTimeout(timer);
+    timers.delete(id);
+  }
   const index = messages.value.findIndex((message) => message.id === id);
   if (index !== -1) messages.value.splice(index, 1);
 }
 
 function handleAlert(message: AlertMessage): void {
+  const duplicate = messages.value.some(
+    (existing) => existing.type === message.type && existing.text === message.text,
+  );
+  if (duplicate) return;
+
   const entry = { ...message, id: nextId++ };
   messages.value.push(entry);
+  while (messages.value.length > MAX_MESSAGES) {
+    const oldest = messages.value[0];
+    if (oldest) dismiss(oldest.id);
+  }
+
+  if (message.durationMs === 0) return;
   const timer = setTimeout(() => {
-    timers.delete(timer);
+    timers.delete(entry.id);
     dismiss(entry.id);
-  }, message.durationMs || 5000);
-  timers.add(timer);
+  }, message.durationMs ?? DEFAULT_DURATION_MS);
+  timers.set(entry.id, timer);
 }
 
 onMounted(() => EventBus.on(EventTypes.ALERT_MESSAGE, handleAlert));
 onUnmounted(() => {
   EventBus.off(EventTypes.ALERT_MESSAGE, handleAlert);
-  for (const timer of timers) clearTimeout(timer);
+  for (const timer of timers.values()) clearTimeout(timer);
   timers.clear();
 });
 </script>
 
 <style>
-.message {
+.alert-message {
   display: flex;
   align-items: center;
   padding: var(--space-base, 1rem);
@@ -58,20 +81,23 @@ onUnmounted(() => {
   background-color: #546e7a;
 }
 
-.message-text {
+.alert-message-text {
   flex: 1;
 }
 
-.message-info,
-.message-success {
+.alert-message-info,
+.alert-message-success {
   background-color: var(--color-success, #2e7d32);
+  color: var(--color-on-success, #fff);
 }
 
-.message-warning {
+.alert-message-warning {
   background-color: var(--color-warning, #8a5a00);
+  color: var(--color-on-warning, #fff);
 }
 
-.message-error {
+.alert-message-error {
   background-color: var(--color-error, #c62828);
+  color: var(--color-on-error, #fff);
 }
 </style>

package/components/AppNavigation.vue

@@ -5,10 +5,14 @@
     </div>
     <ul class="app-navigation-links">
       <li v-for="link in links" :key="link.to">
-        <a :href="link.to" :aria-current="link.active ? 'page' : undefined">
+        <component
+          :is="linkComponent"
+          v-bind="linkProps(link)"
+          :aria-current="link.active ? 'page' : undefined"
+        >
           <span v-if="link.icon" :class="link.icon" aria-hidden="true" />
           {{ link.label }}
-        </a>
+        </component>
       </li>
     </ul>
     <slot />
@@ -16,6 +20,8 @@
 </template>
 
 <script setup lang="ts">
+import type { Component } from "vue";
+
 interface AppNavigationLink {
   label: string;
   to: string;
@@ -23,7 +29,17 @@ interface AppNavigationLink {
   active?: boolean;
 }
 
-defineProps<{ links: AppNavigationLink[] }>();
+const props = withDefaults(
+  defineProps<{
+    links: AppNavigationLink[];
+    linkComponent?: string | Component;
+  }>(),
+  { linkComponent: "a" },
+);
+
+function linkProps(link: AppNavigationLink): { href: string } | { to: string } {
+  return props.linkComponent === "a" ? { href: link.to } : { to: link.to };
+}
 </script>
 
 <style>

package/components/Loading.vue

@@ -28,7 +28,6 @@ withDefaults(defineProps<{ size?: "small" | "large"; label?: string }>(), {
     var(--loading-gradient) 50% 50%,
     var(--loading-gradient) 100% 50%;
   background-size: 20% 100%;
-  animation: dpb-loading 2s infinite linear;
 }
 
 .loading-indicator-small {
@@ -37,6 +36,12 @@ withDefaults(defineProps<{ size?: "small" | "large"; label?: string }>(), {
   margin-bottom: 0.5rem;
 }
 
+@media (prefers-reduced-motion: no-preference) {
+  .loading-indicator {
+    animation: dpb-loading 2s infinite linear;
+  }
+}
+
 @keyframes dpb-loading {
   0%,
   100% {

package/components/OfflineBanner.vue

@@ -1,6 +1,12 @@
 <template>
-  <div v-if="!isOnline" class="offline-banner" role="status" aria-live="polite">
-    <slot>You are offline — showing cached data</slot>
+  <div
+    class="offline-banner"
+    :class="{ 'offline-banner-hidden': isOnline }"
+    role="status"
+    aria-live="polite"
+    aria-atomic="true"
+  >
+    <template v-if="!isOnline"><slot>{{ message }}</slot></template>
   </div>
 </template>
 
@@ -8,13 +14,29 @@
 import { useOfflineStatus } from "../composables/useOfflineStatus";
 
 const { isOnline } = useOfflineStatus();
+
+withDefaults(defineProps<{ message?: string }>(), {
+  message: "You are offline.",
+});
 </script>
 
 <style>
 .offline-banner {
   padding: var(--space-sm, 0.5rem) var(--space-base, 1rem);
-  color: var(--color-text-inverse, #fff);
+  color: var(--color-on-warning, #fff);
   background: var(--color-warning, #8a5a00);
   text-align: center;
 }
+
+.offline-banner-hidden {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border-width: 0;
+}
 </style>

package/composables/EventBus.ts

@@ -1,11 +1,15 @@
 import mitt from "mitt";
 
+export type AlertType = "info" | "success" | "warning" | "error";
+
 export interface AlertMessage {
-  type?: "info" | "success" | "warning" | "error" | string;
+  type?: AlertType;
   text: string;
   durationMs?: number;
 }
 
+// mitt's Emitter constraint requires string and symbol index signatures;
+// the explicit ALERT_MESSAGE/AUTH_UPDATED keys keep their payload typing.
 interface AppEvents {
   [event: string]: unknown;
   [event: symbol]: unknown;

package/composables/theme.ts

@@ -0,0 +1,25 @@
+export const THEME_KEY = "UI_THEME";
+
+// Runs synchronously in <head> before first paint; must stay dependency-free.
+// An explicit stored preference always wins over the OS scheme; re-reading
+// localStorage on media changes keeps setTheme() authoritative afterwards.
+export const THEME_INIT_SCRIPT = `(function () {
+  var key = ${JSON.stringify(THEME_KEY)};
+  function apply() {
+    try {
+      var stored = localStorage.getItem(key);
+      var media = window.matchMedia && window.matchMedia("(prefers-color-scheme: dark)");
+      var dark = stored === "dark" || (stored !== "light" && !!(media && media.matches));
+      document.documentElement.setAttribute("data-theme", dark ? "dark" : "light");
+    } catch (error) {
+      /* localStorage unavailable (privacy mode) */
+    }
+  }
+  apply();
+  try {
+    var media = window.matchMedia && window.matchMedia("(prefers-color-scheme: dark)");
+    if (media && media.addEventListener) media.addEventListener("change", apply);
+  } catch (error) {
+    /* no prefers-color-scheme support */
+  }
+})();`;

package/composables/useAppHeight.ts

@@ -1,19 +1,37 @@
 import { onMounted, onUnmounted } from "vue";
 
+let frame: number | null = null;
+
 export function useAppHeight(): void {
   function updateAppHeight(): void {
     const height = window.visualViewport?.height ?? window.innerHeight;
     document.documentElement.style.setProperty("--app-height", `${height}px`);
   }
 
+  function scheduleAppHeight(): void {
+    if (frame !== null) return;
+    if (typeof requestAnimationFrame === "function") {
+      frame = requestAnimationFrame(() => {
+        frame = null;
+        updateAppHeight();
+      });
+    } else {
+      updateAppHeight();
+    }
+  }
+
   onMounted(() => {
     updateAppHeight();
-    window.addEventListener("resize", updateAppHeight);
-    window.visualViewport?.addEventListener("resize", updateAppHeight);
+    window.addEventListener("resize", scheduleAppHeight);
+    window.visualViewport?.addEventListener("resize", scheduleAppHeight);
   });
 
   onUnmounted(() => {
-    window.removeEventListener("resize", updateAppHeight);
-    window.visualViewport?.removeEventListener("resize", updateAppHeight);
+    window.removeEventListener("resize", scheduleAppHeight);
+    window.visualViewport?.removeEventListener("resize", scheduleAppHeight);
+    if (frame !== null) {
+      cancelAnimationFrame(frame);
+      frame = null;
+    }
   });
 }

package/composables/useOfflineStatus.ts

@@ -1,7 +1,9 @@
 import { onMounted, onUnmounted, ref } from "vue";
 
 export function useOfflineStatus() {
-  const isOnline = ref(true);
+  const isOnline = ref(
+    typeof navigator === "undefined" ? true : navigator.onLine,
+  );
 
   function updateStatus(): void {
     isOnline.value = navigator.onLine;

package/composables/useTheme.ts

@@ -1,25 +1,25 @@
 import { computed, onMounted, onUnmounted, ref } from "vue";
+import { THEME_KEY } from "./theme";
 
 export type ThemePreference = "light" | "dark" | "system";
 
-const THEME_KEY = "UI_THEME";
-
 export function useTheme() {
   const preference = ref<ThemePreference>("system");
-  const isDark = computed(() => preference.value === "dark");
+  const systemPrefersDark = ref(false);
+  const isDark = computed(
+    () =>
+      preference.value === "dark" ||
+      (preference.value === "system" && systemPrefersDark.value),
+  );
   let mediaQuery: MediaQueryList | undefined;
 
   function applyTheme(): void {
     if (typeof document === "undefined") return;
 
-    const prefersDark = mediaQuery?.matches ?? false;
-    const theme =
-      preference.value === "system"
-        ? prefersDark
-          ? "dark"
-          : "light"
-        : preference.value;
-    document.documentElement.setAttribute("data-theme", theme);
+    document.documentElement.setAttribute(
+      "data-theme",
+      isDark.value ? "dark" : "light",
+    );
   }
 
   function setTheme(theme: ThemePreference): void {
@@ -35,7 +35,8 @@ export function useTheme() {
     setTheme(isDark.value ? "light" : "dark");
   }
 
-  function handleSystemThemeChange(): void {
+  function handleSystemThemeChange(event: MediaQueryListEvent): void {
+    systemPrefersDark.value = event.matches;
     if (preference.value === "system") applyTheme();
   }
 
@@ -44,6 +45,7 @@ export function useTheme() {
     preference.value =
       storedTheme === "light" || storedTheme === "dark" ? storedTheme : "system";
     mediaQuery = window.matchMedia?.("(prefers-color-scheme: dark)");
+    systemPrefersDark.value = mediaQuery?.matches ?? false;
     mediaQuery?.addEventListener?.("change", handleSystemThemeChange);
     applyTheme();
   });

package/nuxt.config.ts

@@ -1,8 +1,14 @@
 import { fileURLToPath } from "node:url";
+import { THEME_INIT_SCRIPT } from "./composables/theme";
 
 export default defineNuxtConfig({
   css: [
     fileURLToPath(new URL("./assets/css/tokens.css", import.meta.url)),
     fileURLToPath(new URL("./assets/css/app-shell.css", import.meta.url)),
   ],
+  app: {
+    head: {
+      script: [{ key: "common-web-theme", innerHTML: THEME_INIT_SCRIPT }],
+    },
+  },
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devopsplaybook.io/common-web",
-  "version": "0.6.0",
+  "version": "0.7.0-beta.14.f2476ab",
   "description": "Shared Nuxt layer for DevOpsPlaybook web applications",
   "license": "ISC",
   "engines": {

package/services/AuthService.ts

@@ -55,6 +55,10 @@ export class AuthService {
     if (previous !== token) AuthService.emitAuthUpdated();
   }
 
+  /**
+   * Clears every stored token and emits `AUTH_UPDATED`. The optional argument
+   * is accepted for API compatibility with older callers and is ignored.
+   */
   static async removeToken(_token?: string): Promise<void> {
     const storage = AuthService.storage();
     if (!storage) return;