fix(data-integrity): keep controlled value sync atomic

src/components/CwlEditor.controlledValueComposition.test.tsx

@@ -0,0 +1,274 @@
+import type { Editor } from '@tiptap/react';
+import { act, cleanup, fireEvent, render, waitFor } from '@testing-library/react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { CwlEditor } from './CwlEditor.js';
+
+afterEach(cleanup);
+
+describe('CwlEditor controlled value during composition', () => {
+  it('defers host replacement until composition ends and applies the latest value', async () => {
+    let editor: Editor | undefined;
+    const captureEditor = (instance: Editor) => {
+      editor = instance;
+    };
+
+    const { rerender } = render(
+      <CwlEditor mode="markdown" value="Original" onReady={captureEditor} />,
+    );
+    await waitFor(() => expect(editor).toBeTruthy());
+
+    const editable = document.querySelector('.ProseMirror') as HTMLElement;
+    fireEvent.compositionStart(editable, { data: '' });
+    expect(editor!.view.composing).toBe(true);
+
+    await act(async () => {
+      rerender(
+        <CwlEditor mode="markdown" value="First host value" onReady={captureEditor} />,
+      );
+    });
+    expect(editor!.view.composing).toBe(true);
+    expect(editor!.getText()).toBe('Original');
+
+    await act(async () => {
+      rerender(
+        <CwlEditor mode="markdown" value="Latest host value" onReady={captureEditor} />,
+      );
+    });
+    expect(editor!.view.composing).toBe(true);
+    expect(editor!.getText()).toBe('Original');
+
+    fireEvent.compositionEnd(editable, { data: '' });
+
+    await waitFor(() => {
+      expect(editor!.view.composing).toBe(false);
+      expect(editor!.getText()).toBe('Latest host value');
+    });
+  });
+
+  it('keeps intermediate composition text out of document snapshot callbacks', async () => {
+    let editor: Editor | undefined;
+    const onChange = vi.fn();
+    const onDocumentChange = vi.fn();
+
+    render(
+      <CwlEditor
+        mode="markdown"
+        defaultValue="Original"
+        onChange={onChange}
+        onDocumentChange={onDocumentChange}
+        onReady={(instance) => {
+          editor = instance;
+        }}
+      />,
+    );
+    await waitFor(() => expect(editor).toBeTruthy());
+    await waitFor(() => expect(onChange).toHaveBeenCalledTimes(1));
+    expect(onChange).toHaveBeenLastCalledWith('Original');
+    expect(onDocumentChange).not.toHaveBeenCalled();
+    onChange.mockClear();
+
+    const editable = document.querySelector('.ProseMirror') as HTMLElement;
+    expect(editable).toBe(editor!.view.dom);
+    fireEvent.compositionStart(editable, { data: '' });
+    expect(editor!.view.composing).toBe(true);
+    expect(onDocumentChange).not.toHaveBeenCalled();
+
+    act(() => {
+      editor!.chain().focus('end').insertContent(' composing').run();
+    });
+
+    expect(editor!.view.composing).toBe(true);
+    expect(editor!.getText()).toBe('Original composing');
+    expect(onChange).toHaveBeenLastCalledWith('Original composing');
+    expect(onDocumentChange).not.toHaveBeenCalled();
+
+    fireEvent.compositionEnd(editable, { data: '' });
+    await waitFor(() => {
+      expect(editor!.view.composing).toBe(false);
+      expect(onDocumentChange).toHaveBeenCalledTimes(1);
+    });
+    expect(onDocumentChange.mock.calls[0]![0].snapshot.value).toBe(
+      'Original composing',
+    );
+
+    act(() => {
+      editor!.chain().focus('end').insertContent(' committed').run();
+    });
+
+    expect(onDocumentChange).toHaveBeenCalledTimes(2);
+    expect(onDocumentChange.mock.calls[1]![0].snapshot.value).toBe(
+      'Original composing committed',
+    );
+  });
+
+  it('publishes the finalized composition snapshot when composition ends', async () => {
+    let editor: Editor | undefined;
+    const onDocumentChange = vi.fn();
+
+    render(
+      <CwlEditor
+        mode="markdown"
+        defaultValue="Original"
+        onDocumentChange={onDocumentChange}
+        onReady={(instance) => {
+          editor = instance;
+        }}
+      />,
+    );
+    await waitFor(() => expect(editor).toBeTruthy());
+    expect(onDocumentChange).not.toHaveBeenCalled();
+
+    const editable = editor!.view.dom;
+    fireEvent.compositionStart(editable, { data: '' });
+    act(() => {
+      editor!.chain().focus('end').insertContent(' composing').run();
+    });
+    expect(onDocumentChange).not.toHaveBeenCalled();
+
+    fireEvent.compositionEnd(editable, { data: '' });
+
+    await waitFor(() => {
+      expect(editor!.view.composing).toBe(false);
+      expect(onDocumentChange).toHaveBeenCalledTimes(1);
+    });
+    expect(onDocumentChange.mock.calls[0]![0].snapshot.value).toBe(
+      'Original composing',
+    );
+  });
+
+  it('publishes the finalized local composition before applying a deferred controlled value', async () => {
+    let editor: Editor | undefined;
+    const onDocumentChange = vi.fn();
+    const captureEditor = (instance: Editor) => {
+      editor = instance;
+    };
+
+    const { rerender } = render(
+      <CwlEditor
+        mode="markdown"
+        value="Original"
+        onDocumentChange={onDocumentChange}
+        onReady={captureEditor}
+      />,
+    );
+    await waitFor(() => expect(editor).toBeTruthy());
+
+    const editable = editor!.view.dom;
+    fireEvent.compositionStart(editable, { data: '' });
+    act(() => {
+      editor!.chain().focus('end').insertContent(' composing').run();
+    });
+    expect(editor!.getText()).toBe('Original composing');
+    expect(onDocumentChange).not.toHaveBeenCalled();
+
+    await act(async () => {
+      rerender(
+        <CwlEditor
+          mode="markdown"
+          value="Host replacement"
+          onDocumentChange={onDocumentChange}
+          onReady={captureEditor}
+        />,
+      );
+    });
+    expect(editor!.view.composing).toBe(true);
+    expect(editor!.getText()).toBe('Original composing');
+
+    fireEvent.compositionEnd(editable, { data: '' });
+
+    await waitFor(() => expect(editor!.getText()).toBe('Host replacement'));
+    await waitFor(() => expect(onDocumentChange).toHaveBeenCalledTimes(1));
+    expect(onDocumentChange.mock.calls[0]![0].snapshot.value).toBe(
+      'Original composing',
+    );
+  });
+
+  it('drops a queued composition snapshot when the editor is destroyed first', async () => {
+    let editor: Editor | undefined;
+    const onDocumentChange = vi.fn();
+
+    const { unmount } = render(
+      <CwlEditor
+        mode="markdown"
+        defaultValue="Original"
+        onDocumentChange={onDocumentChange}
+        onReady={(instance) => {
+          editor = instance;
+        }}
+      />,
+    );
+    await waitFor(() => expect(editor).toBeTruthy());
+
+    const editable = editor!.view.dom;
+    fireEvent.compositionStart(editable, { data: '' });
+    act(() => {
+      editor!.chain().focus('end').insertContent(' composing').run();
+    });
+    expect(onDocumentChange).not.toHaveBeenCalled();
+
+    act(() => {
+      editable.dispatchEvent(
+        new CompositionEvent('compositionend', { bubbles: true, data: '' }),
+      );
+      unmount();
+    });
+
+    await act(async () => {
+      await Promise.resolve();
+    });
+    expect(onDocumentChange).not.toHaveBeenCalled();
+  });
+
+  it('drops a deferred controlled replacement when the editor is destroyed first', async () => {
+    let editor: Editor | undefined;
+    const onDocumentChange = vi.fn();
+    const captureEditor = (instance: Editor) => {
+      editor = instance;
+    };
+
+    const { rerender, unmount } = render(
+      <CwlEditor
+        mode="markdown"
+        value="Original"
+        onDocumentChange={onDocumentChange}
+        onReady={captureEditor}
+      />,
+    );
+    await waitFor(() => expect(editor).toBeTruthy());
+
+    const editable = editor!.view.dom;
+    fireEvent.compositionStart(editable, { data: '' });
+    act(() => {
+      editor!.chain().focus('end').insertContent(' composing').run();
+    });
+    expect(editor!.getText()).toBe('Original composing');
+    expect(onDocumentChange).not.toHaveBeenCalled();
+
+    await act(async () => {
+      rerender(
+        <CwlEditor
+          mode="markdown"
+          value="Host replacement"
+          onDocumentChange={onDocumentChange}
+          onReady={captureEditor}
+        />,
+      );
+    });
+    expect(editor!.view.composing).toBe(true);
+    expect(editor!.getText()).toBe('Original composing');
+
+    act(() => {
+      editable.dispatchEvent(
+        new CompositionEvent('compositionend', { bubbles: true, data: '' }),
+      );
+      unmount();
+    });
+
+    await act(async () => {
+      await Promise.resolve();
+      await Promise.resolve();
+    });
+    expect(onDocumentChange).not.toHaveBeenCalled();
+    expect(editor!.getText()).toBe('Original composing');
+  });
+});

