@connectedxm/entity-editor 0.0.1 → 0.0.3

package/README.md

@@ -1,6 +1,6 @@
-# Activity Editor
+# Entity Editor
 
-A **zero-dependency**, lightweight React text editor that intelligently recognizes and styles mentions, hashtags, links, and text formatting in real-time using an innovative bitmap-based architecture.
+A **zero-dependency**, lightweight React text editor with intelligent entity recognition and real-time formatting using an innovative bitmap-based architecture.
 
 ## ✨ Features
 
@@ -9,12 +9,13 @@ A **zero-dependency**, lightweight React text editor that intelligently recogniz
   - **@mentions** (`@username`)
   - **#interests** (`#hashtag`)
   - **🔗 Links** (`https://example.com`)
-  - **Text Formatting**: Bold, italic, underline, strikethrough
-- **⚡ Real-time Processing**: Instant styling as you type with debounced updates
+- **📝 Rich Text Formatting**: Bold, italic, underline, strikethrough with keyboard shortcuts
+- **⚡ Real-time Processing**: Instant styling as you type with optimized performance
 - **🗜️ Bitmap Architecture**: Ultra-efficient character-level state tracking using bit operations
+- **🎨 Customizable Styling**: Configurable colors and styles for all entity types
+- **🔍 Search & Autocomplete**: Built-in search functionality for mentions and interests
+- **⌨️ Keyboard Shortcuts**: Cmd/Ctrl+B/I/U/Shift+S for formatting
 - **📱 Accessible**: Built on standard `contentEditable` with proper cursor management
-- **🎨 Customizable**: CSS classes for easy theming
-- **⌨️ Keyboard Shortcuts**: Cmd/Ctrl+B/I/U/S for formatting selected text
 
 ## 🏗️ Bitmap Architecture
 
@@ -58,53 +59,142 @@ npm install @connectedxm/entity-editor
 ### Basic Usage
 
 ```tsx
-import React, { useState } from "react";
-import Editor from "@connectedxm/entity-editor";
+import React, { useState, useRef } from "react";
+import {
+  Editor,
+  EditorRef,
+  Entity,
+  MarkState,
+  SearchEntity,
+} from "@connectedxm/entity-editor";
 
 function App() {
+  const editorRef = useRef<EditorRef>(null);
   const [plainText, setPlainText] = useState("");
-  const [entities, setEntities] = useState([]);
-  const [search, setSearch] = useState(null);
+  const [entities, setEntities] = useState<Entity[]>([]);
+  const [markState, setMarkState] = useState<MarkState>({
+    bold: false,
+    italic: false,
+    underline: false,
+    strike: false,
+  });
+  const [search, setSearch] = useState<SearchEntity | null>(null);
 
   return (
     <Editor
+      ref={editorRef}
       plainText={plainText}
       setPlainText={setPlainText}
       entities={entities}
       setEntities={setEntities}
+      markState={markState}
+      setMarkState={setMarkState}
       search={search}
       setSearch={setSearch}
-      options={{ mentions: true, interests: true, links: true }}
-      style={{ minHeight: "100px", border: "1px solid #ccc", padding: "10px" }}
+      options={{
+        mentions: true,
+        interests: true,
+        links: true,
+      }}
+      style={{
+        border: "1px solid #ccc",
+        minHeight: "100px",
+        padding: "10px",
+      }}
     />
   );
 }
 ```
 
-### Advanced Features
-
-The editor supports entity recognition options and debounced updates for performance:
+### Advanced Usage with Custom Styling
 
 ```tsx
 <Editor
+  ref={editorRef}
   plainText={plainText}
   setPlainText={setPlainText}
   entities={entities}
   setEntities={setEntities}
+  markState={markState}
+  setMarkState={setMarkState}
   search={search}
   setSearch={setSearch}
   options={{
-    mentions: true, // Enable @mention detection
-    interests: true, // Enable #hashtag detection
-    links: true, // Enable URL detection
+    mentions: true,
+    interests: true,
+    links: true,
+  }}
+  entityStyles={{
+    mentionColor: "#1da1f2",
+    interestColor: "#ff6b35",
+    linkColor: "#9c27b0",
   }}
-  debounceDelay={250} // Delay before processing changes
-  debounceMaxWait={500} // Maximum wait time for updates
   className="custom-editor"
+  debug={false}
 />
 ```
 
