@convokitapp/vue-ui 0.4.1 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,78 @@
 # Changelog
 
+## 0.6.0
+
+- Inbox previews and unread counts. SDK-backed lists page `listInbox` by
+  opaque cursor in activity order (newest surviving message first, empty rooms
+  by creation time); `hasMore` follows the server's `nextCursor`. Pages merge
+  by conversation ID with the later entry winning, re-ordered by
+  `(activityAt desc, id desc)` unless `filter.comparator` is set. Page checks:
+  at most `limit` entries, non-blank unique IDs, and a cursor that advances
+  (`Inbox pagination did not advance`); the offset-era "full page with no new
+  IDs" rule applies to the legacy path only. `mergeInboxEntries` is exported.
+- State: `summaries` (`ReadonlyMap<string, InboxSummary>`) and `currentUserId`
+  on `useConversationList` / `ConversationListState`; `''` and empty without a
+  session, on the legacy path and after disposal.
+- Default rows: preview line (`You: …`, `<name>: …` in groups, media
+  placeholders `Photo` / file name or `File` / `Location` / `Contact`),
+  activity time, unread badge (`99+` above 99 or when capped; accessible name
+  `<count> unread`, `99+ unread` when capped; label hidden from the
+  accessibility tree), bold title while unread. New theme token `badge`
+  (`--ckui-badge`, default primary). `#conversation-item` slot props gain
+  `summary` and `currentUserId`; `ConversationListView` accepts `summaries`
+  and `currentUserId`. Inline `Retry` requests the next page when `hasMore`
+  and `onLoadMore` are bound (bypassing the duplicate-request guard), else
+  refreshes; it renders only when a callback exists.
+- Live updates: `inbox_activity` is throttled by `activityRefreshWindowMs`
+  (default 500, 0 = immediate; max-wait window, generation-guarded, cleared on
+  dispose/session end, `unref`'d where available); `inbox_changed` refreshes
+  immediately and drops a pending window. `refresh()` walks from the head with
+  `limit = min(100, target − consumed)`, `target = max(pageSize, loaded)`,
+  continues past fully hidden pages and never publishes an empty list with
+  `hasMore` while pages remain; rows, summaries, cursor and `hasMore` swap
+  atomically.
+- Adapter: optional `listInbox?({ limit, cursor, archived })` and
+  `onInboxActivity?(handler, onError?)`; the default adapter implements both.
+  Adapters without `listInbox` and custom `pageLoader`s keep the 0.5 offset
+  path with empty summaries. A 404 from `listInbox` falls back to that path for
+  the store's life without evicting rows (warned once); a legacy 404 still
+  evicts, 401/403 evict, 400 keeps rows and reports.
+- Requires core SDK 0.6.x (`listInbox`, `InboxPage` / `InboxEntry` /
+  `InboxSummary`, `realtime.onInboxActivity`) and the coordinated backend.
+
+## 0.5.0
+
+- Precise read positions. Receipts resolve per user from a monotonic read-through
+  position `(createdAt, id)` when the server provides one, and fall back to the
+  acknowledgement time only for legacy participants without a position. A read
+  request that arrives late no longer marks messages that were rendered after it
+  as read. The state exposes `readPositionByUserId` beside `readAtByUserId`;
+  `readerIdsFor`, `defaultReadersResolver`, `MessageListView` and
+  `ConversationView` accept both (`readAtByUserId` alone still works).
+- Targeted acknowledgements. Automatic and explicit reads name the newest
+  rendered, non-pending message (`throughMessageId`); nothing is sent while
+  nothing is rendered. A withheld media-only row is acknowledged once its
+  hydration renders it. One request is in flight at a time, a follow-up is
+  resolved at send time, and targets at or before the accepted one are skipped.
+  A target the server does not know (`MESSAGE_NOT_FOUND`) is skipped and the
+  next newest row is acknowledged once; membership failures still surface as
+  errors.
+- Visibility gating. Automatic acknowledgements wait while the document is
+  hidden and resume when it becomes visible; the SDK-backed `Conversation`
+  wires `document.visibilityState` and `visibilitychange`, and controllers gain
+  `setVisible(visible)`. Unknown, prerender and server environments count as
+  visible. `markReadOnLoad` / `markReadOnReceive` keep their meaning; with both
+  off no request is ever sent, including on visibility changes.
+- 0.5.0 adapter change: `ConvoKitUiClient.markConversationRead(conversationId,
+  options?)` receives `{ throughMessageId }`. Custom adapters must forward it
+  and report an unknown target with `code: 'MESSAGE_NOT_FOUND'` (or a 404
+  without a code). One-argument implementations still type-check but would
+  acknowledge the server's newest message instead of the rendered one.
+- Requires core SDK 0.5.x (`Participant.readPosition`, `ReadEvent.readPosition`,
+  `markConversationRead` target) and the coordinated backend. Mixed fleet:
+  precise receipts need both the sender's and the reader's clients on 0.5;
+  0.4 readers keep timestamp semantics and keep parsing the additive payload.
+
 ## 0.4.1
 
 - Describe a confirmed outgoing message without readers as `Sent` instead of

package/PARITY.md

@@ -14,10 +14,20 @@ while using Vue-native composition patterns.
 | Conversation state | Controller | `useConversation` | `useConversation` |
 | Conversation-list state | Controller | `useConversationList` | `useConversationList` |
 | Inbox offset pagination and de-duplication | Yes | Yes | Yes |
+| Inbox cursor pagination, activity order, later-entry merge | Yes | Yes | Yes |
+| Inbox summaries and viewer in list state (`summaries`, `currentUserId`) | Yes | Yes | Yes |
+| Preview / time / unread badge rows (`badge` token) | `badgeColor` | `--ckui-badge` | `--ckui-badge` |
+| Row replacements receive `summary` / `currentUserId` | `rowBuilder` | Render props | `#conversation-item` slot |
+| `inbox_activity` throttle (`activityRefreshWindowMs`) | Yes | Yes | Yes |
+| Adapter `listInbox` / `onInboxActivity` | Required | Optional | Optional |
+| Inbox 404 fallback to the offset path | Yes | Yes | Yes |
 | Search, archived, participant, predicate, sort filters | Yes | Yes | Yes |
 | Realtime messages, typing, reads | Yes | Yes | Yes |
 | Pending state without provisional timestamps or receipts | Yes | Yes | Yes |
 | Read markers and reader resolution | Yes | Yes | Yes |
+| Read positions (`readPositionByUserId`, `lastReadAt` fallback) | Yes | Yes | Yes |
+| Targeted acknowledgements (`throughMessageId`, newest rendered row) | Yes | Yes | Yes |
+| Visibility-gated auto-read | `WidgetsBindingObserver` | `visibilitychange` | `visibilitychange` |
 | Mark read on load/receive | Yes | Yes | Yes |
 | Typing idle timeout | Yes | Yes | Yes |
 | Image, file, location, contact rendering | Yes | Yes | Yes |
@@ -32,10 +42,29 @@ Vue also exposes controlled/uncontrolled composer text through `v-model`,
 per-part `classNames` and `styles`, `unstyled` mode, native root attributes,
 image loading policy, time formatting, scroll behavior controls, callback props,
 and exposed composable controllers.
-## Unreleased recovery parity
+## Read-position parity (0.5.0)
 
-Room and inbox session eviction, value-cursor history, full viewed-range reconnect
-reconciliation, ID-only deletions and server-sourced read positions are tested in
-this feature branch. They require the unpublished core SDK recovery contract.
-The parity script checks API presence only; the controller, rendered-view and
-actual-SDK protocol tests verify behavior. See README 0.3.0 behavior and integration notes.
+Every UI applies the same receipt rule per user: a read position wins when
+present (`covers` by `(createdAt, id)`), otherwise `lastReadAt` is compared
+with `createdAt`. Acknowledgements target the newest rendered non-pending
+message, coalesce to one request in flight, skip targets at or before the last
+accepted one, re-issue once on a `MESSAGE_NOT_FOUND` miss, and wait while the
+platform reports the view as hidden. The adapter interface gained the optional
+target in all libraries (`markConversationRead(conversationId, options?)` here).
+The parity script checks API presence only; the store, rendered-view and
+actual-SDK protocol tests verify behavior.
+
+## Inbox parity (0.6.0)
+
+Every UI pages the inbox by the server cursor, keeps the server's order within a
+page, merges pages by conversation ID with the later entry winning, and
+re-orders merged rows by `(activityAt desc, id desc)` unless a comparator is
+set. Rows show the same preview (`You:` for the viewer, `<name>:` for a named
+member of a group of more than two, `Photo` / file name or `File` /
+`Location` / `Contact` for media-only messages), the activity time, and an
+unread badge (`99+` above 99 or when capped; accessible name
+`<count> unread`). `inbox_activity` signals are coalesced by a max-wait window
+(`activityRefreshWindowMs`, default 500 ms); `inbox_changed` stays immediate.
+A 404 from the inbox route falls back to the offset path for the store's life
+without evicting rows. The parity script checks API presence only; the store,
+rendered-view and actual-SDK protocol tests verify behavior.

package/README.md

@@ -11,6 +11,105 @@ React package: system typography, separated rows, subtle borders, compact
 actions, and restrained radii. It remains framework-CSS independent and does
 not require Tailwind in the host application.
 
+## 0.6.0 inbox previews and unread counts
+
+This release requires JavaScript SDK 0.6.x (`listInbox`, `onInboxActivity`)
+and the coordinated backend (`GET /api/v1/inbox`, the `inbox_activity` event).
+
+- SDK-backed lists arrive in inbox order: the newest surviving message time
+  first (an empty room sorts by its creation time), paged by an opaque server
+  cursor instead of an offset. The store keeps the server's order within a page
+  and, whenever pages are combined (load more, refresh), merges by conversation
+  ID with the later entry winning and re-orders by `(activityAt desc, id desc)`.
+  Setting `filter.comparator` replaces that order; `updatedAt` is never an
+  ordering input. `mergeInboxEntries(current, incoming)` is exported and applies
+  the same rule.
+- State gains `summaries` (a `ReadonlyMap<string, InboxSummary>` by conversation
+  ID: `latestMessage`, `unreadCount`, `unreadCountCapped`, `readPosition`,
+  `lastReadAt`, `activityAt`) and `currentUserId` (the bound session's user;
+  `''` without a session, on the legacy path and after disposal). `conversations`,
+  filters, comparators, custom offset `pageLoader`s and the `#conversation-item`
+  slot signature are unchanged.
+- Default rows show a one-line preview instead of the participants line when a
+  summary carries a non-empty latest message: `You: …` for the viewer's own
+  message (DMs included), `<name>: …` for a named member of a group of more
+  than two, otherwise the body alone; media-only messages read `Photo`,
+  the file name or `File`, `Location`, `Contact`. Rows show the activity time
+  in the device zone and an unread badge (`5`, `99+` above 99 or when the
+  server capped the count) with the accessible name `<count> unread`
+  (`99+ unread` when capped); the title is bold while unread. The badge uses
+  the new theme token `badge` (`--ckui-badge`, defaults to the primary color)
+  with `outgoingText` as its label color.
+- `#conversation-item` slot props gain `summary` and `currentUserId` (present
+  when known); existing slots keep working. `ConversationListView` accepts
+  `summaries` and `currentUserId` for controlled use. The inline error's
+  `Retry` requests the next page when `hasMore` and `onLoadMore` are bound
+  (past the view's duplicate-request guard), otherwise it refreshes; it
+  renders only when one of those callbacks exists.
+- Live updates: `inbox_changed` still refreshes immediately; the new
+  `inbox_activity` signal (message inserts/edits and read-position advances,
+  fanned out to every client of the app) is throttled by
+  `activityRefreshWindowMs` (default 500 ms, 0 = immediate) with max-wait
+  semantics: the first signal opens a window, later signals wait for it, and one
+  refresh runs when it closes. An `inbox_changed` during the window refreshes
+  at once and drops the timer. `refresh()`, topic-error reconciliation and the
+  rejoin replay stay immediate. A refresh re-walks from the head with
+  `limit = min(100, target − consumed)` where `target = max(pageSize, loaded)`,
+  continues past pages the local filter hides, and swaps rows, summaries,
+  cursor and `hasMore` atomically; it never publishes an empty list with
+  `hasMore` while more pages exist. Rooms are open with `useConversation` as
+  before; room stores ignore `inbox_activity`.
+- Adapter additions: `ConvoKitUiClient.listInbox?({ limit, cursor, archived })`
+  and `onInboxActivity?(handler, onError?)` are optional. The default adapter
+  implements both; custom adapters without `listInbox`, and custom `pageLoader`s,
+  keep the 0.5 offset path with empty `summaries` and no activity subscription.
+  A 404 from `listInbox` (route absent on a rolled-back backend) switches the
+  store to that path for the rest of its life without evicting rows (a warning
+  is logged once); a 404 from `getConversations` still evicts, 401/403 from
+  either endpoint evict, and 400 keeps rows and reports the error.
+
+## 0.5.0 precise read positions
+
+This release requires JavaScript SDK 0.5.x and the coordinated backend.
+
+- Read receipts resolve per user from a monotonic read-through position, the
+  `(createdAt, id)` of a concrete message the server resolved, and fall back to
+  the acknowledgement time only for legacy participants without a position. A
+  read request that arrives late no longer marks messages rendered after it as
+  read. `useConversation` and `Conversation` expose `readPositionByUserId`
+  beside `readAtByUserId`; both are seeded from participants and advanced by
+  server read events only, never from the device clock.
+- Acknowledgements name the newest rendered, non-pending message
+  (`throughMessageId`). Nothing is sent while nothing is rendered, and a
+  media-only row is acknowledged only once its hydration renders it. One
+  request is in flight at a time; a follow-up is resolved at send time and
+  skipped when the newest row is already acknowledged. A target the server
+  does not know (`MESSAGE_NOT_FOUND`, for example deleted meanwhile) is
+  skipped and the next newest row is acknowledged once. Membership failures
+  still surface as errors.
+- Automatic acknowledgements wait while the document is hidden and resume when
+  it becomes visible. The SDK-backed `Conversation` follows
+  `document.visibilityState` and `visibilitychange`; controllers gain
+  `setVisible(visible)` for host-driven surfaces (tabs, drawers, background
+  routes). Unknown, prerender and server environments count as visible.
+  `markReadOnLoad` and `markReadOnReceive` keep their meaning; with both off,
+  no request is ever sent, including on visibility changes. `markRead()` is
+  the host's decision and is not gated.
+- Controlled views accept `readPositionByUserId` next to `readAtByUserId`;
+  `readerIdsFor(message, readAtByUserId, readPositionByUserId?)` and
+  `defaultReadersResolver` apply the unified rule. Custom `#message` and
+  `#read-receipt` slots and `readersResolver` receive the same reader IDs.
+- Adapter change: `ConvoKitUiClient.markConversationRead(conversationId,
+  options?)` receives `{ throughMessageId }`. Custom adapters must forward it
+  to the core SDK (or their backend) and report an unknown target with
+  `code: 'MESSAGE_NOT_FOUND'` (or a 404 without a code). One-argument
+  implementations still type-check but acknowledge the server's newest message
+  instead of the rendered one.
+- Mixed fleet: precise receipts need both the sender's and the reader's
+  clients on 0.5. 0.4 readers keep timestamp semantics and keep parsing the
+  additive payload; the dashboard shows both the read-through and the last
+  acknowledgement time.
+
 ## 0.4.0 live inbox, sending and recovery
 
 This release requires JavaScript SDK 0.4.x and the coordinated backend. The core
@@ -45,6 +144,7 @@ membership changes; no additional customer configuration is needed.
 - Read receipts use persisted participant positions and server read events,
   monotonically. A successful mark-read request does not fabricate a timestamp
   from the device clock. Remote typing expires and clears on disconnect.
+  (0.5.0 replaces the timestamp comparison with read positions; see above.)
 - Pending sends are bound to their original room/session. Reconciliation uses
   the exact clientMessageId, sender and room, never identical text or file count.
   A matching live/history row replaces its pending bubble immediately, even
@@ -148,6 +248,11 @@ Available slots include `conversation-item`, `separator`, `header`, `message`,
 Use `useConversationList` and `useConversation` when you want ConvoKit's
 pagination, de-duplication, realtime, typing, and read state without the
 default UI. Both return readonly Vue refs plus actions and a `dispose()` method.
+`useConversationList` also exposes `summaries` and `currentUserId` and accepts
+`activityRefreshWindowMs`; `ConversationList` forwards the same option.
+`useConversation` also exposes `readPositionByUserId`, `readerIdsFor(message)`,
+`markRead()` and `setVisible(visible)`; call `setVisible(false)` while your own
+surface hides the room so automatic acknowledgements wait until it is shown.
 
 Optimistic rows display `Sending…` until acknowledgement. The final server
 timestamp is formatted in the viewer's local timezone. Custom message slots can
@@ -155,7 +260,8 @@ use `isConvoKitPendingMessage(message)` to present the same state.
 
 ## Appearance
 
-Wrap any subtree with `ConvoKitThemeProvider`, set `density="compact"`, or use
+Wrap any subtree with `ConvoKitThemeProvider` (tokens include `badge` for the
+unread counter), set `density="compact"`, or use
 the per-part `classNames` and `styles` maps. `unstyled` removes package classes
 from the configurable parts for a fully host-owned presentation.