@convokitapp/vue-ui 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,130 @@
 # Changelog
 
+## 0.9.0
+
+- Quoted replies. `useConversation` / `ConversationController` gain
+  `replyTarget` (the message the composer is quoting, as it stood when the
+  quote was started; null otherwise), `replyPreviews` (a read-only map from
+  `Message.replyToMessageId` to the resolved `ReplyPreview`, or the terminal
+  `'unavailable'`; a MISSING key is the distinct third state, "not resolved
+  yet"), `canResolveReplyPreviews` (adapter support), `startReply(messageId)`
+  (a no-op unless the row is rendered, confirmed, not known to be gone and the
+  viewer's role when known is not `READ`; any member may quote any row, own or
+  not; sends nothing, not even a typing update) and `cancelReply()`. Replying
+  and editing are mutually exclusive: `startReply` leaves edit mode and
+  `startEditing` drops the quote. `sendMessage` stamps `replyToMessageId` on
+  the optimistic row so the quoted block renders before the server
+  acknowledges the send, sends the key only when a quote is set (a plain send
+  stays byte-identical to 0.8.0) and clears the target only once the send was
+  accepted; a failed send keeps the draft and the quote. Deleting the quoted
+  message drops the target.
+- Batched preview resolution. After every page load, reconcile and live-insert
+  burst the store issues ONE `getReplyPreviews` call for the distinct quoted
+  parents the rendered rows point at and the loaded window cannot derive; a
+  parent that is on screen is derived locally (text cut at 500 characters,
+  `textTruncated` and `mediaCount` set) and costs no request, and a burst of
+  inserts is coalesced behind a short debounce whose handle is cleared with
+  the subscriptions. Previews are RE-READ, never copied: a `message_deleted`
+  event or a delete response for the id caches the terminal `'unavailable'`;
+  a row image, hydration or edit response for the id refreshes the entry from
+  the rendered row, or marks it stale when the parent is outside the window;
+  a reconnect (`SUBSCRIBED`) marks every non-terminal entry stale. An id a
+  RESOLVED call did not return is `'unavailable'` (the reference and the jump
+  affordance stay, the text becomes `Original message unavailable`) and is
+  never requested again. A REJECTED call writes no entry for any of its ids:
+  they stay unresolved, the failure surfaces through `error` without evicting
+  a row, and the next trigger asks again. A completed reconcile drops entries
+  no rendered row references, so the map stays bounded by the window.
+- Jump to message. `jumpToMessage(messageId)` highlights a rendered row
+  without a request; otherwise it REPLACES the window with a
+  `getMessageContext` window centred on the target and sets
+  `windowMode: 'jumped'`, with `hasOlderMessages` / `hasNewerMessages` from
+  the returned cursors. A jump is a window operation, never a re-open:
+  tombstones, the acknowledgement floor, this open's captured private state,
+  edit mode and the reply target all survive it, it arms no acknowledgement,
+  and the replacement installs exactly the rows the response carried (filtered
+  by tombstones only, with no pending or live-tail replay). A coded 404
+  `MESSAGE_NOT_FOUND` — the guaranteed answer for a quoted message that was
+  deleted — marks that preview `'unavailable'` instead of reporting an error,
+  and leaves the window untouched. Context pages are checked by their own
+  validator (room-scoped, distinct, non-pending, newest-first, within the
+  requested limit, and for a centred window the target exactly once).
+- Jumped windows. While `windowMode` is `jumped` the store acknowledges
+  nothing (the newest rendered row is not the newest row in the room), older
+  AND newer paging go through the window's own cursors (`loadNewerMessages()`
+  joins `loadOlderMessages()`), realtime inserts are recorded but not rendered
+  (ingestion still runs, so hydration, media completion, send confirmation and
+  tombstones keep working) and a queued reconcile re-reads the window with ONE
+  bounded request around its anchor instead of walking history from the live
+  tail — the tail reconcile is not dropped, it stays owed and flushes on the
+  return. `returnToLatest()` sets `live` BEFORE issuing the newest-page
+  request, so inserts arriving during it are folded in by the existing
+  precedence, then drains the deferred rows and issues the acknowledgement
+  they did not; a failed reload stays `jumped` with the window, the
+  affordance and the highlight intact. A newer page that reaches the tail runs
+  `returnToLatest()` rather than flipping in place. `sendMessage` returns to
+  the tail first (keeping the draft and the quote, and sending nothing when
+  that fails), and `jumpToMessage` is a no-op while a send is in flight.
+- Default rows. A `Reply to message` action joins `.ckui-message-actions` on
+  any confirmed row of a writer (never pending rows, never a `READ` role);
+  `canReplyToMessage` replaces that eligibility and `canEditMessage`
+  deliberately does not. A row with `replyToMessageId` renders
+  `.ckui-message-quote` above its text in three states: the resolved author
+  and truncated text (accessible name `Quoted message from <author>`),
+  `Original message unavailable`, and — while the preview is not resolved yet
+  — the reference alone (`Quoted message`), never the unavailable copy. The
+  block is a button that jumps whenever the view can. Rows without the new
+  callbacks render byte-identically to 0.8.0.
+- Highlight, scrolling and accessibility. The jumped-to row is centred with
+  `scrollIntoView({ block: 'center', behavior: 'instant' })`, focused with
+  `preventScroll` (only for an explicit jump, never for autoscroll, page loads
+  or live inserts) and tinted with the new `--ckui-highlight` theme token for
+  about two seconds; a user scroll clears the tint. One store-owned guard,
+  `jumpInFlight`, is set before the window is replaced and released on a short
+  timer: while it is set the list carries `aria-busy="true"` (omitted entirely
+  otherwise, never `aria-busy="false"`) and suspends stick-to-bottom, the
+  highlight clear and both pagination triggers. The custom-row slot wrapper
+  now carries `data-message-id`, so a replaced row is still a jump target; the
+  default row keeps carrying it on its `article`.
+- Composer. A cancellable `.ckui-composer__replying` strip (`role="status"`,
+  visible `Cancel`, accessible name `Cancel reply`, also Escape) renders where
+  the edit banner does and never touches the draft — replying, unlike editing,
+  does not replace the field. Edit mode wins when a host sets both.
+  `#composer` slots receive `replying` and `cancelReply` in Vue's flat shape,
+  beside `editing` / `cancelEdit`.
+- Controlled views. `ConversationView` gains `replyTarget`,
+  `onReplyToMessage`, `onCancelReply`, `canReplyToMessage`,
+  `replyPreviewByMessageId`, `onJumpToMessage`, `highlightedMessageId`,
+  `jumpInFlight`, `hasNewerMessages`, `isLoadingNewer`, `onLoadNewer` and
+  `onReturnToLatest` (and the `@reply-to-message`, `@cancel-reply`,
+  `@jump-to-message`, `@load-newer`, `@return-to-latest` events);
+  `MessageListView` gains all of those except `replyTarget`, `onCancelReply`
+  and `onReturnToLatest`, plus a `#loading-newer` slot. `onReturnToLatest` is
+  what renders the `Jump to latest` control, so the bound `Conversation`
+  passes it only while the window is jumped; a `#jump-to-latest` slot
+  (`JumpToLatestSlotProps`, carrying `returnToLatest`) replaces that control's
+  markup, and renders only where it does. `#message` slots gain the flat
+  `canReply`, `reply()`, `replyPreview` and `jumpToReplyTarget()` members.
+- Adapter. `ConvoKitUiClient.getReplyPreviews?(conversationId, messageIds)`
+  and `getMessageContext?(conversationId, options)` are optional and the
+  default adapter implements both; without them the jump affordance is hidden
+  and reply references render with no quoted text. Replying itself needs no
+  adapter member, so rows offer the action even on a 0.8-era adapter.
+- Mixed fleet. Against a 0.8 backend both new routes answer with an uncoded
+  404 (`HTTP_ERROR`), which is never read as "the message is gone": no preview
+  becomes `'unavailable'` and no window is replaced. After the first such
+  rejection the store turns `canResolveReplyPreviews` / `canJumpToMessage`
+  false for its life so the affordance disappears instead of failing
+  repeatedly; a coded `404 MESSAGE_NOT_FOUND` never trips that.
+- Requires `@convokitapp/sdk` 0.9.x and the corresponding backend deployment.
+- Mixed fleet, sending: a pre-0.9 backend parses only `text` and `media`, so it
+  DROPS an unknown `replyToMessageId` and stores the message with no reference.
+  The optimistic row shows the quote and the confirmed row replaces it without
+  one, so the quote visibly disappears on send. The message itself is delivered;
+  only the reference is lost. This is not detected — the send response is the
+  only signal, and acting on it would mean a second request or rewriting a row
+  that is already delivered.
+
 ## 0.8.0
 
 - Edit and delete your own messages. `useConversation` /

