@convokitapp/vue-ui 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,105 @@
 # Changelog
 
+## 0.8.0
+
+- Edit and delete your own messages. `useConversation` /
+  `ConversationController` gain `editingMessage` (the row being edited, as
+  the user saw it when editing started; null otherwise), `canEditMessages` /
+  `canDeleteMessages` (adapter support, decided once at construction),
+  `startEditing(messageId)` (a no-op unless the row is rendered, the viewer's
+  own, confirmed, not known to be gone, the viewer's role when known is not
+  `READ` and the adapter implements `editMessage`; sends nothing, not even a
+  typing update), `cancelEditing()`, `saveEdit(text)` and
+  `deleteMessage(messageId)` (both resolve to a boolean and reject when the
+  adapter lacks the member). `saveEdit` trims the text, sends `null` for an
+  empty caption, never sends an empty text for a text-only message, and always
+  sends the SNAPSHOT's `revision`, never the live row's; the response is
+  merged through the tombstone and precedence guards and edit mode ends. A
+  stale revision (409 `REVISION_CONFLICT`) reloads the row once through
+  `getMessage`, replaces `editingMessage` with it (so the next save carries
+  the fresh revision), reports the conflict through `error` and keeps edit
+  mode; when a row for the edited message with a higher revision reaches the
+  store by itself (a row image, a hydration, a reconcile or a refresh) the
+  same conflict state is entered without a request. A coded 404
+  (`MESSAGE_NOT_FOUND`, on the save or on the conflict reload) removes the
+  row and ends edit mode; any other failure, including a 403 and the uncoded
+  404 a 0.7 backend answers, is reported through `error` without evicting
+  anything and keeps edit mode. `deleteMessage` keeps the row until the server
+  answers (no optimistic removal): success or `MESSAGE_NOT_FOUND` tombstone
+  and remove it (late responses, row images and hydrations for the id are
+  dropped, the acknowledgement target is re-resolved, edit mode on it ends);
+  other failures keep it and report through `error`. A `message_deleted`
+  notification, a reconcile that no longer sees the row or a history eviction
+  also ends edit mode on it.
+- Row precedence. Wherever rows meet (live events, hydration, reconcile,
+  older pages, send and edit responses) the higher `Message.revision` now
+  wins when both rows carry one and at least one is above 0, and a lower
+  revision never overwrites a higher one; equal revisions and rows without a
+  usable revision (pending rows, 0.7 backends where every row is 0) keep the
+  `updatedAt ?? createdAt` rule with its "complete row wins on ties"
+  heuristic. Pending rows are created with `revision: 0`.
+- Default rows. Eligible rows (the viewer's own confirmed rows while the
+  viewer's role is not `READ`, or whatever `canEditMessage` says; never
+  pending rows) render `.ckui-message-actions` with `Edit message` and
+  `Delete message` icon buttons only while the matching callback is present
+  and the adapter supports the action. The actions are always in the DOM;
+  only `@media (hover: hover) and (pointer: fine)` conceals them
+  (`opacity: 0; pointer-events: none`, never `display: none`) until the row is
+  hovered or focused, so touch and keyboard users always see them. `Delete
+  message` opens an inline prompt (`role="group"`, accessible name
+  `Delete this message?`) with `Delete` (`Confirm delete`) and `Cancel`
+  (`Cancel delete`); `confirmDelete` replaces it. Rows with `revision > 0`
+  show `Edited` (`.ckui-message-edited`, accessible name `Edited`) beside the
+  time, for every sender, never on pending rows. Apart from that label, rows
+  that are not eligible, and every row when the callbacks are absent, render
+  byte-identically to 0.7.0.
+- Composer edit mode (`ConversationView`, driven by `editingMessage`).
+  Entering stashes the unsent draft and prefills the field with the message
+  text without a typing update; the submit path (Enter, the primary button,
+  a custom composer's `send`) calls `onSaveEdit(message, text)` instead of
+  `onSendMessage`, without clearing the field first. `false` keeps edit mode
+  and the edited text; any other result, and Cancel (visible `Cancel`,
+  accessible name `Cancel editing`) or Escape, restore the stash and report
+  typing from it (`onTypingChange(stash.trim().length > 0)`). When edit mode
+  ends externally the field keeps text the user changed and restores the
+  stash only when it is empty or still the snapshot's text; a refreshed
+  snapshot for the same message leaves the draft alone. The primary button is
+  `Check` with the accessible name `Save message` (`Send message` otherwise)
+  and is enabled while the field has text or the edited row has attachments
+  (an empty caption clears it); a banner (`.ckui-composer__editing`,
+  `role="status"`) shows `Editing message` with the message's text or
+  attachment count. `#composer` slots receive `editing` and `cancelEdit`
+  while editing.
+- Controlled views. `ConversationView` gains `editingMessage`,
+  `onEditMessage`, `onSaveEdit`, `onCancelEdit`, `onDeleteMessage`,
+  `canEditMessage` and `confirmDelete` (and the `edit-message`, `save-edit`,
+  `cancel-edit`, `delete-message` emits); `MessageListView` gains
+  `onEditMessage`, `onDeleteMessage`, `canEditMessage` and `confirmDelete`.
+  `#message` slots receive `isEdited`, `canEdit`, `canDelete` and, while
+  eligible, `edit()` and `remove()` (`remove` asks `confirmDelete` when the
+  view has one, otherwise deletes at once: a custom row owns its prompt). The
+  bound `Conversation` wires the composable (`editingMessage`,
+  `startEditing`, `saveEdit`, `cancelEditing`, `deleteMessage`) only while the
+  adapter supports each action, forwards `canEditMessage` and
+  `confirmDelete`, and emits the four events like `send-message`.
+- Adapter: optional `editMessage?(messageId, { text, revision })` and
+  `deleteMessage?(messageId)`; the default adapter implements both. Without
+  them nothing renders and `saveEdit` / `deleteMessage` reject. (The Flutter
+  and Android UIs make the members required on their `ConvoKitUiClient`: a
+  breaking change for custom implementers there, like `listInbox` in 0.6.0.)
+  A custom adapter must reject a stale revision with `code:
+  'REVISION_CONFLICT'` and a gone message with `code: 'MESSAGE_NOT_FOUND'`;
+  an uncoded 404 is reported, never treated as a deleted message.
+- Requires core SDK 0.8.x (`editMessage`, `deleteMessage`, the required
+  `Message.revision`, `isEditedMessage`) and the coordinated backend
+  (`PATCH`/`DELETE /api/v1/messages/:id/own`). Consumer-built `Message`
+  literals gain `revision`. Mixed fleet: against a 0.7 backend the author
+  routes answer an uncoded 404 (`HTTP_ERROR`) that surfaces as `error` and
+  keeps the row; every row parses with revision 0, so nothing reads `Edited`
+  and precedence falls back to timestamps. Deleting a message does not
+  retract files other members already received; stored files are reclaimed by
+  the existing user or app deletion cleanup.
+
 ## 0.7.0
 
 - Private mark unread. `useConversationList` / `ConversationListController`

package/PARITY.md

@@ -26,6 +26,14 @@ while using Vue-native composition patterns.
 | 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 |
+| Edit / delete own messages (0.8.0: `editingMessage`, `startEditing`, `cancelEditing`, `saveEdit`, `deleteMessage`) | Controller | `useConversation` | `useConversation` |
+| Row precedence by `Message.revision`, timestamps on ties | Yes | Yes | Yes |
+| Default row actions + `Edited` label (accessible names `Edit message` / `Delete message` / `Edited`) | Long press + sheet | `.ckui-message-actions` hover/focus reveal | `.ckui-message-actions` hover/focus reveal |
+| Delete confirmation (`Confirm delete` / `Cancel delete`), `confirmDelete` override | `showDialog` | Inline prompt | Inline prompt |
+| Composer edit mode (banner, `Save message`, `Cancel editing`, caption clearing, draft stash) | Yes | Yes | Yes |
+| 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 |
 | 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 |
@@ -91,3 +99,32 @@ 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.
+
+## Message-edit parity (0.8.0)
+
+Every UI lets the viewer edit and delete their own confirmed messages through
+the room controller (`editingMessage`, `canEditMessages` /
+`canDeleteMessages`, `startEditing`, `cancelEditing`, `saveEdit`,
+`deleteMessage`), sends the SNAPSHOT's `revision` captured when editing
+started (never the live row's), reloads the row once on 409
+`REVISION_CONFLICT` and refreshes the snapshot so the next save carries the
+fresh revision, enters the same conflict state without a request when a
+newer row for the edited message arrives on its own, removes the row only on
+a coded 404 `MESSAGE_NOT_FOUND` (an uncoded 404 from a 0.7 backend is an
+error that keeps the row and edit mode), and keeps the row until the server
+accepts a deletion. Rows merge by the higher `Message.revision` when both
+carry one and at least one is above 0, falling back to `updatedAt ??
+createdAt` on ties and for pending rows. Default rows offer `Edit message` /
+`Delete message` (web: `.ckui-message-actions`, always in the DOM, concealed
+only under `(hover: hover) and (pointer: fine)` until hover or focus; natives:
+long press or context menu) with a confirmation (`Confirm delete` /
+`Cancel delete`; `confirmDelete` overrides it) and show `Edited` for
+`revision > 0`; rows that are not eligible render as in 0.7.0. The composer's
+single submit path saves while editing, prefills the message text without a
+typing update, stashes and restores the unsent draft, keeps the edited text on
+failure or conflict, and allows an empty caption for a message with
+attachments (`text: null`). 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 Swift UI's bound
+view gains `onController`. The parity script checks API presence only; the
+store, rendered-view and actual-SDK protocol tests verify behavior.

package/README.md

@@ -11,6 +11,112 @@ 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.8.0 edit and delete your own messages
+
+This release requires JavaScript SDK 0.8.x (`editMessage`, `deleteMessage`,
+the required `Message.revision`, `isEditedMessage`) and the coordinated
+backend (`PATCH`/`DELETE /api/v1/messages/:id/own`). Consumer-built `Message`
+literals (fixtures, controlled views) gain `revision`.
+
+- Who may: the viewer's own confirmed messages, while the viewer's role (the
+  0.7 `membership`, else the viewer's participant row) is not `READ`. The
+  server checks the same rules (403 for other members' messages and `READ`
+  roles); custom row eligibility goes through `canEditMessage`.
+- Controller members (`useConversation` and the `Conversation` controller):
+  `editingMessage` (the row being edited as the user saw it; null otherwise),
+  `canEditMessages` / `canDeleteMessages` (adapter support),
+  `startEditing(messageId)`, `cancelEditing()`, `saveEdit(text)` and
+  `deleteMessage(messageId)`. `saveEdit` sends the snapshot's `revision`,
+  never the live row's: a stale one answers 409 `REVISION_CONFLICT`, the
+  store reloads the row once, shows its current content as the new snapshot
+  (the banner and the row update, the draft stays) and reports the conflict
+  through `error`; the next save carries the fresh revision. A newer row for
+  the edited message arriving on its own (row image, hydration, reconcile)
+  enters the same state without a request. A coded 404 `MESSAGE_NOT_FOUND`
+  removes the row and ends edit mode; a 403, a 500, a network failure or the
+  uncoded 404 a 0.7 backend answers keep the row, the history and edit mode
+  and set `error`. `deleteMessage` removes nothing until the server accepts
+  (or answers `MESSAGE_NOT_FOUND`); other devices learn through the room's
+  deletion notification and late responses for a removed id are dropped.
+- Precedence: when rows meet, the higher `Message.revision` wins when both
+  carry one and at least one is above 0; ties and rows without a usable
+  revision keep the `updatedAt ?? createdAt` rule.
+- Default row actions: eligible rows render `.ckui-message-actions` with
+  `Edit message` and `Delete message` buttons, always in the DOM. Only
+  `@media (hover: hover) and (pointer: fine)` conceals them (`opacity` and
+  `pointer-events`, never `display: none`) until the row is hovered or
+  focused; touch and keyboard users always see them. `Delete message` opens an
+  inline prompt (`role="group"`, name `Delete this message?`) with `Delete`
+  (`Confirm delete`) and `Cancel` (`Cancel delete`); pass `confirmDelete` to
+  use your own dialog. Edited rows show `Edited` (name `Edited`) beside the
+  time. Apart from that label, rows that are not eligible, and every row
+  without the callbacks, render byte-identically to 0.7.0.
+- Composer edit mode: entering stashes the unsent draft and prefills the
+  field with the message text without a typing update. Enter, the primary
+  button (`Check`, name `Save message`) or a custom composer's `send` saves;
+  Cancel (name `Cancel editing`) and Escape restore the stash. Save is
+  enabled while the field has text or the message has attachments: an empty
+  caption is sent as `null` and clears it (attachments are never changed). A
+  refused save keeps the edited text and edit mode; a successful one and a
+  cancel restore the stash. `#composer` slots receive `editing` and
+  `cancelEdit` while editing.
+- Controlled views: `ConversationView` accepts `editingMessage`,
+  `onEditMessage`, `onSaveEdit`, `onCancelEdit`, `onDeleteMessage`,
+  `canEditMessage` and `confirmDelete` (also as `@edit-message`, `@save-edit`,
+  `@cancel-edit`, `@delete-message`); `MessageListView` accepts
+  `onEditMessage`, `onDeleteMessage`, `canEditMessage` and `confirmDelete`.
+  Without the callbacks nothing new renders. `#message` slots receive
+  `isEdited`, `canEdit`, `canDelete` and, while eligible, `edit()` and
+  `remove()` (`remove` runs `confirmDelete` when present, otherwise deletes at
+  once). The bound `Conversation` wires the composable, forwards
+  `canEditMessage` and `confirmDelete`, and emits the four events.
+- Adapter additions: `ConvoKitUiClient.editMessage?(messageId, { text,
+  revision })` and `deleteMessage?(messageId)` are optional; the default
+  adapter implements both. Without them the rows render no actions and
+  `saveEdit` / `deleteMessage` reject. (The Flutter and Android UIs make the
+  same members required on their `ConvoKitUiClient`: a breaking change for
+  custom implementers there, like `listInbox` in 0.6.0.) Custom adapters must
+  reject a stale revision with `code: 'REVISION_CONFLICT'` and a gone message
+  with `code: 'MESSAGE_NOT_FOUND'`.
+- Deleting a message removes it and its attachments from the conversation for
+  every member and cannot be undone; files already received or downloaded
+  cannot be retracted, and stored files are reclaimed by the existing user or
+  app deletion cleanup.
+- Mixed fleet: 0.7 clients ignore `revision`; against a 0.7 backend the author
+  routes answer an uncoded 404 (`HTTP_ERROR`) that keeps the row and edit
+  mode, every row parses with revision 0 and nothing reads `Edited`.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import type { Message } from '@convokitapp/sdk'
+import { ConversationView } from '@convokitapp/vue-ui'
+
+const editing = ref<Message | null>(null)
+const rows = ref<Message[]>([])
+async function saveEdit(message: Message, text: string) {
+  // Send message.revision; on 409 REVISION_CONFLICT reload the row and let the user retry.
+  const saved = await api.editMessage(message.id, { text: text || null, revision: message.revision })
+  rows.value = rows.value.map((row) => (row.id === saved.id ? saved : row))
+  editing.value = null
+}
+const confirmDelete = (message: Message) => window.confirm(`Delete "${message.text ?? 'this message'}"?`)
+</script>
+
+<template>
+  <ConversationView
+    v-bind="conversationProps"
+    :messages="rows"
+    :editing-message="editing"
+    @edit-message="(message) => (editing = message)"
+    @save-edit="saveEdit"
+    @cancel-edit="editing = null"
+    @delete-message="(message) => api.deleteMessage(message.id)"
+    :confirm-delete="confirmDelete"
+  />
+</template>
+```
+
 ## 0.7.0 private mark unread
 
 This release requires JavaScript SDK 0.7.x (`markConversationUnread`,
@@ -292,15 +398,20 @@ state directly. Every important surface has a named slot:
   <template #header="{ conversation }">
     <SupportHeader :title="conversation.displayTitle" />
   </template>
-  <template #message="{ message, isCurrentUser, readerIds }">
-    <SupportBubble :message="message" :mine="isCurrentUser" :read-by="readerIds" />
+  <template #message="{ message, isCurrentUser, readerIds, isEdited, edit, remove }">
+    <SupportBubble :message="message" :mine="isCurrentUser" :read-by="readerIds" :edited="isEdited" @edit="edit" @delete="remove" />
   </template>
-  <template #composer="{ value, setValue, send }">
-    <BrandComposer :model-value="value" @update:model-value="setValue" @send="send" />
+  <template #composer="{ value, setValue, send, editing, cancelEdit }">
+    <BrandComposer :model-value="value" :editing="editing" @update:model-value="setValue" @send="send" @cancel="cancelEdit" />
   </template>
 </ConversationView>
 ```
 
+`#message` slots receive `isEdited`, `canEdit`, `canDelete` and, while the row
+is eligible, `edit()` and `remove()`; `#composer` slots receive `editing` and
+`cancelEdit` while the view is in edit mode, and their `send` saves the edit
+(0.8.0).
+
 Available slots include `conversation-item`, `separator`, `header`, `message`,
 `media`, `read-receipt`, `composer`, `typing-indicator`, `loading`, `empty`,
 `error`, `load-more`, `loading-older`, and `message-error`.
@@ -317,6 +428,9 @@ 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.
+For the viewer's own messages it exposes `editingMessage`, `canEditMessages`,
+`canDeleteMessages`, `startEditing(messageId)`, `cancelEditing()`,
+`saveEdit(text)` and `deleteMessage(messageId)` (0.8.0).
 
 Optimistic rows display `Sending…` until acknowledgement. The final server
 timestamp is formatted in the viewer's local timezone. Custom message slots can