@semantic-components/editor 0.3.0 → 0.61.0

package/README.md

@@ -1,7 +1,14 @@
-# editor
+# @semantic-components/editor
 
-This library was generated with [Nx](https://nx.dev).
+Rich text editor components built on top of Tiptap for the Semantic Components library.
 
-## Running unit tests
+## Contents
 
-Run `nx test editor` to execute the unit tests.
+- **Components**: Editor, toolbar, formatting buttons (bold, italic, underline, strikethrough), alignment, lists, headings, links, code, blockquote, horizontal rule, undo/redo, word/char count
+- **Styles**: ProseMirror editor styles
+
+## Usage
+
+```ts
+import { ScEditor, ScEditorContent, ScEditorToolbar, ScEditorBoldButton } from '@semantic-components/editor';
+```

package/eslint.config.mjs

@@ -0,0 +1,48 @@
+import nx from '@nx/eslint-plugin';
+import baseConfig from '../../eslint.config.mjs';
+
+export default [
+  ...baseConfig,
+  {
+    files: ['**/*.json'],
+    rules: {
+      '@nx/dependency-checks': [
+        'error',
+        {
+          ignoredFiles: ['{projectRoot}/eslint.config.{js,cjs,mjs,ts,cts,mts}'],
+        },
+      ],
+    },
+    languageOptions: {
+      parser: await import('jsonc-eslint-parser'),
+    },
+  },
+  ...nx.configs['flat/angular'],
+  ...nx.configs['flat/angular-template'],
+  {
+    files: ['**/*.ts'],
+    rules: {
+      '@angular-eslint/directive-selector': [
+        'error',
+        {
+          type: 'attribute',
+          prefix: 'sc',
+          style: 'camelCase',
+        },
+      ],
+      '@angular-eslint/component-selector': [
+        'error',
+        {
+          type: 'element',
+          prefix: 'sc',
+          style: 'kebab-case',
+        },
+      ],
+    },
+  },
+  {
+    files: ['**/*.html'],
+    // Override or add rules here
+    rules: {},
+  },
+];

package/ng-package.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "../../node_modules/ng-packagr/ng-package.schema.json",
+  "dest": "../../dist/libs/editor",
+  "lib": {
+    "entryFile": "src/index.ts"
+  }
+}

package/package.json

