@7365admin1/layer-common 3.2.1 → 3.2.2-staging.100

package/utils/nav-sections.test.ts

@@ -0,0 +1,190 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { NAV_SECTIONS, withSections } from "./nav-sections.ts";
+
+/** The Security menu, item for item and in `web-app-security`'s own order. */
+const SECURITY = [
+  "Dashboard",
+  "Feedbacks",
+  "Work Orders",
+  "Vehicle Mgmt",
+  "Building Mgmt",
+  "Visitor Mgmt",
+  "Pass & Key Mgmt",
+  "HID Face Reader",
+  "Daily Occurrence Books",
+  "Manpower",
+  "Virtual Patrol",
+  "Robot Mgmt",
+  "Incident Reports",
+  "Bulletin Board",
+  "Attendance",
+  "My Attendance",
+  "Invitations",
+  "Members",
+  "Roles & Permissions",
+  "Settings",
+].map((title) => ({ title }));
+
+/**
+ * THE RULE THAT MATTERS. Grouping may reorder the rail; it may never change
+ * the menu. Same objects, same count - nothing added, hidden or duplicated.
+ */
+test("every menu item comes back exactly once, and nothing else does", () => {
+  const out = withSections(SECURITY);
+
+  assert.equal(out.length, SECURITY.length);
+  assert.deepEqual(
+    new Set(out.map((e) => e.item)),
+    new Set(SECURITY)
+  );
+});
+
+test("Security is labelled the way the design draws it", () => {
+  const labelled = withSections(SECURITY)
+    .filter((e) => e.section)
+    .map((e) => `${e.section}: ${e.item.title}`);
+
+  assert.deepEqual(labelled, [
+    "OVERVIEW: Dashboard",
+    "SERVICE DESK: Feedbacks",
+    "PROPERTY: Vehicle Mgmt",
+    "SECURITY OPERATIONS: HID Face Reader",
+    "COMMUNITY: Bulletin Board",
+    "WORKFORCE: Attendance",
+    "ADMINISTRATION: Invitations",
+  ]);
+});
+
+/**
+ * A permission-gated menu is a SUBSET, and every application's is different.
+ * Dropping the items a user cannot see must not leave a heading behind or move
+ * one onto the wrong item.
+ */
+test("a user who can only see three modules gets three correct headings", () => {
+  const out = withSections(
+    [{ title: "Dashboard" }, { title: "Work Orders" }, { title: "Settings" }]
+  );
+
+  assert.deepEqual(
+    out.map((e) => e.section),
+    ["OVERVIEW", "SERVICE DESK", "ADMINISTRATION"]
+  );
+});
+
+/**
+ * The eleven applications add menu items without touching this layer. An
+ * unknown title must appear where its author put it, under the heading it
+ * follows - never suppressed, and never given a heading of its own.
+ */
+test("an unmapped module inherits the section above it", () => {
+  const out = withSections([
+    { title: "Dashboard" },
+    { title: "Something New" },
+    { title: "Members" },
+  ]);
+
+  assert.deepEqual(
+    out.map((e) => e.section),
+    ["OVERVIEW", "", "ADMINISTRATION"]
+  );
+  assert.equal(out[1].item.title, "Something New");
+});
+
+test("an unmapped FIRST item prints no heading rather than a blank one", () => {
+  const out = withSections([{ title: "Something New" }, { title: "Members" }]);
+
+  assert.deepEqual(
+    out.map((e) => e.section),
+    ["", "ADMINISTRATION"]
+  );
+});
+
+/**
+ * The applications do not agree on order: Landscape lists Feedbacks after its
+ * equipment modules. Those two Feedbacks/Work Orders items are collected under
+ * ONE SERVICE DESK heading instead of printing the heading twice.
+ */
+test("a section that comes back later is grouped, not labelled twice", () => {
+  const out = withSections([
+    { title: "Feedbacks" },
+    { title: "Equipment Items" },
+    { title: "Work Orders" },
+  ]);
+
+  assert.deepEqual(
+    out.map((e) => `${e.section}|${e.item.title}`),
+    [
+      "SERVICE DESK|Feedbacks",
+      "|Work Orders",
+      "EQUIPMENT|Equipment Items",
+    ]
+  );
+});
+
+/**
+ * Property Management is the screen that showed the defect: its own menu order
+ * printed SERVICE DESK, PROPERTY and SECURITY OPERATIONS twice each.
+ */
+test("Property Management prints each heading exactly once", () => {
+  const PM = [
+    "Dashboard",
+    "Service Providers",
+    "Feedbacks",
+    "Work Orders",
+    "Facility Mgmt",
+    "Pass & Key Mgmt",
+    "HID Face Reader",
+    "Online Forms",
+    "NFC Patrol",
+    "Bulletin Board",
+    "Bulletin Videos",
+    "Visitor Mgmt",
+    "Document Mgmt",
+    "Access Mgmt",
+  ].map((title) => ({ title }));
+
+  const out = withSections(PM);
+  const headings = out.map((e) => e.section).filter(Boolean);
+
+  assert.deepEqual(headings, [
+    "OVERVIEW",
+    "SERVICE DESK",
+    "PROPERTY",
+    "SECURITY OPERATIONS",
+    "COMMUNITY",
+  ]);
+  assert.equal(new Set(headings).size, headings.length);
+  assert.deepEqual(
+    out.map((e) => e.item.title),
+    [
+      "Dashboard",
+      "Service Providers",
+      "Feedbacks",
+      "Work Orders",
+      "Online Forms",
+      "Facility Mgmt",
+      "Pass & Key Mgmt",
+      "Visitor Mgmt",
+      "Document Mgmt",
+      "Access Mgmt",
+      "HID Face Reader",
+      "NFC Patrol",
+      "Bulletin Board",
+      "Bulletin Videos",
+    ]
+  );
+});
+
+test("a missing or empty title does not throw", () => {
+  const out = withSections([{}, { title: "" }] as Array<{ title?: string }>);
+  assert.equal(out.length, 2);
+});
+
+/** Every section name is the uppercase form the type scale is drawn for. */
+test("section names are uppercase", () => {
+  for (const section of Object.values(NAV_SECTIONS)) {
+    assert.equal(section, section.toUpperCase(), section);
+  }
+});

