@7365admin1/layer-common 3.2.2-staging.183 → 3.2.2-staging.189

package/components/Layout/Header.vue

@@ -89,6 +89,8 @@
 </template>
 
 <script setup lang="ts">
+import { moduleNameFromRoute } from "../../utils/breadcrumb";
+
 const props = defineProps({
   hideNavIcon: {
     type: Boolean,
@@ -142,39 +144,12 @@ const siteName = computed(() =>
 const route = useRoute();
 
 /**
- * The module's name comes off the route name, which the applications build
- * from their own folder structure: `org-site-work-orders` is Work Orders.
- * Leading parameter segments (`org`, `site`) are skipped and the name stops at
- * the first one that follows, so a detail route (`...-feedbacks-id`) and a
- * status route (`...-members-status`) both name their module rather than their
- * argument.
+ * The page's name comes off the route name, which the applications build from
+ * their own folder structure: `org-site-work-orders` is Work Orders. The rule
+ * itself lives in `utils/breadcrumb.ts`, where it is unit-tested against every
+ * route shape the eleven applications actually have.
  */
-const ACRONYMS: Record<string, string> = {
-  cctv: "CCTV",
-  hid: "HID",
-  dob: "DOB",
-  anpr: "ANPR",
-  nfc: "NFC",
-  qr: "QR",
-  soa: "SOA",
-  sp: "SP",
-  id: "ID",
-};
-
-const moduleName = computed(() => {
-  const segments = String(route.name ?? "").split("-").filter(Boolean);
-  const params = new Set(Object.keys(route.params ?? {}));
-
-  let i = 0;
-  while (i < segments.length && params.has(segments[i])) i++;
-
-  const words: string[] = [];
-  while (i < segments.length && !params.has(segments[i])) words.push(segments[i++]);
-
-  return words
-    .map((w) => ACRONYMS[w] ?? w.charAt(0).toUpperCase() + w.slice(1))
-    .join(" ");
-});
+const moduleName = computed(() => moduleNameFromRoute(route));
 
 const profile = computed(() => {
   return `/api/public/${currentUser.value?.profile}`;

package/components/SwitchContext.vue

@@ -35,7 +35,9 @@
       </span>
       <v-text-field
         v-model="search"
-        @keydown.enter="emit('search')"
+        @keydown.enter="triggerSearch"
+        clearable
+        @click:clear="clearSearch"
         density="compact"
         width="100%"
         hide-details
@@ -178,6 +180,33 @@ watchEffect(() => {
   }
 });
 
+let searchDebounce: ReturnType<typeof setTimeout> | null = null;
+let skipNextWatch = false;
+
+const triggerSearch = () => {
+  if (searchDebounce) clearTimeout(searchDebounce);
+  emit("search");
+};
+
+const clearSearch = () => {
+  skipNextWatch = true;
+  search.value = "";
+  triggerSearch();
+};
+
+watch(search, () => {
+  if (skipNextWatch) {
+    skipNextWatch = false;
+    return;
+  }
+  if (searchDebounce) clearTimeout(searchDebounce);
+  searchDebounce = setTimeout(triggerSearch, 1000);
+});
+
+onBeforeUnmount(() => {
+  if (searchDebounce) clearTimeout(searchDebounce);
+});
+
 const selectItem = (value: string) => {
   selected.value = value;
   menu.value = false;

package/package.json

@@ -2,7 +2,7 @@
   "name": "@7365admin1/layer-common",
   "license": "MIT",
   "type": "module",
-  "version": "3.2.2-staging.183",
+  "version": "3.2.2-staging.189",
   "author": "7365admin1",
   "main": "./nuxt.config.ts",
   "//files": "What a consumer extending this layer actually loads. Without this npm ships the whole working tree - the changesets, the CI workflows, the render harness in tools/ and any scratch directory that happened to exist at publish time. Nuxt resolves a layer by directory, so every runtime directory below has to stay listed; adding a new top-level runtime directory means adding it here too.",

package/utils/breadcrumb.test.ts

@@ -0,0 +1,108 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { moduleNameFromRoute } from "./breadcrumb.ts";
+
+/**
+ * Real routes, not invented ones: name, path and parameters exactly as
+ * vue-router hands them to the bar in each application.
+ */
+const ID = "68b0c1d2e3f4a5b6c7d8e9f0";
+
+test("a site application names the page, not its parameters", () => {
+  assert.equal(
+    moduleNameFromRoute({
+      name: "org-site-work-orders",
+      path: `/${ID}/${ID}/work-orders`,
+      params: { org: ID, site: ID },
+    }),
+    "Work Orders"
+  );
+});
+
+test("a detail route names its module, not its argument", () => {
+  assert.equal(
+    moduleNameFromRoute({
+      name: "org-site-feedbacks-id",
+      path: `/${ID}/${ID}/feedbacks/${ID}`,
+      params: { org: ID, site: ID, id: ID },
+    }),
+    "Feedbacks"
+  );
+  assert.equal(
+    moduleNameFromRoute({
+      name: "org-site-members-status",
+      path: `/${ID}/${ID}/members/pending`,
+      params: { org: ID, site: ID, status: "pending" },
+    }),
+    "Members"
+  );
+});
+
+test("a fixed folder in front of the context parameter is not the page", () => {
+  // THE DEFECT: every screen of the organization application read "Org".
+  assert.equal(
+    moduleNameFromRoute({
+      name: "org-organization-marketplace",
+      path: `/org/${ID}/marketplace`,
+      params: { organization: ID },
+    }),
+    "Marketplace"
+  );
+  assert.equal(
+    moduleNameFromRoute({
+      name: "org-organization-payment-methods-linked",
+      path: `/org/${ID}/payment-methods/linked`,
+      params: { organization: ID },
+    }),
+    "Payment Methods Linked"
+  );
+});
+
+test("a literal second segment is NOT a skipped context", () => {
+  // `/organizations/status/:status` also begins with a literal folder, but
+  // "Organizations" is the page here - only the THIRD segment is a parameter.
+  assert.equal(
+    moduleNameFromRoute({
+      name: "organizations-status-status",
+      path: "/organizations/status/pending",
+      params: { status: "pending" },
+    }),
+    "Organizations"
+  );
+});
+
+test("a route with no parameters is left alone", () => {
+  assert.equal(
+    moduleNameFromRoute({
+      name: "super-admin-client-list",
+      path: "/super-admin/client-list",
+      params: {},
+    }),
+    "Super Admin Client List"
+  );
+  assert.equal(
+    moduleNameFromRoute({ name: "personal-info-name", path: "/personal-info/name", params: {} }),
+    "Personal Info Name"
+  );
+});
+
+test("acronyms keep their case", () => {
+  assert.equal(
+    moduleNameFromRoute({
+      name: "org-site-virtual-patrol-cctv",
+      path: `/${ID}/${ID}/virtual-patrol/cctv`,
+      params: { org: ID, site: ID },
+    }),
+    "Virtual Patrol CCTV"
+  );
+});
+
+test("a context-only route has no page half", () => {
+  // The organization dashboard: the bar shows the organization's name alone.
+  assert.equal(
+    moduleNameFromRoute({ name: "org-organization", path: `/org/${ID}`, params: { organization: ID } }),
+    ""
+  );
+  assert.equal(moduleNameFromRoute({ name: "", path: "/", params: {} }), "");
+});

package/utils/breadcrumb.ts

@@ -0,0 +1,82 @@
+/**
+ * THE TOP BAR'S BREADCRUMB, PAGE HALF.
+ *
+ * The bar draws `Context / Page`. The page half is derived from the route the
+ * router is already on - nothing is fetched and nothing is configured per app,
+ * because the applications build their route names from their own folder
+ * structure: `org-site-work-orders` is Work Orders.
+ *
+ * Lives here rather than in the component so the rule is testable: it is the
+ * one piece of the bar with real branching, and it named a whole application's
+ * screens wrongly for want of a case.
+ */
+const ACRONYMS: Record<string, string> = {
+  cctv: "CCTV",
+  hid: "HID",
+  dob: "DOB",
+  anpr: "ANPR",
+  nfc: "NFC",
+  qr: "QR",
+  soa: "SOA",
+  sp: "SP",
+  id: "ID",
+};
+
+export function moduleNameFromRoute(route: {
+  name?: unknown;
+  path?: unknown;
+  params?: Record<string, unknown> | null;
+}): string {
+  const segments = String(route.name ?? "").split("-").filter(Boolean);
+  const params = new Set(Object.keys(route.params ?? {}));
+
+  let i = 0;
+
+  /**
+   * A FIXED FOLDER IN FRONT OF THE CONTEXT PARAMETER IS NOT THE PAGE.
+   *
+   * The site applications are `/:org/:site/...`, so skipping the leading
+   * parameters was enough. The organization application is
+   * `/org/:organization/...` - a literal folder first - and the route NAME
+   * cannot tell that "org" is a folder and not a parameter, so every one of
+   * that application's screens named itself "Org" instead of the page it is.
+   *
+   * The PATH can tell: its first segment is that same word, and the segment
+   * after it is a parameter's VALUE. Checked against the path rather than
+   * assumed, because `/organizations/status/:status` also begins with a
+   * literal - and there "Organizations Status" is the right page name, its
+   * second path segment being the folder `status` and not the parameter's
+   * value.
+   */
+  const values = new Set(
+    Object.values(route.params ?? {})
+      .flat()
+      .map((v) => String(v))
+      .filter(Boolean)
+  );
+  const pathParts = String(route.path ?? "").split("/").filter(Boolean);
+
+  if (
+    segments.length > 1 &&
+    !params.has(segments[0]) &&
+    pathParts[0] === segments[0] &&
+    values.has(String(pathParts[1] ?? ""))
+  ) {
+    i++;
+  }
+
+  /**
+   * Leading parameter segments (`org`, `site`) are skipped and the name stops
+   * at the first one that follows, so a detail route (`...-feedbacks-id`) and
+   * a status route (`...-members-status`) both name their module rather than
+   * their argument.
+   */
+  while (i < segments.length && params.has(segments[i])) i++;
+
+  const words: string[] = [];
+  while (i < segments.length && !params.has(segments[i])) words.push(segments[i++]);
+
+  return words
+    .map((w) => ACRONYMS[w] ?? w.charAt(0).toUpperCase() + w.slice(1))
+    .join(" ");
+}

package/utils/dashboard.test.ts

@@ -0,0 +1,118 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { buildWorkOrderStatus } from "./dashboard.ts";
+
+/**
+ * THE DEFECT THIS FILE EXISTS FOR.
+ *
+ * The Property Management "Work Order Status" panel read
+ * `workOrderStatusSummary` - a key no endpoint returns - and fell through to
+ * the `openWorkOrder` KPI metric, which carries no `completed` field. So
+ * Completed read 0 on every site on every day, and Pending was silently
+ * recomputed as (open work orders - in progress) instead of read.
+ *
+ * The shape below is the one `new-dashboard.repo.ts` actually sends.
+ */
+test("the server's breakdown is read, not recomputed", () => {
+  const rows = buildWorkOrderStatus({
+    pending: 20,
+    inProgress: 12,
+    completed: 55,
+  });
+
+  assert.deepEqual(
+    rows.map((r) => [r.label, r.value]),
+    [
+      ["Completed", 55],
+      ["In Progress", 12],
+      ["Pending", 20],
+    ]
+  );
+});
+
+/**
+ * The exact regression. Before the fix this same input drew
+ * Completed 0 / In Progress 12 / Pending 28.
+ */
+test("Completed is never zero when the server says it is not", () => {
+  const completed = buildWorkOrderStatus({
+    pending: 20,
+    inProgress: 12,
+    completed: 55,
+  }).find((r) => r.label === "Completed");
+
+  assert.equal(completed?.value, 55);
+});
+
+/**
+ * The bars are share-of-largest-bucket, so the biggest is always full width
+ * and the rest are proportional to it. This is the widths the panel draws.
+ */
+test("each bar is its share of the largest bucket", () => {
+  const rows = buildWorkOrderStatus({ pending: 25, inProgress: 50, completed: 100 });
+
+  assert.deepEqual(
+    rows.map((r) => r.percent),
+    [100, 50, 25]
+  );
+});
+
+/** Three empty buckets must draw three empty bars, not divide by zero. */
+test("an all-zero breakdown does not divide by zero", () => {
+  const rows = buildWorkOrderStatus({ pending: 0, inProgress: 0, completed: 0 });
+
+  assert.equal(rows.length, 3);
+  for (const row of rows) {
+    assert.equal(row.value, 0);
+    assert.equal(row.percent, 0, row.label);
+    assert.ok(Number.isFinite(row.percent), row.label);
+  }
+});
+
+/** A partial payload is read for what it has and zeroed for what it does not. */
+test("missing buckets read as zero rather than undefined", () => {
+  const rows = buildWorkOrderStatus({ completed: 7 });
+
+  assert.deepEqual(
+    rows.map((r) => r.value),
+    [7, 0, 0]
+  );
+});
+
+/**
+ * NO FALLBACK, DELIBERATELY. When the breakdown is absent there is nothing
+ * honest to draw, so the panel must show its empty state - not bars built out
+ * of a different metric. An empty array is what triggers that.
+ */
+test("no breakdown means no bars, never invented ones", () => {
+  assert.deepEqual(buildWorkOrderStatus(undefined), []);
+  assert.deepEqual(buildWorkOrderStatus(null), []);
+  assert.deepEqual(buildWorkOrderStatus(42 as never), []);
+  assert.deepEqual(buildWorkOrderStatus("55" as never), []);
+});
+
+/**
+ * The tone is a token NAME, not a colour. The template writes `var(--<tone>)`,
+ * so a tone that is not a real token silently paints nothing.
+ */
+test("every row carries a real design token name", () => {
+  const rows = buildWorkOrderStatus({ pending: 1, inProgress: 2, completed: 3 });
+
+  assert.deepEqual(
+    rows.map((r) => r.tone),
+    ["ok", "err", "warn"]
+  );
+});
+
+/**
+ * The buckets are the whole of the server's status report - it folds every
+ * unrecognised status into `pending` rather than dropping it - so nothing the
+ * server counted goes missing on the way to the screen.
+ */
+test("the three buckets account for the whole breakdown", () => {
+  const src = { pending: 20, inProgress: 12, completed: 55 };
+  const total = buildWorkOrderStatus(src).reduce((sum, r) => sum + r.value, 0);
+
+  assert.equal(total, src.pending + src.inProgress + src.completed);
+});

package/utils/dashboard.ts

@@ -0,0 +1,53 @@
+/**
+ * Dashboard arithmetic that is worth testing on its own.
+ *
+ * `DashboardMain.vue` is 4,800 lines of template and wiring, and none of it is
+ * reachable from `node --test`. The one piece with real arithmetic in it - the
+ * work-order status breakdown - lives here instead, so the defect that made
+ * "Completed" read zero on every Property Management dashboard has a test that
+ * fails if it ever comes back.
+ */
+
+export type TWorkOrderStatusSource = {
+  pending?: number;
+  inProgress?: number;
+  completed?: number;
+} | null | undefined;
+
+export type TWorkOrderStatusRow = {
+  label: string;
+  value: number;
+  /** Share of the largest bucket, 0-100 - the bar's width. */
+  percent: number;
+  /** A design token name, not a colour: the caller writes `var(--<tone>)`. */
+  tone: "ok" | "err" | "warn";
+};
+
+/**
+ * The three status bars, from the breakdown the server sends as
+ * `workOrderStatus` (new-dashboard.repo.ts, property branch).
+ *
+ * NO FALLBACK. The screen used to read `workOrderStatusSummary` - a key no
+ * endpoint returns - and fall through to the `openWorkOrder` KPI metric, which
+ * carries no `completed` field: Completed was therefore ALWAYS 0 and Pending
+ * was silently recomputed as (open work orders - in progress) instead of read.
+ * Without the real breakdown there is nothing honest to draw, so this returns
+ * an empty list and the panel shows its empty state.
+ */
+export function buildWorkOrderStatus(
+  src: TWorkOrderStatusSource
+): TWorkOrderStatusRow[] {
+  if (!src || typeof src !== "object") return [];
+
+  const completed = Number(src.completed ?? 0);
+  const inProgress = Number(src.inProgress ?? 0);
+  const pending = Number(src.pending ?? 0);
+  // `1` floors the divisor: three empty buckets must not divide by zero.
+  const max = Math.max(completed, inProgress, pending, 1);
+
+  return [
+    { label: "Completed", value: completed, percent: (completed / max) * 100, tone: "ok" },
+    { label: "In Progress", value: inProgress, percent: (inProgress / max) * 100, tone: "err" },
+    { label: "Pending", value: pending, percent: (pending / max) * 100, tone: "warn" },
+  ];
+}

package/utils/theme-aa-ledger.ts

@@ -76,9 +76,15 @@ export const LIGHT_PAIRS: Array<{
   bg: string;
   need: number;
 }> = [
-  { what: "muted on a card (table header text, sub-lines)", fg: L.muted, bg: L.card, need: 4.5 },
+  { what: "muted on a card (KPI sub-lines, field labels)", fg: L.muted, bg: L.card, need: 4.5 },
   { what: "muted on the page background", fg: L.muted, bg: L.bg, need: 4.5 },
-  { what: "muted on a table header band", fg: L.muted, bg: thead, need: 4.5 },
+  /*
+   * `muted on a table header band` used to sit here at 3.10:1. `.table-card
+   * thead th` now takes `--text2` (9.22:1 light / 9.57:1 dark), and nothing
+   * else paints `--muted` on a `--thead` band - `.table-card__group`'s label
+   * is Vuetify's `text-medium-emphasis`. The pair no longer occurs, so it is
+   * no longer carried as accepted debt.
+   */
   { what: "muted on the sidebar", fg: L.muted, bg: L.sidebar, need: 4.5 },
   { what: "muted on a disabled control's hover fill", fg: L.muted, bg: hoverOnBg, need: 4.5 },
   { what: "ok label on its own chip", fg: L.ok, bg: chip.ok, need: 4.5 },
@@ -115,7 +121,7 @@ export const DARK_PAIRS = () => {
   return [
     { what: "muted on a card", fg: D.muted, bg: D.card, need: 4.5 },
     { what: "muted on the page background", fg: D.muted, bg: D.bg, need: 4.5 },
-    { what: "muted on a table header band", fg: D.muted, bg: dthead, need: 4.5 },
+    { what: "muted on a --thead band (the tint itself, no longer the header text)", fg: D.muted, bg: dthead, need: 4.5 },
     { what: "muted on the sidebar", fg: D.muted, bg: D.sidebar, need: 4.5 },
     { what: "text on a card", fg: D.text, bg: D.card, need: 4.5 },
     { what: "text2 on a card", fg: D.text2, bg: D.card, need: 4.5 },

package/utils/theme.test.ts

@@ -1,4 +1,5 @@
 import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
 import { test } from "node:test";
 
 import { DARK_THEME, LIGHT_THEME, PALETTE, type TPalette } from "./theme.ts";
@@ -505,9 +506,8 @@ test("the light palette is the handoff's, value for value", () => {
  */
 test("the light theme's sub-AA pairs measure exactly what the ledger says", () => {
   const EXPECTED: Record<string, number> = {
-    "muted on a card (table header text, sub-lines)": 3.24,
+    "muted on a card (KPI sub-lines, field labels)": 3.24,
     "muted on the page background": 2.99,
-    "muted on a table header band": 3.1,
     "muted on the sidebar": 3.13,
     "muted on a disabled control's hover fill": 2.71,
     "ok label on its own chip": 4.57,
@@ -548,8 +548,8 @@ test("the light theme's sub-AA pairs measure exactly what the ledger says", () =
   const failing = measured.filter((r) => !r.passes).length;
   assert.equal(
     failing,
-    8,
-    `${failing} light pairs are below AA; the recorded, accepted count is 8. ` +
+    7,
+    `${failing} light pairs are below AA; the recorded, accepted count is 7. ` +
       "If this moved, the owner's design-fidelity decision needs re-stating."
   );
 });
@@ -560,6 +560,90 @@ test("the dark theme has no sub-AA pairs at all", () => {
   assert.deepEqual(bad, [], "dark mode was exact AND compliant - keep it that way");
 });
 
+/* ------------------------------------------------------------------ */
+/* The two contrast fixes QA drove, asserted at the token level AND at  */
+/* the stylesheet that wires them.                                     */
+/* ------------------------------------------------------------------ */
+
+/**
+ * A native `<select>`'s option list is painted by the browser. With no
+ * background of its own the option keeps the theme's ink over whatever the
+ * browser paints - white on Windows/Chrome - which is 1.14:1 in dark mode.
+ * The rule gives it `--card`/`--text`, the same pair the themed popover uses.
+ */
+test("a native option's own fill carries the theme ink in both themes", () => {
+  for (const [name, p] of [["light", PALETTE.light], ["dark", PALETTE.dark]] as const) {
+    assert.ok(
+      contrast(p.text, p.card) >= 4.5,
+      `${name}: option ink on the card fill is ${contrast(p.text, p.card).toFixed(2)}:1`
+    );
+  }
+
+  // What the defect measured, so the number stays on the record.
+  assert.equal(Number(contrast(PALETTE.dark.text, "#ffffff").toFixed(2)), 1.14);
+});
+
+/**
+ * The table header. `--muted` measured 3.10:1 on the header band in light -
+ * below AA and reported by two apps' QA. `--text2` clears AA in both themes
+ * while staying clearly below the primary ink the data rows use, so the
+ * header still reads as secondary to the data.
+ */
+test("the table header clears AA and still reads below the data", () => {
+  for (const [name, p, wash] of [
+    ["light", PALETTE.light, "#14161a"],
+    ["dark", PALETTE.dark, "#ffffff"],
+  ] as const) {
+    const band = over(wash, p.card, 0.02);
+    const header = contrast(p.text2, band);
+    const data = contrast(p.text, band);
+
+    assert.ok(header >= 4.5, `${name}: header is ${header.toFixed(2)}:1, below AA`);
+    assert.ok(
+      header < data,
+      `${name}: the header (${header.toFixed(2)}:1) must stay below the data ` +
+        `(${data.toFixed(2)}:1) or it stops reading as secondary`
+    );
+    assert.ok(
+      contrast(p.muted, band) < header,
+      `${name}: --text2 must be an improvement on the --muted it replaced`
+    );
+  }
+});
+
+/**
+ * The ratios above are the tokens'. They say nothing about whether the CSS
+ * still ASKS for them - a deleted rule would leave every number here passing.
+ * These two assertions are the wiring. Neither can measure a real computed
+ * style: that needs a browser, and the measured evidence for it is in the PR.
+ */
+test("the stylesheets still ask for the tokens the two fixes chose", () => {
+  const css = (f: string) =>
+    readFileSync(new URL(`../assets/css/${f}`, import.meta.url), "utf8")
+      .replace(/\/\*[\s\S]*?\*\//g, "");
+
+  const primitives = css("primitives.css");
+  const optionRule = primitives.slice(primitives.indexOf("select option {"));
+  assert.ok(
+    primitives.includes("select option {"),
+    "the native <option> fill rule is gone - dark mode goes back to 1.14:1"
+  );
+  const optionBody = optionRule.slice(0, optionRule.indexOf("}"));
+  assert.ok(
+    optionBody.includes("background-color: var(--card)"),
+    "the option lost its own fill, which is the whole defect"
+  );
+  assert.ok(optionBody.includes("color: var(--text)"), "the option lost its ink");
+
+  const screens = css("screens.css");
+  const header = screens.slice(screens.indexOf(".table-card thead th {"));
+  const headerBody = header.slice(0, header.indexOf("}"));
+  assert.ok(
+    headerBody.includes("color: var(--text2) !important"),
+    "the table header is back on a token that does not clear AA in light"
+  );
+});
+
 /**
  * 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