@@ -1,137 +1,13 @@
 {
   "name": "@semantic-components/editor",
-  "version": "0.3.0",
-  "private": false,
-  "publishConfig": {
-    "access": "public"
-  },
-  "author": "Khalil LAGRIDA",
-  "license": "MIT",
+  "version": "0.61.0",
   "peerDependencies": {
-    "@angular/core": ">=19.0.0",
-    "@semantic-icons/lucide-icons": ">=0.45.0",
-    "@angular/cdk": ">=19.0.0",
-    "@semantic-components/utils": "0.45.0",
-    "@angular/forms": ">=19.0.0",
-    "@tiptap/core": "^2.12.0",
-    "@tiptap/extension-document": "^2.12.0",
-    "@tiptap/extension-heading": "^2.12.0",
-    "@tiptap/extension-paragraph": "^2.12.0",
-    "@tiptap/extension-text": "^2.12.0",
-    "@tiptap/extension-highlight": "^2.12.0",
-    "@tiptap/extension-text-style": "^2.12.0",
-    "@tiptap/extension-color": "^2.12.0",
-    "@tiptap/extension-font-family": "^2.12.0",
-    "@tiptap/extension-underline": "^2.12.0",
-    "@tiptap/extension-image": "^2.12.0",
-    "@tiptap/extension-youtube": "^2.12.0",
-    "@tiptap/extension-link": "^2.12.0",
-    "@tiptap/extension-text-align": "^2.12.0",
-    "@tiptap/extension-list-item": "^2.12.0",
-    "@tiptap/extension-bullet-list": "^2.12.0",
-    "@tiptap/extension-ordered-list": "^2.12.0",
-    "@tiptap/extension-strike": "^2.12.0",
-    "@tiptap/extension-italic": "^2.12.0",
-    "@tiptap/extension-bold": "^2.12.0",
-    "@tiptap/extension-horizontal-rule": "^2.12.0",
-    "@tiptap/extension-blockquote": "^2.12.0",
-    "@tiptap/extension-code": "^2.12.0",
-    "@tiptap/extension-history": "^2.12.0",
-    "@tiptap/extension-table-header": "^2.12.0",
-    "@tiptap/extension-table-row": "^2.12.0",
-    "@tiptap/extension-table-cell": "^2.12.0",
-    "@tiptap/extension-table": "^2.12.0",
-    "@semantic-components/ui": "0.56.0"
-  },
-  "peerDependenciesMeta": {
-    "@tiptap/extension-blockquote": {
-      "optional": true
-    },
-    "@tiptap/extension-bold": {
-      "optional": true
-    },
-    "@tiptap/extension-bullet-list": {
-      "optional": true
-    },
-    "@tiptap/extension-code": {
-      "optional": true
-    },
-    "@tiptap/extension-color": {
-      "optional": true
-    },
-    "@tiptap/extension-font-family": {
-      "optional": true
-    },
-    "@tiptap/extension-highlight": {
-      "optional": true
-    },
-    "@tiptap/extension-history": {
-      "optional": true
-    },
-    "@tiptap/extension-horizontal-rule": {
-      "optional": true
-    },
-    "@tiptap/extension-image": {
-      "optional": true
-    },
-    "@tiptap/extension-italic": {
-      "optional": true
-    },
-    "@tiptap/extension-link": {
-      "optional": true
-    },
-    "@tiptap/extension-list-item": {
-      "optional": true
-    },
-    "@tiptap/extension-ordered-list": {
-      "optional": true
-    },
-    "@tiptap/extension-text-style": {
-      "optional": true
-    },
-    "@tiptap/extension-strike": {
-      "optional": true
-    },
-    "@tiptap/extension-text-align": {
-      "optional": true
-    },
-    "@tiptap/extension-underline": {
-      "optional": true
-    },
-    "@tiptap/extension-youtube": {
-      "optional": true
-    },
-    "@tiptap/extension-table-header": {
-      "optional": true
-    },
-    "@tiptap/extension-table-row": {
-      "optional": true
-    },
-    "@tiptap/extension-table-cell": {
-      "optional": true
-    },
-    "@tiptap/extension-table": {
-      "optional": true
-    }
-  },
-  "sideEffects": false,
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/khalilou88/semantic-components",
-    "directory": "libs/editor"
-  },
-  "module": "fesm2022/semantic-components-editor.mjs",
-  "typings": "index.d.ts",
-  "exports": {
-    "./package.json": {
-      "default": "./package.json"
-    },
-    ".": {
-      "types": "./index.d.ts",
-      "default": "./fesm2022/semantic-components-editor.mjs"
-    }
-  },
-  "dependencies": {
-    "tslib": "^2.3.0"
-  }
-}
+    "@angular/core": ">=21.1.0",
+    "@semantic-components/ui": "0.61.0",
+    "@tiptap/core": ">=3.18.0",
+    "@tiptap/extension-placeholder": ">=3.18.0",
+    "@tiptap/extension-text-align": ">=3.18.0",
+    "@tiptap/starter-kit": ">=3.18.0"
+  },
+  "sideEffects": false
+}

package/project.json

