commspliant-html-editor 0.0.4 → 0.0.5

package/README.md

@@ -57,7 +57,7 @@ Give the editor a parent with a definite height (`height: 100%` on a sized ances
 | `onFullscreenChange` | `(fullscreen: boolean) => void` | — | Fires when full screen is entered or exited |
 | `placeholder` | `string` | — | Empty-state hint |
 | `disabled` | `boolean` | `false` | Same lock as `readOnly`. Either prop being true locks the editor |
-| `readOnly` | `boolean` | `false` | When true, neither surface can be edited and both are grayed out; menus and toolbar are grayed out and not clickable |
+| `readOnly` | `boolean` | `false` | Locks document editing. When `enableComments` is also true, comment chrome stays available and `onCommentsChange` still fires; anchor writes do not call `onChange`. See [Comments](#comments) |
 | `className` | `string` | — | Extra class on the editor root |
 | `locale` | `'en' \| 'es'` | `'en'` | Library chrome language. Document content is not translated |
 | `toolbarBackground` | `string` | `#f0f0f0` | CSS color for the icon toolbar row. Omit to use the default light gray |
@@ -88,11 +88,16 @@ Give the editor a parent with a definite height (`height: 100%` on a sized ances
 | `pages` | `string[]` | — | Controlled page HTML strings when `enableMultiPages` is true |
 | `defaultPages` | `string[]` | — | Initial pages when uncontrolled and `enableMultiPages` is true |
 | `onPagesChange` | `(pages: string[], activePageIndex: number) => void` | — | Fires when any page changes while multi-page mode is enabled |
+| `enableComments` | `boolean` | `false` | When true, comment chrome and thread state are enabled. See [Comments](#comments) |
+| `commentAuthor` | `CommentAuthor` | — | `{ userId, userName }` identity for posting messages in the comment panel |
+| `comments` | `CommentThread[]` | — | Controlled comment thread array (metadata separate from document HTML) |
+| `defaultComments` | `CommentThread[]` | `[]` | Initial threads when uncontrolled |
+| `onCommentsChange` | `(threads: CommentThread[]) => void` | — | Fires when comment threads change |
 | `toolbarCustomization` | `ToolbarCustomizationPersistence` | — | Host load/save for icon-toolbar layout. Omit to persist in `localStorage`. See [Customize toolbar](#customize-toolbar) |
 | `darkMode` | `boolean` | `false` | Initial chrome theme when nothing is persisted (`true` = dark). See [Dark mode](#dark-mode) |
 | `darkModePersistence` | `DarkModePersistence` | — | Host load/save for the chrome theme. Omit to persist in `localStorage`. See [Dark mode](#dark-mode) |
 
-`mode`, `value`, and `fullscreen` are optional. Omit them for internal state; pass them to control from the parent. Chrome includes a File menu (Save, Load, and Print), an Edit menu (Undo, Redo, and Page properties), an Insert menu (Link, Bookmark, Image, Audio, YouTube video, Table, and Horizontal line), a Table menu (Insert table, row and column items, Merge cells, Unmerge cells, and table/cell/row properties), a View menu (Visual, HTML, Toolbar customize and position, Light/Dark mode, Preview, Read aloud, and Full screen), and a Format menu (paragraph styles, font, clear formatting, paragraph, and image properties), unless `menuVisible` is `false`. The icon toolbar has File (Save and Load), Print, Edit (Undo and Redo), Insert (Link, Bookmark, Image, Table, and Horizontal line), Table (Merge cells and Unmerge cells), Font, Align, Paragraph, and View (Visual | HTML | Preview | Read aloud) groups, with Full screen pinned last, unless `toolbarVisible` is `false`. Hide both to drop the chrome slot entirely. View → Toolbar → Position docks the icon toolbar (the menu bar stays at the top). Top and bottom wrap onto multiple rows when they cannot fit on one line; Full screen stays last, pinned to the right of the first row. Left and right stay a single column and grow the editor instead of wrapping into extra columns. Full screen covers the host page with a fixed overlay; an X control (and Escape) returns to the in-page layout. Visual and HTML mode stay independent of the overlay. By default, Save writes the current document to an HTML file and Load replaces it from an HTML file; pass `onSave` and/or `onOpen` to delegate to host callbacks instead (see [Save and open](#save-and-open)). Dropping an `.html` / `.htm` file onto the document surface does the same as Load, unless `disableHtmlFileDrop` is set. Print opens the browser print dialog for the document HTML only (not the editor chrome). Preview (View menu and View icon group) opens a large dialog with a scrollable rendering of the current document HTML. Read aloud (View menu and View icon group) uses the browser’s built-in speech synthesis to read the current selection, or the full document when nothing is selected; click again to stop. Undo and Redo walk document HTML history; they are grayed out when there is nothing to undo or redo. The File, Edit, and Insert menu items use the same icons as the toolbar buttons where both exist. Link wraps the selection (or inserts the URL as the visible text at the caret) in an `<a href>` tag; an optional title becomes the native hover tooltip, and opening in a new tab sets `target="_blank"`. Bookmark inserts a named destination (`id`) at the caret or around the selection. Audio and YouTube video are available from the Insert menu only (no toolbar buttons). Horizontal line inserts an `<hr>` at the caret.
+`mode`, `value`, and `fullscreen` are optional. Omit them for internal state; pass them to control from the parent. Chrome includes a File menu (Save, Load, and Print), an Edit menu (Undo, Redo, and Page properties), an Insert menu (Link, Bookmark, Image, Audio, YouTube video, Table, Horizontal line, and Page break), a Table menu (Insert table, row and column items, Merge cells, Unmerge cells, and table/cell/row properties), a View menu (Visual, HTML, Toolbar customize and position, Zoom, Light/Dark mode, Preview, Read aloud, and Full screen), and a Format menu (paragraph styles, font, clear formatting, paragraph, and image properties), unless `menuVisible` is `false`. The icon toolbar has File (Save and Load), Print, Edit (Undo and Redo), Insert (Link, Bookmark, Image, Table, and Horizontal line), Table (Merge cells and Unmerge cells), Font, Align, Paragraph, and View (Visual | HTML | Preview | Read aloud) groups, with Full screen pinned last, unless `toolbarVisible` is `false`. Hide both to drop the chrome slot entirely. View → Toolbar → Position docks the icon toolbar (the menu bar stays at the top). Top and bottom wrap onto multiple rows when they cannot fit on one line; Full screen stays last, pinned to the right of the first row. Left and right stay a single column and grow the editor instead of wrapping into extra columns. Full screen covers the host page with a fixed overlay; an X control (and Escape) returns to the in-page layout. Visual and HTML mode stay independent of the overlay. By default, Save writes the current document to an HTML file and Load replaces it from an HTML file; pass `onSave` and/or `onOpen` to delegate to host callbacks instead (see [Save and open](#save-and-open)). Dropping an `.html` / `.htm` file onto the document surface does the same as Load, unless `disableHtmlFileDrop` is set. Print opens the browser print dialog for the document HTML only (not the editor chrome). Preview (View menu and View icon group) opens a large dialog with a scrollable rendering of the current document HTML. Read aloud (View menu and View icon group) uses the browser’s built-in speech synthesis to read the current selection, or the full document when nothing is selected; click again to stop. Undo and Redo walk document HTML history; they are grayed out when there is nothing to undo or redo. The File, Edit, and Insert menu items use the same icons as the toolbar buttons where both exist. Link wraps the selection (or inserts the URL as the visible text at the caret) in an `<a href>` tag; an optional title becomes the native hover tooltip, and opening in a new tab sets `target="_blank"`. Bookmark inserts a named destination (`id`) at the caret or around the selection. Audio and YouTube video are available from the Insert menu only (no toolbar buttons). Horizontal line inserts an `<hr>` at the caret. Page break inserts a hard print break at the caret (Insert → Page break, or Ctrl/Cmd+Enter in visual mode). Content after the break starts on a new printed page. Serialized HTML uses inline `break-after: page` / `page-break-after: always` on a `<div>` — distinct from **Insert → Page**, which adds a new editor page when `enableMultiPages` is on.
 
 `menuColor`, `menuBackground`, `menuFontSize`, and `menuFontFamily` restyle the dropdown menu bar and panels only — not the icon toolbar. `border` is the outer editor box and is ignored in fullscreen. Custom menu fonts must already be available on the page.
 
@@ -111,7 +116,7 @@ import { Editor } from 'commspliant-html-editor'
 
 ### Page properties
 
-Edit → Page → **Page properties** opens a dialog with **Font**, **Paragraph**, and **Print** tabs. Paragraph sub-tabs include **Spacing**, **Border**, **Background** (fill color and page opacity), and **Background Image**. The **Print** tab edits `@page` size, orientation, and margins.
+Edit → Page → **Page properties** opens a dialog with **Font**, **Paragraph**, and **Print** tabs. Paragraph sub-tabs include **Spacing**, **Border**, **Background** (fill color and page opacity), and **Background Image**. The **Print** tab edits `@page` size, orientation, and margins. In visual mode, the white editing surface previews that page size and print margins on screen (display-only; serialized HTML is unchanged). Use **View → Zoom** for screen-only fit and percentage zoom; zoom is not stored in the document.
 
 The first time page properties are applied, content is wrapped in a single `<div data-page>` shell with `width: 100%` and `height: 100%`. Background **color** is written on that shell. Background **image** uses the same file, URL, or custom picker as Insert → Image, plus independent width and height (default width `100%`, height unset), and opacity, fit, and position controls (the same options as Image properties → Advanced). Rotation is not supported for page backgrounds. Width and height write `background-size`; keyword fit values (`cover`, `contain`) replace those dimensions.
 
@@ -347,7 +352,7 @@ let stored: CustomParagraphStyle[] = []
 | `id` | `string` | Stable id. The dialog assigns one on create |
 | `name` | `string` | Visible name. Always trimmed and non-empty on save |
 | `font` | `CustomParagraphStyleFont` | Size, unit, marks, family, and colors captured by the dialog |
-| `paragraph` | `CustomParagraphStyleParagraph` | Optional paragraph box: align, list, margin, padding, line-height, border, radius, shadow, background, opacity |
+| `paragraph` | `CustomParagraphStyleParagraph` | Optional paragraph box: align, list, margin, padding, line-height, border, radius, shadow, background, opacity, and page-break (`breakInside`, `breakAfter`, `breakBefore`) |
 
 Omit all three props to keep only the built-in styles.
 
@@ -450,6 +455,54 @@ export function MultiPageEditor() {
 }
 ```
 
+### Page break
+
+In visual mode, use **Insert → Page break** or **Ctrl/Cmd+Enter** to insert a hard print break at the caret. The editor shows a dashed line; serialized HTML is a `<div>` with inline `break-after: page` and `page-break-after: always`. Content after the break starts on a new page when printing.
+
+This is not the same as **Insert → Page** (multi-page mode), which adds a separate editor page surface.
+
+### Comments
+
+Set `enableComments` to add lightweight comment threads anchored in the document with `data-comment-thread` markers. Thread metadata (`CommentThread[]`) is separate from document HTML — use `comments` / `onCommentsChange` to persist it.
+
+- **Add comment** (toolbar Insert group and Insert → Comment) wraps the selection or marks the selected image, then opens the comment panel.
+- **Show/Hide comments** (View menu and View icon group) toggles highlight styling only; thread data and anchors remain.
+- **`commentAuthor`** (`{ userId, userName }`) is required to enable Post in the panel.
+
+**Sanitized HTML:** export `stripCommentAnchors` from the package to remove comment-only spans and attributes for published document HTML:
+
+```tsx
+import { Editor, stripCommentAnchors } from 'commspliant-html-editor'
+
+// Editor HTML may include anchors:
+// <p>Price was <span data-comment-thread="cmt_…">£150</span> last week.</p>
+
+const clean = stripCommentAnchors(html)
+// <p>Price was £150 last week.</p>
+```
+
+**Read-only documents:** with `readOnly` and `enableComments`, users can still add and reply to comments. Anchor DOM updates fire `onCommentsChange` only — not `onChange`. Supply `value` and `comments` on load; the editor re-applies anchors for highlights.
+
+```tsx
+import { useState } from 'react'
+import { Editor, type CommentThread } from 'commspliant-html-editor'
+
+export function ReviewEditor() {
+  const [comments, setComments] = useState<CommentThread[]>([])
+
+  return (
+    <Editor
+      value="<p>Immutable version</p>"
+      readOnly
+      enableComments
+      commentAuthor={{ userId: 'u1', userName: 'Reviewer' }}
+      comments={comments}
+      onCommentsChange={setComments}
+    />
+  )
+}
+```
+
 ### Custom actions
 
 Pass a `customActions` array to add host buttons, menu items, or both. Labels and tooltips are your copy — the library does not translate them.

package/dist/404.html

@@ -0,0 +1,19 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>HTML editor Playground</title>
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link
+      href="https://fonts.googleapis.com/css2?family=Source+Serif+4:ital,opsz,wght@0,8..60,400;0,8..60,500;0,8..60,600;0,8..60,700;1,8..60,400&family=Inter:ital,wght@0,400;0,500;0,600;0,700;1,400&display=swap"
+      rel="stylesheet"
+    />
+    <script type="module" crossorigin src="/assets/index-8mpvnzOy.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-Cu8klpl0.css">
+  </head>
+  <body>
+    <div id="root"></div>
+  </body>
+</html>