@7365admin1/layer-common 4.73.0 → 4.73.1-staging.452

package/composables/useHidReaderSelection.ts

@@ -0,0 +1,50 @@
+import {
+  EMPTY_HID_READER_CHOICE,
+  resolveHidReaderId,
+  type HidReaderChoice,
+} from "../utils/hid-reader-selection";
+
+/**
+ * ONE HID READER CHOICE, SHARED BY EVERY HID SCREEN.
+ *
+ * Declared at MODULE scope on purpose. Each screen held its own `ref("")`, and
+ * because the HID screens are separate pages the ref was rebuilt on every
+ * navigation — HID Reader Users, HID Cards, Access Logs and HID QR Code each
+ * reset to the first reader no matter what had just been picked next door.
+ *
+ * A module-scoped ref is enough because moving between those pages is a ROUTE
+ * change, not a page load: the menu's items carry a `route` and
+ * `NavigationItem.vue` renders them through `:to`, so vue-router handles them
+ * and this module is never re-evaluated.
+ *
+ * Deliberately NOT persisted. `localStorage` would carry the choice through a
+ * hard refresh as well, which is a real but much smaller benefit than the
+ * navigation case, and it is worth adding only once somebody has felt the
+ * absence. See `utils/hid-reader-selection.ts` for the staleness rule that
+ * would have to hold either way.
+ *
+ * Intercom keeps its own reader and is not wired to this. Its question is which
+ * panel you are calling, not which door you are administering, and joining them
+ * would mean switching reader on Access Logs changed who you would dial.
+ */
+const choice = ref<HidReaderChoice>({ ...EMPTY_HID_READER_CHOICE });
+
+export default function useHidReaderSelection() {
+  /** Remember a choice. The site travels with it; an id alone means nothing. */
+  function selectHidReader(siteId: string, readerId: string) {
+    choice.value = { siteId: String(siteId ?? ""), readerId: String(readerId ?? "") };
+  }
+
+  /**
+   * The reader this screen should show, given the readers it just loaded.
+   *
+   * Call it after the reader list arrives, and write the answer back with
+   * `selectHidReader` so the screens agree on what "current" means even when
+   * one of them had to fall back to the first reader.
+   */
+  function resolveForSite(siteId: string, readers: readonly { _id?: unknown }[]) {
+    return resolveHidReaderId(siteId, readers, choice.value);
+  }
+
+  return { choice, selectHidReader, resolveForSite };
+}

package/composables/useMember.ts

