@7365admin1/layer-common 3.1.4-staging.53 → 3.1.4-staging.55

package/utils/camera-wall.ts

@@ -0,0 +1,281 @@
+/**
+ * THE CAMERA WALL'S RULES, WITH NO MARKUP IN THEM.
+ *
+ * `CameraWall.vue` draws the wall; this file decides what it is allowed to draw.
+ * Keeping the two apart is not tidiness — every rule below is one somebody can
+ * get wrong in a way nobody notices until a supervisor is looking at the wrong
+ * picture, so each one is stated once, here, and pinned by `camera-wall.test.ts`.
+ *
+ * ## The four rules
+ *
+ * 1. **Only `type: "ip"` cameras go on a wall.** An ANPR unit belongs to visitor
+ *    and vehicle management: it is pointed at a number plate, it is wired to a
+ *    barrier, and its record carries a real device address and a real credential.
+ *    Putting one on a monitoring wall is a defect, not a feature. The request
+ *    already asks the server for `type=ip`; `wallCameras()` filters again on the
+ *    way in, because "the caller passed the right query" is an assumption and
+ *    this is the rule.
+ * 2. **A capability we have not been told about is NOT available.** An absent or
+ *    malformed descriptor reads as `unknown`, and `unknown` counts as no — so a
+ *    browser talking to an older API cannot draw a control that would do nothing.
+ * 3. **A control that is off is drawn, dimmed, and says why** — never hidden. The
+ *    sentence shown is the SERVER'S own sentence, never rewritten here, so a
+ *    camera cannot explain itself two different ways on two screens.
+ * 4. **"Live" means a picture is arriving**, not "we asked for one". The tile
+ *    says `Connecting…` until the player page is actually up, and `No signal`
+ *    when it never comes.
+ *
+ * These match the iSecure365 mobile monitoring build one for one, deliberately:
+ * the same product should not answer the same question differently on a phone
+ * and on a laptop.
+ */
+
+/** One capability's answer, as the API returns it (core's `CameraCapabilityEntry`). */
+export type TWallCapability = {
+  state?: "supported" | "unsupported" | "unknown";
+  transport?: string | null;
+  reason?: string | null;
+  /** The server's own sentence. Displayed verbatim; never rewritten here. */
+  detail?: string | null;
+};
+
+/** A camera as the wall needs it. Extra fields on the record are ignored. */
+export type TWallCamera = {
+  _id: string;
+  name?: string;
+  /**
+   * The stored address. For a `type: "ip"` camera this is a complete, directly
+   * renderable live-video page — it is the picture, not a fragment to resolve.
+   */
+  host?: string;
+  type?: string;
+  status?: string;
+  capabilities?: Record<string, TWallCapability>;
+};
+
+/* -------------------------------------------------------------------------- */
+/* Layouts                                                                     */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * The three wall sizes.
+ *
+ * Square only, and only three of them. A VMS layout picker exists so a
+ * supervisor can change what they are watching in one click; a list of eleven
+ * arrangements is a settings screen wearing a toolbar's clothes.
+ */
+export const WALL_LAYOUTS = [
+  { key: "1x1", columns: 1, tiles: 1, label: "Single" },
+  { key: "2x2", columns: 2, tiles: 4, label: "Four" },
+  { key: "3x3", columns: 3, tiles: 9, label: "Nine" },
+] as const;
+
+export type TWallLayoutKey = (typeof WALL_LAYOUTS)[number]["key"];
+
+/** Four tiles: enough to be a wall, small enough to still be readable. */
+export const DEFAULT_WALL_LAYOUT: TWallLayoutKey = "2x2";
+
+export function wallLayout(key: string | undefined) {
+  return WALL_LAYOUTS.find((l) => l.key === key) ?? WALL_LAYOUTS[1];
+}
+
+/**
+ * At three columns a tile is small enough that the chrome starts eating the
+ * picture, so the tile drops its status WORD and keeps the dot.
+ */
+export function isDenseLayout(key: string | undefined) {
+  return wallLayout(key).columns >= 3;
+}
+
+/* -------------------------------------------------------------------------- */
+/* Which cameras, and in what order                                            */
+/* -------------------------------------------------------------------------- */
+
+/** Rule 1. Only `type: "ip"`. See the note at the top of this file. */
+export function wallCameras(items: unknown): TWallCamera[] {
+  if (!Array.isArray(items)) return [];
+  return items.filter(
+    (c): c is TWallCamera => !!c && typeof c === "object" && (c as TWallCamera).type === "ip"
+  );
+}
+
+/**
+ * The tiles, in order, padded with `null` to the layout's size.
+ *
+ * An empty selection is **not** "no cameras" — it is "nobody has chosen yet",
+ * and the wall falls back to the site's own order. A supervisor who clears the
+ * picker gets their site back, not a black screen.
+ */
+export function wallTiles(
+  cameras: TWallCamera[],
+  selectedIds: string[] | undefined,
+  layoutKey: string | undefined
+): Array<TWallCamera | null> {
+  const { tiles } = wallLayout(layoutKey);
+  const byId = new Map(cameras.map((c) => [c._id, c]));
+  const chosen =
+    selectedIds && selectedIds.length
+      ? selectedIds.map((id) => byId.get(id)).filter((c): c is TWallCamera => !!c)
+      : cameras;
+
+  const out: Array<TWallCamera | null> = chosen.slice(0, tiles);
+  while (out.length < tiles) out.push(null);
+  return out;
+}
+
+/* -------------------------------------------------------------------------- */
+/* Capabilities                                                                */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * The two words a switched-off control wears.
+ *
+ * Lifted unchanged from the mobile build, and the "yet" is the whole point: it
+ * is the difference between a feature that is broken and a feature that is
+ * waiting on something somebody has to switch on.
+ */
+export const CAPABILITY_TAGS = {
+  unsupported: "Not set up yet",
+  unknown: "Not checked yet",
+} as const;
+
+/**
+ * What a client with no descriptor at all should say. This is the server's own
+ * `device-not-probed` sentence, reused rather than reinvented, so an older API
+ * that sends no descriptor still explains itself in the product's own words.
+ */
+const NOT_PROBED = "This camera has not been asked what it can do yet.";
+
+/** The four capabilities the wall draws a control for, and their plain names. */
+export const WALL_CAPABILITY_CONTROLS = [
+  { key: "playback", title: "Recorded footage" },
+  { key: "events", title: "Events and alarms" },
+  { key: "ptz", title: "Move camera" },
+  { key: "presets", title: "Stored positions" },
+] as const;
+
+export type TCapabilityView = {
+  state: "supported" | "unsupported" | "unknown";
+  available: boolean;
+  /** `null` when the capability works — a working control needs no tag. */
+  tag: string | null;
+  /** The server's sentence, or the not-probed one. Never empty. */
+  detail: string;
+};
+
+/** Rule 2 and rule 3, in one place. */
+export function capabilityView(
+  camera: TWallCamera | null | undefined,
+  key: string
+): TCapabilityView {
+  const entry = camera?.capabilities?.[key];
+  const state =
+    entry?.state === "supported" || entry?.state === "unsupported"
+      ? entry.state
+      : "unknown";
+
+  return {
+    state,
+    available: state === "supported",
+    tag: state === "supported" ? null : CAPABILITY_TAGS[state],
+    detail: (entry?.detail || "").trim() || NOT_PROBED,
+  };
+}
+
+/* -------------------------------------------------------------------------- */
+/* Tile state                                                                  */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * How long a player page may take to load before the tile stops claiming it is
+ * coming. Deliberately generous — lifted from the mobile build, where the
+ * argument is that reporting a working video service as dead is the worse of
+ * the two mistakes.
+ */
+export const LIVE_CONNECT_TIMEOUT_MS = 15_000;
+
+export type TTileState =
+  | "live"
+  | "connecting"
+  | "no-signal"
+  | "offline"
+  | "unavailable";
+
+/**
+ * The four words a tile may say about itself.
+ *
+ * `offline` and `no-signal` are two different facts and used to share one word:
+ * "Offline" on every tile at once means the BROWSER lost the network; "No
+ * signal" on one tile means that camera is not answering. A supervisor needs to
+ * know which of those they are looking at.
+ */
+export const TILE_LABELS = {
+  live: "Live",
+  connecting: "Connecting…",
+  "no-signal": "No signal",
+  offline: "No connection",
+  unavailable: "Not set up yet",
+} as const;
+
+/** What the browser knows about the embedded player page. */
+export type TPlayerState = "loading" | "ready" | "timeout";
+
+export type TTileView = {
+  state: TTileState;
+  label: string;
+  /** A sentence for the states that need explaining; `null` when live. */
+  detail: string | null;
+  /** Whether the player page may be embedded at all. */
+  showPlayer: boolean;
+};
+
+/**
+ * Rule 4, plus every reason a tile may have nothing to show.
+ *
+ * Order matters: the browser being offline beats everything (it explains every
+ * tile at once), then the record's own problems, then the server's verdict on
+ * live video, and only then what the embedded page is actually doing.
+ */
+export function tileView(
+  camera: TWallCamera | null | undefined,
+  opts: { online?: boolean; player?: TPlayerState } = {}
+): TTileView {
+  const online = opts.online !== false;
+  const dead = (state: TTileState, detail: string | null): TTileView => ({
+    state,
+    label: TILE_LABELS[state],
+    detail,
+    showPlayer: false,
+  });
+
+  if (!camera) return dead("unavailable", "No camera in this position.");
+  if (!online)
+    return dead("offline", "This browser has no internet connection.");
+  if (camera.status && camera.status !== "active")
+    return dead("unavailable", "This camera is not active.");
+  if (!camera.host) return dead("unavailable", "This camera has no address configured.");
+
+  const live = capabilityView(camera, "liveVideo");
+  if (live.state === "unsupported") return dead("unavailable", live.detail);
+
+  const player = opts.player ?? "loading";
+  if (player === "timeout")
+    return {
+      state: "no-signal",
+      label: TILE_LABELS["no-signal"],
+      // Invented: only the browser can know the page never loaded, so the
+      // server has no reason code for it. Worded as a fact, not a diagnosis —
+      // we genuinely cannot tell a dead camera from a dead video service.
+      detail: "The live view did not load. The camera or the video service may be down.",
+      showPlayer: true,
+    };
+  if (player === "loading")
+    return {
+      state: "connecting",
+      label: TILE_LABELS.connecting,
+      detail: null,
+      showPlayer: true,
+    };
+
+  return { state: "live", label: TILE_LABELS.live, detail: null, showPlayer: true };
+}