package/utils/nav-sections.ts

@@ -0,0 +1,151 @@
+/**
+ * THE GROUPED SIDEBAR - one heading per section, each printed once.
+ *
+ * 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.
+ *
+ * The applications do not agree on the order they list their modules in
+ * (Property Management interleaves five sections; Landscape puts Feedbacks
+ * after Equipment). Walking that order and printing a heading whenever the
+ * section changed - what this file used to do - made Property Management draw
+ * SERVICE DESK, PROPERTY and SECURITY OPERATIONS TWICE each. It reads as a
+ * bug, so the items are now GROUPED:
+ *
+ *   - every item is collected under its section, and each heading is printed
+ *     exactly once, in the order the design lists the sections (which is the
+ *     order they are declared in the map below).
+ *   - inside a section the application's own order is preserved, so items that
+ *     belong together stay in the sequence their author chose.
+ *   - a title this map has never heard of inherits the section of the item
+ *     above it, so a new menu item added by any of the eleven applications is
+ *     grouped with its neighbours rather than disappearing or forcing a stray
+ *     heading.
+ *   - an item with no section at all (an unmapped FIRST item) leads the rail
+ *     with no heading, exactly as before.
+ *
+ * This changes what ORDER the items are drawn in and nothing else. No item is
+ * added, hidden, renamed, re-routed or re-gated - the array that comes out
+ * holds the same objects as the array that went in.
+ */
+
+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 };
+
+/** The design's section order - the order they are declared above. */
+export const SECTION_ORDER: string[] = [
+  ...new Set(Object.values(NAV_SECTIONS)),
+];
+
+/**
+ * Groups the menu by section and tags each item with the heading to print
+ * above it, or "" when the heading is already printed. Same length, same
+ * objects; only the order changes.
+ */
+export function withSections<T extends { title?: string }>(
+  items: T[]
+): Array<TSectionedNavItem<T>> {
+  // An unmapped title inherits the section of the item above it.
+  let current = "";
+  const resolved = items.map((item, index) => {
+    current = NAV_SECTIONS[String(item?.title ?? "")] ?? current;
+    return { item, section: current, index };
+  });
+
+  // Sectionless items (an unmapped first item) rank -1 and lead the rail.
+  // Inside a section the application's own order is kept.
+  const grouped = [...resolved].sort(
+    (a, b) =>
+      SECTION_ORDER.indexOf(a.section) - SECTION_ORDER.indexOf(b.section) ||
+      a.index - b.index
+  );
+
+  let printed = "";
+  return grouped.map(({ item, section }) => {
+    const label = section === printed ? "" : section;
+    printed = section;
+    return { item, section: label };
+  });
+}