src/components/CwlEditor.editabilityComposition.test.tsx

@@ -0,0 +1,32 @@
+import { cleanup, fireEvent, render, waitFor } from '@testing-library/react';
+import type { Editor } from '@tiptap/react';
+import { afterEach, describe, expect, it } from 'vitest';
+import { CwlEditor } from './CwlEditor.js';
+
+afterEach(cleanup);
+
+describe('CwlEditor editability transition during composition', () => {
+  it('clears local composition state before revoking edit authority', async () => {
+    let editor: Editor | undefined;
+    const captureEditor = (instance: Editor) => {
+      editor = instance;
+    };
+
+    const { rerender } = render(
+      <CwlEditor defaultValue="기준" editable onReady={captureEditor} />,
+    );
+    await waitFor(() => expect(editor).toBeTruthy());
+
+    const editable = document.querySelector('.ProseMirror') as HTMLElement;
+    fireEvent.compositionStart(editable, { data: '' });
+    expect(editor!.view.composing).toBe(true);
+
+    rerender(
+      <CwlEditor defaultValue="기준" editable={false} onReady={captureEditor} />,
+    );
+
+    await waitFor(() => expect(editor!.isEditable).toBe(false));
+    expect(editor!.view.composing).toBe(false);
+    expect(editor!.getText()).toBe('기준');
+  });
+});