@@ -0,0 +1,28 @@
+{
+  "name": "editor",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "libs/editor/src",
+  "prefix": "sc",
+  "projectType": "library",
+  "tags": [],
+  "targets": {
+    "build": {
+      "executor": "@nx/angular:ng-packagr-lite",
+      "outputs": ["{workspaceRoot}/dist/{projectRoot}"],
+      "options": {
+        "project": "libs/editor/ng-package.json",
+        "tsConfig": "libs/editor/tsconfig.lib.json"
+      },
+      "configurations": {
+        "production": {
+          "tsConfig": "libs/editor/tsconfig.lib.prod.json"
+        },
+        "development": {}
+      },
+      "defaultConfiguration": "production"
+    },
+    "lint": {
+      "executor": "@nx/eslint:lint"
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1 @@
+export * from './lib/components';

package/src/lib/components/editor/README.md

@@ -0,0 +1,354 @@
+# Editor Component
+
+Composable WYSIWYG editor built with [Tiptap](https://tiptap.dev/), a headless rich-text editor framework powered by ProseMirror.
+
+## Installation
+
+The editor component requires Tiptap packages as peer dependencies. Install them alongside `@semantic-components/ui`:
+
+```bash
+npm install @semantic-components/ui \
+  @tiptap/core \
+  @tiptap/starter-kit \
+  @tiptap/extension-text-align \
+  @tiptap/extension-placeholder
+```
+
+Or if you already have `@semantic-components/ui` installed:
+
+```bash
+npm install @tiptap/core @tiptap/starter-kit @tiptap/extension-text-align @tiptap/extension-placeholder
+```
+
+**Note**: Link and Underline extensions are included in `@tiptap/starter-kit` v3, so no need to install them separately.
+
+## Features
+
+- **Rich Text Editing**: Bold, italic, underline, strikethrough, headings, lists, blockquotes, code, links, and more
+- **Keyboard Shortcuts**: Built-in shortcuts for all formatting commands (Ctrl+B, Ctrl+I, Ctrl+U, Ctrl+Z, Ctrl+Y, etc.)
+- **Customizable Toolbar**: Composable architecture allows full control over toolbar layout
+- **Two-Way Binding**: Seamless synchronization with Angular signals
+- **Accessibility**: Full keyboard navigation and ARIA support
+- **Extensible**: Built on Tiptap, allowing custom extensions and commands
+
+## Implementation
+
+The editor is powered by [Tiptap](https://tiptap.dev/), a headless rich-text editor framework built on ProseMirror. This provides:
+
+- **Robust editing**: Industry-standard editing engine
+- **Extensibility**: Add custom extensions and commands
+- **Keyboard shortcuts**: Built-in shortcuts for all formatting
+- **Better browser support**: Works consistently across modern browsers
+- **Future-ready**: Foundation for collaboration, mentions, slash commands, etc.
+
+### Extensions Included
+
+The editor comes pre-configured with these Tiptap extensions:
+
+- **StarterKit**: Bold, Italic, Strike, Underline, Code, Heading, Lists, Blockquote, History, HardBreak, Paragraph, Text, Link
+  - Link configured with: `openOnClick: false`, `target="_blank"`, `rel="noopener noreferrer"`
+- **TextAlign**: Text alignment (left, center, right, justify)
+- **Placeholder**: Customizable placeholder text
+
+### Bundle Size
+
+- **Total**: ~30 KB (minified)
+- **Gzipped**: ~10 KB
+
+This is an acceptable trade-off for the significant improvements in reliability, extensibility, and developer experience.
+
+## Basic Usage
+
+```typescript
+import { Component, signal } from '@angular/core';
+import { ScEditor, ScEditorContent, ScEditorToolbar, ScEditorToolbarGroup, ScEditorBoldButton, ScEditorItalicButton, ScEditorUnderlineButton, ScEditorFooter, ScEditorCount, ScEditorWordCount, ScEditorCharCount } from '@semantic-components/ui-lab';
+
+@Component({
+  selector: 'app-example',
+  imports: [ScEditor, ScEditorContent, ScEditorToolbar, ScEditorToolbarGroup, ScEditorBoldButton, ScEditorItalicButton, ScEditorUnderlineButton, ScEditorFooter, ScEditorCount, ScEditorWordCount, ScEditorCharCount],
+  template: `
+    <div sc-editor class="border rounded-lg overflow-hidden">
+      <div sc-editor-toolbar>
+        <div sc-editor-toolbar-group>
+          <button sc-editor-bold>Bold</button>
+          <button sc-editor-italic>Italic</button>
+          <button sc-editor-underline>Underline</button>
+        </div>
+      </div>
+
+      <div sc-editor-content [(value)]="content" placeholder="Start typing..."></div>
+
+      <div sc-editor-footer>
+        <div sc-editor-count>
+          <span sc-editor-word-count></span>
+          <span sc-editor-char-count></span>
+        </div>
+      </div>
+    </div>
+  `,
+})
+export class ExampleComponent {
+  readonly content = signal('');
+}
+```
+
+## API
+
+### ScEditor (Directive)
+
+Root directive that manages editor state and provides context to child components.
+
+**Selector**: `[sc-editor]`
+
+**Inputs**:
+
+- `disabled: boolean` - Disables the editor
+- `readonly: boolean` - Makes the editor read-only
+
+**Signals** (accessed via `inject(SC_EDITOR)`):
+
+- `isBold()` - Whether bold is active
+- `isItalic()` - Whether italic is active
+- `isUnderline()` - Whether underline is active
+- `isStrikethrough()` - Whether strikethrough is active
+- `isOrderedList()` - Whether ordered list is active
+- `isUnorderedList()` - Whether unordered list is active
+- `isBlockquote()` - Whether blockquote is active
+- `alignment()` - Current text alignment ('left' | 'center' | 'right' | 'justify')
+- `currentHeading()` - Current heading level ('p' | 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6')
+- `canUndo()` - Whether undo is available
+- `canRedo()` - Whether redo is available
+- `editorInstance()` - The Tiptap Editor instance (for advanced usage)
+
+**Methods**:
+
+- `execCommand(command: string, value?: string)` - Execute a formatting command
+- `updateToolbarState()` - Update toolbar button states (called automatically)
+- `initializeEditor(element: HTMLElement, content: string, placeholder: string)` - Initialize Tiptap (called automatically)
+- `destroyEditor()` - Cleanup Tiptap instance (called automatically)
+
+### ScEditorContent (Component)
+
+Content area where text editing happens.
+
+**Selector**: `div[sc-editor-content]`
+
+**Inputs**:
+
+- `value: string` - Two-way bindable HTML content (use with `[(value)]`)
+- `placeholder: string` - Placeholder text (default: "Start typing...")
+- `ariaLabel: string` - ARIA label (default: "Rich text editor")
+- `class: string` - Additional CSS classes (use Tailwind utilities for sizing, e.g., `min-h-[300px] max-h-[500px]`)
+
+**Outputs**:
+
+- `focus` - Emitted when editor gains focus
+- `blur` - Emitted when editor loses focus
+
+### Toolbar Components
+
+All toolbar buttons inject `SC_EDITOR` and call the appropriate commands.
+
+**Available Buttons**:
+
+- `ScEditorBoldButton` - Toggle bold
+- `ScEditorItalicButton` - Toggle italic
+- `ScEditorUnderlineButton` - Toggle underline
+- `ScEditorStrikethroughButton` - Toggle strikethrough
+- `ScEditorCodeButton` - Toggle inline code
+- `ScEditorLinkButton` - Insert/edit link (prompts for URL)
+- `ScEditorBulletListButton` - Toggle bullet list
+- `ScEditorNumberedListButton` - Toggle numbered list
+- `ScEditorBlockquoteButton` - Toggle blockquote
+- `ScEditorAlignLeftButton` - Align left
+- `ScEditorAlignCenterButton` - Align center
+- `ScEditorAlignRightButton` - Align right
+- `ScEditorAlignJustifyButton` - Align justify
+- `ScEditorUndoButton` - Undo last action
+- `ScEditorRedoButton` - Redo last action
+- `ScEditorClearFormattingButton` - Remove all formatting
+
+**Containers**:
+
+- `ScEditorToolbar` - Toolbar container
+- `ScEditorToolbarGroup` - Group related buttons
+- `ScEditorSeparator` - Visual separator between groups
+- `ScEditorFooter` - Footer container
+- `ScEditorHeader` - Header container
+
+**Utilities**:
+
+- `ScEditorCount` - Container for count components (uses `<ng-content>`, allows custom layout)
+- `ScEditorWordCount` - Display word count (e.g., "42 words")
+- `ScEditorCharCount` - Display character count (e.g., "256 characters")
+- `ScEditorHeadingSelect` - Dropdown to select heading level
+
+## Keyboard Shortcuts
+
+All standard keyboard shortcuts are handled by Tiptap:
+
+- **Ctrl+B** / **Cmd+B** - Bold
+- **Ctrl+I** / **Cmd+I** - Italic
+- **Ctrl+U** / **Cmd+U** - Underline
+- **Ctrl+Z** / **Cmd+Z** - Undo
+- **Ctrl+Shift+Z** / **Cmd+Shift+Z** - Redo
+- **Ctrl+Y** / **Cmd+Y** - Redo
+- **Ctrl+E** / **Cmd+E** - Inline code
+
+## Advanced Usage
+
+### Accessing the Tiptap Editor Instance
+
+For advanced use cases, you can access the underlying Tiptap editor:
+
+```typescript
+import { inject, effect } from '@angular/core';
+import { SC_EDITOR } from '@semantic-components/ui-lab';
+
+export class MyComponent {
+  readonly editor = inject(SC_EDITOR);
+
+  constructor() {
+    effect(() => {
+      const instance = this.editor.editorInstance();
+      if (instance) {
+        // Access Tiptap API
+        console.log(instance.getJSON()); // Get content as JSON
+        console.log(instance.getHTML()); // Get content as HTML
+        console.log(instance.getText()); // Get plain text
+
+        // Execute custom commands
+        instance.chain().focus().toggleBold().run();
+      }
+    });
+  }
+}
+```
+
+### Custom Commands
+
+You can execute any Tiptap command via the editor instance:
+
+```typescript
+this.editor.editorInstance()?.chain().focus().setHeading({ level: 2 }).insertContent('Hello world!').run();
+```
+
+## Migration from execCommand
+
+Previous versions used the deprecated `document.execCommand()` API. The current version uses Tiptap internally while maintaining the same external API for backwards compatibility.
+
+**Breaking Changes**: None! The external API remains identical.
+
+**Advanced Users**: If you directly accessed `contentElement()` for DOM manipulation, you should now use `editorInstance()` to interact with the editor via Tiptap's API.
+
+## Future Enhancements
+
+Built on Tiptap, these features can be easily added in the future:
+
+1. **Collaboration** - Real-time co-editing with `@tiptap/extension-collaboration`
+2. **Mentions** - @-mentions with autocomplete
+3. **Slash Commands** - `/` for quick formatting
+4. **Tables** - Rich table support
+5. **Images** - Drag-and-drop image upload
+6. **Custom Extensions** - Domain-specific formatting
+7. **Markdown Support** - Input/output markdown
+8. **Character Limits** - Built-in extension for content limits
+
+## Styling
+
+The editor uses Tailwind CSS with CSS variables for theming. All styles respect the current theme (light/dark mode) and use OKLCH color format.
+
+**CSS Variables Used**:
+
+- `--border` - Border color (blockquote, hr)
+- `--muted` - Muted background (code, pre)
+- `--muted-foreground` - Muted text (placeholder, blockquote)
+- `--primary` - Primary color (links)
+
+Colors are defined in OKLCH format and automatically adapt to light/dark themes.
+
+**Customization**:
+
+```html
+<!-- Custom font and text size -->
+<div sc-editor-content class="font-serif text-lg"></div>
+
+<!-- Custom height constraints -->
+<div sc-editor-content class="min-h-[300px] max-h-[600px]"></div>
+
+<!-- Remove default padding -->
+<div sc-editor-content class="p-0"></div>
+
+<!-- Default: Both counts with standard layout -->
+<div sc-editor-footer>
+  <div sc-editor-count>
+    <span sc-editor-word-count></span>
+    <span sc-editor-char-count></span>
+  </div>
+</div>
+
+<!-- Only word count -->
+<div sc-editor-footer>
+  <div sc-editor-count>
+    <span sc-editor-word-count></span>
+  </div>
+</div>
+
+<!-- Only character count -->
+<div sc-editor-footer>
+  <div sc-editor-count>
+    <span sc-editor-char-count></span>
+  </div>
+</div>
+
+<!-- Custom separator and styling -->
+<div sc-editor-footer>
+  <div sc-editor-count>
+    <span sc-editor-word-count class="text-blue-600"></span>
+    <span class="text-muted-foreground">•</span>
+    <span sc-editor-char-count class="text-green-600"></span>
+  </div>
+</div>
+
+<!-- Footer with additional content -->
+<div sc-editor-footer>
+  <button class="text-sm text-primary hover:underline">Save draft</button>
+  <div sc-editor-count>
+    <span sc-editor-word-count></span>
+    <span sc-editor-char-count></span>
+  </div>
+</div>
+
+<!-- Without using ScEditorCount container -->
+<div sc-editor-footer class="justify-between">
+  <div class="flex gap-2">
+    <span sc-editor-word-count class="text-xs"></span>
+    <span sc-editor-char-count class="text-xs"></span>
+  </div>
+  <button>Submit</button>
+</div>
+```
+
+Default classes applied: `block outline-none overflow-y-auto min-h-[150px] max-h-[400px] p-4 prose prose-sm max-w-none dark:prose-invert`
+
+## Accessibility
+
+The editor follows WCAG AA standards:
+
+- Full keyboard navigation
+- ARIA labels on all buttons
+- Focus management
+- Screen reader support
+- High contrast mode support
+
+## Browser Support
+
+Works in all modern browsers that support ES2015+ and ProseMirror:
+
+- Chrome/Edge 90+
+- Firefox 88+
+- Safari 14+
+
+## License
+
+MIT

package/src/lib/components/editor/editor-align-center-button.ts

@@ -0,0 +1,45 @@
+import {
+  Component,
+  ChangeDetectionStrategy,
+  computed,
+  input,
+  inject,
+  ViewEncapsulation,
+} from '@angular/core';
+import { cn } from '@semantic-components/ui';
+import { SC_EDITOR } from './editor';
+
+@Component({
+  selector: 'button[sc-editor-align-center]',
+  template: `
+    <ng-content />
+  `,
+  host: {
+    'data-slot': 'editor-align-center',
+    type: 'button',
+    '[class]': 'class()',
+    '[disabled]': 'editor.disabled()',
+    '[attr.aria-pressed]': 'editor.alignment() === "center"',
+    '[attr.title]': '"Align center"',
+    '(click)': 'onClick()',
+  },
+  encapsulation: ViewEncapsulation.None,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class ScEditorAlignCenterButton {
+  readonly editor = inject(SC_EDITOR);
+  readonly classInput = input<string>('', { alias: 'class' });
+
+  protected readonly class = computed(() =>
+    cn(
+      'p-1.5 rounded hover:bg-accent disabled:opacity-50 [&_svg]:size-4',
+      this.editor.alignment() === 'center' &&
+        'bg-accent text-accent-foreground',
+      this.classInput(),
+    ),
+  );
+
+  onClick(): void {
+    this.editor.execCommand('justifyCenter');
+  }
+}