-### Styling Entities
+### Using the Editor Ref API
+
+The editor exposes imperative methods through a ref:
+
+```tsx
+const editorRef = useRef<EditorRef>(null);
+
+// Programmatically select/replace entities
+const handleMentionSelect = (username: string) => {
+  if (search?.type === "mention") {
+    editorRef.current?.selectEntity(
+      "mention",
+      search.startIndex,
+      search.endIndex,
+      username
+    );
+  }
+};
+
+// Toggle formatting programmatically
+const makeBold = () => {
+  editorRef.current?.toggleMark("bold");
+};
+```
+
+### Handling Search and Autocomplete
+
+```tsx
+// Handle search results for mentions
+{
+  search?.type === "mention" && (
+    <div className="autocomplete-dropdown">
+      <h4>Select a user to mention:</h4>
+      {searchResults.map((user) => (
+        <div key={user.id} onClick={() => handleMentionSelect(user.username)}>
+          {user.name} (@{user.username})
+        </div>
+      ))}
+    </div>
+  );
+}
+
+// Handle search results for interests
+{
+  search?.type === "interest" && (
+    <div className="autocomplete-dropdown">
+      <h4>Select an interest to tag:</h4>
+      {interestResults.map((interest) => (
+        <div
+          key={interest.id}
+          onClick={() => handleInterestSelect(interest.name)}
+        >
+          #{interest.name}
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+### Styling Entities with CSS
 
 Add CSS to style the recognized entities:
 
@@ -117,34 +207,35 @@ Add CSS to style the recognized entities:
 }
 
 .activity-interest {
-  color: #1da1f2;
+  color: #ff6b35;
   font-weight: 500;
 }
 
 .activity-link {
-  color: #1da1f2;
+  color: #9c27b0;
   text-decoration: underline;
 }
 
 .activity-bold {
   font-weight: bold;
 }
+
 .activity-italic {
   font-style: italic;
 }
+
 .activity-underline {
   text-decoration: underline;
 }
+
 .activity-strike {
   text-decoration: line-through;
 }
 ```
 
-## 📊 Bitmap to Entity Conversion
-
-The bitmap system automatically converts character-level bit data into structured entities for easy consumption:
+## 📊 Entity Structure
 
-### Entity Structure
+The editor converts bitmap data into structured entities for easy consumption:
 
 ```typescript
 interface Entity {
@@ -152,49 +243,38 @@ interface Entity {
   startIndex: number;
   endIndex: number;
   marks: ("bold" | "italic" | "underline" | "strike")[];
-  link?: string; // For detected URLs
-  mention?: string; // For completed @mentions
-  interest?: string; // For completed #hashtags
+  href?: string; // For links
+  username?: string; // For mentions
+  interest?: string; // For interests
+}
+
+interface SearchEntity {
+  type: "mention" | "interest" | "link";
+  search: string;
+  startIndex: number;
+  endIndex: number;
 }
 ```
 
-### Conversion Process
+### Bitmap to Entity Conversion
 
 1. **Bitmap Scanning**: The system scans through the bitmap array
 2. **Grouping**: Consecutive characters with identical bit values are grouped together
 3. **Entity Creation**: Each group becomes an entity with its type determined by the bitmap value
 4. **Mark Extraction**: Formatting bits are converted to a `marks` array
 
-**Example Conversion**:
-
-```typescript
-// Input bitmap for "Hello @john"
-bitmap: [0, 0, 0, 0, 0, 0, 32, 32, 32, 32, 32];
-
-// Output entities
-entities: [
-  {
-    type: "mention",
-    startIndex: 6,
-    endIndex: 11,
-    marks: [],
-    mention: undefined, // Will be filled when mention is resolved
-  },
-];
-```
-
 ## 🎯 Recognition Patterns
 
 - **Mentions**: `@username` (alphanumeric, underscores, hyphens, apostrophes)
 - **Interests**: `#hashtag` (alphanumeric, underscores, hyphens)
 - **Links**: `https://` or `http://` URLs
