feat(editor): add text alignment plugin

Author: cdskill

.agents/skills/angular-rte-architecture/references/current-architecture.md

@@ -43,6 +43,7 @@ an explicit escape hatch.
 An `RtePlugin` has a unique `key` and can contribute:
 
 - `nodes`
+- `extendNodes(nodes)`
 - `marks`
 - `commands(schema)`
 - `commandStates(schema)`

.agents/skills/angular-rte-plugin-development/references/plugin-contract.md

@@ -21,6 +21,7 @@ as the configurable engine-plugin example.
 | ---------------------------- | --------------------------------------------------------- |
 | `key`                        | Stable unique identity for the Angular RTE plugin.        |
 | `nodes`                      | Add optional ProseMirror node specs to the editor schema. |
+| `extendNodes(nodes)`         | Return amended specs for existing schema nodes.           |
 | `marks`                      | Add optional ProseMirror mark specs to the editor schema. |
 | `commands(schema)`           | Register consumer-executable named commands.              |
 | `commandStates(schema)`      | Report meaningful active state for named commands.        |
@@ -63,11 +64,13 @@ A node plugin normally needs:
 
 1. A `NodeSpec` with correct content expression, group, parse rules, and DOM
    serialization.
-2. Commands for inserting, toggling, wrapping, lifting, or changing node type.
-3. State queries only when they provide useful UI state.
-4. Read-only queries only when consumer UI needs structured state.
-5. Keyboard behavior that composes with the base keymap.
-6. Tests for schema validity, parsing, serialization, and editing behavior.
+2. `extendNodes` when a feature needs to add attributes or serialization
+   behavior to an existing schema node such as `paragraph`.
+3. Commands for inserting, toggling, wrapping, lifting, or changing node type.
+4. State queries only when they provide useful UI state.
+5. Read-only queries only when consumer UI needs structured state.
+6. Keyboard behavior that composes with the base keymap.
+7. Tests for schema validity, parsing, serialization, and editing behavior.
 
 Do not introduce an Angular node view until the feature needs Angular-specific
 interactive rendering.

apps/sandbox-e2e/src/example.spec.ts

