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

package/utils/hid-reader-selection.ts

@@ -0,0 +1,52 @@
+/**
+ * WHICH HID READER THE OPERATOR IS WORKING ON — the one rule behind it.
+ *
+ * Every HID screen used to hold its own `ref("")` and default it to
+ * `readers[0]`, so picking HID 2 on HID Reader Users and clicking through to
+ * HID Cards put you back on HID 1. They are separate PAGES, so the component
+ * unmounted and the ref was rebuilt from scratch every time — there was no way
+ * to make a choice stick. "I am working on HID 2" is a mode, not a per-screen
+ * preference.
+ *
+ * Navigation between those pages is a route change rather than a page load
+ * (`NavigationItem.vue` renders the menu's `route` through `:to`), so the
+ * module-scoped ref in `useHidReaderSelection` survives it. This file holds the
+ * part worth testing: deciding whether a remembered choice may still be used.
+ */
+
+export type HidReaderChoice = { siteId: string; readerId: string };
+
+/** Anything with an id — the four screens all carry a different reader shape. */
+type ReaderLike = { _id?: unknown };
+
+export const EMPTY_HID_READER_CHOICE: HidReaderChoice = { siteId: "", readerId: "" };
+
+/**
+ * The reader a screen should show, given what this site actually has.
+ *
+ * A remembered id is honoured ONLY when it belongs to this site and is still in
+ * the list. That single condition covers every way it goes stale:
+ *
+ * - the operator switched site, so the id belongs to a site they have left
+ * - the reader was deleted or deactivated since they chose it
+ * - nothing has been chosen yet
+ *
+ * In all three the first reader is returned instead. The alternative — using
+ * the id anyway — sends requests for a reader the site does not own, which come
+ * back empty and read on screen as a reader with no users, no cards and no
+ * logs, rather than as the mistake it is.
+ */
+export function resolveHidReaderId(
+  siteId: string,
+  readers: readonly ReaderLike[] | null | undefined,
+  choice: HidReaderChoice = EMPTY_HID_READER_CHOICE,
+): string {
+  const ids = (Array.isArray(readers) ? readers : [])
+    .map((reader) => String(reader?._id ?? ""))
+    .filter(Boolean);
+
+  if (choice.siteId === String(siteId ?? "") && ids.includes(choice.readerId)) {
+    return choice.readerId;
+  }
+  return ids[0] ?? "";
+}

package/utils/occupancy-role.ts

