@convokitapp/react-ui 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ConvoKit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PARITY.md

@@ -0,0 +1,32 @@
+# React UI parity
+
+This package mirrors the current `convokit_flutter_ui` baseline while using
+React-native composition patterns.
+
+| Capability | Flutter UI | React UI |
+| --- | --- | --- |
+| SDK-backed conversation list | `ConvoKitConversationList` | `ConversationList` |
+| Controlled conversation list | `ConvoKitConversationListView` | `ConversationListView` |
+| SDK-backed conversation | `ConvoKitConversation` | `Conversation` |
+| Controlled conversation | `ConvoKitConversationView` | `ConversationView` |
+| Controlled message list | `ConvoKitMessageListView` | `MessageListView` |
+| Replaceable SDK boundary | `ConvoKitUiClient` | `ConvoKitUiClient` |
+| Conversation controller | `ConvoKitConversationController` | `useConversation` |
+| Conversation-list controller | `ConvoKitConversationListController` | `useConversationList` |
+| Offset pagination and de-duplication | Yes | Yes |
+| Search, archived, participant, predicate, sort filters | Yes | Yes |
+| Realtime messages, typing, reads | Yes | Yes |
+| Read markers and reader resolution | Yes | Yes |
+| Mark read on load/receive | Yes | Yes |
+| Typing idle timeout | Yes | Yes |
+| Image, file, location, contact rendering | Yes | Yes |
+| Row/header/message/media/receipt/composer replacements | Builders | Render props |
+| Empty/loading/error replacements | Builders | Render props |
+| Theme tokens | Theme extension | CSS variables/provider |
+| Compact presentation | Custom builders | `density="compact"` plus render props |
+| Host-owned attachment opening | Callback | Callback |
+| Accessibility primitives | Material semantics | Native semantics + Radix Avatar |
+
+React additionally exposes controlled/uncontrolled composer text, per-part
+`classNames` and `styles`, an `unstyled` mode, native element props, image
+loading policy, time formatting, and scroll behavior controls.

package/README.md

@@ -0,0 +1,110 @@
+# ConvoKit React UI
+
+Accessible, plug-and-play React chat components for
+[`@convokitapp/sdk`](https://www.npmjs.com/package/@convokitapp/sdk). Defaults
+follow shadcn-style composition and CSS variables, use Radix Avatar for an
+accessible primitive, and remain framework-CSS independent.
+
+## Install
+
+```bash
+npm install @convokitapp/sdk @convokitapp/react-ui
+```
+
+Import the packaged styles once:
+
+```tsx
+import '@convokitapp/react-ui/styles.css'
+```
+
+## SDK-backed UI
+
+Connect the core SDK, adapt it once, and render the list and selected room. The
+client secret belongs only in your token backend.
+
+```tsx
+import { ConvoKitClient } from '@convokitapp/sdk'
+import {
+  Conversation,
+  ConversationList,
+  createConvoKitUiClient,
+} from '@convokitapp/react-ui'
+
+const sdk = new ConvoKitClient({
+  backendUrl: 'https://api.example.com',
+  clientId: 'public-client-id',
+  tokenProvider: async (appUserId) =>
+    fetch('/api/chat/token', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ appUserId }),
+    }).then(async (response) => (await response.json()).token),
+})
+
+await sdk.connectUser(currentUser.id)
+const uiClient = createConvoKitUiClient(sdk)
+
+<ConversationList
+  client={uiClient}
+  onConversationSelect={(room) => setRoomId(room.id)}
+/>
+
+<Conversation
+  client={uiClient}
+  conversationId={roomId}
+  onAttachmentClick={(media) => openAttachment(media)}
+/>
+```
+
+## Controlled components
+
+Use `ConversationListView`, `ConversationView`, and `MessageListView` when your
+application owns state. `useConversationList` and `useConversation` expose the
+same controller capabilities as the Flutter UI package without forcing a
+state-management library.
+
+## Customization
+
+Every meaningful section can be replaced through render props, including the
+conversation row, separator, header, message, media block, read receipt, typing
+indicator, composer, and loading/empty/error states.
+
+```tsx
+<ConversationView
+  {...state}
+  onSendMessage={send}
+  density="compact"
+  classNames={{ root: 'h-full', outgoingMessage: 'my-message' }}
+  styles={{ composer: { padding: 16 } }}
+  renderReadReceipt={({ readerIds }) => (
+    <span>{readerIds.size ? `Seen by ${readerIds.size}` : 'Sent'}</span>
+  )}
+  renderMedia={({ media }) =>
+    media.type === 'location' ? <MyMap location={media} /> : undefined
+  }
+/>
+```
+
+Set `unstyled` to remove package component classes while retaining behavior and
+semantic markup. Use `ConvoKitThemeProvider` or override the documented
+`--ckui-*` variables to theme defaults without rebuilding CSS.
+
+## Public examples
+
+The public
+[`ConvoKit-React-UI-Examples`](https://github.com/ConvoKitApp/ConvoKit-React-UI-Examples)
+repository contains runnable standard, branded-support, and compact-operations
+configurations plus a live SDK-backed example. The package implementation
+remains in its private source repository.
+
+## Verification
+
+```bash
+npm ci
+npm run validate
+```
+
+The release gate type-checks source and tests, runs component/controller tests
+with coverage thresholds, builds ESM/CommonJS/TypeScript declarations and CSS,
+checks Flutter UI parity, validates package exports, and inspects the npm
+tarball.