@visns-studio/visns-components 6.28.0 → 6.31.0

package/README.md

@@ -9,6 +9,110 @@ A comprehensive React component library used by the VISNS Studio team for CRM an
 
 VISNS Components is a React-based UI component library that provides a set of reusable, consistent, and customizable components for building web applications. It includes components for authentication, data grids, forms, navigation, and more, designed to work seamlessly together.
 
+## Recent Updates (v6.31.0)
+
+### The header badge self-heals too, and the pop takes its timings from the server
+
+Follow-up to 6.30.0. That release stopped the two holders of the shared
+`call-queue-monitor.{env}` channel from destroying each other's subscription,
+and taught the call pop to notice a missing channel and rebuild it. This one
+finishes the job.
+
+- **`useZoomPhoneLive` / `ZoomPhoneBadge` resubscribe the same way the pop
+  does** — on every socket reconnect and every `resubscribeCheckMs` (new
+  option/prop, default 60 s, `0` disables) while the tab is visible. Before,
+  a badge whose channel was taken away kept its green `Live` stamp and never
+  received another presence event.
+- **`hasPrivateChannel(instance, name, held)`** takes the subscription the
+  caller is listening on. With two self-healing holders, whichever rebuilt
+  first left the registry looking healthy while the other still held the dead
+  object; passing what you hold makes the answer "no" until you re-acquire.
+- **`CallQueuePop` adopts `missed_grace_ms` and `max_ringing_ms` from the
+  live snapshot** when the server sends them, so the browser and the server
+  agree on how long a declined leg keeps the card. The `missedGraceMs` prop's
+  default is now **20000** (it was 10000 — half the server's, so a card left
+  10 s before the server considered the call gone).
+- **Phantom cards expire.** New `maxRingingMs` prop (default 120000, or the
+  snapshot's `max_ringing_ms`): a card whose `startedAt` is older than that
+  is removed and logged — a lost ended webhook must not ring on a screen
+  forever. `expiredCallIds(calls, now, maxRingingMs)` is exported.
+
+## Recent Updates (v6.30.0)
+
+### `CallQueuePop` no longer loses its channel to the header's phone badge
+
+Two components listen on the same private channel (`call-queue-monitor.{env}`):
+the call pop, mounted at the app root, and `ZoomPhoneBadge` in the header. A
+host that hides its header on some routes (the CRM does, on client and task
+record pages) unmounted the badge, whose cleanup called `echo.leave()` — and
+laravel-echo's `leave()` destroys a channel for every holder, not just the
+caller. The pop kept reporting `subscribed: true` and simply stopped popping
+until the tab was reloaded. Production's webhook ledger showed every ring
+broadcast OK, which is exactly why this took a while to find.
+
+- **`acquirePrivateChannel` / `releasePrivateChannel` / `hasPrivateChannel`**
+  (new, exported): a ref-counted front for `echo.private()` / `echo.leave()`.
+  The channel is opened on the first acquire and only really left when the
+  last holder releases it. Both `CallQueuePop` and `useZoomPhoneLive` go
+  through it. **A host component that listens on a channel one of ours also
+  listens on must use it too** — a direct `echo.leave()` will still take the
+  channel away from everyone.
+- **The pop rechecks its channel** on every socket reconnect and every
+  `resubscribeCheckMs` (new prop, default 60 s, `0` disables) while the tab is
+  visible, and resubscribes when it finds the channel gone — then refetches
+  the live snapshot so anything that rang meanwhile is caught up.
+- **Diagnostics gain a "Channel live" row** beside "Subscribed", fed by the
+  new `channelPresent` status field (`noteCallPopChannelPresent`, exported).
+  The two readings disagreeing is the symptom this release fixes; before,
+  there was no second reading.
+
+## Recent Updates (v6.29.0)
+
+### `TicketConversation` names who a reply reaches
+
+A helpdesk reply goes to everybody on the email chain, not to the one person
+whose message happens to be on screen — and on a forwarded ticket that is
+regularly somebody the agent has never seen. The composer said *"This is
+emailed to the customer."*, which is true and is not enough to check a send
+against.
+
+The server now says who, in two places, and the component draws both:
+
+```jsonc
+// GET {base}/{ticketId}/conversation
+{
+  "reply_audience": {            // or null — not answerable by email, or unknown
+    "to": [{ "name": "Dana Reid", "address": "dana@acme.test" }],
+    "cc": [{ "name": null, "address": "accounts@acme.test" }]
+  },
+  "data": [
+    { "id": 4, "direction": "out", "recipients": { "to": [], "cc": [] } },
+    { "id": 3, "direction": "note", "recipients": null }
+  ]
+}
+```
+
+- **Before sending** — the `.consequence` sentence beside the Internal note
+  switch becomes `Emailed to Dana Reid · Cc accounts@acme.test` (the ` · Cc …`
+  half is omitted when Cc is empty). An internal note is unchanged, and a
+  `reply_audience` of `null` falls back to the old sentence rather than naming
+  nobody.
+- **After sending** — each entry carrying `recipients` draws one quiet
+  `To … · Cc …` line between its head and its body. **Both directions**: on our
+  reply it says who we reached, on the customer's it says who else at their end
+  has already read it, which is what tells an agent whether the answer needs to
+  go anywhere new. Nothing on a note, or on a row imported before the server
+  knew any of this (`recipients: null`).
+- A recipient renders as `name || address`; the **full `Name <address>` list is
+  in the `title`**, because two people called Dana is exactly the case a name
+  alone cannot settle.
+- **Nothing is folded to "+3 more".** The recipient worth noticing is the
+  unexpected one, which is the one a fold would hide — so both lines wrap and
+  take the space they need.
+
+The `POST {base}/{ticketId}/reply` response's `data` carries `recipients` too,
+so a reply prepended by the composer shows its own line immediately.
+
 ## Recent Updates (v6.27.0)
 
 ### A tint on one column: `cellColours`
@@ -2214,6 +2318,9 @@ endpoint nor an Echo instance present it renders nothing and logs nothing.
 | `syncChannelName` | `'throughlife-call-queue-pop'` | The `BroadcastChannel` that keeps every open tab's stack in step. Falsy switches cross-tab sync off. |
 | `clientDetailFields` | `CLIENT_DETAIL_FIELDS` (adviser / coding / age / city) | `[{ key, label, demo? }]` — the client-block rows, in card order; rows with an empty value are dropped; `demo` seeds the demo card. Pass your CRM's own fields so the card never names a field it does not have. Must be referentially stable (a module-scope constant, not an inline literal) — it sits in the demo effect's dependency list. |
 | `demoEnabled` | `true` | Registers `window.callPopDemo()` / `window.callPopClear()` for reviewing the UI without a backend. |
+| `missedGraceMs` | `20000` | How long a card survives a `.queue.missed` before it is taken as gone — a call rings several devices, so one declined leg only starts this timer and a further `.queue.ringing` cancels it. Was `10000`, half the server's own `missed_grace_seconds`, which took the card off screen ten seconds before the server considered the call gone. The snapshot's `missed_grace_ms` wins over it. |
+| `maxRingingMs` | `120000` | The backstop for an end that never arrived: a card still ringing after this is removed client-side, because a dropped `.queue.ended` otherwise leaves a phantom card ringing all afternoon. Demo cards and cards already leaving are exempt. The snapshot's `max_ringing_ms` wins over it. |
+| `resubscribeCheckMs` | `60000` | How often the pop confirms its Echo channel is still subscribed (visible tabs only), resubscribing and refetching the snapshot when it is not. `0` turns the check off. |
 
 **Payload contract.** Snake_case and camelCase are both accepted, so a Laravel
 resource passes through untouched: `call_id`/`callId`, `queue_id`/`queueId`,
@@ -2223,6 +2330,22 @@ resource passes through untouched: `call_id`/`callId`, `queue_id`/`queueId`,
 The snapshot's `pickup_codes` map is keyed by Zoom call queue id — a queue
 absent from it still pops, its card simply has no Pick up button.
 
+The snapshot carries three optional settings alongside the calls, and each wins
+over the matching prop once it lands — the server holds the webhook ledger and
+the config, so it is the side that decides when a call is over:
+
+```jsonc
+{
+  "calls": [ /* … */ ],
+  "pickup_codes": { "77": "*996439" },
+  "channel": "call-queue-monitor.production", // environment-scoped Echo channel
+  "missed_grace_ms": 20000,                   // overrides `missedGraceMs`
+  "max_ringing_ms": 120000                    // overrides `maxRingingMs`
+}
+```
+
+An older backend sends none of them and the props stand in unchanged.
+
 Named exports for testing: `toLocalDigits`, `formatAuPhone`, `formatEventDate`,
 `formatDueDate`, `toCallWorkspaceId`, `normaliseCall`, `normalisePickupCodes`,
 `formatElapsed`, `hasMonitorPermission`, `clientDetails`.

package/package.json

@@ -93,7 +93,7 @@
         "react-dom": "^17.0.0 || ^18.0.0 || ^19.0.0"
     },
     "name": "@visns-studio/visns-components",
-    "version": "6.28.0",
+    "version": "6.31.0",
     "description": "Various packages to assist in the development of our Custom Applications.",
     "main": "src/index.js",
     "files": [

package/src/components/callQueue/CallQueueDiagnostics.jsx

@@ -559,6 +559,19 @@ const CallQueueDiagnostics = ({
                             ? 'bad'
                             : 'ok'
                     )}
+                    {/* Deliberately beside "Subscribed", not folded into
+                        it: a channel torn down by somebody else's
+                        `echo.leave()` leaves "Subscribed" stuck on Yes, and
+                        the two readings disagreeing is the symptom. */}
+                    {row(
+                        'Channel live',
+                        yesNo(status.channelPresent, 'not checked'),
+                        status.channelPresent === false
+                            ? 'bad'
+                            : status.channelPresent === true
+                              ? 'ok'
+                              : undefined
+                    )}
                     {row(
                         'Last event',
                         status.lastEventName