@@ -0,0 +1,109 @@
+/**
+ * OWNER / OCCUPANT / PERSON IN CHARGE - the three standings a business
+ * tenancy has, and everything the product says about them.
+ *
+ * One list, because three screens read it: the form that asks the question
+ * (`PeopleFormMgmt`), the list and preview that print the answer back, and
+ * the row menu that reassigns it (`people-mgmt`). The values are the ones the
+ * server stores and validates - `OccupancyRoles` in core's `person.model.ts`
+ * - so a value added on one side has to be added on the other.
+ */
+export const OCCUPANCY_ROLE_OPTIONS: TOccupancyRoleOption[] = [
+  {
+    value: "owner",
+    title: "Owner",
+    action: "Assign Owner",
+    prompt: "Assign Owner",
+    description:
+      "The legal titleholder or primary deed owner of the property.",
+  },
+  {
+    value: "occupant",
+    title: "Occupant",
+    action: "Assign Occupant",
+    prompt: "Assign Occupant",
+    description:
+      "The person currently living in, renting, or utilizing the physical unit.",
+  },
+  {
+    value: "person-in-charge",
+    title: "Person in Charge",
+    action: "Assign Person in Charge",
+    prompt: "Assign Person in Charge (PIC)",
+    description:
+      "The designated manager responsible for maintenance, emergencies, and daily operations.",
+  },
+];
+
+/**
+ * The same three, in the order the ROW MENU draws them, which is not the
+ * order the form's radio does. Derived rather than re-typed so the wording
+ * cannot drift between the two.
+ */
+export const OCCUPANCY_ROLE_ACTIONS: TOccupancyRoleOption[] = (
+  ["person-in-charge", "owner", "occupant"] as TOccupancyRole[]
+).map(
+  (value) =>
+    OCCUPANCY_ROLE_OPTIONS.find(
+      (option) => option.value === value,
+    ) as TOccupancyRoleOption,
+);
+
+/**
+ * The label for a stored role, or "" for a person who was never asked - which
+ * is everyone on a residential site and everyone saved before the question
+ * existed. Callers decide what to print instead; nobody should print a raw
+ * `person-in-charge` at a user.
+ */
+export function occupancyRoleLabel(role?: string | null): string {
+  return (
+    OCCUPANCY_ROLE_OPTIONS.find((option) => option.value === role)?.title ?? ""
+  );
+}
+
+/**
+ * Does this person hold OWNER at their unit?
+ *
+ * The role when there is one, `isOwner` when there is not - the same test the
+ * server applies (`holdsUnitOwner` in core's `unit-owner.util.ts`). A person
+ * recorded before the role existed carries only the flag, and the people list
+ * already prints them as "Owner".
+ */
+export function holdsUnitOwner(person?: {
+  occupancyRole?: string | null;
+  isOwner?: boolean;
+}): boolean {
+  if (!person) return false;
+
+  if (person.occupancyRole) return person.occupancyRole === "owner";
+
+  return person.isOwner === true;
+}
+
+/**
+ * MUST THIS PERSON HAND THE UNIT OVER BEFORE THEY CAN BE DEACTIVATED?
+ *
+ * The owner of a unit does not leave while they still own it - the standing
+ * moves to another tenant at the same block, level and unit first.
+ *
+ * Keyed to the ROLE and never to `isOwner`, exactly as the server keys it
+ * (`mustHandOverBeforeDeactivating` in core): the flag is on every resident in
+ * the estate, and no residential screen can change it, so a rule keyed to it
+ * would trap records that can never satisfy it.
+ */
+export function mustHandOverBeforeDeactivating(person?: {
+  occupancyRole?: string | null;
+}): boolean {
+  return person?.occupancyRole === "owner";
+}
+
+/**
+ * Why a deactivation was held back. The SERVER carries the enforcing copy of
+ * this rule and of these words (core `unit-owner.util.ts`); this one exists so
+ * the console can say it before the round trip rather than after.
+ */
+export function ownerHandoverRequiredMessage(name?: string): string {
+  const who = name?.trim() ? `"${name.trim()}"` : "This person";
+
+  return `${who} is the owner of this unit. Assign the owner role to another tenant at the same block, level and unit before deactivating them.`;
+}

package/utils/service-type.ts

@@ -0,0 +1,30 @@
+/**
+ * A SERVICE PROVIDER'S LINE OF BUSINESS, AS PEOPLE NAME IT.
+ *
+ * `/api/service-providers` returns the service CODE (`mechanical_electrical_services`),
+ * which is a database value, not something to show an operator. This is the same
+ * mapping `API-core src/utils/converter.ts spmServiceNewToOld` applies — copied
+ * rather than imported, because that is a server package this layer does not
+ * depend on.
+ *
+ * NOT the same labels as `utils/module-applications.ts APPLICATIONS`. Those name
+ * the seven role-permission applications ("Mechanical & electrical", "Pest
+ * control") and are keyed `mechanical-electrical`, not `*_services`. These are
+ * the shorter names the service-provider screens use ("M&E", "Pest Control").
+ *
+ * An unknown code is returned untouched: a new service type shows as its raw
+ * code, which is visibly odd, rather than vanishing from the row.
+ */
+const SERVICE_TYPE_LABELS: Readonly<Record<string, string>> = Object.freeze({
+  security_agency: "Security",
+  cleaning_services: "Cleaning",
+  pool_maintenance_services: "Pool Maintenance",
+  pest_control_services: "Pest Control",
+  landscaping_services: "Landscape",
+  mechanical_electrical_services: "Mechanical & Electrical",
+});
+
+export function serviceTypeLabel(service: string | null | undefined): string {
+  const code = String(service ?? "");
+  return SERVICE_TYPE_LABELS[code] ?? code;
+}