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

package/components/Layout/NavigationDrawer.vue

@@ -28,45 +28,90 @@
       primary-tinted fill (see `NavigationItem.vue`); 0.12 left the fill at
       1.15:1, 0.18 is 1.44:1 light, 1.33:1 dark.
   -->
+  <!--
+    RESPONSIVE: THE RAIL BECOMES AN OVERLAY BELOW 1024px.
+
+    `permanent` was hardcoded, which is why the prototype's own behaviour - and
+    ours - was a 252px rail still sitting there on a 360px phone with the
+    content squeezed into what was left. Dropping `permanent` and naming the
+    breakpoint hands the whole behaviour to Vuetify: at >= 1024 the drawer is
+    part of the layout exactly as it is today, and below it the same drawer
+    becomes temporary, floats OVER the content with a scrim, and closes on the
+    scrim, on Escape and on a navigation.
+
+    1024 rather than Vuetify's default 1280: at 1024 the rail still leaves a
+    772px content column, which is a usable table. Below that it does not.
+
+    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"
-    permanent
+    :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" />
@@ -75,6 +120,10 @@
 </template>
 
 <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: "" },
@@ -85,6 +134,32 @@ const emit = defineEmits(["navigate"]);
 const { drawer } = useLocal();
 const { APP_NAME } = useRuntimeConfig().public;
 const route = useRoute();
+
+/**
+ * `drawer` is shared application state and it defaults to OPEN, which is right
+ * for a rail and wrong for an overlay - a phone would load with the menu
+ * covering the page behind a scrim. So the default follows the viewport, and a
+ * user who resizes past the breakpoint gets the state that suits where they
+ * landed.
+ *
+ * Only the DEFAULT is managed here. Once the hamburger has been used, the
+ * user's choice stands until the layout itself changes underneath them.
+ */
+const { mobile } = useDisplay({ mobileBreakpoint: 1024 });
+
+watch(mobile, (isOverlay) => (drawer.value = !isOverlay), { immediate: true });
+
+/**
+ * An overlay drawer that survives a navigation leaves the scrim over the page
+ * the user just asked for. A rail must NOT close - that would be a step added
+ * to every desktop navigation.
+ */
+watch(
+  () => route.fullPath,
+  () => {
+    if (mobile.value) drawer.value = false;
+  }
+);
 const orgId = computed(() => String(route.params.org ?? ""));
 const siteId = computed(() => String(route.params.site ?? ""));
 const { useHidFaceReaderMenu } = useHidNavigation();
@@ -118,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);
@@ -130,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/composables/useThemePreference.ts

@@ -0,0 +1,63 @@
+/**
+ * THE USER'S LIGHT/DARK CHOICE, REMEMBERED.
+ *
+ * Until now `Layout/Header.vue` flipped `theme.global.name` and wrote nothing,
+ * so the choice was gone on the next reload.
+ *
+ * A COOKIE, NOT localStorage. The handoff says "persists in localStorage", and
+ * for a single-page prototype that is right - but this product is ELEVEN
+ * applications on eleven hostnames. localStorage is per-origin, so a user who
+ * picked dark mode in Security would land on a white screen in Property
+ * Management, and again in Account, and would have to set it eleven times.
+ *
+ * A cookie written with the layer's own `cookieConfig` carries the parent
+ * domain, which is exactly how `sid`, `user` and `landing-page` already travel
+ * between these applications. So this is the estate's existing preference
+ * mechanism rather than a new one, and it is also the only one that makes the
+ * setting mean what a user expects it to mean.
+ *
+ * NO FLASH OF THE WRONG THEME. Nothing here corrects the theme after mount -
+ * `plugins/vuetify.ts` reads the same cookie BEFORE `createVuetify` and boots
+ * on it, so the first paint is already right. The apps are `ssr: false`, so
+ * there is no server render to disagree with.
+ */
+import { useTheme } from "vuetify";
+import type { CookieOptions } from "#app";
+
+export type TThemeName = "light" | "dark";
+
+/** The one place the cookie is named. `plugins/vuetify.ts` reads the same one. */
+export const THEME_COOKIE = "theme";
+
+export default function useThemePreference() {
+  // `runtimeConfig.public.cookieConfig` is typed `unknown`, so it is narrowed
+  // here rather than at every call site. Same object `sid`, `user` and
+  // `landing-page` are written with - it carries the shared parent domain.
+  const cookieConfig = useRuntimeConfig().public.cookieConfig as CookieOptions<
+    TThemeName | null
+  > & { readonly?: false };
+
+  const vuetifyTheme = useTheme();
+
+  const stored = useCookie<TThemeName | null>(THEME_COOKIE, cookieConfig);
+
+  const current = computed<TThemeName>(() =>
+    vuetifyTheme.global.current.value.dark ? "dark" : "light"
+  );
+
+  /**
+   * Sets the theme AND remembers it. The write is the whole point - a caller
+   * that only wants a temporary theme for one subtree should use
+   * `<v-theme-provider>` instead, which is what `plain-dark` does.
+   */
+  function setTheme(name: TThemeName) {
+    vuetifyTheme.global.name.value = name;
+    stored.value = name;
+  }
+
+  function toggleTheme() {
+    setTheme(current.value === "dark" ? "light" : "dark");
+  }
+
+  return { current, setTheme, toggleTheme, stored };
+}

package/nuxt.config.ts

@@ -7,6 +7,37 @@ export default defineNuxtConfig({
     transpile: ["vuetify"],
   },
 
+  /**
+   * THE REDESIGN'S TYPEFACE - LOADED, DELIBERATELY NOT APPLIED YET.
+   *
+   * `--font-sans` in `assets/css/tokens.css` names Manrope, and a token that
+   * names a font nobody loaded is a trap: the next phase writes
+   * `font-family: var(--font-sans)`, silently falls back to Arial, and looks
+   * fine to whoever wrote it. So the stylesheet is requested here.
+   *
+   * Nothing sets `font-family` on the page in Phase 1. Switching eleven
+   * applications to a new typeface before one screen has been rebuilt would
+   * leave the whole product looking half-migrated; each phase adopts the token
+   * as it rebuilds its own surfaces. Browsers do not download a webfont no
+   * element uses, so until then this costs one small CSS request.
+   */
+  app: {
+    head: {
+      link: [
+        { rel: "preconnect", href: "https://fonts.googleapis.com" },
+        {
+          rel: "preconnect",
+          href: "https://fonts.gstatic.com",
+          crossorigin: "",
+        },
+        {
+          rel: "stylesheet",
+          href: "https://fonts.googleapis.com/css2?family=Manrope:wght@400;500;600;700;800&family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200&display=swap",
+        },
+      ],
+    },
+  },
+
   runtimeConfig: {
     public: {
       cookieConfig: {

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.82",
   "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/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);
+  }
+});