@7365admin1/layer-common 3.2.2-staging.80 → 3.2.2-staging.81

package/package.json

@@ -2,7 +2,7 @@
   "name": "@7365admin1/layer-common",
   "license": "MIT",
   "type": "module",
-  "version": "3.2.2-staging.80",
+  "version": "3.2.2-staging.81",
   "author": "7365admin1",
   "main": "./nuxt.config.ts",
   "publishConfig": {
@@ -14,7 +14,8 @@
     "build": "nuxt build .playground",
     "generate": "nuxt generate .playground",
     "preview": "nuxt preview .playground",
-    "test": "esbuild composables/useVisitorSocket.ts --format=esm --outfile=test/.build/useVisitorSocket.mjs --log-level=error && node --test \"test/*.test.mjs\"",
+    "test": "esbuild composables/useVisitorSocket.ts --format=esm --outfile=test/.build/useVisitorSocket.mjs --log-level=error && node --test \"test/*.test.mjs\" && yarn test:units",
+    "test:units": "node --experimental-strip-types --test \"utils/*.test.ts\"",
     "release": "yarn run build && changeset publish"
   },
   "devDependencies": {

package/plugins/vuetify.ts

@@ -43,8 +43,37 @@ import {
 import "vuetify-pro-tiptap/style.css";
 
 import { LIGHT_THEME, DARK_THEME } from "../utils/theme";
+import { THEME_COOKIE } from "../composables/useThemePreference";
+import type { CookieOptions } from "#app";
+
+/**
+ * The design tokens. Loaded HERE rather than in `nuxt.config.ts` so they land
+ * after `vuetify/styles` in the bundle - `tokens.css` aliases `--v-theme-*`,
+ * which Vuetify has to have emitted first.
+ */
+import "../assets/css/tokens.css";
+import "../assets/css/shell.css";
 
 export default defineNuxtPlugin((app) => {
+  /**
+   * BOOT ON THE REMEMBERED THEME, DON'T CORRECT IT AFTERWARDS.
+   *
+   * Reading the cookie here, before `createVuetify`, is what makes the choice
+   * survive a reload with no flash: Vuetify's first paint is already the right
+   * theme, so there is no moment where the wrong one is on screen. Setting it
+   * from a component's `onMounted` would repaint the whole application one
+   * frame in, which is the flash this is written to avoid.
+   *
+   * `useThemePreference()` writes this cookie; nothing else does.
+   */
+  const stored = useCookie<string | null>(
+    THEME_COOKIE,
+    // typed `unknown` in runtimeConfig; same object `sid` and `user` use
+    useRuntimeConfig().public.cookieConfig as CookieOptions<string | null> & {
+      readonly?: false;
+    }
+  ).value;
+
   const vuetify = createVuetify({
     defaults: {
       VTextField: {
@@ -97,7 +126,7 @@ export default defineNuxtPlugin((app) => {
      * `utils/theme.ts`, which `utils/theme.test.ts` measures on every run.
      */
     theme: {
-      defaultTheme: "light",
+      defaultTheme: stored === "dark" ? "dark" : "light",
       themes: {
         light: LIGHT_THEME,
         dark: DARK_THEME,

package/utils/status.test.ts

@@ -0,0 +1,41 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { statusTone, statusToneClass } from "./status.ts";
+
+test("the handoff's mapping, word for word", () => {
+  for (const s of ["Completed", "Paid", "Available", "Open"]) {
+    assert.equal(statusTone(s), "ok", s);
+  }
+
+  assert.equal(statusTone("Pending"), "warn");
+
+  for (const s of ["In Use", "Closed", "Checkout"]) {
+    assert.equal(statusTone(s), "err", s);
+  }
+
+  assert.equal(statusTone("Role"), "info");
+});
+
+/** The same status arrives spelled three ways from three endpoints. */
+test("casing, spacing and underscores do not change a status's colour", () => {
+  for (const s of ["in use", "IN USE", "In_Use", "in-use", "  In Use  "]) {
+    assert.equal(statusTone(s), "err", s);
+  }
+});
+
+/**
+ * The important one. A status the design never named must NOT be guessed into
+ * a colour - a wrong green on a failed job reads as success. Neutral is
+ * visible, honest, and gets it noticed.
+ */
+test("an unmapped status comes out neutral rather than guessed", () => {
+  for (const s of ["Cancelled", "Overdue", "Draft", "", null, undefined]) {
+    assert.equal(statusTone(s), "neutral", String(s));
+  }
+});
+
+test("the class name matches what tokens.css actually defines", () => {
+  assert.equal(statusToneClass("Paid"), "tone-ok");
+  assert.equal(statusToneClass("Whatever"), "tone-neutral");
+});

package/utils/status.ts

@@ -0,0 +1,54 @@
+/**
+ * THE SEMANTIC STATUS MAPPING, IN ONE PLACE.
+ *
+ * The design assigns a colour to a status WORD rather than to a module, so the
+ * same word has to look the same wherever it appears - "Open" on a Daily
+ * Occurrence Book and "Open" on a work order are the same green. Keeping the
+ * list here rather than in each screen is what makes that true, and is what
+ * Phases 3 and 4 read when they restyle the chips.
+ *
+ * Straight from the handoff:
+ *   Completed / Paid / Available / Open -> ok
+ *   Pending                             -> warn
+ *   In Use / Closed / Checkout          -> err
+ *   Role and info tags                  -> info
+ *
+ * Anything not listed is `neutral` on purpose. A status this product has and
+ * the design did not name must NOT be guessed into a colour - a wrong green on
+ * a failed job is worse than a grey one - so it comes out neutral and visible,
+ * which is how it gets noticed and added.
+ */
+export type TStatusTone = "ok" | "warn" | "err" | "info" | "neutral";
+
+const TONES: Record<string, TStatusTone> = {
+  completed: "ok",
+  paid: "ok",
+  available: "ok",
+  open: "ok",
+
+  pending: "warn",
+
+  "in use": "err",
+  closed: "err",
+  checkout: "err",
+
+  role: "info",
+  info: "info",
+};
+
+/**
+ * The tone for a status word. Case- and space-insensitive, because the same
+ * status arrives as "In Use", "in_use" and "IN USE" from different endpoints.
+ */
+export function statusTone(status: string | null | undefined): TStatusTone {
+  if (!status) return "neutral";
+
+  const key = String(status).trim().toLowerCase().replace(/[_-]+/g, " ");
+
+  return TONES[key] ?? "neutral";
+}
+
+/** The class `assets/css/tokens.css` paints that tone with. */
+export function statusToneClass(status: string | null | undefined): string {
+  return `tone-${statusTone(status)}`;
+}

package/utils/theme.test.ts

@@ -1,7 +1,7 @@
 import assert from "node:assert/strict";
 import { test } from "node:test";
 
-import { DARK_THEME, LIGHT_THEME } from "./theme.ts";
+import { DARK_THEME, LIGHT_THEME, PALETTE, type TPalette } from "./theme.ts";
 
 /**
  * The dark theme was shipped once with `primary` chosen for the one place it
@@ -199,18 +199,336 @@ test("a filled primary surface carries a readable label in both themes", () => {
  * Both themes correct the same two Vuetify defaults, and a value that drifts
  * apart between them is a bug nobody sees until they flip the switch.
  */
-test("disabled text clears 4.5:1 on the surface each theme puts it on", () => {
-  assert.equal(LIGHT_THEME.variables["disabled-opacity"], 0.55);
-  assert.equal(DARK_THEME.variables["disabled-opacity"], 0.55);
-  assert.ok(contrast(over("#000000", WHITE, 0.55), WHITE) >= 4.5);
+/**
+ * Both opacities are applied to `on-surface`, which is now the design's ink
+ * rather than pure black - so an opacity that was right for black is not right
+ * for this. These hold the corrected values in place, measured against the ink
+ * they are actually applied to.
+ */
+test("disabled text is no paler than it was before the palette changed", () => {
+  assert.equal(LIGHT_THEME.variables["disabled-opacity"], 0.62);
+  assert.equal(DARK_THEME.variables["disabled-opacity"], 0.62);
+
+  // The bar is the previous rendering, not 4.5: Vuetify multiplies its own
+  // field alpha on top of this, which is Phase 3's problem to unpick.
+  const wasLight = contrast(over("#000000", WHITE, 0.55), WHITE);
+  const nowLight = contrast(over(PALETTE.light.text, WHITE, 0.62), WHITE);
   assert.ok(
-    contrast(over(WHITE, dark.background, 0.55), dark.background) >= 4.5
+    nowLight >= wasLight,
+    `disabled light went backwards: ${wasLight.toFixed(2)} -> ${nowLight.toFixed(2)}`
   );
+
+  const nowDark = contrast(
+    over(PALETTE.dark.text, PALETTE.dark.card, 0.62),
+    PALETTE.dark.card
+  );
+  assert.ok(nowDark >= 4.5, `disabled dark: ${nowDark.toFixed(2)}`);
+});
+
+/**
+ * THE REGRESSION THIS CAUGHT. `text-medium-emphasis` is `on-surface` at this
+ * opacity, and it is roughly two hundred lines of secondary text across eleven
+ * applications. At Vuetify's 0.6 the new ink lands at 4.41:1 on the page.
+ */
+test("medium-emphasis text clears AA on every surface, in both themes", () => {
+  for (const [name, p] of [
+    ["light", PALETTE.light],
+    ["dark", PALETTE.dark],
+  ] as const) {
+    const alpha = (name === "light" ? LIGHT_THEME : DARK_THEME).variables[
+      "medium-emphasis-opacity"
+    ];
+
+    for (const bg of [p.card, p.bg, p.sidebar]) {
+      const ratio = contrast(over(p.text, bg, alpha), bg);
+      assert.ok(
+        ratio >= 4.5,
+        `${name} medium emphasis on ${bg}: ${ratio.toFixed(2)} at alpha ${alpha}`
+      );
+    }
+  }
 });
 
 test("the dark divider clears the 3:1 a boundary wants", () => {
-  const border = "#62666a"; // white at 0.35 over the dark page
+  // Derived, not hardcoded: this used to be a literal "#62666a" with a comment
+  // saying it was white at 0.35 over the dark page, and it stopped being that
+  // the moment the page colour moved.
+  const border = over(WHITE, dark.background, 0.35);
 
   assert.equal(DARK_THEME.variables["border-opacity"], 0.35);
   assert.ok(contrast(border, dark.background) >= 3);
 });
+
+/* ==================================================================== */
+/* THE REDESIGN PALETTE.                                                */
+/*                                                                      */
+/* Measured against the design as handed over, the light theme failed   */
+/* AA on 27 text pairs and the dark theme on 6. The owner's instruction */
+/* was "minimal darkening, keep the look", so what these tests hold in  */
+/* place is BOTH halves of that: every pair a person reads clears AA,   */
+/* AND the values that were not the problem are still exactly the ones  */
+/* the design specifies. A later phase that "tidies" a colour back to   */
+/* its handoff value, or drifts one away from it, fails here.           */
+/* ==================================================================== */
+
+const L = PALETTE.light;
+const D = PALETTE.dark;
+
+/** The soft chip backgrounds, as the design states them - literally. */
+const SOFT = {
+  light: {
+    ok: ["#0f8a62", 0.1],
+    warn: ["#be8c19", 0.13],
+    err: ["#cf4b4b", 0.1],
+    info: ["#3b6fd4", 0.1],
+  },
+  dark: {
+    ok: ["#41c795", 0.12],
+    warn: ["#dcaf4e", 0.13],
+    err: ["#e57373", 0.12],
+    info: ["#7da6ec", 0.12],
+  },
+} as const;
+
+/** `--thead` is a 2% ink wash over the card, not a colour of its own. */
+const thead = (p: TPalette) =>
+  over(p === L ? "#14161a" : WHITE, p.card, 0.02);
+
+const soft = (p: TPalette, key: "ok" | "warn" | "err" | "info", on: string) => {
+  const [hex, alpha] = SOFT[p === L ? "light" : "dark"][key];
+  return over(hex, on, alpha);
+};
+
+const accentSoft = (p: TPalette, on: string) => over(p.accent, on, 0.12);
+
+for (const [name, p] of [
+  ["light", L],
+  ["dark", D],
+] as const) {
+  /**
+   * `--muted` is the table header of every table in the product, the
+   * breadcrumb, and every KPI sub-line. It failed on all four of its surfaces
+   * in the light theme at 2.99-3.24:1, which is the single most-read text in
+   * the design.
+   */
+  test(`${name}: muted text is readable on every surface it is used on`, () => {
+    for (const [where, bg] of [
+      ["a card", p.card],
+      ["the page", p.bg],
+      ["a table header", thead(p)],
+      ["the sidebar", p.sidebar],
+    ] as const) {
+      assert.ok(
+        contrast(p.muted, bg) >= 4.5,
+        `${name} muted on ${where}: ${contrast(p.muted, bg).toFixed(2)}`
+      );
+    }
+  });
+
+  test(`${name}: primary and secondary text clear AA on every surface`, () => {
+    for (const fg of [p.text, p.text2]) {
+      for (const bg of [p.card, p.bg, p.sidebar]) {
+        assert.ok(
+          contrast(fg, bg) >= 4.5,
+          `${name} ${fg} on ${bg}: ${contrast(fg, bg).toFixed(2)}`
+        );
+      }
+    }
+  });
+
+  /**
+   * A status chip is its own soft background, so the label is NOT read on the
+   * card - measuring it against white flatters it by about half a point.
+   */
+  test(`${name}: every status chip's label is readable on its own chip`, () => {
+    for (const [key, fg] of [
+      ["ok", p.ok],
+      ["warn", p.warn],
+      ["err", p.err],
+      ["info", p.info],
+    ] as const) {
+      const bg = soft(p, key, p.card);
+      assert.ok(
+        contrast(fg, bg) >= 4.5,
+        `${name} ${key} chip: ${contrast(fg, bg).toFixed(2)}`
+      );
+    }
+  });
+
+  /** The same four also appear as bare text: status dots, chart labels, the
+   *  red Logout row in the profile dropdown. */
+  test(`${name}: the status colours are readable as plain text on a card`, () => {
+    for (const fg of [p.ok, p.warn, p.err, p.info]) {
+      assert.ok(
+        contrast(fg, p.card) >= 4.5,
+        `${name} ${fg} on a card: ${contrast(fg, p.card).toFixed(2)}`
+      );
+    }
+  });
+
+  /**
+   * The active sidebar item is `--accent-text` on `--accent-soft`, and
+   * `--accent-soft` is transparent - so it takes the colour of whatever is
+   * behind it. Behind it is the SIDEBAR, which is not the card. Solving this
+   * against the card gives 4.50:1 and ships a 4.35:1 sidebar.
+   */
+  test(`${name}: accent text is readable on accent-soft over BOTH surfaces`, () => {
+    for (const [where, under] of [
+      ["the sidebar", p.sidebar],
+      ["a card", p.card],
+    ] as const) {
+      const bg = accentSoft(p, under);
+      assert.ok(
+        contrast(p.accentText, bg) >= 4.5,
+        `${name} accent-text on accent-soft over ${where}: ${contrast(
+          p.accentText,
+          bg
+        ).toFixed(2)}`
+      );
+    }
+
+    assert.ok(contrast(p.accentText, p.card) >= 4.5, "as a plain link");
+  });
+
+  /**
+   * THE REASON `--accent-strong` EXISTS. If someone deletes it and points the
+   * primary button back at `--accent`, the second assertion is what fails, and
+   * the message says why rather than just reporting a number.
+   */
+  test(`${name}: a white label sits on accent-strong, never on accent`, () => {
+    assert.ok(
+      contrast(WHITE, p.accentStrong) >= 4.5,
+      `white on accent-strong: ${contrast(WHITE, p.accentStrong).toFixed(2)}`
+    );
+    assert.ok(
+      contrast(WHITE, p.accent) < 4.5,
+      "white on --accent passes now? then --accent-strong is redundant - " +
+        "re-measure before deleting it"
+    );
+    // The fill still has to be findable against the card it sits on.
+    assert.ok(
+      contrast(p.accentStrong, p.card) >= 3,
+      `accent-strong against a card: ${contrast(p.accentStrong, p.card).toFixed(2)}`
+    );
+  });
+
+  /** Non-text uses of the accent only owe 3:1, and they keep the design value. */
+  test(`${name}: the accent clears 3:1 where it is a line rather than a word`, () => {
+    assert.ok(contrast(p.accent, p.card) >= 3, "chart line / tab underline");
+    assert.ok(contrast(WHITE, p.accent) >= 3, "the toggle knob on its on state");
+  });
+
+  /**
+   * Vuetify DERIVES the label on a filled colour and its derivation picks
+   * white, which on the dark palette is 2.04:1 to 2.99:1. Every one is set
+   * explicitly in `theme.ts`; this is what proves they were all set.
+   */
+  test(`${name}: every filled semantic colour carries a readable label`, () => {
+    const t = p === L ? LIGHT_THEME : DARK_THEME;
+
+    for (const key of ["primary", "success", "warning", "error", "info"]) {
+      const on = (t.colors as Record<string, string>)[`on-${key}`];
+      const fill = (t.colors as Record<string, string>)[key];
+
+      assert.ok(on, `on-${key} is not set - Vuetify would guess, and it guesses white`);
+      assert.ok(
+        contrast(on, fill) >= 4.5,
+        `${name} on-${key}: ${contrast(on, fill).toFixed(2)}`
+      );
+    }
+
+    assert.ok(
+      contrast(t.colors["on-primary-button"], t.colors["primary-button"]) >= 4.5
+    );
+  });
+}
+
+/**
+ * "KEEP THE LOOK" IS HALF THE INSTRUCTION, AND IT IS THE HALF A CONTRAST TEST
+ * CANNOT CATCH ON ITS OWN - darkening everything until it passes would satisfy
+ * every test above and would not be the design. These are the values that were
+ * NOT the problem, pinned to what the handoff says.
+ */
+test("the design's own values are unchanged wherever they already passed", () => {
+  assert.equal(L.accent, "#5b8def", "the brand accent is the design's, exactly");
+  assert.equal(D.accent, "#5b8def");
+
+  assert.equal(L.bg, "#f6f6f2");
+  assert.equal(L.sidebar, "#fbfbf8");
+  assert.equal(L.card, "#ffffff");
+  assert.equal(L.border, "#e8e8e1");
+  assert.equal(L.text, "#191b1f");
+  assert.equal(L.text2, "#41454d");
+
+  // The dark theme passed AA as designed and therefore moves nowhere at all.
+  assert.deepEqual(
+    [D.bg, D.sidebar, D.card, D.border, D.text, D.text2, D.muted],
+    ["#131418", "#17181d", "#1c1e24", "#2a2d35", "#eef0f3", "#c6cad2", "#868c98"],
+    "the dark palette needed no darkening - it should still be the handoff's"
+  );
+  assert.deepEqual(
+    [D.ok, D.warn, D.err, D.info, D.accentText],
+    ["#41c795", "#dcaf4e", "#e57373", "#7da6ec", "#78a2f4"]
+  );
+});
+
+/**
+ * Minimal darkening means MINIMAL. Each light value that moved is checked to
+ * still be recognisably the colour it was - if a later pass "fixes" contrast
+ * by reaching for a different green, this is what objects.
+ */
+test("the light values that moved are still the same colours", () => {
+  const moved: Array<[string, string, string]> = [
+    ["muted", "#8b8f98", L.muted],
+    ["ok", "#0f8a62", L.ok],
+    ["warn", "#a97a14", L.warn],
+    ["err", "#cf4b4b", L.err],
+    ["info", "#3b6fd4", L.info],
+    ["accent-strong vs accent", "#5b8def", L.accentStrong],
+  ];
+
+  for (const [name, before, after] of moved) {
+    const shift = contrast(before, after);
+    assert.ok(
+      shift < 1.9,
+      `${name} moved from ${before} to ${after}, a ${shift.toFixed(
+        2
+      )}:1 jump - that is a different colour, not a darkened one`
+    );
+    assert.ok(shift > 1, `${name} did not move at all`);
+  }
+});
+
+/**
+ * THE BRIDGE. Every design token in `assets/css/tokens.css` is an alias onto a
+ * `--v-theme-*`, so a token whose Vuetify colour does not exist resolves to
+ * nothing and paints transparent - silently, in eleven applications. This is
+ * the list that CSS file reads.
+ */
+test("every design token has a Vuetify colour behind it, in both themes", () => {
+  const required = [
+    "background", "surface", "sidebar", "border",
+    "text-primary", "text2", "muted",
+    "success", "warning", "error", "info",
+    "accent", "accent-strong", "accent-text",
+    "primary", "primary-button", "brand-surface",
+  ];
+
+  for (const [name, t] of [["light", LIGHT_THEME], ["dark", DARK_THEME]] as const) {
+    for (const key of required) {
+      const value = (t.colors as Record<string, string>)[key];
+      assert.match(
+        value ?? "",
+        /^#[0-9a-f]{6}$/i,
+        `${name} is missing a usable colour for "${key}" - tokens.css aliases it`
+      );
+    }
+  }
+
+  assert.deepEqual(
+    Object.keys(LIGHT_THEME.colors),
+    Object.keys(DARK_THEME.colors),
+    "a colour wired into one theme and forgotten in the other is how this " +
+      "file broke before"
+  );
+});