@sqlrooms/discuss 0.27.0 → 0.28.0

package/README.md

@@ -1,74 +1,17 @@
-A simple discussion system for SQLRooms applications. Can be used for commenting and annotation with support for threaded conversations, real-time updates, and anchor-based discussions.
+Threaded discussion slice and UI components for SQLRooms.
 
-## Overview
+Use this package to add comments/replies linked to data points or UI anchors.
 
-The `@sqlrooms/discuss` module provides a complete discussion system with the following key features:
+## Installation
 
-- **Threaded conversations**: Support for replies to discussions and comments
-- **Anchor-based discussions**: Link discussions to specific data points or UI elements
-- **Real-time state management**: Built on Zustand for reactive updates
-- **Customizable rendering**: Flexible component system for custom UI implementations
-- **Delete confirmation**: Built-in confirmation dialogs for safe content removal
-- **Highlighting**: Visual highlighting of specific discussions
-
-## Main Components
-
-### Core Components
-
-#### `DiscussionList`
-
-The main container component that renders all discussions with built-in forms for adding, editing, and replying to content.
-
-```tsx
-import {DiscussionList} from '@sqlrooms/discuss';
-
-<DiscussionList
-  className="flex flex-col gap-4"
-  renderComment={(props) => <CustomCommentRenderer {...props} />}
-  renderDiscussion={(props) => <CustomDiscussionRenderer {...props} />}
-/>;
-```
-
-#### `CommentItem`
-
-Individual comment renderer with built-in edit/delete actions.
-
-```tsx
-import {CommentItem} from '@sqlrooms/discuss';
-
-<CommentItem comment={comment} discussion={discussion}>
-  <div className="flex flex-col gap-1">
-    <div className="text-muted-foreground text-xs">
-      {comment.userId} - {formatTimeRelative(comment.timestamp)}
-    </div>
-    <div className="whitespace-pre-wrap text-sm">{comment.text}</div>
-  </div>
-</CommentItem>;
+```bash
+npm install @sqlrooms/discuss @sqlrooms/room-shell @sqlrooms/ui @sqlrooms/utils
 ```
 
-#### `DiscussionItem`
-
-Container for a complete discussion thread including root comment and replies.
-
-```tsx
-import {DiscussionItem} from '@sqlrooms/discuss';
-
-<DiscussionItem
-  discussion={discussion}
-  renderComment={customCommentRenderer}
-  className="rounded border p-4"
-/>;
-```
-
-### Store Integration
-
-#### Store Setup with `createDiscussSlice`
-
-To use the discussion system, you need to integrate it with your room store using `createDiscussSlice`:
+## Store setup
 
 ```tsx
 import {
-  createDefaultDiscussConfig,
   createDiscussSlice,
   DiscussSliceConfig,
   DiscussSliceState,
@@ -77,284 +20,108 @@ import {
   BaseRoomConfig,
   createRoomShellSlice,
   createRoomStore,
+  LayoutConfig,
   RoomShellSliceState,
+  persistSliceConfigs,
 } from '@sqlrooms/room-shell';
-import {z} from 'zod';
-
-// 1. Extend your app config with DiscussSliceConfig
-export const RoomConfig = BaseRoomConfig.merge(DiscussSliceConfig);
-export type RoomConfig = z.infer<typeof RoomConfig>;
 
-// 2. Extend your app state with DiscussSliceState
-export type RoomState = RoomShellSliceState<RoomConfig> & DiscussSliceState;
+type RoomState = RoomShellSliceState & DiscussSliceState;
 
-// 3. Create the store with discuss slice
-export const {roomStore, useRoomStore} = createRoomStore<RoomConfig, RoomState>(
-  (set, get, store) => ({
-    // Add the discuss slice with a user ID
-    ...createDiscussSlice({userId: 'current-user-id'})(set, get, store),
-
-    // Add your room shell slice
-    ...createRoomShellSlice<RoomConfig>({
-      connector: yourDatabaseConnector,
-      config: {
-        // Include default discuss config
-        ...createDefaultDiscussConfig(),
-        // Your other config...
-        layout: {
-          /* your layout */
-        },
-        dataSources: [
-          /* your data sources */
-        ],
-      },
-      room: {
-        // Your room configuration
+export const {roomStore, useRoomStore} = createRoomStore<RoomState>(
+  persistSliceConfigs(
+    {
+      name: 'discuss-demo-storage',
+      sliceConfigSchemas: {
+        room: BaseRoomConfig,
+        layout: LayoutConfig,
+        discuss: DiscussSliceConfig,
       },
-    })(set, get, store),
-  }),
+    },
+    (set, get, store) => ({
+      ...createRoomShellSlice({
+        config: {title: 'Discuss Demo', dataSources: []},
+      })(set, get, store),
+      ...createDiscussSlice({userId: 'user-1'})(set, get, store),
+    }),
+  ),
 );
 ```
 
-#### Using the Store Hook
+## Initialization
 
-Access discussion state and actions using the provided hook:
+Call `room.initialize()` after store creation so slice lifecycle hooks run:
 
 ```tsx
-import {useStoreWithDiscussion} from '@sqlrooms/discuss';
+import {useEffect} from 'react';
+import {roomStore} from './store';
 
-function MyComponent() {
-  // Get discussions
-  const discussions = useStoreWithDiscussion(
-    (state) => state.discuss.config.discussions,
-  );
+function App() {
+  useEffect(() => {
+    void roomStore.getState().room.initialize();
+  }, []);
 
-  // Get actions
-  const addDiscussion = useStoreWithDiscussion(
-    (state) => state.discuss.addDiscussion,
-  );
-  const setReplyToItem = useStoreWithDiscussion(
-    (state) => state.discuss.setReplyToItem,
-  );
-
-  // Add a new discussion
-  const handleAddDiscussion = (text: string, anchorId?: string) => {
-    addDiscussion(text, anchorId);
-  };
-
-  // Start replying to a discussion
-  const handleReply = (discussionId: string) => {
-    setReplyToItem({discussionId});
-  };
+  return null;
 }
 ```
 
-## Usage Examples
-
-### Basic Discussion Panel
+## Render discussions
 
 ```tsx
-import {DiscussionList, CommentItem} from '@sqlrooms/discuss';
-import {useStoreWithDiscussion} from '@sqlrooms/discuss';
+import {CommentItem, DiscussionList} from '@sqlrooms/discuss';
 import {formatTimeRelative} from '@sqlrooms/utils';
+import {useRoomStore} from './store';
 
-const DiscussionPanel = () => {
-  const discussions = useStoreWithDiscussion(
-    (state) => state.discuss.config.discussions,
-  );
+export function DiscussionPanel() {
+  const discussions = useRoomStore((state) => state.discuss.config.discussions);
 
-  return (
-    <div className="h-full">
-      {discussions.length === 0 ? (
-        <div className="py-10 text-center text-gray-400">
-          <p>No comments yet. Start a discussion!</p>
-        </div>
-      ) : (
-        <DiscussionList
-          className="flex flex-col gap-4"
-          renderComment={(props) => {
-            const {comment, discussion} = props;
-            const {anchorId} = discussion;
-            const isRootComment = comment.id === discussion.rootComment.id;
+  if (discussions.length === 0) {
+    return <div className="p-4 text-sm text-muted-foreground">No discussions yet.</div>;
+  }
 
-            return (
-              <CommentItem {...props}>
-                <div className="flex flex-col gap-1">
-                  {anchorId && isRootComment && (
-                    <div className="text-md flex items-center gap-2 font-medium">
-                      📍 Linked to: {anchorId}
-                    </div>
-                  )}
-                  <div className="text-muted-foreground text-xs">
-                    {comment.userId} - {formatTimeRelative(comment.timestamp)}
-                  </div>
-                  <div className="whitespace-pre-wrap text-sm">
-                    {comment.text}
-                  </div>
-                </div>
-              </CommentItem>
-            );
-          }}
-        />
-      )}
-    </div>
-  );
-};
-```
-
-### Anchor-Based Discussions
-
-Link discussions to specific data points or UI elements:
-
-```tsx
-import {useStoreWithDiscussion} from '@sqlrooms/discuss';
-
-function DataVisualization() {
-  const addDiscussion = useStoreWithDiscussion(
-    (state) => state.discuss.addDiscussion,
-  );
-  const setHighlightedDiscussionId = useStoreWithDiscussion(
-    (state) => state.discuss.setHighlightedDiscussionId,
-  );
-
-  // Handle clicking on a data point
-  const handleDataPointClick = (dataId: string) => {
-    // Add a discussion linked to this data point
-    addDiscussion('What do you think about this data point?', dataId);
-  };
-
-  // Highlight related discussion when hovering over data
-  const handleDataPointHover = (dataId: string) => {
-    const discussions =
-      useStoreWithDiscussion.getState().discuss.config.discussions;
-    const relatedDiscussion = discussions.find((d) => d.anchorId === dataId);
-    if (relatedDiscussion) {
-      setHighlightedDiscussionId(relatedDiscussion.id);
-    }
-  };
-
-  return (
-    <div>
-      {/* Your data visualization with clickable elements */}
-      <div
-        onClick={() => handleDataPointClick('airport-LAX')}
-        onMouseEnter={() => handleDataPointHover('airport-LAX')}
-        className="cursor-pointer hover:bg-blue-100"
-      >
-        LAX Airport
-      </div>
-    </div>
-  );
-}
-```
-
-### Custom Comment Rendering
-
-```tsx
-import {DiscussionList, CommentItem} from '@sqlrooms/discuss';
-import {Avatar, Badge} from '@sqlrooms/ui';
-
-const CustomDiscussionPanel = () => {
   return (
     <DiscussionList
-      renderComment={(props) => {
-        const {comment, discussion} = props;
-
-        return (
-          <CommentItem {...props}>
-            <div className="flex gap-3">
-              <Avatar className="h-8 w-8">
-                {comment.userId.charAt(0).toUpperCase()}
-              </Avatar>
-              <div className="flex-1">
-                <div className="mb-1 flex items-center gap-2">
-                  <span className="font-medium">{comment.userId}</span>
-                  <Badge variant="secondary" className="text-xs">
-                    {formatTimeRelative(comment.timestamp)}
-                  </Badge>
-                </div>
-                <div className="text-sm leading-relaxed">{comment.text}</div>
-              </div>
-            </div>
-          </CommentItem>
-        );
-      }}
+      className="flex flex-col gap-4"
+      renderComment={(props) => (
+        <CommentItem {...props}>
+          <div className="text-xs text-muted-foreground">
+            {props.comment.userId} • {formatTimeRelative(props.comment.timestamp)}
+          </div>
+          <div className="whitespace-pre-wrap text-sm">{props.comment.text}</div>
+        </CommentItem>
+      )}
     />
   );
-};
+}
 ```
 
-### Programmatic Discussion Management
+## Actions
 
 ```tsx
-import {useStoreWithDiscussion} from '@sqlrooms/discuss';
-
-function DiscussionManager() {
-  const {
-    addDiscussion,
-    removeDiscussion,
-    addComment,
-    setReplyToItem,
-    setEditingItem,
-    submitEdit,
-  } = useStoreWithDiscussion((state) => state.discuss);
-
-  // Add a new discussion
-  const createDiscussion = () => {
-    addDiscussion('New discussion topic', 'optional-anchor-id');
-  };
+import {useRoomStore} from './store';
+import {Button} from '@sqlrooms/ui';
 
-  // Reply to a discussion
-  const replyToDiscussion = (discussionId: string) => {
-    setReplyToItem({discussionId});
-    // User can now type in the form and call submitEdit
-  };
-
-  // Edit a comment
-  const editComment = (discussionId: string, commentId: string) => {
-    setEditingItem({discussionId, commentId});
-    // User can now edit in the form and call submitEdit
-  };
-
-  // Direct comment addition (bypassing UI state)
-  const addDirectComment = (discussionId: string, text: string) => {
-    addComment(discussionId, text);
-  };
+function DiscussionActions() {
+  const addDiscussion = useRoomStore((state) => state.discuss.addDiscussion);
+  const setReplyToItem = useRoomStore((state) => state.discuss.setReplyToItem);
+  const submitEdit = useRoomStore((state) => state.discuss.submitEdit);
 
   return (
     <div className="flex gap-2">
-      <button onClick={createDiscussion}>New Discussion</button>
-      <button onClick={() => replyToDiscussion('discussion-id')}>Reply</button>
-      <button onClick={() => editComment('discussion-id', 'comment-id')}>
-        Edit
-      </button>
+      <Button onClick={() => addDiscussion('Initial note', 'data-point-id')}>
+        Add discussion
+      </Button>
+      <Button onClick={() => setReplyToItem({discussionId: 'some-id'})}>
+        Reply mode
+      </Button>
+      <Button onClick={() => submitEdit('Reply text')}>Submit</Button>
     </div>
   );
 }
 ```
 
-## API Reference
-
-### Types
-
-- `Comment`: Individual comment with id, userId, text, timestamp, and optional parentId
-- `Discussion`: Container with id, optional anchorId, rootComment, and array of reply comments
-- `DiscussSliceConfig`: Configuration type for the discuss slice
-- `DiscussSliceState`: State type including all discussion actions and UI state
-
-### Key Functions
-
-- `createDiscussSlice({ userId })`: Creates the discussion slice for your store
-- `createDefaultDiscussConfig()`: Returns default configuration for discussions
-- `useStoreWithDiscussion(selector)`: Hook to access discussion state and actions
-
-### Main Actions
-
-- `submitEdit(text)`: Submit based on current UI state (add/reply/edit)
-- `addDiscussion(text, anchorId?)`: Add new discussion
-- `addComment(discussionId, text, parentId?)`: Add reply to discussion
-- `setReplyToItem(item)`: Set reply context for UI
-- `setEditingItem(item)`: Set editing context for UI
-- `setHighlightedDiscussionId(id)`: Highlight specific discussion
+## Main exports
 
-This module integrates seamlessly with the SQLRooms ecosystem and provides a complete foundation for building collaborative discussion features in your applications.
+- components: `DiscussionList`, `DiscussionItem`, `CommentItem`, `DeleteConfirmDialog`
+- slice: `createDiscussSlice`, `createDefaultDiscussConfig`
+- config/types: `DiscussSliceConfig`, `DiscussSliceState`, `Discussion`, `Comment`
+- hook: `useStoreWithDiscussion`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sqlrooms/discuss",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "type": "module",
   "sideEffects": false,
   "main": "dist/index.js",
@@ -16,9 +16,9 @@
   },
   "dependencies": {
     "@paralleldrive/cuid2": "^3.0.0",
-    "@sqlrooms/room-shell": "0.27.0",
-    "@sqlrooms/ui": "0.27.0",
-    "@sqlrooms/utils": "0.27.0",
+    "@sqlrooms/room-shell": "0.28.0",
+    "@sqlrooms/ui": "0.28.0",
+    "@sqlrooms/utils": "0.28.0",
     "immer": "^11.0.1",
     "lucide-react": "^0.556.0",
     "zod": "^4.1.8"
@@ -33,5 +33,5 @@
     "lint": "eslint .",
     "typedoc": "typedoc"
   },
-  "gitHead": "f215995ab4adeac4c58171739261a15cbba9e82b"
+  "gitHead": "dcac54f8adf77240e293c93d224a0ce9fd8142a9"
 }