lexical-loro 1.0.6__tar.gz

lexical_loro-1.0.6/.gitignore

@@ -0,0 +1,49 @@
+.DS_Store
+.wss-loro
+.wss-yjs
+build
+node_modules
+package-lock.json
+tsconfig.tsbuildinfo
+
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+*-lock.json
+
+node_modules
+lib
+dist
+dist-ssr
+*.local
+
+.coverage
+.pytest_cache
+htmlcov
+dist
+
+__pycache__
+lexical_loro/__version__.py
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+
+.models
+
+__tests__/*.json
+
+documents

lexical_loro-1.0.6/LICENSE

@@ -0,0 +1,21 @@
+Copyright (c) 2021-2023 Datalayer, Inc.
+
+MIT License
+
+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.

lexical_loro-1.0.6/PKG-INFO

@@ -0,0 +1,387 @@
+Metadata-Version: 2.5
+Name: lexical-loro
+Version: 1.0.6
+Dynamic: Author
+Dynamic: Author-email
+Dynamic: Summary
+Dynamic: Keywords
+Project-URL: Homepage, https://github.com/datalayer/lexical-loro
+Project-URL: Documentation, https://github.com/datalayer/lexical-loro#readme
+Project-URL: Repository, https://github.com/datalayer/lexical-loro.git
+Project-URL: Issues, https://github.com/datalayer/lexical-loro/issues
+License: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing :: Markup
+Requires-Python: >=3.8
+Requires-Dist: click>=8.0.0
+Requires-Dist: loro>=1.6.0
+Requires-Dist: mcp>=2
+Requires-Dist: starlette>=0.27
+Requires-Dist: uvicorn>=0.23.1
+Requires-Dist: websockets>=12.0
+Provides-Extra: dev
+Requires-Dist: black>=23.0.0; extra == 'dev'
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'test'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'test'
+Requires-Dist: pytest>=7.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+[![Datalayer](https://assets.datalayer.tech/datalayer-25.svg)](https://datalayer.io)
+
+[![Become a Sponsor](https://img.shields.io/static/v1?label=Become%20a%20Sponsor&message=%E2%9D%A4&logo=GitHub&style=flat&color=1ABC9C)](https://github.com/sponsors/datalayer)
+
+# ✍️ 🦜 Collaborative Plugin for Lexical with Loro CRDT
+
+A collaborative editing plugin for [Lexical](https://github.com/facebook/lexical) Rich Editor built with [Loro](https://github.com/loro-dev) CRDT, providing real-time collaborative editing capabilities with conflict-free synchronization.
+
+## Core Components
+
+This package provides three main components for building collaborative text editors:
+
+1. **`LoroCollaborativePlugin.tsx`** - A Lexical plugin that integrates Loro CRDT for real-time collaborative editing
+2. **`LexicalModel` Python Library** - A standalone document model for Lexical content with CRDT capabilities
+3. **`lexical-loro` WebSocket Server** - A Python server using [loro-py](https://github.com/loro-dev/loro-py) for real-time collaboration
+
+## Quick Start
+
+### Using the Lexical Plugin
+
+```tsx
+import { LoroCollaborativePlugin } from './src/LoroCollaborativePlugin';
+
+function MyEditor() {
+  return (
+    <LexicalComposer initialConfig={editorConfig}>
+      <RichTextPlugin />
+      <LoroCollaborativePlugin 
+        websocketUrl="ws://localhost:8081"
+        docId="my-document"
+        username="user1"
+      />
+    </LexicalComposer>
+  );
+}
+```
+
+### Using the LexicalModel Library
+
+```python
+from lexical_loro import LexicalModel
+
+# Create a new document
+model = LexicalModel.create_document("my-document")
+
+# Add content
+model.add_block({
+    "text": "My Document",
+    "format": 0,
+    "style": ""
+}, "heading1")
+
+model.add_block({
+    "text": "This is a paragraph.",
+    "format": 0,
+    "style": ""
+}, "paragraph")
+
+# Save to file
+model.save_to_file("document.json")
+
+# Load from file
+loaded_model = LexicalModel.load_from_file("document.json")
+```
+
+### Using the Python Server
+
+```bash
+# Install the Python package
+pip install -e .
+
+# Start the server
+lexical-loro-server --port 8081
+```
+
+## Examples
+
+For complete working examples, see the `src/examples/` directory which contains:
+- Full React application with dual editor support
+- Server selection interface
+- Connection status indicators
+- Rich text formatting examples
+
+**DISCLAIMER** Collaborative Cursors still need fixes, see [this issue](https://github.com/datalayer/lexical-loro/issues/1).
+
+<div align="center" style="text-align: center">
+  <img alt="" src="https://assets.datalayer.tech/lexical-loro.gif" />
+</div>
+
+## Core Features
+
+- 🔄 **Real-time Collaboration**: Multiple users can edit the same document simultaneously
+- 🚀 **Conflict-free**: Uses Loro CRDT to automatically resolve conflicts  
+- 📝 **Lexical Integration**: Seamless integration with Lexical rich text editor
+- 📚 **Standalone Library**: Use LexicalModel independently for document management
+- 🌐 **WebSocket Server**: Python server for maintaining document state
+- 📡 **Connection Management**: Robust WebSocket connection handling
+- ✨ **Rich Text Support**: Preserves formatting during collaborative editing
+- 💾 **Serialization**: JSON export/import and file persistence
+- 🔧 **Extensible**: Plugin-based architecture for easy customization
+
+## Technology Stack
+
+**Core Dependencies:**
+- **Lexical**: v0.33.1 (Facebook's extensible text editor framework)
+- **Loro CRDT**: v1.5.10 (Conflict-free replicated data types)
+- **React**: 18/19 (for plugin hooks and components)
+- **Python**: 3.8+ with loro-py and websockets
+
+**Development Dependencies:**
+- **TypeScript**: For type safety
+- **Vite**: For building and development (examples only)
+- **pytest**: Python testing
+- **ESLint**: Code linting
+
+## Installation
+
+### Core Plugin
+
+The Lexical plugin is a single TypeScript/React component that you can copy into your project:
+
+```bash
+# Copy the plugin file
+cp src/LoroCollaborativePlugin.tsx your-project/src/
+```
+
+**Dependencies required:**
+```bash
+npm install lexical @lexical/react @lexical/selection loro-crdt react react-dom
+```
+
+### Python Server
+
+Install the Python WebSocket server:
+
+```bash
+# Install from this repository
+pip install -e .
+
+# Or install specific dependencies
+pip install websockets click loro
+```
+
+## Usage
+
+### 1. Lexical Plugin Integration
+
+Add the plugin to your Lexical editor:
+
+```tsx
+import { LexicalComposer } from '@lexical/react/LexicalComposer';
+import { RichTextPlugin } from '@lexical/react/LexicalRichTextPlugin';
+import { ContentEditable } from '@lexical/react/LexicalContentEditable';
+import { LoroCollaborativePlugin } from './LoroCollaborativePlugin';
+
+const editorConfig = {
+  namespace: 'MyEditor',
+  theme: {},
+  onError: console.error,
+};
+
+function CollaborativeEditor() {
+  return (
+    <LexicalComposer initialConfig={editorConfig}>
+      <div className="editor-container">
+        <RichTextPlugin
+          contentEditable={<ContentEditable className="editor-input" />}
+          placeholder={<div className="editor-placeholder">Start typing...</div>}
+          ErrorBoundary={() => <div>Error occurred</div>}
+        />
+        <LoroCollaborativePlugin 
+          websocketUrl="ws://localhost:8081"
+          docId="shared-document"
+          username="user123"
+        />
+      </div>
+    </LexicalComposer>
+  );
+}
+```
+
+### 2. Standalone LexicalModel Library
+
+Use the LexicalModel library independently for document management:
+
+```python
+from lexical_loro import LexicalModel
+
+# Create a new document
+model = LexicalModel.create_document("my-document")
+
+# Add different types of content
+model.add_block({
+    "text": "My Document",
+    "format": 0,
+    "style": ""
+}, "heading1")
+
+model.add_block({
+    "text": "This is a paragraph with **bold** text.",
+    "format": 0,
+    "style": ""
+}, "paragraph")
+
+model.add_block({
+    "text": "",
+    "format": 0,
+    "style": ""
+}, "list")
+
+# Serialize to JSON
+json_data = model.to_json()
+
+# Save to file
+model.save_to_file("document.json")
+
+# Load from file
+loaded_model = LexicalModel.load_from_file("document.json")
+
+# Access blocks
+for block in loaded_model.get_blocks():
+    print(f"{block['type']}: {block.get('text', '')}")
+```
+
+For more examples, see:
+- `examples/memory_only_example.py` - Basic document creation and manipulation
+- `examples/file_sync_example.py` - File persistence and batch operations  
+- `examples/collaboration_example.py` - Simulating collaborative editing
+- `docs/LEXICAL_MODEL_GUIDE.md` - Comprehensive documentation
+
+### 3. Python Server Setup
+
+Start the WebSocket server:
+
+```bash
+# Default port (8081)
+lexical-loro-server
+
+# Custom port
+lexical-loro-server --port 8082
+
+# With debug logging
+lexical-loro-server --port 8081 --log-level DEBUG
+```
+
+### 4. Programmatic Server Usage
+
+```python
+import asyncio
+from lexical_loro import LoroWebSocketServer
+
+async def main():
+    server = LoroWebSocketServer(port=8081)
+    await server.start()
+    print("Server running on ws://localhost:8081")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Plugin API
+
+For detailed API documentation, see [`docs/API.md`](docs/API.md).
+
+### Quick Reference
+
+```tsx
+interface LoroCollaborativePluginProps {
+  websocketUrl: string;          // WebSocket server URL
+  docId: string;                 // Unique document identifier
+  username: string;              // User identifier
+  userColor?: string;            // User cursor color (optional)
+  debug?: boolean;               // Enable debug logging (optional)
+}
+```
+
+## Initialization Best Practices
+
+⚠️ **Important**: Always wait for collaboration initialization before enabling other plugins.
+
+See [`docs/INITIALIZATION_GUIDE.md`](docs/INITIALIZATION_GUIDE.md) for comprehensive guidance on:
+- Proper plugin ordering
+- Initialization callbacks
+- Error handling
+- Common anti-patterns to avoid
+
+## Examples
+
+For complete working examples and demonstrations, see the `src/examples/` directory:
+
+```bash
+# Run the example application
+npm install
+make example
+
+# This starts both Node.js and Python servers plus a React demo app
+# Open http://localhost:3000/split/index.html to see the 2 editors view
+```
+
+The examples include:
+- **Complete React App**: Full collaborative editor with UI
+- **Server Selection**: Switch between Node.js and Python backends  
+- **Dual Editors**: Simple text area and rich Lexical editor
+- **Real-time Demo**: Multi-user collaboration testing
+
+See `src/examples/README.md` for detailed example documentation.
+
+## Architecture
+
+```
+EDITOR 1                                           EDITOR 2
+
+loro                                               loro
+- node(data: root(1))                              - node(data: root(12))
+  - node(data: element(2))                           - node(data: element(22))
+    - node(data: text(3))                              - node(data: text(13))
+  - node(data: counter(4))                           - node(data: counter(4))
+
+                <---- loro updates via websocket ------>
+                <---- loro node ids are the same ------>
+             <---- lexical node keys are different ------>
+
+lexical                                            lexical
+- root(1)                                          - root(12)
+  - element(2)                                       - element(22)
+    - text(3)                                          - text(13)
+  - counter(4)                                       - counter(49)
+```
+
+## Examples
+
+Loro examples
+
+- http://localhost:3000/?isCollab=true
+
+- http://localhost:3000/split/?isCollab=true
+
+Y.js examples (for reference)
+
+- http://localhost:3000/?isCollab=true&useYjs=true
+
+- http://localhost:3000/split/?isCollab=true&useYjs=true