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

package/utils/nav-sections.ts

@@ -0,0 +1,128 @@
+/**
+ * THE GROUPED SIDEBAR - section labels, without touching the menu.
+ *
+ * The design draws the sidebar in labelled sections (OVERVIEW, SERVICE DESK,
+ * PROPERTY, SECURITY OPERATIONS, COMMUNITY, WORKFORCE, ADMINISTRATION). Each
+ * application builds its own menu array in its `layouts/default.vue`, gated
+ * item by item on permissions, and that array is the product's navigation.
+ *
+ * So this file adds a LABEL and nothing else:
+ *
+ *   - the order of the menu is the order the application gave us. Nothing is
+ *     moved, sorted, merged, hidden or renamed. A label is inserted when the
+ *     section CHANGES as we walk that existing order, which means the label is
+ *     always true of the items under it.
+ *   - a title this map has never heard of inherits the section above it, so a
+ *     new menu item added by any of the eleven applications appears exactly
+ *     where its author put it, under the heading it follows, rather than
+ *     disappearing or forcing a stray heading.
+ *   - the first item always gets its section printed, even if that section is
+ *     "" (nothing) - a leading blank label is simply not rendered.
+ *
+ * A section may therefore appear twice in one sidebar. That is deliberate: the
+ * applications do not all list their modules in the same order (Landscape puts
+ * Feedbacks after Equipment; Property Management interleaves five sections),
+ * and printing the heading again is honest, where suppressing it would leave a
+ * run of items sitting under a heading that is not theirs.
+ */
+
+export const NAV_SECTIONS: Record<string, string> = {
+  // OVERVIEW
+  Dashboard: "OVERVIEW",
+  Home: "OVERVIEW",
+
+  // SERVICE DESK
+  "Service Providers": "SERVICE DESK",
+  Feedbacks: "SERVICE DESK",
+  "Work Orders": "SERVICE DESK",
+  "Online Forms": "SERVICE DESK",
+
+  // SERVICE DELIVERY - the five service applications' own working modules
+  "Cleaning Schedule": "SERVICE DELIVERY",
+  "Landscape Schedule": "SERVICE DELIVERY",
+  "Pest Schedule": "SERVICE DELIVERY",
+  "Pool Schedule": "SERVICE DELIVERY",
+  "Technician Schedule": "SERVICE DELIVERY",
+  Area: "SERVICE DELIVERY",
+  Unit: "SERVICE DELIVERY",
+  "Schedule Task": "SERVICE DELIVERY",
+
+  // EQUIPMENT
+  "Equipment Management": "EQUIPMENT",
+  "Equipment Items": "EQUIPMENT",
+
+  // PROPERTY
+  "Vehicle Mgmt": "PROPERTY",
+  "Building Mgmt": "PROPERTY",
+  "Visitor Mgmt": "PROPERTY",
+  "Pass & Key Mgmt": "PROPERTY",
+  "Facility Mgmt": "PROPERTY",
+  "People Mgmt": "PROPERTY",
+  "Document Mgmt": "PROPERTY",
+  "Access Mgmt": "PROPERTY",
+  "Event Mgmt": "PROPERTY",
+  "Emergency Contacts": "PROPERTY",
+  "Online Billing": "PROPERTY",
+  "SOA Mgmt": "PROPERTY",
+
+  // SECURITY OPERATIONS
+  "HID Face Reader": "SECURITY OPERATIONS",
+  "Daily Occurrence Books": "SECURITY OPERATIONS",
+  Manpower: "SECURITY OPERATIONS",
+  "Virtual Patrol": "SECURITY OPERATIONS",
+  "NFC Patrol": "SECURITY OPERATIONS",
+  "Robot Mgmt": "SECURITY OPERATIONS",
+  "Incident Reports": "SECURITY OPERATIONS",
+  CCTV: "SECURITY OPERATIONS",
+
+  // COMMUNITY
+  "Bulletin Board": "COMMUNITY",
+  "Bulletin Videos": "COMMUNITY",
+
+  // WORKFORCE
+  Attendance: "WORKFORCE",
+  "My Attendance": "WORKFORCE",
+
+  // ADMINISTRATION
+  Invitations: "ADMINISTRATION",
+  "SP Approvals": "ADMINISTRATION",
+  Members: "ADMINISTRATION",
+  "Roles & Permissions": "ADMINISTRATION",
+  Settings: "ADMINISTRATION",
+  "Site Settings": "ADMINISTRATION",
+  Organizations: "ADMINISTRATION",
+  Users: "ADMINISTRATION",
+  "Promo Codes": "ADMINISTRATION",
+
+  // ACCOUNT - `web-app-account` is a personal-settings application, not a site
+  "Personal Info": "ACCOUNT",
+  "Payment Methods": "ACCOUNT",
+
+  // SERVICES - the account application's list of the products a user can enter
+  "Property Management": "SERVICES",
+  Security: "SERVICES",
+  Hygiene: "SERVICES",
+  "Mechanical & Electrical": "SERVICES",
+  "Pest Control Services": "SERVICES",
+  "Landscaping Services": "SERVICES",
+  "Pool Maintenance Services": "SERVICES",
+};
+
+export type TSectionedNavItem<T> = { item: T; section: string };
+
+/**
+ * Walks the menu IN THE ORDER GIVEN and tags each item with the section label
+ * to print above it, or "" for no label. Same length, same order, same objects.
+ */
+export function withSections<T extends { title?: string }>(
+  items: T[]
+): Array<TSectionedNavItem<T>> {
+  let current = "";
+
+  return items.map((item, index) => {
+    const section = NAV_SECTIONS[String(item?.title ?? "")] ?? current;
+    const changed = index === 0 || section !== current;
+    current = section;
+    return { item, section: changed ? section : "" };
+  });
+}

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"
+  );
+});