@convokitapp/vue-ui 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,103 @@
 # Changelog
 
+## 0.7.0
+
+- Private mark unread. `useConversationList` / `ConversationListController`
+  gain `markUnread(conversationId)` and
+  `clearUnread(conversationId, { ifVersion? })`; the latter resolves to the
+  response's `cleared` ("this request removed the marker"). On any 200 (a mark,
+  or a clear whether `cleared` is true or false) the row's current summary
+  takes the response's `unreadMarkedAt` and `privateStateVersion` as one unit,
+  only while the response is not older than the stored version, and
+  `isUnread` is recomputed as
+  `unreadCount > 0 || unreadCountCapped || unreadMarkedAt !== null`; a lower
+  version is ignored so a delayed response never resurrects a marker a newer
+  action removed. Both methods reject when the adapter lacks the new members
+  or the store is disposed or session-ended (nothing is sent); request
+  failures are reported through `error` without evicting rows and reject.
+  Other devices learn of the change through `inbox_activity`, which the
+  backend now also sends for the caller's own marker changes.
+- Rows. The unread predicate (bold title, `data-unread`) is
+  `summary.isUnread || summary.unreadCount > 0 || summary.unreadCountCapped`,
+  so consumer-built summaries that omit `isUnread` keep their badges. A count
+  (or a capped count) keeps the numeric badge unchanged; `isUnread` without
+  one renders a numberless dot, `.ckui-unread-badge.ckui-unread-badge--dot`
+  (`role="img"`, accessible name `Unread`, never `0 unread`), in the `badge`
+  colour. It is spread into the row's meta span, so rows without a badge no
+  longer carry an empty comment vnode. `#conversation-item` slots receive the
+  same `summary` with its three new fields; no signature changes.
+- Rooms. The store captures `conversation.membership.privateStateVersion` (and
+  whether `membership.unreadMarkedAt` was set) once per open, the first time
+  its `conversation` goes from null to a DTO: on `loadInitial`, or on the
+  reconcile that follows a transient first-load failure; a refresh that
+  replaces an existing DTO never recaptures, and the capture is dropped
+  whenever `conversation` returns to null (reload, dispose, authoritative
+  401/403/404). Every targeted acknowledgement of that open sends
+  `{ throughMessageId, privateStateVersion }`; a DTO without `membership`
+  (0.6 backend) sends the 0.6 body. An automatic acknowledgement for a row
+  received before the DTO (during the load, or while a transient first-load
+  failure stands) waits for the capture, like it waits while hidden, and is
+  issued with the version once the open captures. A room opened with a
+  marker that renders no non-pending, acknowledgeable row calls
+  `clearConversationUnread(conversationId, { ifVersion: captured })` once per
+  open under the load-acknowledgement triggers and visibility gating (also on
+  an explicit `markRead()`, never once a row is rendered); `cleared: false`
+  is not an error. The store still never sends an acknowledgement without a
+  target, fabricates no read state and holds no marker state.
+- Adapter: optional `markConversationUnread?(conversationId)` and
+  `clearConversationUnread?(conversationId, { ifVersion? })`; the default
+  adapter implements both. `markConversationRead` options may now carry
+  `privateStateVersion`: custom adapters must forward the options object
+  unchanged, or acknowledgements advance the position but never clear the
+  marker. Adapters without `clearConversationUnread` leave the marker in
+  empty rooms.
+- Requires core SDK 0.7.x (`markConversationUnread`, `clearConversationUnread`,
+  `Conversation.membership`, the required `InboxSummary` members `isUnread`,
+  `unreadMarkedAt` and `privateStateVersion`) and the coordinated backend.
+  Consumer-built `InboxSummary` literals gain those three members. Mixed
+  fleet: against a 0.6 backend the new adapter members fail with a 404
+  (`HTTP_ERROR`), acknowledgements carry no version and lists show no dots.
+
+## 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,18 @@ 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 |
+| List `markUnread` / `clearUnread` (0.7.0) | Controller | `useConversationList` | `useConversationList` |
+| Numberless unread dot (`isUnread`, count 0, name `Unread`) | `ConvoKitUnreadDot` | `.ckui-badge--dot` | `.ckui-unread-badge--dot` |
+| Acknowledgements carry the version captured at open | Yes | Yes | Yes |
+| Empty marked room clears through `clearConversationUnread` | Yes | Yes | Yes |
+| Adapter `markConversationUnread` / `clearConversationUnread` | 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 +58,36 @@ 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.
+
+## Mark-unread parity (0.7.0)
+
+Every UI keeps the marker private to the caller, exposes list-level
+`markUnread` / `clearUnread` (the latter returning the response's `cleared`),
+applies a mutation response to the current summary only when its
+`privateStateVersion` is not older than the stored one, and recomputes
+`isUnread` as `unreadCount > 0 || unreadCountCapped || unreadMarkedAt != null`.
+Rows keep the numeric badge for a count and render a numberless dot named
+`Unread` for a marker without one. Room stores capture the opened
+`membership.privateStateVersion` once per open and send it with every
+targeted acknowledgement; a room opened with a marker that renders nothing
+clears it once through `clearConversationUnread(id, { ifVersion })`, never
+through an untargeted acknowledgement. The adapter additions are optional in
+the TypeScript UIs and required in the Dart and Kotlin ones (a breaking
+change for custom implementers there, like `listInbox` in 0.6.0). The parity
+script checks API presence only; the store, rendered-view and actual-SDK
+protocol tests verify behavior.

package/README.md

@@ -11,6 +11,125 @@ 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.7.0 private mark unread
+
+This release requires JavaScript SDK 0.7.x (`markConversationUnread`,
+`clearConversationUnread`, `Conversation.membership`, the `InboxSummary`
+members `isUnread`, `unreadMarkedAt` and `privateStateVersion`) and the
+coordinated backend (`POST`/`DELETE /api/v1/conversations/:id/unread`, the
+`privateStateVersion` acknowledgement field, the `membership` sibling on
+`GET /api/v1/conversations/:id`).
+
+- The marker is private: other members, webhooks and `read` events never see
+  it. `useConversationList` and the `ConversationList` controller gain
+  `markUnread(conversationId)` and `clearUnread(conversationId, { ifVersion? })`.
+  Wire them through `#conversation-item` (a row action or menu) or
+  `@controller-change`; the default row adds no affordance. `clearUnread`
+  resolves to the response's `cleared` ("this request removed the marker",
+  not "the room is read"). Both reject from a disposed or session-ended
+  controller without sending anything.
+- Summaries carry `isUnread`
+  (`unreadCount > 0 || unreadCountCapped || unreadMarkedAt !== null`),
+  `unreadMarkedAt` and `privateStateVersion`. After a mark or a clear the
+  row's summary takes the response only while it is not older than what the
+  row already holds; a delayed response never resurrects a marker a newer
+  action removed. Other devices refresh through `inbox_activity`, which the
+  backend also sends for your own marker changes; `activityRefreshWindowMs`
+  applies as before.
+- Dot rule: a count (or a capped count) keeps the numeric badge (`5`, `99+`,
+  accessible name `<count> unread`); `isUnread` without one renders a
+  numberless dot with the accessible name `Unread`, never `0 unread`
+  (`.ckui-unread-badge.ckui-unread-badge--dot`, `badge` colour). The title is
+  bold and `data-unread` is set in both cases; rows without a summary are
+  unchanged.
+- Capture at open: the room store captures
+  `conversation.membership.privateStateVersion` once per open (the first time
+  its `conversation` goes from null to a DTO: on load, or on the reconcile
+  after a transient first-load failure) and sends it with every targeted
+  acknowledgement of that open. A refresh never recaptures, so a mark made
+  elsewhere while the room is open survives its acknowledgements until the
+  room is reopened; a DTO without `membership` (0.6 backend) sends no version.
+  An automatic acknowledgement for a row that arrives before the DTO (during
+  the load, or while a transient first-load failure stands) waits for the
+  capture, like it waits while hidden, so it too carries the version.
+- Empty rooms: when the opened membership carries a marker and nothing
+  non-pending is rendered, the store calls
+  `clearConversationUnread(conversationId, { ifVersion })` once per open under
+  the same triggers and visibility gating as the load acknowledgement (and on
+  an explicit `markRead()`); once a row is rendered its acknowledgement clears
+  the marker instead. The UI still never sends an acknowledgement without a
+  target. `cleared: false` is not an error.
+- Adapter additions: `ConvoKitUiClient.markConversationUnread?(conversationId)`
+  and `clearConversationUnread?(conversationId, { ifVersion? })` are optional;
+  the default adapter implements both. Custom adapters without them make
+  `markUnread` / `clearUnread` reject and leave the marker in empty rooms.
+  (The Flutter and Android UIs make the same members, and the
+  `privateStateVersion` acknowledgement parameter, required on their
+  `ConvoKitUiClient`: a breaking change for custom implementers there, like
+  `listInbox` in 0.6.0.)
+  `markConversationRead` options now carry `privateStateVersion`; forward the
+  options object unchanged, or acknowledgements advance the position but never
+  clear the marker.
+- Mixed fleet: 0.6 lists ignore `isUnread`; against a 0.6 backend the new
+  adapter members fail with a 404 (`HTTP_ERROR`) and no dots render.
+
+## 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 +310,10 @@ 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`, accepts
+`activityRefreshWindowMs` (`ConversationList` forwards the same option), and
+offers `markUnread(conversationId)` / `clearUnread(conversationId, options?)`
+for a host-built row action.
 `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 +324,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 and dot), 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.