@@ -8,14 +8,22 @@ test('renders the configured plugin toolbar', async ({ page }) => {
   ).toBeVisible();
 
   const toolbar = page.getByRole('toolbar', { name: 'Editor toolbar' });
-  const paragraph = toolbar.getByRole('button', { name: 'P' });
-  const heading1 = toolbar.getByRole('button', { name: 'H1' });
-  const heading2 = toolbar.getByRole('button', { name: 'H2' });
-  const heading3 = toolbar.getByRole('button', { name: 'H3' });
-  const underline = toolbar.getByRole('button', { name: 'U' });
+  const paragraph = toolbar.getByRole('button', { name: 'Paragraph' });
+  const heading1 = toolbar.getByRole('button', { name: 'Heading 1' });
+  const heading2 = toolbar.getByRole('button', { name: 'Heading 2' });
+  const heading3 = toolbar.getByRole('button', { name: 'Heading 3' });
+  const alignLeft = toolbar.getByRole('button', { name: 'Align left' });
+  const alignCenter = toolbar.getByRole('button', { name: 'Align center' });
+  const alignRight = toolbar.getByRole('button', { name: 'Align right' });
+  const justify = toolbar.getByRole('button', { name: 'Justify' });
+  const underline = toolbar.getByRole('button', { name: 'Underline' });
+  const clearFormatting = toolbar.getByRole('button', {
+    name: 'Clear formatting',
+  });
   const bulletList = toolbar.getByRole('button', { name: 'Bullet list' });
   const orderedList = toolbar.getByRole('button', { name: 'Ordered list' });
   const blockquote = toolbar.getByRole('button', { name: 'Blockquote' });
+  const codeBlock = toolbar.getByRole('button', { name: 'Code block' });
   const liftListItem = toolbar.getByRole('button', { name: 'Lift list item' });
   const sinkListItem = toolbar.getByRole('button', { name: 'Sink list item' });
   const link = toolbar.getByRole('button', { name: 'Link' });
@@ -24,31 +32,42 @@ test('renders the configured plugin toolbar', async ({ page }) => {
   const redo = toolbar.getByRole('button', { name: 'Redo' });
 
   await expect(page.locator('rte-editor > button')).toHaveCount(0);
-  await expect(toolbar.getByRole('button')).toHaveCount(17);
+  await expect(toolbar.getByRole('button')).toHaveCount(23);
   await expect(paragraph).toHaveAttribute('title', 'Paragraph');
   await expect(heading1).toHaveAttribute('title', 'Heading 1');
   await expect(heading2).toHaveAttribute('title', 'Heading 2');
   await expect(heading3).toHaveAttribute('title', 'Heading 3');
-  await expect(toolbar.getByRole('button', { name: 'B' })).toHaveAttribute(
+  await expect(alignLeft).toHaveAttribute('title', 'Align left');
+  await expect(alignLeft).toBeEnabled();
+  await expect(alignCenter).toHaveAttribute('title', 'Align center');
+  await expect(alignCenter).toBeEnabled();
+  await expect(alignRight).toHaveAttribute('title', 'Align right');
+  await expect(alignRight).toBeEnabled();
+  await expect(justify).toHaveAttribute('title', 'Justify');
+  await expect(justify).toBeEnabled();
+  await expect(toolbar.getByRole('button', { name: 'Bold' })).toHaveAttribute(
     'title',
     'Bold',
   );
-  await expect(toolbar.getByRole('button', { name: 'I' })).toHaveAttribute(
+  await expect(toolbar.getByRole('button', { name: 'Italic' })).toHaveAttribute(
     'title',
     'Italic',
   );
   await expect(underline).toHaveAttribute('title', 'Underline');
   await expect(underline).toBeEnabled();
-  await expect(toolbar.getByRole('button', { name: 'S' })).toHaveAttribute(
-    'title',
-    'Strikethrough',
-  );
+  await expect(
+    toolbar.getByRole('button', { name: 'Strikethrough' }),
+  ).toHaveAttribute('title', 'Strikethrough');
+  await expect(clearFormatting).toHaveAttribute('title', 'Clear formatting');
+  await expect(clearFormatting).toBeEnabled();
   await expect(bulletList).toHaveAttribute('title', 'Bullet list');
   await expect(bulletList).toBeDisabled();
   await expect(orderedList).toHaveAttribute('title', 'Ordered list');
   await expect(orderedList).toBeDisabled();
   await expect(blockquote).toHaveAttribute('title', 'Blockquote');
   await expect(blockquote).toBeEnabled();
+  await expect(codeBlock).toHaveAttribute('title', 'Code block');
+  await expect(codeBlock).toBeEnabled();
   await expect(liftListItem).toHaveAttribute('title', 'Lift list item');
   await expect(liftListItem).toBeDisabled();
   await expect(sinkListItem).toHaveAttribute('title', 'Sink list item');
@@ -61,6 +80,9 @@ test('renders the configured plugin toolbar', async ({ page }) => {
   await expect(redo).toBeDisabled();
 
   await expect(page.locator('.ProseMirror')).toContainText('Angular RTE');
+  await expect(page.locator('pre')).toContainText(
+    '<p style="text-align: center;">Build headless editing primitives with a plugin stack that remains fully selected by the consumer.</p>',
+  );
   await expect(page.locator('pre')).toContainText(
     '<h1><strong>Angular RTE</strong></h1>',
   );
@@ -91,6 +113,15 @@ test('renders the configured plugin toolbar', async ({ page }) => {
   await expect(page.locator('pre')).toContainText(
     '<p>Build headless editing primitives with a plugin stack that remains fully selected by the consumer.</p>',
   );
+  await alignRight.click();
+  await expect(alignRight).toHaveAttribute('aria-pressed', 'true');
+  await expect(page.locator('pre')).toContainText(
+    '<p style="text-align: right;">Build headless editing primitives with a plugin stack that remains fully selected by the consumer.</p>',
+  );
+  await alignLeft.click();
+  await expect(page.locator('pre')).toContainText(
+    '<p>Build headless editing primitives with a plugin stack that remains fully selected by the consumer.</p>',
+  );
   await expect(bulletList).toBeEnabled();
   await expect(orderedList).toBeEnabled();
 
@@ -99,6 +130,14 @@ test('renders the configured plugin toolbar', async ({ page }) => {
   await expect(page.locator('pre')).toContainText(
     '<ul><li><p>Build headless editing primitives with a plugin stack that remains fully selected by the consumer.</p></li></ul>',
   );
+  await alignRight.click();
+  await expect(page.locator('pre')).toContainText(
+    '<ul><li style="text-align: right;"><p>Build headless editing primitives with a plugin stack that remains fully selected by the consumer.</p></li></ul>',
+  );
+  await alignLeft.click();
+  await expect(page.locator('pre')).toContainText(
+    '<ul><li><p>Build headless editing primitives with a plugin stack that remains fully selected by the consumer.</p></li></ul>',
+  );
   await page.locator('.ProseMirror').press('Tab');
   await expect(page.locator('.ProseMirror')).toBeFocused();
   await page.locator('.ProseMirror').press('Escape');
@@ -134,7 +173,9 @@ test('renders the configured plugin toolbar', async ({ page }) => {
   await expect(underline).toHaveAttribute('aria-pressed', 'true');
 
   await page.locator('.ProseMirror a[href="https://angular.dev"]').hover();
-  await expect(page.getByRole('dialog', { name: 'Link preview' })).toBeVisible();
+  await expect(
+    page.getByRole('dialog', { name: 'Link preview' }),
+  ).toBeVisible();
   await expect(
     page.getByRole('dialog', { name: 'Link preview' }).getByRole('link'),
   ).toContainText('https://angular.dev');

apps/sandbox/src/app/app.spec.ts

@@ -11,8 +11,12 @@ import {
   HistoryPlugin,
   LINK_PLUGIN_DEFAULT_OPTIONS,
   LinkPlugin,
+  ListsPlugin,
+  TEXT_ALIGN_PLUGIN_DEFAULT_OPTIONS,
+  TextAlignPlugin,
   TextFormattingKit,
   createRteEditor,
+  createRtePlugin,
 } from '@angular-rte/editor';
 
 import { App } from './app';
@@ -34,9 +38,14 @@ describe('App', () => {
       'ProseMirror editor foundation',
     );
     expect(compiled.querySelectorAll('[role="toolbar"] button')).toHaveLength(
-      19,
+      23,
     );
-    expect(compiled.querySelector('[aria-label="Clear formatting"]')).not.toBeNull();
+    expect(
+      compiled.querySelector('[aria-label="Clear formatting"]'),
+    ).not.toBeNull();
+    expect(
+      compiled.querySelector('[aria-label="Align center"]'),
+    ).not.toBeNull();
     expect(compiled.querySelector('[aria-label="Link URL"]')).toBeNull();
     expect(compiled.querySelector('.ProseMirror')?.textContent).toContain(
       'Angular RTE',
@@ -60,8 +69,9 @@ describe('App', () => {
       compiled.querySelector('.ProseMirror code.language-go')?.textContent,
     ).toContain('fmt.Println');
     expect(
-      compiled.querySelector('.ProseMirror code.language-typescript .hljs-keyword')
-        ?.textContent,
+      compiled.querySelector(
+        '.ProseMirror code.language-typescript .hljs-keyword',
+      )?.textContent,
     ).toContain('import');
     expect(
       compiled.querySelector('.ProseMirror code.language-go .hljs-keyword')
@@ -323,9 +333,7 @@ describe('App', () => {
     editor.mount(host);
 
     expect(editor.execute('clearFormatting')).toBeTrue();
-    expect(editor.html()).toBe(
-      '<p>const first = 1;<br>const second = 2;</p>',
-    );
+    expect(editor.html()).toBe('<p>const first = 1;<br>const second = 2;</p>');
 
     editor.unmount(host);
   });
@@ -366,7 +374,8 @@ describe('App', () => {
 
   it('should keep Tab inside code blocks for indentation', () => {
     const editor = createRteEditor({
-      content: '<pre><code class="language-typescript">const answer = 42;</code></pre>',
+      content:
+        '<pre><code class="language-typescript">const answer = 42;</code></pre>',
       plugins: [
         CodeBlockPlugin.configure({
           languages: ['plaintext', 'typescript'],
@@ -477,6 +486,113 @@ describe('App', () => {
     editor.unmount(host);
   });
 
+  it('should expose text alignment through the public plugin', () => {
+    const editor = createRteEditor({
+      content: '<p>Aligned text</p>',
+      plugins: [TextAlignPlugin, HeadingsPlugin],
+    });
+    const host = document.createElement('div');
+
+    editor.mount(host);
+
+    expect(TextAlignPlugin.key).toBe('textAlign');
+    expect(editor.canExecute('setTextAlignCenter')).toBeTrue();
+    expect(editor.isCommandActive('setTextAlignLeft')).toBeTrue();
+    expect(editor.query('textAlign')).toBe('left');
+    expect(editor.execute('setTextAlignCenter')).toBeTrue();
+    expect(editor.isCommandActive('setTextAlignCenter')).toBeTrue();
+    expect(editor.query('textAlign')).toBe('center');
+    expect(editor.html()).toBe(
+      '<p style="text-align: center;">Aligned text</p>',
+    );
+    expect(editor.execute('setTextAlignLeft')).toBeTrue();
+    expect(editor.html()).toBe('<p>Aligned text</p>');
+
+    editor.setHtml('<h2 style="text-align: right;">Aligned heading</h2>');
+
+    expect(editor.isCommandActive('setTextAlignRight')).toBeTrue();
+    expect(editor.query('textAlign')).toBe('right');
+    expect(editor.execute('setTextAlignJustify')).toBeTrue();
+    expect(editor.html()).toBe(
+      '<h2 style="text-align: justify;">Aligned heading</h2>',
+    );
+
+    editor.unmount(host);
+  });
+
+  it('should align list items and blockquotes at the container level', () => {
+    const editor = createRteEditor({
+      content:
+        '<ul><li><p>Aligned list item</p></li></ul><blockquote><p>Aligned quote</p></blockquote>',
+      plugins: [TextAlignPlugin, ListsPlugin, BlockquotePlugin],
+    });
+    const host = document.createElement('div');
+
+    editor.mount(host);
+
+    expect(editor.execute('setTextAlignCenter')).toBeTrue();
+    expect(editor.html()).toContain(
+      '<li style="text-align: center;"><p>Aligned list item</p></li>',
+    );
+    expect(editor.execute('setTextAlignLeft')).toBeTrue();
+    expect(editor.html()).toContain('<li><p>Aligned list item</p></li>');
+
+    editor.setHtml('<blockquote><p>Aligned quote</p></blockquote>');
+
+    expect(editor.execute('setTextAlignRight')).toBeTrue();
+    expect(editor.html()).toBe(
+      '<blockquote style="text-align: right;"><p>Aligned quote</p></blockquote>',
+    );
+
+    editor.unmount(host);
+  });
+
+  it('should expose configurable text alignment defaults and validation', () => {
+    const configured = TextAlignPlugin.configure({
+      alignments: ['left', 'center'],
+      nodes: ['paragraph'],
+    });
+
+    expect(TEXT_ALIGN_PLUGIN_DEFAULT_OPTIONS).toEqual({
+      alignments: ['left', 'center', 'right', 'justify'],
+      nodes: ['paragraph', 'heading', 'listItem', 'blockquote'],
+    });
+    expect(TextAlignPlugin.options).toEqual(TEXT_ALIGN_PLUGIN_DEFAULT_OPTIONS);
+    expect(configured.options).toEqual({
+      alignments: ['left', 'center'],
+      nodes: ['paragraph'],
+    });
+    expect(() =>
+      TextAlignPlugin.configure({
+        alignments: [],
+      }),
+    ).toThrowError(
+      'TextAlignPlugin alignments must include at least one value.',
+    );
+    expect(() =>
+      TextAlignPlugin.configure({
+        alignments: ['center', 'center'],
+      }),
+    ).toThrowError('TextAlignPlugin alignments entries must be unique.');
+    expect(() =>
+      TextAlignPlugin.configure({
+        nodes: ['paragraph', 'paragraph'],
+      }),
+    ).toThrowError('TextAlignPlugin nodes entries must be unique.');
+    expect(() =>
+      createRteEditor({
+        plugins: [
+          createRtePlugin({
+            key: 'badNodeExtension',
+            extendNodes: () => ({ missing: { content: 'inline*' } }),
+          }),
+        ],
+      }),
+    ).toThrowError(
+      'RTE plugin "badNodeExtension" extends unknown node "missing".',
+    );
+  });
+
   it('should expose configurable headings defaults and validation', () => {
     const configured = HeadingsPlugin.configure({
       levels: [2, 3, 4],

apps/sandbox/src/app/sandbox-editor.ts

@@ -10,6 +10,7 @@ import {
   ListsPlugin,
   RteContent,
   RteEditor,
+  TextAlignPlugin,
   createRteEditor,
   TextFormattingKit,
 } from '@angular-rte/editor';
@@ -70,10 +71,11 @@ import { SandboxToolbar } from './sandbox-toolbar';
 export class SandboxEditor {
   protected readonly editor = createRteEditor({
     content:
-      '<h1><strong>Angular RTE</strong></h1><p>Build headless editing primitives with a plugin stack that remains fully selected by the consumer.</p><blockquote><p>Quote important passages without taking ownership away from the consuming app.</p></blockquote><p>Use the toolbar to shape content without surrendering UI ownership: try <em>italic</em>, <u>underline</u>, <s>strikethrough</s>, and <a href="https://angular.dev" target="_blank" rel="noopener noreferrer">links</a>.</p><pre><code class="language-typescript">import { createRteEditor } from "@angular-rte/editor";&#10;&#10;const editor = createRteEditor({&#10;  plugins: [CodeBlockPlugin],&#10;});&#10;&#10;editor.execute("setCodeBlockLanguage", "typescript");</code></pre><pre><code class="language-go">package main&#10;&#10;import "fmt"&#10;&#10;func main() {&#10;  fmt.Println("Angular RTE")&#10;}</code></pre><ul><li><p>Compose plugins in TypeScript.</p></li><li><p>Keep toolbar markup in the consuming app.</p></li></ul><ol><li><p>Pick capabilities for the current product surface.</p></li><li><p>Render controls with Angular templates and rteCommand.</p></li></ol><p>Switch paragraphs into lists, nest items with Tab, and lift them back out with Shift+Tab.</p>',
+      '<h1><strong>Angular RTE</strong></h1><p style="text-align: center;">Build headless editing primitives with a plugin stack that remains fully selected by the consumer.</p><blockquote><p>Quote important passages without taking ownership away from the consuming app.</p></blockquote><p>Use the toolbar to shape content without surrendering UI ownership: try <em>italic</em>, <u>underline</u>, <s>strikethrough</s>, and <a href="https://angular.dev" target="_blank" rel="noopener noreferrer">links</a>.</p><pre><code class="language-typescript">import { createRteEditor } from "@angular-rte/editor";&#10;&#10;const editor = createRteEditor({&#10;  plugins: [CodeBlockPlugin],&#10;});&#10;&#10;editor.execute("setCodeBlockLanguage", "typescript");</code></pre><pre><code class="language-go">package main&#10;&#10;import "fmt"&#10;&#10;func main() {&#10;  fmt.Println("Angular RTE")&#10;}</code></pre><ul><li><p>Compose plugins in TypeScript.</p></li><li><p>Keep toolbar markup in the consuming app.</p></li></ul><ol><li><p>Pick capabilities for the current product surface.</p></li><li><p>Render controls with Angular templates and rteCommand.</p></li></ol><p>Switch paragraphs into lists, nest items with Tab, and lift them back out with Shift+Tab.</p>',
     placeholder: 'Start writing...',
     plugins: [
       HeadingsPlugin,
+      TextAlignPlugin,
       ...TextFormattingKit,
       LinkPlugin,
       ListsPlugin,