package/PARITY.md

@@ -34,6 +34,15 @@ while using Vue-native composition patterns.
 | Controlled edit surface (`editingMessage`, `onEditMessage`, `onSaveEdit`, `onCancelEdit`, `onDeleteMessage`, `canEditMessage`) | Named params | Props | Props + emits |
 | Row replacements receive `isEdited` / `canEdit` / `canDelete` / `edit` / `remove` | Controller state | Render props | `#message` slot |
 | Adapter `editMessage` / `deleteMessage` | Required | Optional | Optional |
+| Quoted replies (0.9.0: `replyTarget`, `startReply`, `cancelReply`, `Message.replyToMessageId`) | Controller | `useConversation` | `useConversation` |
+| Batched reply previews (`replyPreviews`, one request per burst, `'unavailable'` is terminal) | Controller | Store | Store |
+| Jump to message (0.9.0: `jumpToMessage`, `returnToLatest`, `loadNewerMessages`, `windowMode`) | Controller | `useConversation` | `useConversation` |
+| Quoted block + `Reply to message` action (`Original message unavailable`, `Quoted message`) | Scope builder | `.ckui-message-quote` | `.ckui-message-quote` |
+| Composer reply strip (`Cancel reply`, draft untouched) | Scope builder | Nested `replying` | Flat `replying` / `cancelReply` |
+| Jump highlight + focus (`--ckui-highlight`, `aria-busy` while landing) | `ensureVisible` | `scrollIntoView` | `scrollIntoView` |
+| Controlled reply / jump surface (`replyTarget`, `onJumpToMessage`, `onReturnToLatest`, …) | Named params | Props | Props + emits |
+| Row replacements receive `canReply` / `reply` / `replyPreview` / `jumpToReplyTarget` | Scope object | Render props | `#message` slot |
+| Adapter `getReplyPreviews` / `getMessageContext` | Required | Optional | Optional |
 | 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 |