package/utils/status.test.ts

@@ -0,0 +1,77 @@
+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));
+  }
+});
+
+/**
+ * PHASE 4. Each of these words is on a module screen today with a colour a
+ * per-screen `getStatusColor` gave it. The list has to keep giving it the SAME
+ * tone, or adopting the shared chip would quietly repaint a status.
+ */
+test("the product's own status words keep the tone the screens already gave them", () => {
+  for (const s of ["Accepted", "Approved", "Resolved", "Active"]) {
+    assert.equal(statusTone(s), "ok", s);
+  }
+
+  for (const s of ["Rejected", "Deleted", "Suspended"]) {
+    assert.equal(statusTone(s), "err", s);
+  }
+
+  for (const s of ["In Progress", "In-Progress", "To-Do", "Awaiting Approval"]) {
+    assert.equal(statusTone(s), "warn", s);
+  }
+
+  for (const s of ["Ongoing", "For Review"]) {
+    assert.equal(statusTone(s), "info", s);
+  }
+
+  for (const s of ["Inactive", "Expired"]) {
+    assert.equal(statusTone(s), "neutral", s);
+  }
+});
+
+/**
+ * The one place the handoff and the old per-screen colour disagree: `Open` was
+ * grey on the cleaning schedules and the design names it `ok`. Pinned so the
+ * disagreement is a decision on the record rather than a surprise.
+ */
+test("Open follows the design, not the old grey", () => {
+  assert.equal(statusTone("open"), "ok");
+});
+
+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,90 @@
+/**
+ * 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",
+
+  /**
+   * PHASE 4 - THE WORDS THIS PRODUCT ACTUALLY USES.
+   *
+   * The handoff names ten words; the module screens show more than that, and
+   * each of them is ALREADY painted a colour today by a per-screen
+   * `getStatusColor`. So these are not new opinions - each one is the tone the
+   * screens already give that word, moved into the one list so that "Ongoing"
+   * is the same blue on a cleaning schedule and on a scheduled area. Where the
+   * old per-screen colour and the design disagree the design wins, and there
+   * is exactly one of those: `Open` was grey and the handoff names it `ok`.
+   *
+   * Anything still unlisted stays neutral, deliberately - see above.
+   */
+  ongoing: "info", // was `primary`
+  "in progress": "warn", // was #FB8C00, orange
+  "for review": "info", // was `primary`
+  "to do": "warn", // was `orange`
+
+  accepted: "ok", // was `success`
+  approved: "ok",
+  resolved: "ok", // was #4CAF50, green
+  active: "ok", // was `success`
+
+  rejected: "err", // was `error`
+  deleted: "err", // was `error`
+  suspended: "err", // was `error`
+
+  complete: "ok",
+
+  inactive: "neutral", // was `grey`
+  "in active": "neutral", // the same word, printed "In-Active"
+  declined: "neutral", // was Vuetify's `default`
+  expired: "neutral", // was `grey`
+
+  "awaiting approval": "warn", // a waiting state, like Pending
+};
+
+/**
+ * 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)}`;
+}