hale-commenting-system 1.0.7 → 2.0.1

package/README.md

@@ -1,20 +1,21 @@
-# @apollo/commenting-system
+# hale-commenting-system
 
-A reusable React commenting system with GitHub/GitLab integration and AI-powered summarization.
+A local-first React commenting system with localStorage persistence. Perfect for prototypes, design reviews, and local development.
 
 ## Features
 
-- 📌 **Visual Comment Pins** - Click anywhere to add comment threads
-- 🔄 **GitHub/GitLab Sync** - Two-way sync with issue trackers
-- 🤖 **AI Summarization** - Powered by DeepSeek R1 via MaaS
-- 📦 **Version Management** - Track comments across prototype versions
+- 📌 **Visual Comment Pins** - Click anywhere on your app to add comment threads
+- 💾 **LocalStorage Persistence** - Comments persist across page refreshes
+- 🔄 **Threaded Conversations** - Add multiple replies to each comment pin
+- 📦 **Version Management** - Filter comments by prototype version
 - 🎨 **PatternFly UI** - Built with PatternFly React components
 - 🧙 **CLI Wizard** - Automated setup with `npx hale-commenting-system init`
+- 🚀 **Zero Configuration** - No backend, no auth, no setup hassle
 
 ## Installation
 
 ```bash
-npm install @apollo/commenting-system
+npm install hale-commenting-system
 ```
 
 ## Quick Start
@@ -26,185 +27,195 @@ npx hale-commenting-system init
 ```
 
 This will:
-- Detect your project type (React, PatternFly, Vite/Webpack)
-- Prompt for GitHub OAuth credentials
-- Generate serverless authentication functions
-- Create environment files (.env.local, .env.example)
-- Generate apollo-comments.config.json
-- Provide integration instructions
+1. Detect your React project
+2. Auto-integrate the commenting system into your App component
+3. You're done! Start your dev server and click anywhere to add comments
 
-## Manual Setup
+## How It Works
 
-### 1. Basic Setup
+All comments are stored locally in your browser's localStorage. They persist across:
+- Page refreshes
+- Browser restarts
+- Dev server restarts
+
+Perfect for:
+- Local prototyping
+- Design reviews
+- Quick feedback sessions
+- Testing before adding a backend
+
+## Usage
+
+Once installed, the commenting system provides two modes:
+
+### View Mode (Default)
+- Click the "Show Pins" toggle to see existing comment pins
+- Click on pins to view threads and replies
+- Read-only, no editing
+
+### Comment Mode
+- Click "Enable Commenting" to enter edit mode
+- Your cursor becomes a crosshair
+- Click anywhere to create a new comment thread
+- Click pins to add replies, edit, or delete
+
+### Keyboard Shortcuts
+- Press `Enter` in the comment textarea to submit
+- Press `Esc` to close the comment drawer
+
+## Manual Integration
+
+If the CLI doesn't work for your project, you can manually integrate:
 
 ```tsx
+import React from 'react';
+import { BrowserRouter as Router } from 'react-router-dom';
 import {
   CommentProvider,
-  VersionProvider,
-  GitHubAuthProvider,
   CommentOverlay,
   CommentDrawer
-} from '@apollo/commenting-system';
-import apolloCommentsConfig from './apollo-comments.config.json';
-import React from 'react';
+} from 'hale-commenting-system';
 
 function App() {
   const [selectedThreadId, setSelectedThreadId] = React.useState<string | null>(null);
 
   return (
-    <GitHubAuthProvider config={apolloCommentsConfig}>
-      <VersionProvider>
-        <CommentProvider>
-          <CommentDrawer 
+    <Router>
+      <CommentProvider>
+        <CommentDrawer 
+          selectedThreadId={selectedThreadId} 
+          onThreadSelect={setSelectedThreadId}
+        >
+          <CommentOverlay 
             selectedThreadId={selectedThreadId} 
             onThreadSelect={setSelectedThreadId}
-          >
-            <CommentOverlay 
-              selectedThreadId={selectedThreadId} 
-              onThreadSelect={setSelectedThreadId}
-            />
-            {/* Your app content */}
-          </CommentDrawer>
-        </CommentProvider>
-      </VersionProvider>
-    </GitHubAuthProvider>
+          />
+          {/* Your app content */}
+        </CommentDrawer>
+      </CommentProvider>
+    </Router>
   );
 }
 ```
 
-### 2. API Configuration
-
-The CLI generates serverless functions for GitHub OAuth. For manual setup, create:
+## API
 
-**Vercel**: `/api/github-oauth-login.ts` and `/api/github-oauth-callback.ts`
-**Netlify**: `/netlify/functions/github-oauth-login.ts` and `/netlify/functions/github-oauth-callback.ts`
+### `<CommentProvider>`
+Root provider that manages comment state and localStorage persistence.
 
-See the [manual setup guide](https://github.com/apollo/commenting-system/blob/main/docs/manual-setup.md) for templates.
+### `<CommentOverlay>`
+Invisible overlay that handles click events for creating new comments.
 
-### 3. Environment Variables
+**Props:**
+- `selectedThreadId: string | null` - Currently selected thread ID
+- `onThreadSelect: (id: string | null) => void` - Callback when a thread is selected
 
-```env
-GITHUB_CLIENT_ID=your_github_client_id
-GITHUB_CLIENT_SECRET=your_github_client_secret
-GITHUB_OWNER=your_github_org
-GITHUB_REPO=your_repo_name
+### `<CommentDrawer>`
+Sidebar drawer that displays the selected thread and its replies.
 