@@ -70,6 +70,8 @@ export default function useMember() {
     status = "active",
     siteId = "",
     roleState = "",
+    /** A building unit id, or "none": members on no unit yet. */
+    unit = "",
   } = {}) {
     const query: Record<string, any> = { page, limit, type, status };
 
@@ -79,6 +81,7 @@ export default function useMember() {
     if (user) query.user = user;
     if (org) query.org = org;
     if (siteId) query.siteId = siteId;
+    if (unit) query.unit = unit;
     return useNuxtApp().$api<Record<string, any>>("/api/members", {
       method: "GET",
       query,
@@ -154,6 +157,14 @@ export default function useMember() {
     });
   }
 
+  /** Attach a member to a building unit, or detach them (`unit` ""). */
+  function updateMemberUnit(id: string, unit: string) {
+    return useNuxtApp().$api<Record<string, any>>("/api/members/unit", {
+      method: "PUT",
+      body: { id, unit },
+    });
+  }
+
   function getByUserTypeOrg(user: string, type: string, org: string) {
     return useNuxtApp().$api<TMember>(
       `/api/members/user/${user}/app/${type}/org`,
@@ -197,6 +208,7 @@ export default function useMember() {
   return {
     getSiteAccess,
     saveSiteAccess,
+    updateMemberUnit,
     members,
     member,
     page,

package/composables/usePeople.ts

@@ -115,6 +115,24 @@ export default function () {
     });
   }
 
+  /**
+   * The blocks, levels and units at a site that actually have an occupant.
+   * The other half of the unit picker: this narrows the cascade, then
+   * `getPeopleByUnit` answers "which person in this unit?".
+   */
+  async function getOccupiedStructure(
+    site: string,
+    { type = "", status = "active", block = "", level = "" } = {}
+  ) {
+    return await useNuxtApp().$api<Record<string, any>>(
+      `/api/people/site/${site}/occupied-structure`,
+      {
+        method: "GET",
+        query: { type, status, block, level },
+      }
+    );
+  }
+
   async function getPeopleByUnit(
     _id: string,
     { status = "active", type = "" } = {}
@@ -148,6 +166,7 @@ export default function () {
     findPersonByPlateNumberMultipleResult,
     findPersonByContact,
     getPeopleByUnit,
+    getOccupiedStructure,
     searchCompanyList,
     findUsersByPlateNumber,
     reviewResidentPerson,

package/composables/useSecurityPermission.ts

@@ -714,6 +714,21 @@ export default function useSecurityPermission() {
         description:
           "Allows the user to start NFC patrolling on a specific route.",
       },
+      // Copied from Property. The security web app's NFC Patrol > Routes page
+      // gates Add, Edit and Delete on these, and API-core's `nfcPatrol` gate
+      // asks for the same strings on route create and update.
+      "add-nfc-patrol": {
+        check: true,
+        description: "Allows the user to add routes.",
+      },
+      "update-nfc-patrol": {
+        check: true,
+        description: "Allows the user to edit routes.",
+      },
+      "delete-nfc-patrol": {
+        check: true,
+        description: "Allows the user to delete routes.",
+      },
     },
     // NEW. Seeing the CCTV wall, as distinct from setting cameras up
     // (`site-settings:manage-cctv-camera`).
@@ -743,6 +758,11 @@ export default function useSecurityPermission() {
         siteSettingsPermissions["manage-resident-visitors"],
       "manage-work-order-settings":
         siteSettingsPermissions["manage-work-order-settings"],
+      // The security web app's Site Settings shows the NFC Management and NFC
+      // Patrol Settings panels on these, as Property's does.
+      "manage-nfc-management": siteSettingsPermissions["manage-nfc-management"],
+      "manage-nfc-patrol-settings":
+        siteSettingsPermissions["manage-nfc-patrol-settings"],
       "manage-red-dot-settings": {
         check: true,
         description:

package/composables/useServiceProvider.ts

@@ -15,6 +15,9 @@ export type TSiteProviderMember = {
   lastLoginAt?: string | null;
   /** a subcontractor: the provider that brought its company onto the site */
   invitedVia?: string;
+  /** The building unit this person is attached to (a unit's Management tab). */
+  unit?: string | null;
+  unitName?: string;
 };
 
 export type TSiteProviderCompany = {
@@ -90,6 +93,8 @@ export default function useServiceProvider() {
     status = "",
     /** "engagements": also providers engaged through an accepted invitation. */
     include = "",
+    /** A building unit id, or "none": providers on no unit yet. */
+    unit = "",
   } = {}) {
     return useNuxtApp().$api<Record<string, any>>("/api/service-providers", {
       method: "GET",
@@ -102,6 +107,7 @@ export default function useServiceProvider() {
         siteId,
         ...(status ? { status } : {}),
         ...(include ? { include } : {}),
+        ...(unit ? { unit } : {}),
       },
     });
   }
@@ -269,6 +275,17 @@ export default function useServiceProvider() {
     );
   }
 
+  /** Attach a provider to a building unit, or detach it (`unit` ""). */
+  async function updateUnit(id: string, unit: string) {
+    return useNuxtApp().$api<Record<string, any>>(
+      `/api/service-providers/${id}/unit`,
+      {
+        method: "PATCH",
+        body: { unit },
+      }
+    );
+  }
+
    async function getByEmail({
     email = "",
     orgId = "",
@@ -293,17 +310,29 @@ export default function useServiceProvider() {
    * Members > Service Providers: the provider people with access to this
    * site, and one entry per provider company with its head count. The
    * site's own organisation only - the server refuses anyone else.
+   * `unit`: a building unit id, or "none" (people on no unit yet).
    */
-  function getSiteMembers(siteId: string): Promise<{
+  function getSiteMembers(siteId: string, unit = ""): Promise<{
     items: TSiteProviderMember[];
     companies: TSiteProviderCompany[];
   }> {
     return useNuxtApp().$api("/api/service-providers/site-members", {
       method: "GET",
-      query: { siteId },
+      query: { siteId, ...(unit ? { unit } : {}) },
     });
   }
 
+  /** Attach one of those people to a building unit, or detach them (`unit` ""). */
+  function updateSiteMemberUnit(id: string, unit: string) {
+    return useNuxtApp().$api<Record<string, any>>(
+      `/api/service-providers/site-members/${id}/unit`,
+      {
+        method: "PATCH",
+        body: { unit },
+      }
+    );
+  }
+
   /** The same list as an Excel file, under the same filters. */
   function exportSiteMembers(
     siteId: string,
@@ -320,6 +349,7 @@ export default function useServiceProvider() {
 
   return {
     getSiteMembers,
+    updateSiteMemberUnit,
     exportSiteMembers,
     serviceProviders,
     serviceProvider,
@@ -338,6 +368,7 @@ export default function useServiceProvider() {
     add,
     addViaInvite,
     updateStatus,
+    updateUnit,
     getByEmail,
   };
 }

package/composables/useSiteCategory.ts

@@ -0,0 +1,45 @@
+/**
+ * THE CATEGORY OF THE SITE THE USER IS CURRENTLY IN.
+ *
+ * One shared answer, published once by the application's layout from the site
+ * it already loaded for the switcher, and read by anything that has to behave
+ * differently on a commercial or industrial site - the business Add Tenant
+ * form, the tenant list. Publishing it rather than re-fetching it per
+ * component means no two screens can disagree about which site this is.
+ *
+ * READ FROM THE CUSTOMER-SITE RECORD, NOT THE SITE RECORD. Both carry a
+ * `category` and `customer-site.service` keeps them equal (it writes the site
+ * on create and on update), but `siteSchema` DEFAULTS the site's own copy to
+ * `commercial` - so a site created without an explicit category reads back as
+ * commercial there even when it is a residential estate. The customer-site
+ * copy has no default: it is either the category somebody chose or nothing.
+ *
+ * An empty category means "not published yet" or "never set", and every
+ * caller must behave as it did before this existed - never assume commercial
+ * from silence.
+ */
+const BUSINESS_SITE_CATEGORIES: string[] = ["commercial", "industrial"];
+
+export default function useSiteCategory() {
+  const siteCategory = useState<string>("current-site-category", () => "");
+
+  function setSiteCategory(value?: string | null) {
+    siteCategory.value = typeof value === "string" ? value : "";
+  }
+
+  /**
+   * The categories whose units are LET TO A BUSINESS rather than lived in.
+   *
+   * These are the sites where a unit has an owner, an occupier and often a
+   * person in charge who is neither, so they are the sites that ask for a
+   * tenant's standing and print it back (see `OCCUPANCY_ROLE_OPTIONS`).
+   *
+   * The category never changes what the APPLICATION is called: the rail says
+   * Property Management on every site it serves.
+   */
+  const isBusinessSite = computed(() =>
+    BUSINESS_SITE_CATEGORIES.includes(siteCategory.value),
+  );
+
+  return { siteCategory, isBusinessSite, setSiteCategory };
+}

package/package.json

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

package/pages/[org]/[site]/access-mgmt/administrator/index.vue

@@ -5,7 +5,7 @@
       :org="orgId"
       message="Enable HID as a service for this site before managing HID users."
     >
-      <HidUserEnrollment :site="siteId" />
+      <HidUserEnrollment :site="siteId" :org="orgId" />
     </HidEnabledGate>
   </v-container>
 </template>

package/pages/[org]/[site]/access-mgmt/hid-cards/index.vue

@@ -5,7 +5,7 @@
       :org="orgId"
       message="Enable HID as a service for this site before managing physical HID cards."
     >
-      <HidUserEnrollment :site="siteId" card-management />
+      <HidUserEnrollment :site="siteId" :org="orgId" card-management />
     </HidEnabledGate>
   </v-container>
 </template>

package/pages/[org]/[site]/access-mgmt/hid-qr-code/index.vue

@@ -0,0 +1,23 @@
+<template>
+  <v-container fluid>
+    <HidEnabledGate
+      :site="siteId"
+      :org="orgId"
+      message="Enable HID as a service for this site before generating a QR code."
+    >
+      <HidProfileQrCode :site="siteId" />
+    </HidEnabledGate>
+  </v-container>
+</template>
+
+<script setup lang="ts">
+definePageMeta({
+  layout: "default",
+  middleware: ["01-auth", "02-org"],
+  memberOnly: true,
+});
+
+const route = useRoute();
+const siteId = computed(() => String(route.params.site ?? ""));
+const orgId = computed(() => String(route.params.org ?? ""));
+</script>

package/pages/[org]/[site]/access-mgmt/hid-readers/index.vue

@@ -5,7 +5,7 @@
       :org="orgId"
       message="Enable HID as a service for this site before managing HID readers."
     >
-      <HidReaderManagement :site="siteId" />
+      <HidReaderManagement :site="siteId" :org="orgId" />
     </HidEnabledGate>
   </v-container>
 </template>

package/types/document.d.ts

@@ -3,4 +3,18 @@ declare type TDocument = {
   name: string;
   attachment: string;
   type: string;
+  /**
+   * Set at upload or renewal, absent when the document never expires.
+   *
+   * An ISO instant on the way out of the API and a `YYYY-MM-DD` string on the
+   * way back in, which is what `InputDatePicker` binds to - hence the loose
+   * type rather than `string`.
+   */
+  expiryDate?: string | Date | null;
+  remarks?: string;
+  size?: number;
+  parentId?: string | null;
+  createdAt?: string | Date;
+  updatedAt?: string | Date;
+  status?: string;
 };

package/types/facility.d.ts

@@ -73,6 +73,10 @@ declare type TFacility = {
   hourInterval?: number;
   isBookingFeeEnabled: boolean;
   isGuestEnabled: boolean;
+  /** Residents may complete this facility's checklist themselves. */
+  isResidentChecklistEnabled?: boolean;
+  /** Security may complete it. Mutually exclusive with the above. */
+  isSecurityChecklistEnabled?: boolean;
   bookingAmount: number | null;
   peakBookingFeeAmount?: number | null;
   bookingFeeGuestAmount?: number | null;

package/types/member.d.ts

@@ -10,6 +10,10 @@ declare type TMember = {
   customerOrgId?: string;
   customerSiteId?: string;
   status?: string;
+  email?: string;
+  /** The building unit this member manages (a unit's Management tab). */
+  unit?: string | null;
+  unitName?: string;
   createdAt?: string;
   updatedAt?: string;
   deletedAt?: string;

package/types/people.d.ts

@@ -22,11 +22,38 @@ declare type TPeople = {
   email?: string;
   files?: { name: string, id: string }[];
   isOwner?: boolean;
+  /**
+   * Owner / occupant / person-in-charge, as the BUSINESS people form asks it.
+   * Absent on everyone else - `isOwner` is still the flag that decides unit
+   * ownership, and the server derives it from this when it is sent. See
+   * `OccupancyRoles` in core's `person.model.ts`.
+   */
+  occupancyRole?: TOccupancyRole;
+  // Link to this person's `users` row. Empty for the person types that carry
+  // no login, and empty for a resident whose account was never written.
+  user?: string;
+};
+
+declare type TOccupancyRole = "owner" | "occupant" | "person-in-charge";
+
+/** One standing and everything the product says about it. See `utils/occupancy-role.ts`. */
+declare type TOccupancyRoleOption = {
+  value: TOccupancyRole;
+  /** The label a stored role is printed with. */
+  title: string;
+  /** The row menu's wording. */
+  action: string;
+  /** The confirmation's heading and its sentence. */
+  prompt: string;
+  description: string;
 };
 
 declare type TPlateNumber = { plateNumber: string, recNo?: string, _id?: string, status: TVehicleStatus, type: TVehicleType, anprCameras?: TVehicleAnprCamera[] };
 
 
-declare type TPeoplePayload = Pick<TGuest, "name" | "block" | "level" | "unit" | "unitName" | "contact" | "plateNumber" | "nric" | "contact" | "remarks" | "org" | "site" | "start" | "end" | "type" | "isOwner"> & { status?: string }
+// `""` is the FORM's "nothing picked yet" - it is stripped from the payload
+// before it is sent, because absence is what the server reads as "never
+// asked". See `PeopleFormMgmt.vue`.
+declare type TPeoplePayload = Pick<TGuest, "name" | "block" | "level" | "unit" | "unitName" | "contact" | "plateNumber" | "nric" | "contact" | "remarks" | "org" | "site" | "start" | "end" | "type" | "isOwner"> & { status?: string; user?: string; occupancyRole?: TOccupancyRole | "" }
 
 declare type TPeopleType = "guest" | "resident" | "tenant"

package/types/service-provider.d.ts

@@ -7,6 +7,11 @@ declare type TServiceProvider = {
   serviceProviderOrgId: string;
   type: string;
   nature: string;
+  status?: string;
+  email?: string;
+  /** The building unit this provider serves (a unit's Management tab). */
+  unit?: string | null;
+  unitName?: string;
 };
 
 declare type TServiceProviderName = {

package/utils/hid-permission-assignments.ts

@@ -0,0 +1,190 @@
+/**
+ * WHO IS ASSIGNED TO A HID READER — the editing model behind the permissions
+ * dialog.
+ *
+ * This is the step that actually grants access. Enrolling a person gives the
+ * reader a face, a card or a PIN it can RECOGNISE; it puts nobody in the group
+ * the access rule is attached to, so a recognised person is still refused at
+ * the door (access log event 6). `PUT /sites/:siteId/permissions` is the only
+ * call in the system that writes that group membership.
+ *
+ * Two contracts make this file necessary rather than inlining the logic in the
+ * component:
+ *
+ * 1. **The PUT REPLACES the whole assignment set for the reader.** The server
+ *    keeps other readers' rows and overwrites this reader's with exactly what
+ *    is sent. The candidate list, however, is fetched ONE CATEGORY AT A TIME.
+ *    Saving from the tab in front of you while sending only that tab's people
+ *    would silently revoke every resident if you were looking at the service
+ *    providers tab. So the edit state is held for the whole reader and the
+ *    payload is always built from all of it.
+ *
+ * 2. **The body schema accepts three keys and nothing else.**
+ *    `hidPermissionAssignmentSchema` is `{ subjectId, category, intercom }`,
+ *    and Joi rejects unknown keys rather than stripping them. The candidate
+ *    rows carry `name`, `subtitle`, `location` and friends for display, so the
+ *    payload has to be narrowed deliberately — passing a candidate straight
+ *    through is a 400.
+ */
+
+/** The three real categories. `intercom` is a candidate FILTER, never a category. */
+export const HID_PERMISSION_CATEGORIES: THidPermissionCategory[] = [
+  "resident",
+  "property_management",
+  "service_provider",
+];
+
+export type HidAssignmentState = Map<string, { category: THidPermissionCategory; intercom: boolean }>;
+
+/** Body row for `updateSitePermissions` — exactly the keys Joi allows. */
+export type HidAssignmentPayload = {
+  subjectId: string;
+  category: THidPermissionCategory;
+  intercom: boolean;
+};
+
+function isRealCategory(value: unknown): value is THidPermissionCategory {
+  return HID_PERMISSION_CATEGORIES.includes(value as THidPermissionCategory);
+}
+
+/**
+ * The reader's CURRENT assignments, as the edit state.
+ *
+ * Seeded from `getSitePermissions`, which returns every category at once —
+ * that is what makes a whole-reader payload possible from a one-category view.
+ * Rows with an unrecognised category are dropped rather than carried: sending
+ * one back fails the enum check and takes the entire save with it.
+ */
+export function seedAssignments(
+  assignments: readonly THidPermissionAssignment[] | undefined | null,
+): HidAssignmentState {
+  const state: HidAssignmentState = new Map();
+  if (!Array.isArray(assignments)) return state;
+  for (const assignment of assignments) {
+    const subjectId = String(assignment?.subjectId ?? "");
+    if (!subjectId || !isRealCategory(assignment?.category)) continue;
+    state.set(subjectId, {
+      category: assignment.category,
+      intercom: assignment.intercom === true,
+    });
+  }
+  return state;
+}
+
+/**
+ * Add or remove one person.
+ *
+ * `saved` is the state the dialog opened with, and it is consulted for one
+ * reason: the `intercom` flag. Nothing here edits that flag, but
+ * `userHasSiteIntercomPermission` reads it off these same rows, so it must
+ * survive a round trip through the checkbox.
+ *
+ * - **Untick then save** drops it, which is right — an unassigned person
+ *   holding a dangling intercom right would keep answering the door panel
+ *   after losing the door.
+ * - **Untick then re-tick, without saving** must restore it. Removing from the
+ *   draft forgets the flag, so re-adding recovers it from `saved`; otherwise a
+ *   misclick corrected a second later would silently revoke intercom on the
+ *   next save, with nothing on screen to show it had happened.
+ */
+export function setAssignment(
+  state: HidAssignmentState,
+  saved: HidAssignmentState,
+  subjectId: string,
+  category: THidPermissionCategory,
+  selected: boolean,
+): HidAssignmentState {
+  const next: HidAssignmentState = new Map(state);
+  const id = String(subjectId ?? "");
+  if (!id || !isRealCategory(category)) return next;
+  if (!selected) {
+    next.delete(id);
+    return next;
+  }
+  const intercom = next.get(id)?.intercom ?? saved.get(id)?.intercom ?? false;
+  next.set(id, { category, intercom: intercom === true });
+  return next;
+}
+
+/** The whole reader's assignments, narrowed to the three keys the API accepts. */
+export function toAssignmentPayload(state: HidAssignmentState): HidAssignmentPayload[] {
+  return [...state.entries()].map(([subjectId, value]) => ({
+    subjectId,
+    category: value.category,
+    intercom: value.intercom === true,
+  }));
+}
+
+/**
+ * The server sends `selected` with each candidate, describing what is SAVED.
+ * Once the dialog is open the local edit state is the truth, so the flag is
+ * recomputed rather than trusted — otherwise paging or searching would redraw
+ * a row with the saved value and quietly discard an unsaved tick.
+ */
+export function applySelection(
+  candidates: readonly THidPermissionCandidate[] | undefined | null,
+  state: HidAssignmentState,
+): THidPermissionCandidate[] {
+  if (!Array.isArray(candidates)) return [];
+  return candidates.map((candidate) => ({
+    ...candidate,
+    selected: state.has(String(candidate?.subjectId ?? "")),
+  }));
+}
+
+/** Per-category totals for the dialog header, counted over the whole reader. */
+export function countByCategory(state: HidAssignmentState): Record<THidPermissionCategory, number> {
+  const counts = { resident: 0, property_management: 0, service_provider: 0 } as Record<
+    THidPermissionCategory,
+    number
+  >;
+  for (const value of state.values()) counts[value.category] += 1;
+  return counts;
+}
+
+/** Has anything changed since the dialog opened? Drives the Save button. */
+export function hasChanges(saved: HidAssignmentState, draft: HidAssignmentState): boolean {
+  if (saved.size !== draft.size) return true;
+  for (const [subjectId, value] of draft) {
+    const before = saved.get(subjectId);
+    if (!before) return true;
+    if (before.category !== value.category) return true;
+    if (before.intercom !== value.intercom) return true;
+  }
+  return false;
+}
+
+/**
+ * What a listing response tells us: the rows, and how many pages exist.
+ *
+ * It deliberately does NOT return the current page, and the caller must keep
+ * owning that. `paginate` in `@7365admin1/node-server-utils` returns only
+ * `{ items, pages, pageRange }` — it never echoes the page it was asked for. A
+ * caller that read one back therefore got a default on every fetch and pinned
+ * itself to page one, so the pager moved and the rows never did.
+ *
+ * `items` sits at the root on some of these endpoints and under `data` on
+ * others, so both are read.
+ */
+export function readCandidatePage(response: unknown): {
+  items: THidPermissionCandidate[];
+  pages: number;
+  pageRange: string;
+} {
+  const source = (response && typeof response === "object" ? response : {}) as Record<string, unknown>;
+  const nested = (source.data && typeof source.data === "object" ? source.data : {}) as Record<string, unknown>;
+  const items = Array.isArray(source.items)
+    ? source.items
+    : Array.isArray(nested.items)
+      ? nested.items
+      : [];
+  const pages = Number(source.pages ?? nested.pages ?? 1);
+  // `paginate` builds this ("1-10 of 37") and the table renders it verbatim.
+  // Without it the pager draws its placeholder, "-- - -- of --".
+  const pageRange = String(source.pageRange ?? nested.pageRange ?? "");
+  return {
+    items: items as THidPermissionCandidate[],
+    pages: Number.isFinite(pages) && pages > 0 ? pages : 1,
+    pageRange,
+  };
+}