-- **Formatting**: Detected from applied HTML styles
+- **Formatting**: Applied via keyboard shortcuts or toolbar
 
 ## ⚡ Performance Benefits
 
 ### Why Bitmap Architecture?
 
-The bitmap approach provides significant performance advantages over traditional entity-based systems:
+The bitmap approach provides significant performance advantages:
 
 **Memory Efficiency**:
 
@@ -206,48 +286,81 @@ The bitmap approach provides significant performance advantages over traditional
 
 - Bit operations are CPU-native and extremely fast
 - O(1) property checks vs O(n) object property lookups
-- Efficient grouping algorithm for entity generation
 - **5-10x faster** entity processing
 
 **Update Performance**:
 
 - Only modified bitmap regions trigger re-rendering
-- Debounced updates prevent excessive DOM manipulation
-- Minimal React re-renders through optimized state management
+- Optimized React re-renders through efficient state management
 
-### Benchmark Comparison
+## 📝 API Reference
 
-```
-Traditional Approach    vs    Bitmap Approach
-─────────────────────         ──────────────────
-Memory: 500KB+                Memory: 40KB
-Update: 15-30ms               Update: 2-5ms
-Bundle: +50KB deps            Bundle: 0KB deps
-```
+### Props
 
-## 🏆 Why Zero Dependencies?
+| Prop           | Type                                     | Required | Description                           |
+| -------------- | ---------------------------------------- | -------- | ------------------------------------- |
+| `ref`          | `React.RefObject<EditorRef>`             | Yes      | Ref to access editor methods          |
+| `plainText`    | `string`                                 | Yes      | The current plain text content        |
+| `setPlainText` | `(text: string) => void`                 | Yes      | Callback to update plain text         |
+| `entities`     | `Entity[]`                               | Yes      | Array of recognized entities          |
+| `setEntities`  | `(entities: Entity[]) => void`           | Yes      | Callback to update entities           |
+| `markState`    | `MarkState`                              | Yes      | Current formatting state              |
+| `setMarkState` | `(state: MarkState) => void`             | Yes      | Callback to update formatting state   |
+| `search`       | `SearchEntity \| null`                   | Yes      | Current search state for autocomplete |
+| `setSearch`    | `(search: SearchEntity \| null) => void` | Yes      | Callback to update search state       |
+| `options`      | `EntityOptions`                          | No       | Configure which entities to detect    |
+| `entityStyles` | `StyleOptions`                           | No       | Custom colors for entity types        |
+| `style`        | `React.CSSProperties`                    | No       | Inline styles for the editor          |
+| `className`    | `string`                                 | No       | CSS class name for the editor         |
+| `debug`        | `boolean`                                | No       | Enable debug mode (default: false)    |
+
+### Interfaces
 
-This editor proves that powerful text editing doesn't require heavy libraries:
+```typescript
+interface EntityOptions {
+  mentions?: boolean; // Enable @mention detection
+  interests?: boolean; // Enable #hashtag detection
+  links?: boolean; // Enable URL detection
+}
 
-- **Performance**: No bundle bloat, faster load times
-- **Security**: No third-party vulnerabilities
-- **Control**: Full understanding and control over every feature
-- **Maintenance**: Easier updates and customization
-- **Reliability**: No breaking changes from external dependencies
+interface StyleOptions {
+  mentionColor?: string; // Custom color for mentions
+  interestColor?: string; // Custom color for interests
+  linkColor?: string; // Custom color for links
+}
 
-## 🧪 Testing
+interface MarkState {
+  bold: boolean;
+  italic: boolean;
+  underline: boolean;
+  strike: boolean;
+}
+
+interface EditorRef {
+  selectEntity: (
+    entityType: EntityType,
+    startIndex: number,
+    endIndex: number,
+    newText: string
+  ) => void;
+  toggleMark: (markType: MarkType) => void;
+}
+```
+
+### Keyboard Shortcuts
+
+- **Ctrl/Cmd + B**: Toggle bold
+- **Ctrl/Cmd + I**: Toggle italic
+- **Ctrl/Cmd + U**: Toggle underline
+- **Ctrl/Cmd + Shift + S**: Toggle strikethrough
 