src/components/CwlEditor.runtimeEditable.test.tsx

@@ -0,0 +1,23 @@
+// @vitest-environment node
+
+import { renderToString } from 'react-dom/server';
+import { describe, expect, it } from 'vitest';
+import { CwlEditor } from './CwlEditor.js';
+
+describe('standalone editor editable runtime contract', () => {
+  it('rejects a non-boolean editable state instead of coercing it into edit authority', () => {
+    expect(() =>
+      renderToString(
+        <CwlEditor editable={'false' as unknown as boolean} />,
+      ),
+    ).toThrowError(
+      new RangeError('editor editable state must be a boolean when provided'),
+    );
+  });
+
+  it('preserves omitted, explicitly editable, and explicitly read-only states', () => {
+    expect(() => renderToString(<CwlEditor />)).not.toThrow();
+    expect(() => renderToString(<CwlEditor editable />)).not.toThrow();
+    expect(() => renderToString(<CwlEditor editable={false} />)).not.toThrow();
+  });
+});

src/components/CwlEditor.runtimeToolbarVisibility.test.tsx

@@ -0,0 +1,25 @@
+// @vitest-environment node
+
+import { renderToString } from 'react-dom/server';
+import { describe, expect, it } from 'vitest';
+import { CwlEditor } from './CwlEditor.js';
+
+describe('standalone editor toolbar visibility runtime contract', () => {
+  it('rejects a non-boolean toolbar visibility state instead of coercing it', () => {
+    expect(() =>
+      renderToString(
+        <CwlEditor hideToolbar={'false' as unknown as boolean} />,
+      ),
+    ).toThrowError(
+      new RangeError(
+        'editor toolbar visibility state must be a boolean when provided',
+      ),
+    );
+  });
+
+  it('preserves omitted, visible, and hidden toolbar states', () => {
+    expect(() => renderToString(<CwlEditor />)).not.toThrow();
+    expect(() => renderToString(<CwlEditor hideToolbar={false} />)).not.toThrow();
+    expect(() => renderToString(<CwlEditor hideToolbar />)).not.toThrow();
+  });
+});