-# Vite (if using Vite)
-VITE_GITHUB_CLIENT_ID=your_github_client_id
-VITE_GITHUB_OWNER=your_github_org
-VITE_GITHUB_REPO=your_repo_name
-```
-
-## CLI Commands
-
-### Initialize
-
-```bash
-hale-commenting-system init
-```
+**Props:**
+- `selectedThreadId: string | null` - Thread to display
+- `onThreadSelect: (id: string | null) => void` - Callback to close the drawer
+- `children: React.ReactNode` - Your app content
 
-Options:
-- `-y, --yes` - Skip prompts and use defaults
-- `--platform <platform>` - Specify platform (vercel, netlify, manual)
+### `useComments()` Hook
 
-### Validate
+Access comment state and actions:
 
-```bash
-hale-commenting-system validate
+```tsx
+import { useComments } from 'hale-commenting-system';
+
+function MyComponent() {
+  const {
+    threads,              // All comment threads
+    showPins,             // Whether pins are visible
+    enableCommenting,     // Whether commenting mode is active
+    toggleShowPins,       // Toggle pin visibility
+    toggleEnableCommenting, // Toggle commenting mode
+    addThread,            // Create a new thread
+    addReply,             // Add a reply to a thread
+    updateComment,        // Update a comment
+    deleteComment,        // Delete a comment
+    deleteThread,         // Delete a thread
+    clearAllThreads,      // Clear all comments
+    getThreadsForRoute    // Get comments for current route
+  } = useComments();
+}
 ```
 
-Checks your setup for:
-- Configuration files
-- Serverless functions
-- GitHub connectivity
-- Repository access
-
-## Components
-
-### Core Components
+## Version Management
 
-- **CommentOverlay** - Renders comment pins on the page
-- **CommentDrawer** - Side panel for viewing/editing comments
-- **CommentPin** - Individual comment pin component
-- **AIAssistant** - AI chatbot toggle and panel
+The system supports filtering comments by version (useful for iterating on prototypes):
 
-### Providers
-
-- **CommentProvider** - Comment state and CRUD operations
-- **VersionProvider** - Version management
-- **GitHubAuthProvider** - GitHub authentication
-- **GitLabAuthProvider** - GitLab authentication  
-- **AIProvider** - AI chat state and API calls
-
-## Types
+```tsx
+import { VersionProvider, useVersion } from 'hale-commenting-system';
 
-```typescript
-import type { 
-  Comment, 
-  Thread, 
-  SyncStatus,
-  AIMessage, 
-  GitHubResult 
-} from '@apollo/commenting-system';
-```
+function App() {
+  return (
+    <VersionProvider>
+      <CommentProvider>
+        {/* Your app */}
+      </CommentProvider>
+    </VersionProvider>
+  );
+}
 
-## Peer Dependencies
-
-- @patternfly/react-core: ^6.0.0
-- @patternfly/react-icons: ^6.0.0
-- @patternfly/chatbot: ^6.0.0
-- react: ^18.0.0
-- react-dom: ^18.0.0
-- react-router-dom: ^6.0.0 || ^7.0.0
-
-## Configuration File
-
-The CLI generates `apollo-comments.config.json`:
-
-```json
-{
-  "version": "1.0.0",
-  "platform": "vercel",
-  "github": {
-    "owner": "your-org",
-    "repo": "your-repo",
-    "clientId": "your-client-id"
-  },
-  "redirectUri": "https://your-domain.com/api/github-oauth-callback",
-  "features": {
-    "aiSummarization": true,
-    "versionTracking": true,
-    "gitlabIntegration": false
-  }
+// In your component
+function MyComponent() {
+  const { currentVersion, setCurrentVersion } = useVersion();
+  
+  // Comments are automatically filtered by version
+  return (
+    <select value={currentVersion} onChange={(e) => setCurrentVersion(e.target.value)}>
+      <option value="1">Version 1</option>
+      <option value="2">Version 2</option>
+      <option value="3">Version 3 (current)</option>
+    </select>
+  );
 }
 ```
 
-## Development
+## TypeScript
 
-```bash
-# Install dependencies
-npm install
+The package includes full TypeScript definitions:
 
-# Build library and CLI
-npm run build
-
-# Watch mode (library only)
-npm run dev
+```tsx
+import type { Thread, Comment } from 'hale-commenting-system';
+
+interface Thread {
+  id: string;
+  x: number;
+  y: number;
+  route: string;
+  comments: Comment[];
+  version?: string;
+}
 
-# Type check
-npm run type-check
+interface Comment {
+  id: string;
+  author?: string;
+  text: string;
+  createdAt: string;
+}
 ```
 
-## Testing the Package Locally
+## Browser Compatibility
 
-```bash
-# In this package directory
-npm link
+Works in all modern browsers that support:
+- localStorage
+- React 18+
+- ES2020+
 
-# In your test project
-npm link @apollo/commenting-system
-apollo-comments init
-```
+## Roadmap
+
+This is the MVP (local-only) version. Future enhancements:
+- [ ] Backend sync (GitHub Issues, GitLab, custom)
+- [ ] OAuth authentication
+- [ ] Real-time collaboration
+- [ ] Export/import comments
+- [ ] Comment notifications
+- [ ] Rich text editing
+- [ ] File attachments
 
 ## License
 
@@ -213,10 +224,3 @@ MIT
 ## Author
 
 Justin Hale
-
-## Support
-
-- [Documentation](https://github.com/apollo/commenting-system)
-- [Issues](https://github.com/apollo/commenting-system/issues)
-- [Discussions](https://github.com/apollo/commenting-system/discussions)
-