-The editor includes comprehensive tests covering:
+## 🧪 Testing
 
-- **Bitmap Operations**: Bit manipulation, mask operations, value encoding/decoding
-- **Entity Conversion**: Bitmap-to-entity transformation accuracy
-- **Keyboard Shortcuts**: Formatting toggle functionality via Cmd/Ctrl+B/I/U/S
-- **Edge Cases**: Boundary conditions, overlapping entities, empty states
-- **Performance**: Large document handling and update efficiency
+Run the test suite:
 
 ```bash
-npm test      # Run all tests
-npm run test:run  # Run tests once without watch mode
+npm test      # Run tests in watch mode
+npm run test:run  # Run tests once
 ```
 
 ## 🏗️ Development
@@ -262,37 +375,19 @@ npm run dev
 # Build for production
 npm run build
 
-# Run tests
-npm test
+# Create local package
+npm run local
 ```
 
-## 📝 API Reference
-
-### Props
+## 🏆 Why Zero Dependencies?
 
-| Prop              | Type                                     | Default | Description                           |
-| ----------------- | ---------------------------------------- | ------- | ------------------------------------- |
-| `plainText`       | `string`                                 | -       | The current plain text content        |
-| `setPlainText`    | `(text: string) => void`                 | -       | Callback to update plain text         |
-| `entities`        | `Entity[]`                               | -       | Array of recognized entities          |
-| `setEntities`     | `(entities: Entity[]) => void`           | -       | Callback to update entities           |
-| `search`          | `ActiveEntity \| null`                   | -       | Current search state for autocomplete |
-| `setSearch`       | `(search: ActiveEntity \| null) => void` | -       | Callback to update search state       |
-| `options`         | `EntityOptions`                          | `{}`    | Configure which entities to detect    |
-| `debounceDelay`   | `number`                                 | `250`   | Delay before processing changes (ms)  |
-| `debounceMaxWait` | `number`                                 | `500`   | Maximum wait time for updates (ms)    |
-| `style`           | `React.CSSProperties`                    | -       | Optional inline styles                |
-| `className`       | `string`                                 | -       | Optional CSS class name               |
-
-### EntityOptions
+This editor proves that powerful text editing doesn't require heavy libraries:
 
-```typescript
-interface EntityOptions {
-  mentions?: boolean; // Enable @mention detection
-  interests?: boolean; // Enable #hashtag detection
-  links?: boolean; // Enable URL detection
-}
-```
+- **Performance**: No bundle bloat, faster load times
+- **Security**: No third-party vulnerabilities
+- **Control**: Full understanding and control over every feature
+- **Maintenance**: Easier updates and customization
+- **Reliability**: No breaking changes from external dependencies
 
 ## 🤝 Contributing
 
@@ -302,16 +397,20 @@ This project maintains its zero-dependency philosophy and bitmap-based architect
 2. **Bitmap First**: All new features should leverage the bitmap system
 3. **Performance Focused**: Optimize for memory usage and processing speed
 4. **TypeScript**: Maintain strict typing throughout
-5. **Test Coverage**: Add comprehensive tests for bitmap operations
+5. **Test Coverage**: Add comprehensive tests for new features
 6. **API Stability**: Keep the component interface simple and focused
 
 ### Understanding the Codebase
 
+- `src/Editor.tsx` - Main editor component
+- `src/interfaces.ts` - TypeScript interfaces and types
 - `src/helpers/bitmap.ts` - Core bitmap manipulation functions
 - `src/helpers/entities.ts` - Bitmap-to-entity conversion logic
 - `src/helpers/marks/` - Individual formatting bit operations
 - `src/helpers/entities/` - Entity type detection and processing
 - `src/helpers/dom.ts` - DOM manipulation and cursor management
+- `src/helpers/keyboard.ts` - Keyboard shortcut handling
+- `src/hooks/useDebounce.ts` - Debounce hook for performance
 
 ## 📄 License