@antelopejs/dms 0.4.2 → 0.4.4

package/frontend-vue/layers/dms-ui/app/components/grid/GridRow.vue

@@ -11,10 +11,13 @@ const props = defineProps<GridRowProps>();
 
 const gridContext = inject<GridContext>(GRID_CONTEXT);
 
-const columnCount = props.childCount || 0;
-if (gridContext) {
-  gridContext.registerRowColumnCount(columnCount);
-}
+/** The identity this row counts under, so its width dies with it. */
+const rowId = Symbol("grid-row");
+
+const columnCount = computed(() => props.childCount || 0);
+
+watchEffect(() => gridContext?.setRowColumnCount(rowId, columnCount.value));
+onUnmounted(() => gridContext?.dropRow(rowId));
 
 const rowStyle = computed(() => {
   const gap = gridContext?.gap.value ?? DEFAULT_GAP;

package/frontend-vue/layers/dms-ui/app/components/grid/constants.ts

@@ -1,7 +1,14 @@
 export const GRID_CONTEXT = Symbol("grid-context");
 
 export interface GridContext {
-  registerRowColumnCount: (count: number) => void;
+  /**
+   * A row states how many columns it holds, and says so again whenever that
+   * changes: a row built by hand never moves, but one an editor fills gains and
+   * loses children while the page is open.
+   */
+  setRowColumnCount: (row: symbol, count: number) => void;
+  /** A row that unmounts stops counting, so a stale width cannot outlive it. */
+  dropRow: (row: symbol) => void;
   maxColumns: ComputedRef<number>;
   gap: ComputedRef<string>;
   minColumnWidth: ComputedRef<string>;

package/frontend-vue/layers/dms-ui/app/components/kpi/KpiCard.vue

@@ -1,7 +1,10 @@
 <script setup lang="ts">
 import { computed } from "vue";
 import { useChartFetch } from "../../composables/chart/useChartFetch";
-import { formatValueParts } from "../../composables/chart/formatValue";
+import {
+  ABSENT_VALUE_PARTS,
+  formatValueParts,
+} from "../../composables/chart/formatValue";
 import { resolveSparklineAccent } from "../../composables/chart/resolveSparklineAccent";
 import type {
   KpiCardResponse,
@@ -69,18 +72,20 @@ const { data, isLoading } = useChartFetch<KpiCardResponse>({
   watchSource: () => watchKey.value,
 });
 
-const value = computed(() => data.value?.value ?? 0);
+const value = computed(() => data.value?.value);
 const delta = computed(() => data.value?.delta ?? null);
 const sparkline = computed(() => data.value?.sparkline ?? []);
 
 const formattedParts = computed(() =>
-  formatValueParts(
-    value.value,
-    props.valueFormat,
-    locale.value,
-    props.currencyCode,
-    props.valuePrecision,
-  ),
+  value.value === undefined
+    ? ABSENT_VALUE_PARTS
+    : formatValueParts(
+        value.value,
+        props.valueFormat,
+        locale.value,
+        props.currencyCode,
+        props.valuePrecision,
+      ),
 );
 
 const showTrend = computed(() => props.showDelta && delta.value !== null);

package/frontend-vue/layers/dms-ui/app/composables/chart/formatValue.ts

@@ -112,6 +112,21 @@ export interface FormattedValueParts {
   unitIsPrefix: boolean;
 }
 
+/**
+ * What a card prints where its figure would go when the query measured nothing.
+ *
+ * An em dash and not a zero: a zero is itself a measurement, so a card printing
+ * one for a period with no rows in it states a result nobody computed. No unit
+ * either — there is no quantity for it to qualify.
+ */
+export const ABSENT_VALUE_TEXT = "—";
+
+export const ABSENT_VALUE_PARTS: FormattedValueParts = {
+  value: ABSENT_VALUE_TEXT,
+  unit: "",
+  unitIsPrefix: false,
+};
+
 /** Splits the same formatted value into numeric and unit parts for KPI cards. */
 export function formatValueParts(
   value: number,

package/frontend-vue/layers/dms-ui/app/composables/chart/types.ts

@@ -82,7 +82,8 @@ export interface DonutRecord {
 }
 
 export interface ChartCardResponse {
-  value: number;
+  /** Absent when the query measured no group; the card shows no figure. */
+  value?: number;
   delta?: number;
   previousValue?: number;
   series: ChartSeries[];
@@ -90,7 +91,8 @@ export interface ChartCardResponse {
 }
 
 export interface KpiCardResponse {
-  value: number;
+  /** Absent when the query measured no group; the card shows no figure. */
+  value?: number;
   delta?: number;
   previousValue?: number;
   sparkline?: number[];

package/frontend-vue/layers/dms-ui/app/composables/chart/useThemeRevision.ts

@@ -1,29 +1,8 @@
 import { onBeforeUnmount, onMounted, ref, type Ref } from "vue";
 import { clearChartColorCache } from "./useChartTheme";
 
-interface ColorModeLike {
-  preference?: string;
-  value?: string;
-  $subscribe?: (cb: () => void) => () => void;
-}
-
-type ColorModeFactory = () => ColorModeLike;
-
 const THEME_OBSERVED_ATTRIBUTES = ["class", "data-theme", "style"];
 
-function getColorModeFactory(): ColorModeFactory | undefined {
-  const fn = (globalThis as unknown as { useColorMode?: ColorModeFactory })
-    .useColorMode;
-  return typeof fn === "function" ? fn : undefined;
-}
-
-function trySubscribeColorMode(bump: () => void) {
-  const factory = getColorModeFactory();
-  if (!factory) return;
-  const mode = factory();
-  mode?.$subscribe?.(bump);
-}
-
 function createThemeObserver(bump: () => void): MutationObserver {
   const observer = new MutationObserver(bump);
   observer.observe(document.documentElement, {
@@ -47,7 +26,6 @@ export function useThemeRevision(): Ref<number> {
 
   onMounted(() => {
     observer = createThemeObserver(bump);
-    trySubscribeColorMode(bump);
   });
 
   onBeforeUnmount(() => {

package/frontend-vue/layers/dms-ui/app/composables/form/types/props.ts

@@ -17,6 +17,8 @@ export interface FormProps extends FormComponentProps {
   submitUrl?: string;
   submitUrlMethod?: HttpMethod;
   submitLabel?: string;
+  /** Whether the buttons show; left out, once there is somewhere to submit to. */
+  showActions?: boolean;
   successMessage?: string;
   errorMessage?: string;
   schema?: Record<string, unknown>;

package/frontend-vue/layers/dms-ui/app/composables/form/useForm.ts

@@ -28,6 +28,23 @@ export function cloneFormValue(
   return JSON.parse(JSON.stringify(value));
 }
 
+/**
+ * Whether a form shows its reset and submit buttons.
+ *
+ * Asked for, they show whatever else holds — a form placed in the builder shows
+ * them before it has somewhere to submit to. Left to the form, they show once
+ * it has an address and a field someone can fill in.
+ */
+export function formShowsActions(
+  options: { showActions?: boolean; submitUrl?: string },
+  fields: ReadonlyArray<{ disabled?: boolean }>,
+): boolean {
+  return (
+    options.showActions ??
+    (!!options.submitUrl && !fields.every((field) => field.disabled))
+  );
+}
+
 export function computeResetState(
   state: Record<string, unknown>,
   initialValues: FormData,
@@ -137,6 +154,25 @@ export function replaceUrlVariables(
   return processedUrl;
 }
 
+/** Where a submit goes, or what it lacks to go anywhere. */
+export type SubmitTarget = { url: string } | { missing: "url" | "token" };
+
+/**
+ * Where a submit is sent. A form with no URL has nowhere to send it — it is a
+ * read-only one — and a URL naming a token the page does not carry, such as an
+ * edit form opened without the id of its row, is not a route either: loading
+ * already skips such a URL, and submitting to it wrote to a path that was never
+ * meant to exist.
+ */
+export function resolveSubmitTarget(
+  submitUrl: string | undefined,
+  context: ReplaceUrlVariablesContext,
+): SubmitTarget {
+  if (!submitUrl) return { missing: "url" };
+  const url = replaceUrlVariables(submitUrl, context);
+  return url.includes("{{") ? { missing: "token" } : { url };
+}
+
 function processBeforeStateMappers(
   data: FormData,
   fields: FormFieldOrGroup[],
@@ -258,6 +294,28 @@ export function buildValidationSchema(
   return z.object(newShape).passthrough();
 }
 
+// A switch always holds a value (off is `false`): it can never be left
+// missing, so marking it required would only suggest an action that does not
+// exist.
+const ALWAYS_FILLED_FIELD_TYPES = new Set(["boolean"]);
+
+/**
+ * Whether the form marks a field as required: declared so, or made so by a
+ * watch action, and neither disabled nor hidden, since `buildValidationSchema`
+ * does not validate inactive fields, nor a type that always holds a value.
+ */
+export function isFieldMarkedRequired(
+  field: Pick<FormField, "id" | "required" | "disabled" | "type">,
+  disabled: Set<string> | undefined,
+  hidden: Set<string> | undefined,
+  required: Set<string> | undefined,
+): boolean {
+  if (field.disabled || disabled?.has(field.id) || hidden?.has(field.id))
+    return false;
+  if (field.type && ALWAYS_FILLED_FIELD_TYPES.has(field.type)) return false;
+  return !!field.required || (required?.has(field.id) ?? false);
+}
+
 function watchFieldChanges(
   state: Ref<Record<string, unknown>>,
   componentId: string | undefined,
@@ -474,16 +532,29 @@ export const useForm = (props: FormProps) => {
     }
   };
 
+  const showUnresolvedTargetToast = () => {
+    toast.add({
+      title: processI18n("$dms.form.error_title"),
+      description: processI18n("$dms.form.error_no_target"),
+      color: Color.error,
+    });
+  };
+
   const onSubmit = async (event: FormSubmitEvent<FormData>) => {
+    const target = resolveSubmitTarget(props.submitUrl, buildUrlContext());
+    if ("missing" in target) {
+      // A read-only form renders no submit button, but Enter in one of its
+      // fields still submits it: that does nothing. Falling back on `/` sent
+      // the values to the site root with a PUT and reported nothing.
+      if (target.missing === "token") showUnresolvedTargetToast();
+      return;
+    }
+    const submitUrl = target.url;
     const plainData = collectSubmitData(
       event,
       allFields.value,
       effectiveSubmitDefaults.value,
     );
-    const submitUrl = replaceUrlVariables(
-      props.submitUrl || "/",
-      buildUrlContext(),
-    );
 
     loading.value = true;
     try {
@@ -546,6 +617,7 @@ export const useForm = (props: FormProps) => {
     allFields,
     disabledFields,
     hiddenFields,
+    requiredFields,
     isFieldGroup,
     submitSucceeded,
     resolvedFetchUrl,

package/frontend-vue/layers/dms-ui/app/composables/tree/useTree.ts

@@ -106,12 +106,6 @@ export async function useTree<T = unknown>(props: TreeProps) {
     },
   });
 
-  if (!props.fetchUrl && !props.staticNodes) {
-    throw new Error(
-      "Either fetchUrl or staticNodes must be provided to useTree",
-    );
-  }
-
   const loadingNodes = ref<Set<string>>(new Set());
   // Shallow on purpose: `TreeItem` carries a string index signature and
   // recurses through `children`, so Vue's deep `UnwrapRef` on a tree node
@@ -194,12 +188,16 @@ export async function useTree<T = unknown>(props: TreeProps) {
     }
   }
 
+  // A tree with neither a URL nor nodes of its own holds nothing yet, which is
+  // what a block just placed on a page looks like: it is configured after it is
+  // placed, and the editor says what is still missing. Refusing to render at
+  // all would answer that gesture with a crash.
   const dataLoader = props.fetchUrl
     ? () =>
         $authFetch<TreeNode<T>[]>(props.fetchUrl!, {
           method: props.fetchUrlMethod || "GET",
         })
-    : () => Promise.resolve(props.staticNodes as TreeNode<T>[]);
+    : () => Promise.resolve((props.staticNodes ?? []) as TreeNode<T>[]);
 
   const { data, status, refresh } = await useDmsAsyncData(
     `tree-${props.componentId}-${props.pageId}-${props.componentId}`,

package/frontend-vue/layers/dms-ui/i18n/locales/ui-en-GB.json

@@ -161,6 +161,7 @@
       "success_message": "Data has been successfully saved",
       "error_title": "Error",
       "error_unknown": "An unknown error occurred",
+      "error_no_target": "This form does not know which item to save. Open it from a link that names one.",
       "no_data": "No data available",
       "empty_value": "—",
       "actions": "Actions",
@@ -169,6 +170,7 @@
       "row_added_success": "The item has been successfully added",
       "error_missing_fields": "Missing required fields",
       "error_fill_all_fields": "Please fill in all required fields",
+      "required_legend": "Required fields",
       "fetch_error_title": "Failed to fetch data",
       "fetch_error_unknown": "An unexpected error occurred. Please try again later.",
       "select_date": "Select date",

package/frontend-vue/layers/dms-ui/i18n/locales/ui-fr-FR.json

@@ -161,6 +161,7 @@
       "success_message": "Les données ont été enregistrées avec succès",
       "error_title": "Erreur",
       "error_unknown": "Une erreur inconnue s'est produite",
+      "error_no_target": "Ce formulaire ne sait pas quel élément enregistrer. Ouvrez-le depuis un lien qui en désigne un.",
       "no_data": "Aucune donnée disponible",
       "empty_value": "—",
       "actions": "Actions",
@@ -169,6 +170,7 @@
       "row_added_success": "L'élément a été ajouté avec succès",
       "error_missing_fields": "Champs requis manquants",
       "error_fill_all_fields": "Veuillez remplir tous les champs requis",
+      "required_legend": "Champs requis",
       "error_not_submitted": "Le formulaire n'a pas été soumis",
       "fetch_error_title": "Échec de la récupération des données",
       "fetch_error_unknown": "Une erreur inattendue s'est produite. Veuillez réessayer plus tard.",

package/frontend-vue/package.json

@@ -39,7 +39,7 @@
     "@vue-flow/controls": "^1.1.3",
     "@vue-flow/core": "^1.48.2",
     "@vue-flow/minimap": "^1.5.4",
-    "@vueuse/core": "^13.0.0",
+    "@vueuse/core": "^14.3.0",
     "@vueuse/integrations": "^14.1.0",
     "apexcharts": "^4.4.0",
     "defu": "^6.1.4",
@@ -59,7 +59,7 @@
   },
   "devDependencies": {
     "@antelopejs/core": ">=1.9.1 <2",
-    "@antelopejs/dms-frontend": ">=0.2.6 <1.0.0",
+    "@antelopejs/dms-frontend": ">=0.2.8 <1.0.0",
     "@eslint/js": "^8.57.0",
     "@inertiajs/vue3": "^3.7.0",
     "@nuxt/ui": "4.10.0",

package/frontend-vue/pnpm-lock.yaml

@@ -66,8 +66,8 @@ importers:
         specifier: ^1.5.4
         version: 1.5.4(@vue-flow/core@1.48.2(vue@3.5.25(typescript@5.9.3)))(vue@3.5.25(typescript@5.9.3))
       '@vueuse/core':
-        specifier: ^13.0.0
-        version: 13.9.0(vue@3.5.25(typescript@5.9.3))
+        specifier: ^14.3.0
+        version: 14.4.0(vue@3.5.25(typescript@5.9.3))
       '@vueuse/integrations':
         specifier: ^14.1.0
         version: 14.1.0(focus-trap@7.8.0)(fuse.js@7.5.0)(sortablejs@1.14.0)(vue@3.5.25(typescript@5.9.3))
@@ -124,8 +124,8 @@ importers:
         specifier: '>=1.9.1 <2'
         version: 1.9.1(@types/node@24.8.1)
       '@antelopejs/dms-frontend':
-        specifier: '>=0.2.6 <1.0.0'
-        version: 0.2.6(@antelopejs/core@1.9.1(@types/node@24.8.1))
+        specifier: '>=0.2.8 <1.0.0'
+        version: 0.2.8(@antelopejs/core@1.9.1(@types/node@24.8.1))
       '@eslint/js':
         specifier: ^8.57.0
         version: 8.57.0
@@ -200,8 +200,8 @@ packages:
     resolution: {integrity: sha512-MPLJak0rPluV4lgsdsO5ba03sgTxIGSncajBcoaoppuppQmksdpaemojIHiVLJ4LiG0iiH21Roaed8XXy1XkYQ==}
     hasBin: true
 
-  '@antelopejs/dms-frontend@0.2.6':
-    resolution: {integrity: sha512-dCR9EWkpW4CekV5M87igyCZyRNXt9fVr5M2t9neATj1JqN/r6MltYJd4ShKnilSN4zQZ4ykkuFL/b9b0k79rDw==}
+  '@antelopejs/dms-frontend@0.2.8':
+    resolution: {integrity: sha512-7qrlf2M3J26DZxGZVvM/3qjPDeDfoRMrE7HEPFxWav8Pe1QFct7LtgY7NmKup9XdrRyUw4nqckxvW8UZDSjpeg==}
     engines: {node: '>=20.12.0'}
     hasBin: true
     peerDependencies:
@@ -1753,11 +1753,6 @@ packages:
   '@vueuse/core@12.8.2':
     resolution: {integrity: sha512-HbvCmZdzAu3VGi/pWYm5Ut+Kd9mn1ZHnn4L5G8kOQTPs/IwIAmJoBrmYk2ckLArgMXZj0AW3n5CAejLUO+PhdQ==}
 
-  '@vueuse/core@13.9.0':
-    resolution: {integrity: sha512-ts3regBQyURfCE2BcytLqzm8+MmLlo5Ln/KLoxDVcsZ2gzIwVNnQpQOL/UKV8alUqjSZOlpFZcRNsLRqj+OzyA==}
-    peerDependencies:
-      vue: ^3.5.0
-
   '@vueuse/core@14.1.0':
     resolution: {integrity: sha512-rgBinKs07hAYyPF834mDTigH7BtPqvZ3Pryuzt1SD/lg5wEcWqvwzXXYGEDb2/cP0Sj5zSvHl3WkmMELr5kfWw==}
     peerDependencies:
@@ -1858,9 +1853,6 @@ packages:
   '@vueuse/metadata@12.8.2':
     resolution: {integrity: sha512-rAyLGEuoBJ/Il5AmFHiziCPdQzRt88VxR+Y/A/QhJ1EWtWqPBBAxTAFaSkviwEuOEZNtW8pvkPgoCZQ+HxqW1A==}
 
-  '@vueuse/metadata@13.9.0':
-    resolution: {integrity: sha512-1AFRvuiGphfF7yWixZa0KwjYH8ulyjDCC0aFgrGRz8+P4kvDFSdXLVfTk5xAN9wEuD1J6z4/myMoYbnHoX07zg==}
-
   '@vueuse/metadata@14.1.0':
     resolution: {integrity: sha512-7hK4g015rWn2PhKcZ99NyT+ZD9sbwm7SGvp7k+k+rKGWnLjS/oQozoIZzWfCewSUeBmnJkIb+CNr7Zc/EyRnnA==}
 
@@ -1873,11 +1865,6 @@ packages:
   '@vueuse/shared@12.8.2':
     resolution: {integrity: sha512-dznP38YzxZoNloI0qpEfpkms8knDtaoQ6Y/sfS0L7Yki4zh40LFHEhur0odJC6xTHG5dxWVPiUWBXn+wCG2s5w==}
 
-  '@vueuse/shared@13.9.0':
-    resolution: {integrity: sha512-e89uuTLMh0U5cZ9iDpEI2senqPGfbPRTHM/0AaQkcxnpqjkZqDYP8rpfm7edOz8s+pOCOROEy1PIveSW8+fL5g==}
-    peerDependencies:
-      vue: ^3.5.0
-
   '@vueuse/shared@14.1.0':
     resolution: {integrity: sha512-EcKxtYvn6gx1F8z9J5/rsg3+lTQnvOruQd8fUecW99DCK04BkWD7z5KQ/wTAx+DazyoEE9dJt/zV8OIEQbM6kw==}
     peerDependencies:
@@ -4344,7 +4331,7 @@ snapshots:
     transitivePeerDependencies:
       - '@types/node'
 
-  '@antelopejs/dms-frontend@0.2.6(@antelopejs/core@1.9.1(@types/node@24.8.1))':
+  '@antelopejs/dms-frontend@0.2.8(@antelopejs/core@1.9.1(@types/node@24.8.1))':
     dependencies:
       boxen: 5.1.2
       chalk: 4.1.2
@@ -5944,13 +5931,6 @@ snapshots:
     transitivePeerDependencies:
       - typescript
 
-  '@vueuse/core@13.9.0(vue@3.5.25(typescript@5.9.3))':
-    dependencies:
-      '@types/web-bluetooth': 0.0.21
-      '@vueuse/metadata': 13.9.0
-      '@vueuse/shared': 13.9.0(vue@3.5.25(typescript@5.9.3))
-      vue: 3.5.25(typescript@5.9.3)
-
   '@vueuse/core@14.1.0(vue@3.5.25(typescript@5.9.3))':
     dependencies:
       '@types/web-bluetooth': 0.0.21
@@ -5989,8 +5969,6 @@ snapshots:
 
   '@vueuse/metadata@12.8.2': {}
 
-  '@vueuse/metadata@13.9.0': {}
-
   '@vueuse/metadata@14.1.0': {}
 
   '@vueuse/metadata@14.4.0': {}
@@ -6008,10 +5986,6 @@ snapshots:
     transitivePeerDependencies:
       - typescript
 
-  '@vueuse/shared@13.9.0(vue@3.5.25(typescript@5.9.3))':
-    dependencies:
-      vue: 3.5.25(typescript@5.9.3)
-
   '@vueuse/shared@14.1.0(vue@3.5.25(typescript@5.9.3))':
     dependencies:
       vue: 3.5.25(typescript@5.9.3)

package/frontend-vue/tests/chart-absent-value.test.ts

@@ -0,0 +1,78 @@
+import { createSSRApp, defineComponent, h, ref } from "vue";
+import { renderToString } from "vue/server-renderer";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import ChartCard from "../layers/dms-ui/app/components/chart/ChartCard.vue";
+import KpiCard from "../layers/dms-ui/app/components/kpi/KpiCard.vue";
+import { ABSENT_VALUE_TEXT } from "../layers/dms-ui/app/composables/chart/formatValue";
+
+// A period the query measured nothing in: the response carries its series and no
+// figure at all, which is what the contract answers rather than a zero.
+vi.mock("../layers/dms-ui/app/composables/chart/useChartFetch", () => ({
+  useChartFetch: () => ({
+    data: ref({ series: [{ name: "Revenue", data: [] }] }),
+    isLoading: ref(false),
+  }),
+}));
+
+const Slot = defineComponent({
+  setup:
+    (_, { slots }) =>
+    () =>
+      h("div", slots.default?.()),
+});
+
+const SLOT_COMPONENTS = [
+  "DmsCard",
+  "DmsClientOnly",
+  "UIcon",
+  "USkeleton",
+  "DmsTrendBadge",
+  "DmsSparkline",
+  "UBadge",
+];
+
+function stubNuxt() {
+  vi.stubGlobal("useI18n", () => ({
+    locale: ref("en-US"),
+    t: (key: string) => key,
+  }));
+  vi.stubGlobal("useTranslation", () => ({
+    processI18n: (text: string) => text,
+  }));
+  vi.stubGlobal("useComponentEvent", () => ({}));
+  vi.stubGlobal("useWatch", () => ({ state: ref({}) }));
+}
+
+type CardProps = InstanceType<typeof ChartCard>["$props"];
+
+async function renderCards() {
+  stubNuxt();
+  const props: CardProps = {
+    title: "Revenue",
+    componentId: "card",
+    pageId: "absent",
+    valueFormat: "currency",
+  };
+  const app = createSSRApp({
+    render: () => h("main", [h(ChartCard, props), h(KpiCard, props)]),
+  });
+  for (const name of SLOT_COMPONENTS) app.component(name, Slot);
+  return renderToString(app);
+}
+
+afterEach(() => vi.unstubAllGlobals());
+
+describe("a card whose query measured nothing", () => {
+  it("shows an absence where the figure goes, on both cards", async () => {
+    const html = await renderCards();
+    expect(html.split(ABSENT_VALUE_TEXT)).toHaveLength(3);
+  });
+
+  it("prints no zero, and no unit for a quantity there is none of", async () => {
+    const html = await renderCards();
+    expect(html, "a zero reads exactly like a measured figure").not.toContain(
+      "<span>0</span>",
+    );
+    expect(html).not.toContain("€");
+  });
+});

package/frontend-vue/tests/color-mode-server-render.test.ts

@@ -0,0 +1,84 @@
+/**
+ * The color-mode plugin as the server runs it: the `<html>` tag of the rendered
+ * document already carries an explicit preference, so the first paint is right
+ * without waiting for JavaScript, and `system` is left to the pre-paint script.
+ */
+import { useHead } from "@unhead/vue";
+import { createHead, renderSSRHead } from "@unhead/vue/server";
+import { createSSRApp, ref } from "vue";
+import { beforeEach, expect, it, vi } from "vitest";
+
+interface CookieOptions {
+  default: () => unknown;
+  maxAge?: number;
+}
+
+const COLOR_MODE_COOKIE = "dms-color-mode";
+const ONE_YEAR_IN_SECONDS = 60 * 60 * 24 * 365;
+const requestCookies = new Map<string, unknown>();
+const cookieReads = vi.fn();
+
+vi.stubGlobal("defineDmsPlugin", (setup: unknown) => setup);
+vi.stubGlobal("useHead", useHead);
+vi.stubGlobal("useDmsCookie", (name: string, options: CookieOptions) => {
+  cookieReads(name, options);
+  return ref(
+    requestCookies.has(name) ? requestCookies.get(name) : options.default(),
+  );
+});
+
+const { default: colorModePlugin } = await import(
+  "../layers/dms-layout/app/plugins/color-mode"
+);
+
+async function renderHead(preference?: string) {
+  if (preference !== undefined)
+    requestCookies.set(COLOR_MODE_COOKIE, preference);
+  const app = createSSRApp({ render: () => null });
+  const head = createHead();
+  app.use(head);
+  await app.runWithContext(() => colorModePlugin({} as never));
+  return renderSSRHead(head);
+}
+
+beforeEach(() => {
+  requestCookies.clear();
+  cookieReads.mockClear();
+});
+
+it.each(["light", "dark"])(
+  "renders the %s class on <html> for an explicit preference",
+  async (preference) => {
+    const { htmlAttrs } = await renderHead(preference);
+
+    expect(htmlAttrs).toContain(` class="${preference}"`);
+  },
+);
+
+it.each([undefined, "system", "sepia"])(
+  "leaves the class to the browser for a %s preference",
+  async (preference) => {
+    const { htmlAttrs } = await renderHead(preference);
+
+    expect(htmlAttrs).not.toContain("class");
+  },
+);
+
+it("reads the dms-color-mode cookie, kept a year and defaulting to system", async () => {
+  await renderHead();
+
+  expect(cookieReads).toHaveBeenCalledOnce();
+  const [name, options] = cookieReads.mock.calls[0] as [string, CookieOptions];
+  expect(name).toBe(COLOR_MODE_COOKIE);
+  expect(options.maxAge).toBe(ONE_YEAR_IN_SECONDS);
+  expect(options.default()).toBe("system");
+});
+
+it("ships the pre-paint script as a classic inline script in <head>", async () => {
+  // No src, type, defer or async: the browser runs it while it parses <head>,
+  // before the deferred entry module that installs Nuxt UI.
+  const { headTags, bodyTags, bodyTagsOpen } = await renderHead("dark");
+
+  expect(headTags).toMatch(/<script id="dms-color-mode">\(\(\) => \{/);
+  expect(bodyTags + bodyTagsOpen).toBe("");
+});