package/README.md

@@ -11,6 +11,126 @@ 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.9.0 quoted replies and jump to message
+
+This release requires JavaScript SDK 0.9.x (`Message.replyToMessageId`,
+`SendMessageInput.replyToMessageId`, `ReplyPreview`, `MessageContextPage`,
+`getReplyPreviews`, `getMessageContext`) and the coordinated backend
+(`GET /api/v1/conversations/:id/reply-previews` and
+`GET /api/v1/conversations/:id/context`). Everything is additive: a room with
+no replies renders exactly as in 0.8.0.
+
+- Who may: any active member may quote any message in the room, own or not,
+  while the viewer's role (the 0.7 `membership`, else the viewer's participant
+  row) is not `READ`; pending rows are never quotable. That is deliberately
+  wider than the edit/delete eligibility, and it is **not** routed through
+  `canEditMessage` — the separate `canReplyToMessage` prop replaces it.
+- Controller members (`useConversation` and the `Conversation` controller):
+  `replyTarget` (the message the composer is quoting, or null),
+  `replyPreviews` (quoted parents by `Message.replyToMessageId`),
+  `highlightedMessageId`, `jumpInFlight`, `windowMode` (`live` or `jumped`),
+  `hasNewerMessages`, `isLoadingNewer`, `canJumpToMessage` /
+  `canResolveReplyPreviews` (adapter support), plus `startReply(messageId)`,
+  `cancelReply()`, `jumpToMessage(messageId)`, `loadNewerMessages()` and
+  `returnToLatest()`. Replying and editing are mutually exclusive: each clears
+  the other. `startReply` sends nothing, and unlike edit mode it leaves the
+  draft alone.
+- Sending: the reply target is stamped on the optimistic row, so the quoted
+  block renders before the server acknowledges the send, and it is cleared
+  only once the send is accepted. A send without a quote omits
+  `replyToMessageId` entirely, so it stays byte-identical to 0.8.0. The
+  reference is write-once: the backend rejects a retry that changes it.
+- Preview resolution is **batched, never per row**: after each page load,
+  reconcile and live-insert burst the store issues one `getReplyPreviews` call
+  for the distinct parents the loaded window cannot derive (a parent that is
+  on screen costs no request). Previews are re-read, never copied: a parent
+  edit, a deletion, or a reconnect invalidates the cached entry. An id that a
+  **resolved** call did not return is cached as the terminal `'unavailable'`
+  and rendered `Original message unavailable`, with the reference and the jump
+  affordance intact. A **rejected** call writes no entry for any of its ids:
+  they stay unresolved (the row renders the reference with no quoted text),
+  the failure surfaces through `error`, and the next trigger asks again.
+- Jump windows: `jumpToMessage` highlights a rendered row without a request;
+  otherwise it **replaces** the window with a context window centred on the
+  target and sets `windowMode: 'jumped'`. A jump is a window operation, never
+  a re-open — tombstones, the acknowledgement floor, this open's captured
+  private state, edit mode and the reply target all survive it. While jumped
+  the store acknowledges nothing, realtime inserts are recorded but not
+  rendered, paging goes through the window's own cursors in both directions,
+  and a queued reconcile re-reads the window with one bounded request instead
+  of walking history from the tail (the tail reconcile stays owed and runs on
+  the return). `returnToLatest()` reloads the newest page, drains the deferred
+  rows and acknowledges them; if it fails the window and the affordance stay.
+  A jump is refused while a send is in flight, and a send from a jumped window
+  returns to the tail first, keeping the draft and the quote.
+- Default rows: a `Reply to message` action joins the existing actions menu,
+  and a reply renders `.ckui-message-quote` above its text with the quoted
+  author and text, `Original message unavailable` when the parent is gone, or
+  the reference alone while the preview is not resolved yet. The block is a
+  button (name `Quoted message from <author>`) whenever the view can jump. The
+  jumped-to row is centred (`scrollIntoView({ block: 'center', behavior:
+  'instant' })`), focused and tinted with `--ckui-highlight` for about two
+  seconds; the list carries `aria-busy="true"` only while the jump lands, and
+  stick-to-bottom, pagination and the highlight clear are suspended for that
+  window. Rows without the new callbacks render byte-identically to 0.8.0.
+- Composer: a cancellable `.ckui-composer__replying` strip (`role="status"`,
+  `Cancel reply`, Escape) sits where the edit banner does. It never replaces
+  the draft. `#composer` slots receive `replying` and `cancelReply`.
+- Controlled views: `ConversationView` accepts `replyTarget`,
+  `onReplyToMessage`, `onCancelReply`, `canReplyToMessage`,
+  `replyPreviewByMessageId`, `onJumpToMessage`, `highlightedMessageId`,
+  `jumpInFlight`, `hasNewerMessages`, `isLoadingNewer`, `onLoadNewer` and
+  `onReturnToLatest` (also as `@reply-to-message`, `@cancel-reply`,
+  `@jump-to-message`, `@load-newer`, `@return-to-latest`);
+  `MessageListView` accepts all of those except `replyTarget`,
+  `onCancelReply` and `onReturnToLatest`. `onReturnToLatest` is what renders
+  the `Jump to latest` control, so pass it only while the window is jumped.
+  `#message` slots receive `canReply`, `reply()`, `replyPreview` and
+  `jumpToReplyTarget()`; the slot wrapper carries `data-message-id` so a
+  replaced row is still a jump target.
+- Adapter additions: `ConvoKitUiClient.getReplyPreviews?(conversationId,
+  messageIds)` and `getMessageContext?(conversationId, options)` are optional;
+  the default adapter implements both. (The Flutter and Android UIs make the
+  same members required on their `ConvoKitUiClient`, a breaking change for
+  custom implementers there.) Replying itself needs no adapter member.
+- Mixed fleet: against a 0.8 backend both routes answer Express's unmatched
+  route with an uncoded 404 (`HTTP_ERROR`). That is **not** "the message is
+  gone": no preview becomes `unavailable` and no window is replaced. After the
+  first such rejection the store sets `canResolveReplyPreviews` /
+  `canJumpToMessage` to false for its life, so the affordance disappears
+  instead of failing repeatedly; a coded `404 MESSAGE_NOT_FOUND` never does
+  that — it is a real missing target and marks that one preview `unavailable`.
+  A 0.8 client against a 0.9 backend simply ignores the new row key.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import type { Message, ReplyPreview } from '@convokitapp/sdk'
+import { ConversationView } from '@convokitapp/vue-ui'
+
+const replyTarget = ref<Message | null>(null)
+const previews = ref(new Map<string, ReplyPreview | 'unavailable'>())
+const highlighted = ref<string | null>(null)
+async function send(text: string) {
+  await api.sendMessage({ text, ...(replyTarget.value ? { replyToMessageId: replyTarget.value.id } : {}) })
+  replyTarget.value = null
+}
+</script>
+
+<template>
+  <ConversationView
+    v-bind="conversationProps"
+    :reply-target="replyTarget"
+    :reply-preview-by-message-id="previews"
+    :highlighted-message-id="highlighted"
+    @send-message="send"
+    @reply-to-message="(message) => (replyTarget = message)"
+    @cancel-reply="replyTarget = null"
+    @jump-to-message="(messageId) => (highlighted = messageId)"
+  />
+</template>
+```
+
 ## 0.8.0 edit and delete your own messages
 
 This release requires JavaScript SDK 0.8.x (`editMessage`, `deleteMessage`,
@@ -414,7 +534,12 @@ is eligible, `edit()` and `remove()`; `#composer` slots receive `editing` and
 
 Available slots include `conversation-item`, `separator`, `header`, `message`,
 `media`, `read-receipt`, `composer`, `typing-indicator`, `loading`, `empty`,
-`error`, `load-more`, `loading-older`, and `message-error`.
+`error`, `load-more`, `loading-older`, `loading-newer`, `jump-to-latest`, and
+`message-error`. `#loading-newer` (in `MessageListView`) replaces the newer-end
+spinner of a jumped window, and `#jump-to-latest` (in `ConversationView`)
+replaces the default `Jump to latest` control, receiving `returnToLatest`
+(`JumpToLatestSlotProps`); both render only while the window is jumped, so a
+live window stays byte-identical to 0.8.0 (0.9.0).
 
 ## Composables