@convokitapp/vue-ui 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # 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

package/PARITY.md

@@ -14,6 +14,13 @@ 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 |
@@ -46,3 +53,18 @@ 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,63 @@ 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.
@@ -191,6 +248,8 @@ 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.
@@ -201,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.