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

package/components/Layout/Header.vue

@@ -1,54 +1,87 @@
 <template>
-  <v-app-bar scroll-behavior="elevate" scroll-threshold="200">
+  <!--
+    PHASE 2 - THE 58px TOP BAR.
+
+    Same bar, same hamburger, same theme toggle, same profile menu with the
+    same two actions. What changes is its height (the design's 58px), the
+    breadcrumb it now carries, and the shape of the menu it opens.
+
+    The breadcrumb READS state that is already in the page - the site the
+    application has loaded and the route the router is on. It fetches nothing
+    and navigates nowhere; it is a label.
+  -->
+  <v-app-bar
+    :height="58"
+    flat
+    scroll-behavior="elevate"
+    scroll-threshold="200"
+    class="app-topbar-shell"
+  >
     <v-app-bar-nav-icon v-if="!props.hideNavIcon" @click="drawer = !drawer"></v-app-bar-nav-icon>
 
+    <div class="app-topbar-shell__crumb">
+      <span v-if="siteName" class="app-topbar-shell__site">{{ siteName }}</span>
+      <span v-if="siteName && moduleName" class="app-topbar-shell__sep">/</span>
+      <span class="app-topbar-shell__module">{{ moduleName }}</span>
+    </div>
+
     <template #append>
       <!--
         The icon now says which theme you would GET, and the choice is
         remembered - see `composables/useThemePreference.ts`. Same button, same
         place, same one click.
       -->
+      <!-- The design's 36px bordered icon button. Same one click, same icon. -->
       <v-btn
         :icon="current === 'dark' ? 'mdi-weather-sunny' : 'mdi-weather-night'"
         :aria-label="current === 'dark' ? 'Switch to light theme' : 'Switch to dark theme'"
         variant="text"
-        class="mx-2"
+        size="36"
+        class="app-topbar-shell__icon-btn ms-2"
         @click="toggleTheme"
       />
 
       <v-menu offset="10px" :close-on-content-click="false">
         <template #activator="{ props }">
-          <v-btn fab variant="text" icon v-bind="props" class="mx-2">
+          <v-btn fab variant="text" icon v-bind="props" class="ms-2 me-1">
             <AvatarMain :image-src="currentUser?.profile" :name="name" />
           </v-btn>
         </template>
 
-        <v-card width="350" max-height="600px" elevation="2" rounded="xl" class="pa-4">
-          <v-row no-gutters>
-            <v-col cols="12">
-              <v-row no-gutters justify="center">
-               <AvatarMain :image-src="currentUser?.profile" :name="name" />
-              </v-row>
-            </v-col>
-
-            <v-col cols="12" class="text-center mt-2 mb-4">
-              {{ name }}
-            </v-col>
-
-            <v-col cols="12" class="mb-3">
-              <v-btn v-if="APP_NAME.toLowerCase() !== 'account'" block rounded="xl" variant="tonal" size="x-large"
-                class="text-none text-subtitle-1 font-weight-regular" @click="redirect(APP_ACCOUNT, 'home')">
-                Manage Account
-              </v-btn>
-            </v-col>
-
-            <v-col cols="12">
-              <v-btn block rounded="xl" variant="tonal" size="x-large"
-                class="text-none text-subtitle-1 font-weight-regular" @click="logout()">
-                Logout
-              </v-btn>
-            </v-col>
-          </v-row>
+        <!--
+          240px, 14px radius and the design's menu shadow. The two actions and
+          the condition on the first are exactly as they were.
+        -->
+        <v-card :width="240" elevation="0" class="app-profile-menu">
+          <div class="app-profile-menu__head">
+            <AvatarMain :image-src="currentUser?.profile" :name="name" />
+
+            <div class="app-profile-menu__who">
+              <div class="app-profile-menu__name">{{ name }}</div>
+              <div v-if="siteName" class="app-profile-menu__site">{{ siteName }}</div>
+            </div>
+          </div>
+
+          <div class="app-profile-menu__rows">
+            <button
+              v-if="APP_NAME.toLowerCase() !== 'account'"
+              type="button"
+              class="app-profile-menu__row"
+              @click="redirect(APP_ACCOUNT, 'home')"
+            >
+              <v-icon icon="mdi-account-cog-outline" size="18" />
+              Manage Account
+            </button>
+
+            <button
+              type="button"
+              class="app-profile-menu__row app-profile-menu__row--danger"
+              @click="logout()"
+            >
+              <v-icon icon="mdi-logout" size="18" />
+              Logout
+            </button>
+          </div>
         </v-card>
       </v-menu>
     </template>
@@ -83,6 +116,55 @@ const { current, toggleTheme } = useThemePreference();
 
 const { currentUser } = useLocalAuth();
 
+/**
+ * THE BREADCRUMB: `Site name / Current module`.
+ *
+ * Both halves are read from what the page already holds - the shared `site`
+ * state the applications populate, and the router's own current route. NO
+ * request is made from this component; if the site has not been loaded on a
+ * given screen the site half is simply omitted and the module stands alone.
+ */
+const { site } = useSite();
+
+const siteName = computed(() => String(site.value?.name ?? "").trim());
+
+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.
+ */
+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 profile = computed(() => {
   return `/api/public/${currentUser.value?.profile}`;
 });
@@ -116,6 +198,151 @@ const { getNameInitials } = useUtils();
 </script>
 
 <style scoped>
+/* ---------------------------------------------------------------- */
+/* The top bar.                                                      */
+/* ---------------------------------------------------------------- */
+
+/**
+ * The design's bar is 58px INCLUDING its rule. A real `border-bottom` is added
+ * to the 58px Vuetify lays out, so the bar measures 59 and every page below it
+ * starts a pixel low; an inset shadow draws the same 1px line inside the 58.
+ */
+.app-topbar-shell,
+.app-profile-menu {
+  /* The shell is the first surface to wear the design's typeface - see the
+     note in NavigationDrawer.vue. */
+  font-family: var(--font-sans);
+}
+
+.app-topbar-shell {
+  box-shadow: inset 0 -1px 0 var(--border);
+}
+
+.app-topbar-shell__crumb {
+  flex: 1 1 auto;
+  min-width: 0;
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  font-size: var(--fs-breadcrumb);
+  /* Truncates rather than wraps: two lines would break a 58px bar, and the
+     site name is the half worth losing first. */
+  overflow: hidden;
+  white-space: nowrap;
+}
+
+.app-topbar-shell__site,
+.app-topbar-shell__sep {
+  color: var(--muted);
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.app-topbar-shell__module {
+  color: var(--text);
+  font-weight: 700;
+  flex: 0 0 auto;
+}
+
+/**
+ * THE TOP-BAR AVATAR is the design's accent-soft circle with accent-text
+ * initials, and only this one. `AvatarMain` gives every person a colour of
+ * their own from their name, which is right in a list of people - it is how
+ * you tell two rows apart - and wrong for the one avatar that is always the
+ * same person. `!important` because that per-person colour arrives as an
+ * inline style, and the rule is confined to the bar and its own menu.
+ */
+.app-topbar-shell :deep(.v-avatar),
+.app-profile-menu :deep(.v-avatar) {
+  background-color: var(--accent-soft) !important;
+  /* The initials' colour arrives inline as well, and in dark mode it is the
+     per-person colour ON a blue wash: 1.26:1, invisible. */
+  color: var(--accent-text) !important;
+  font-weight: 800;
+}
+
+/* 36px, 1px border, 10px radius - the design's icon button. */
+.app-topbar-shell__icon-btn {
+  border: 1px solid var(--border);
+  border-radius: var(--r-inner);
+}
+
+/* ---------------------------------------------------------------- */
+/* The 240px profile menu.                                           */
+/* ---------------------------------------------------------------- */
+
+.app-profile-menu {
+  border-radius: var(--r-menu);
+  box-shadow: var(--shadow-menu);
+  border: 1px solid var(--border);
+  overflow: hidden;
+}
+
+.app-profile-menu__head {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 14px;
+  border-bottom: 1px solid var(--border);
+}
+
+.app-profile-menu__who {
+  min-width: 0;
+}
+
+.app-profile-menu__name {
+  font-size: 13.5px;
+  font-weight: 800;
+  line-height: 1.3;
+  color: var(--text);
+  overflow: hidden;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+}
+
+.app-profile-menu__site {
+  font-size: 11.5px;
+  font-weight: 600;
+  line-height: 1.3;
+  color: var(--muted);
+  overflow: hidden;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+}
+
+.app-profile-menu__rows {
+  padding: 6px;
+}
+
+.app-profile-menu__row {
+  width: 100%;
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 9px 10px;
+  border-radius: var(--r-inner-sm);
+  font-size: var(--fs-btn);
+  font-weight: var(--fw-btn);
+  color: var(--text2);
+  text-align: start;
+  cursor: pointer;
+  background: transparent;
+}
+
+.app-profile-menu__row:hover {
+  background: var(--hover);
+}
+
+/* Logout is the design's red row: the colour lives on the label, and the
+   soft error background is what the hover paints. */
+.app-profile-menu__row--danger {
+  color: var(--err);
+}
+
+.app-profile-menu__row--danger:hover {
+  background: var(--err-bg);
+}
+
 .APP_NAME {
   display: inline-block;
   word-wrap: break-word;

package/components/Layout/NavigationDrawer.vue

@@ -45,45 +45,73 @@
     Nothing about the menu changes - same items, same order, same permissions,
     same routes. Only where the panel is drawn.
   -->
+  <!--
+    PHASE 2 - THE GROUPED SIDEBAR.
+
+    The rail is 252px as drawn, the brand row is the design's 34px tile plus
+    the product name, and the menu is printed in labelled sections.
+
+    The MENU ITSELF IS UNTOUCHED. Each application still builds its own array,
+    gated item by item on its own permissions, and it is rendered in exactly
+    that order; `utils/nav-sections.ts` only decides which label to print above
+    which item, and an item whose title it does not know keeps its place under
+    the heading it follows. Nothing here can add, hide, move or rename a menu
+    entry, and no route, permission or click handler is involved.
+  -->
   <v-navigation-drawer
     v-model="drawer"
     :mobile-breakpoint="1024"
+    :width="252"
     class="bg-brand-surface brand-drawer"
   >
-    <v-list>
-      <v-list-item>
-        <v-list-item-title class="text-h6">
-          {{ props.title || APP_NAME }}
-        </v-list-item-title>
-      </v-list-item>
+    <div class="brand-drawer__brand">
+      <div class="brand-drawer__logo">
+        <v-icon :icon="brandIcon" size="19" />
+      </div>
 
-      <slot name="action" />
+      <div class="brand-drawer__names">
+        <div class="brand-drawer__app">{{ props.title || APP_NAME }}</div>
+        <div class="brand-drawer__suite">iService 365</div>
+      </div>
+    </div>
+
+    <v-list>
+      <!--
+        The site selector, in the design's bordered card. The slot's CONTENTS
+        are whatever the application puts there, still inside the same
+        `v-list` it has always been inside - this only draws the box around it.
+      -->
+      <div v-if="$slots.action" class="brand-drawer__context">
+        <slot name="action" />
+      </div>
 
       <!-- NAVIGATION ITEMS -->
-      <v-tooltip
-        v-for="(item, index) in navigationItems"
+      <template
+        v-for="({ item, section }, index) in sectionedItems"
         :key="`${item.title}-${index}`"
-        location="right"
-        :disabled="!item.disabled"
       >
-        <template #activator="{ props: tooltipProps }">
-          <div v-bind="tooltipProps">
-            <NavigationItem
-              :title="item.title"
-              :icon="item.icon"
-              :route="item.route"
-              :children="item.children"
-              :link="item.link"
-              :class="{
-                'opacity-50 pointer-events-none': item.disabled,
-              }"
-              @click="() => handleClick(item)"
-            />
-          </div>
-        </template>
-
-        <span>Please complete onboarding first</span>
-      </v-tooltip>
+        <div v-if="section" class="brand-drawer__section">{{ section }}</div>
+
+        <v-tooltip location="right" :disabled="!item.disabled">
+          <template #activator="{ props: tooltipProps }">
+            <div v-bind="tooltipProps">
+              <NavigationItem
+                :title="item.title"
+                :icon="item.icon"
+                :route="item.route"
+                :children="item.children"
+                :link="item.link"
+                :class="{
+                  'opacity-50 pointer-events-none': item.disabled,
+                }"
+                @click="() => handleClick(item)"
+              />
+            </div>
+          </template>
+
+          <span>Please complete onboarding first</span>
+        </v-tooltip>
+      </template>
 
       <!-- SERVICES SLOT -->
       <slot name="services" />
@@ -94,6 +122,8 @@
 <script setup lang="ts">
 import { useDisplay } from "vuetify";
 
+import { withSections } from "../../utils/nav-sections";
+
 const props = defineProps({
   navigationItems: { type: Array, required: true },
   title: { type: String, default: "" },
@@ -163,6 +193,39 @@ const navigationItems = computed(() => {
   return items;
 });
 
+const sectionedItems = computed(() => withSections(navigationItems.value));
+
+/**
+ * The design's brand tile carries the product's own mark. One icon for eleven
+ * applications would be one application's icon on ten of them, so the tile
+ * follows `APP_NAME` - the same value the row already prints - and falls back
+ * to the suite's shield for anything not listed.
+ */
+const BRAND_ICONS: Record<string, string> = {
+  security: "mdi-shield-check",
+  "property-management": "mdi-office-building",
+  hygiene: "mdi-broom",
+  landscape: "mdi-flower",
+  "pest-control": "mdi-bug",
+  "pool-mgmt": "mdi-pool",
+  "mechanical-electrical": "mdi-flash",
+  admin: "mdi-shield-crown",
+  org: "mdi-domain",
+  account: "mdi-account-circle",
+  main: "mdi-view-grid",
+};
+
+const brandIcon = computed(() => {
+  // `APP_NAME` is an environment value and is spelled for people ("Property
+  // Management"), so it is normalised rather than matched literally.
+  const key = String(APP_NAME ?? "")
+    .toLowerCase()
+    .trim()
+    .replace(/[\s_]+/g, "-");
+
+  return BRAND_ICONS[key] ?? "mdi-shield-check";
+});
+
 const handleClick = (item: any) => {
   if (item.disabled) return;
   emit("navigate", item);
@@ -175,5 +238,165 @@ const handleClick = (item: any) => {
   --v-border-opacity: 0.45;
   --v-hover-opacity: 0.08;
   --v-activated-opacity: 0.18;
+
+  /**
+   * Phase 1 loaded Manrope and named it `--font-sans` but deliberately set it
+   * on nothing: switching eleven applications to a new typeface before a
+   * single surface had been rebuilt would have left the product looking
+   * half-migrated. The shell IS the surface Phase 2 rebuilds, so it is the
+   * first thing to wear it.
+   */
+  font-family: var(--font-sans);
+}
+
+/* ---------------------------------------------------------------- */
+/* The brand row: 34px accent tile + product name + suite name.      */
+/* ---------------------------------------------------------------- */
+
+.brand-drawer__brand {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 14px 16px 10px;
+}
+
+.brand-drawer__logo {
+  flex: 0 0 34px;
+  width: 34px;
+  height: 34px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  border-radius: var(--r-inner);
+  /* A white glyph, so the fill has to be the one accent that carries white:
+     `--accent` is 3.23:1 under it, `--accent-strong` is 4.57:1. */
+  background: var(--accent-strong);
+  color: var(--on-accent-strong);
+}
+
+.brand-drawer__names {
+  min-width: 0;
+}
+
+.brand-drawer__app {
+  font-size: var(--fs-card-title);
+  font-weight: var(--fw-card-title);
+  line-height: 1.2;
+  color: var(--text);
+  overflow: hidden;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+  text-transform: capitalize;
+}
+
+.brand-drawer__suite {
+  font-size: 11.5px;
+  font-weight: 600;
+  line-height: 1.3;
+  color: var(--muted);
+}
+
+/**
+ * The organisation / site selector, drawn as the design's bordered card.
+ *
+ * Two applications have no selector to draw: `web-app-admin` passes no slot at
+ * all (handled by the `v-if`), and `web-app-org`'s super-admin layout passes an
+ * EMPTY one - `<template #action> </template>` - which the `v-if` cannot see.
+ * An empty bordered box on that rail would be a box around nothing, so a card
+ * with no element inside it is not drawn.
+ */
+.brand-drawer__context:not(:has(*)) {
+  display: none;
+}
+
+.brand-drawer__context {
+  margin: 2px 4px 4px;
+  border: 1px solid var(--border);
+  border-radius: var(--r-inner-lg);
+  background: var(--card);
+  overflow: hidden;
+}
+
+/* ---------------------------------------------------------------- */
+/* Section labels and the menu items under them.                     */
+/* ---------------------------------------------------------------- */
+
+.brand-drawer__section {
+  padding: 14px 12px 6px;
+  font-size: var(--fs-section-label);
+  font-weight: var(--fw-section-label);
+  letter-spacing: var(--ls-section-label);
+  line-height: 1.2;
+  text-transform: uppercase;
+  color: var(--muted);
+}
+
+/* The first label sits directly under the site selector, so it does not need
+   the separating space the ones between two menu blocks do. */
+.brand-drawer__section:first-child {
+  padding-top: 4px;
+}
+
+/**
+ * `:deep` because the items are `NavigationItem`s - a child component - and
+ * the design's item shape (10px radius, 8px 12px, 13px label) belongs to the
+ * rail rather than to that component, which is also rendered elsewhere.
+ *
+ * ONLY shape and type. The active state's colour still comes from
+ * `color="primary"` on the item itself, which is `--accent-text`.
+ */
+.brand-drawer :deep(.v-list) {
+  padding: 0 8px 12px;
+}
+
+/**
+ * The two `!important`s are not carelessness: Vuetify puts `rounded-0` and
+ * `text-subtitle-2` ON the item, and both of those are utility classes that
+ * are themselves `!important`. Nothing weaker can reach the design's 10px
+ * radius or its 13px label. Both are confined to `.brand-drawer`.
+ */
+.brand-drawer :deep(.v-list-item) {
+  border-radius: var(--r-inner) !important;
+  min-height: 38px;
+  padding-top: 8px;
+  padding-bottom: 8px;
+  padding-inline: 12px;
+  font-size: var(--fs-nav) !important;
+}
+
+.brand-drawer :deep(.v-list-item__prepend > .v-icon) {
+  font-size: 19px;
+  opacity: 1;
+}
+
+/* Vuetify's own 16px gap between the icon and the label, brought to the 10px
+   the design draws. The spacer element is what holds that distance - a margin
+   on the icon leaves it where it was. */
+.brand-drawer :deep(.v-list-item__spacer) {
+  width: 10px;
+}
+
+.brand-drawer :deep(.v-list-item--active) {
+  font-weight: var(--fw-section-label);
+}
+
+/**
+ * The design's active item is a 12% accent wash, which is exactly what
+ * `--accent-soft` is. Vuetify paints the same idea with an overlay whose
+ * opacity is theme-wide, so the fill is stated here instead of leaving the
+ * rail's active row to a number tuned for tables and cards.
+ */
+.brand-drawer :deep(.v-list-item--active > .v-list-item__overlay) {
+  opacity: 0;
+}
+
+.brand-drawer :deep(.v-list-item--active) {
+  background: var(--accent-soft);
+}
+
+/* A child row indents by the icon slot it does not have, so the labels of a
+   group line up with the labels of its siblings rather than with their icons. */
+.brand-drawer :deep(.v-list-group__items .v-list-item) {
+  padding-inline-start: 41px !important;
 }
 </style>

package/package.json

@@ -2,7 +2,7 @@
   "name": "@7365admin1/layer-common",
   "license": "MIT",
   "type": "module",
-  "version": "3.2.2-staging.81",
+  "version": "3.2.2-staging.82",
   "author": "7365admin1",
   "main": "./nuxt.config.ts",
   "publishConfig": {

package/utils/nav-sections.test.ts

@@ -0,0 +1,131 @@
+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. A label is decoration; the menu is the product. If
+ * this ever fails, someone has taught the sidebar to reorder itself.
+ */
+test("the menu comes back in the order it went in, item for item", () => {
+  const out = withSections(SECURITY);
+
+  assert.equal(out.length, SECURITY.length);
+  out.forEach((entry, i) => {
+    assert.equal(entry.item, SECURITY[i], `position ${i}`);
+  });
+});
+
+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. The heading is printed again rather than left off, so no
+ * item ever sits under a heading that is not its own.
+ */
+test("a section that comes back later is labelled again, not orphaned", () => {
+  const out = withSections([
+    { title: "Feedbacks" },
+    { title: "Equipment Items" },
+    { title: "Work Orders" },
+  ]);
+
+  assert.deepEqual(
+    out.map((e) => e.section),
+    ["SERVICE DESK", "EQUIPMENT", "SERVICE DESK"]
+  );
+});
+
+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,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 : "" };
+  });
+}