A rich text editor that’s also a form field. The form gets its content as
HTML, under the element’s name attribute.
orb-rich-text implementation plan
The phased plan for growing orb-rich-text into a full document editor. It replaces the original feature list (features.md); the table below maps each listed feature to the section that covers it.
Feature map
| Feature (from the original list) | Section |
|---|---|
| Better keyboard features | 1.1 |
| Block quotes | 1.3 |
| Separators | 1.4 |
| Code | 1.5 |
| Indent level | 1.6 |
| Line height | 1.7 |
| Advanced list functionality | 1.8 |
| Font color, family, size, background | 2.1 |
| Auto formatting GitHub-flavored Markdown | 2.2 |
| Special characters and emojis | 2.3 |
| Tables | 3.1 |
| Media | 3.2 |
| Document outline / TOC | 3.3 |
| Inline commands / actions / tags | 4.1 |
| Parameters / placeholders | 4.2 |
| Templates | 4.3 |
| Full screen with menubar | 5.1 |
| Interface modes | 5.2 |
| Pages, page breaks, margins, header, footer | 5.3 (print only) |
| Mainstream import & export options | 5.4 |
| Change tracking → versions and saving | 6.1–6.3 |
| Comments and other collab features | 7.1–7.2 |
| Writing assistants | Shelved. Only the spellcheck prop (0.5) is in scope. |
Not on the original list but included: making the editor a form field (0.9).
Decisions
| Decision | Choice |
|---|---|
| Editing engine | Keep the hand-rolled engine (editing.ts), where the live HTML is the document. No ProseMirror or similar. |
| Storage format | Canonical HTML is the lossless format. Every other format (Markdown, DOCX, text, JSON) is import/export only and may lose information. JSON is derived, never the source of truth. |
| Visual formatting | Inline styles for anything visual (alignment, indent, line height, colors, fonts), so saved HTML looks right outside the editor. data-* attributes only for meaning the editor alone uses (mentions, placeholders, comments, suggestions, page settings). |
| Block-type controls | A “Text style” select (Paragraph, Heading 1–6). Quote and Code block are their own toolbar toggles, so the select only holds text styles. |
orb-popover / orb-menu |
May be modified as needed (0.7). |
| Task lists | <input type="checkbox"> inside the list item. |
| Outline and comments sidebar | Built into the editor, behind props. |
| New dependencies | prismjs, emojibase-data, mammoth, docx, diff (jsdiff). Dev dependencies, loaded on first use with import(), like markdown-it in orb-markdown. |
| Pages | Print only. No on-screen page layout. Page size, margins, header and footer apply when printing (@page) and in DOCX export. |
| Full screen | Popover API (popover="manual" on a wrapper inside the shadow root). No Fullscreen API, no CSS fallback. |
| Real-time collaboration | Out of scope. “Collab” means comments and suggested changes. |
| Server-side features | None. The component exposes props, events and function hooks; storage and uploads are the app’s job. |
| Undo history across refresh | Opt-in. Requires history-key and persist-history. |
| Table cells | Hold text directly, like list items (line breaks with <br>). No lists or several paragraphs in a cell in v1. |
| Images and video | Always block-level <figure>, with an optional <figcaption>. |
| Header and footer | Plain text in left, center and right positions, with {page}, {pages}, {title} and {date} placeholders. |
| Modes | edit, suggest, comment, view, preview. |
| Lossy export (Markdown, text) | Suggestions are left out by default (suggestions: "reject"). HTML keeps everything. |
| Pasted fonts | Fonts not in the fonts prop are dropped when pasting. |
| Inline code shortcut | None. The backtick auto-format rule (2.2) covers it. There’s no toolbar button for inline code. |
| Form field | Yes, in Phase 0 (0.9). |
Conventions
- Stencil + shadow DOM,
orb-tags andorbSomethingevents with typed details. Every prop, event, method,@slotand@partgets a JSDoc comment, because those feeddocs-jsonand the custom-elements manifest. CSS custom properties are documented at the top of the.cssfile. - Async hooks are function props, following
init/destroyonorb-overlayandorb-popover:upload,loadVersion,save,mentions,tags. - Interception uses cancelable events, following
orbHideRequestandorbSearch. - Arrays and objects are set as JS properties, like
filesonorb-file-input. Simple settings stay usable as HTML attributes. - Build the UI from existing Orb components:
orb-button/-group,orb-tooltip,orb-menu/orb-mi,orb-popover,orb-overlay,orb-menubar,orb-split-view/-panel,orb-textbox,orb-card,orb-relative-time. Positioning uses@floating-ui/dom; dragging and resizing useinteractjs. - Icons specific to the editor stay in
rich-text/icons.tsx, in Lucide style. - Custom states go through
ElementInternalsandtoggleState(:state(dirty),:state(user-invalid)). - Tests are Playwright specs using
mount()fromtests/utils.ts, run in Chromium, Firefox and WebKit. - Comments follow the codebase’s style: short, plain sentences that explain why.
Phases at a glance
| Phase | Contents | Estimate (1 developer) |
|---|---|---|
| 0. Groundwork | Module split, schema, cleanup step, command list, toolbar, spellcheck, undo rework, non-editable pieces and caret popups, link popover, form field, test helpers |
4.5–6.5w |
| 1. Input and blocks | Keyboard handling, text style select and h1–h6, quotes, separators, code, indent, line height, lists and task lists | 4–6w |
| 2. Inline styling and typing shortcuts | Fonts and colors, GFM auto-formatting and Markdown paste, special characters and emoji | 2.5–3.5w |
| 3. Structured content | Tables, media, outline and TOC | 5–8w |
| 4. Inline objects | / commands, mentions, tags, emoji shortcodes, placeholders, templates |
2.5–3.5w |
| 5. Document chrome and formats | Full screen and menubar, modes, print, page setup, page breaks, import and export | 4–6w |
| 6. Saving and history | Save and unsaved state, versions and compare, undo history across refresh | 2–3.5w |
| 7. Collaboration | Comments, suggested changes | 4–6.5w |
Total: about 28.5–43.5 weeks (7–10 months). Each phase ends with its tests and an update to rich-text.md, in the same format as menubar.md: usage, live demo, manual test steps, keyboard table, accessibility checklist.
Phase 0: Groundwork
0.1 Module layout
src/components/rich-text/
rich-text.tsx component: props, events, methods, layout
rich-text.css component chrome (toolbar, panels, sidebar)
content.css content styles; also injected into the print iframe
icons.tsx
editing/
host.ts the EditorHost interface
selection.ts getRange, selectRange, keep/restore, points, caretAnchor
schema.ts node definitions (0.2)
sanitize.ts parsing, the paste cleanup
normalize.ts canonical form (0.3)
dom.ts shared helpers: closestIn, splitAround, wrapEach, hasContent…
inline.ts marks, styles, links
blocks.ts block types, quotes, separators, block styles, split/join
lists.ts tables.ts media.ts code.ts outline.ts
input.ts beforeinput/keydown behaviors (1.1)
rules.ts auto-formatting rules (2.2)
triggers.ts / @ # : {{ sessions (4.1)
annotations.ts comments and suggestions (Phase 7)
history.ts undo (0.6)
history-store.ts IndexedDB storage (6.3)
commands.ts the command list (0.4)
ui/
toolbar.tsx toolbar controls (JSX function components)
pickers.tsx color, emoji, special-character, table-size pickers
special-characters.ts curated character list
sidebar.tsx comment and suggestion cards
convert/ loaded on first use with import()
markdown.ts docx.ts json.ts diff.ts print.ts
src/utils/
form.ts browserMessage, exposeFormProps (0.9), shared with orb-mask-input
files.ts isAccepted, moved from orb-file-input (3.2)
ids.ts uid() (6.3)
rich-text.tsx keeps the Stencil-facing parts. Larger features live in small controller classes that receive an EditorHost, so the component doesn’t grow into thousands of lines:
// editing/host.ts
export interface EditorHost {
readonly root: HTMLElement; // the contenteditable
readonly el: HTMLElement; // <orb-rich-text>
readonly editable: boolean;
/** The selection to edit: the live one, the last one, or the end */
takeRange(): Range;
/** Runs an edit as one undo step and selects its result. Returns false if nothing changed. */
apply(edit: (range: Range) => Range | null, options?: { record?: boolean; inputType?: string }): boolean;
/** Re-renders the component, for controllers that keep their own state */
update(): void; // forceUpdate(this) from @stencil/core
}
apply is today’s executeCommand body made reusable:
apply(edit: (range: Range) => Range | null, { record = true, inputType = "insertReplacementText" } = {}) {
if (!this.editable) return false;
const range = this.takeRange();
if (this.el.shadowRoot?.activeElement !== this.editorRef) {
this.editorRef.focus({ preventScroll: true });
selectRange(range);
}
this.saveTyping();
const result = edit(range);
if (!result) return false;
const fixed = normalizeAround(this.editorRef, result, this.schema);
selectRange(fixed, { redraw: true });
// Again after the next layout, in case Safari measured the caret before
// the change was laid out.
requestAnimationFrame(() => {
const current = getRange(this.editorRef);
if (current) selectRange(current, { redraw: true });
});
this.afterChange(record);
this.dispatchInput(inputType); // 0.9
return true;
}
0.2 Schema (editing/schema.ts)
One table replaces INLINE_TAGS, FORMATTING_TAGS, BLOCK_TAGS, TEXT_BLOCKS and ALLOWED_TAGS. This also fixes HR and TABLE being in BLOCK_TAGS but dropped on paste.
export type StyleProp =
| "text-align" | "margin-inline-start" | "line-height"
| "color" | "background-color" | "font-family" | "font-size"
| "list-style-type" | "width";
export type NodeKind =
| "mark" // strong, em, u, s, code, a, sub, sup
| "style" // span with inline styles
| "annotation" // comment anchors, suggestions. Survive Clear formatting.
| "text-block" // p, h1–h6, li, td, th, pre, figcaption
| "container" // ul, ol, blockquote, table, thead, tbody, tr
| "atom-inline" // br, mentions, tags, params, task checkboxes
| "atom-block"; // hr, page break, figure, TOC, page settings
export interface NodeSpec {
name: string;
tag: string;
kind: NodeKind;
/** Tells apart specs that share a tag, like a suggestion <ins> and a plain one */
match?: (el: Element) => boolean;
/** Tags converted to this one, such as B to STRONG */
aliases?: string[];
/** Attributes kept, each with a check that returns the cleaned value or null to drop it */
attrs?: Record<string, (value: string, options: SchemaOptions) => string | null>;
styles?: StyleProp[];
/** Tags it may be directly inside. Normalize fixes anything else. */
parents?: string[];
}
export interface SchemaOptions {
fonts: FontOption[];
embedProviders: EmbedProvider[];
}
const BLOCK_STYLES: StyleProp[] = ["text-align", "margin-inline-start", "line-height"];
const has = (attr: string) => (el: Element) => el.hasAttribute(attr);
const not = (test: (el: Element) => boolean) => (el: Element) => !test(el);
export const NODES: NodeSpec[] = [
{ name: "paragraph", tag: "P", kind: "text-block", aliases: ["DIV"], styles: BLOCK_STYLES },
...[1, 2, 3, 4, 5, 6].map((n): NodeSpec => ({
name: `heading${n}`, tag: `H${n}`, kind: "text-block", styles: BLOCK_STYLES, attrs: { id: slugId },
})),
{ name: "bold", tag: "STRONG", kind: "mark", aliases: ["B"] },
{ name: "italic", tag: "EM", kind: "mark", aliases: ["I"] },
{ name: "underline", tag: "U", kind: "mark", aliases: ["INS"], match: not(has("data-suggestion")) },
{ name: "strike", tag: "S", kind: "mark", aliases: ["STRIKE", "DEL"], match: not(has("data-suggestion")) },
{ name: "insertion", tag: "INS", kind: "annotation", match: has("data-suggestion"), attrs: SUGGESTION_ATTRS },
{ name: "deletion", tag: "DEL", kind: "annotation", match: has("data-suggestion"), attrs: SUGGESTION_ATTRS },
{ name: "link", tag: "A", kind: "mark", attrs: { href: safeHref } },
{ name: "comment", tag: "SPAN", kind: "annotation", match: has("data-comment"), attrs: { "data-comment": idList } },
{ name: "mention", tag: "SPAN", kind: "atom-inline", match: has("data-mention"), attrs: { "data-mention": id } },
{ name: "style", tag: "SPAN", kind: "style", styles: ["color", "background-color", "font-family", "font-size"] },
{
name: "checkbox", tag: "INPUT", kind: "atom-inline", parents: ["LI"],
match: (el) => el.getAttribute("type") === "checkbox",
attrs: { type: () => "checkbox", checked: () => "" },
},
{ name: "separator", tag: "HR", kind: "atom-block", match: not(has("data-page-break")) },
{ name: "pageBreak", tag: "HR", kind: "atom-block", match: has("data-page-break"), attrs: { "data-page-break": () => "" } },
// …lists, quotes, code, tables, figures, TOC, page settings (added in their phases)
];
/** The spec for an element, or undefined if it isn't allowed */
export function specOf(el: Element): NodeSpec | undefined { /* first tag/alias + match */ }
const tagsOf = (kind: NodeKind) => NODES.filter((n) => n.kind === kind).map((n) => n.tag);
export const TEXT_BLOCK_TAGS = tagsOf("text-block");
export const TEXT_BLOCK_SELECTOR = TEXT_BLOCK_TAGS.map((t) => t.toLowerCase()).join(", ");
Each style property has a check on its value:
const color = (v: string) => (CSS.supports("color", v) && !/var\(|url\(/i.test(v) ? v : null);
export const STYLE_CHECKS: Record<StyleProp, (value: string, o: SchemaOptions) => string | null> = {
"text-align": (v) => (["center", "right", "justify"].includes(v) ? v : null),
"margin-inline-start": indentStep, // rounds to 2em steps, 1–8 levels
"line-height": (v) => (/^\d(\.\d+)?$/.test(v) && +v >= 1 && +v <= 3 ? v : null),
color,
"background-color": color,
"font-family": (v, o) => o.fonts.find((f) => sameFamily(f.value, v))?.value ?? null,
"font-size": toPoints, // px → pt (×0.75), clamped to 6–96pt
"list-style-type": (v) => (LIST_STYLES.includes(v) ? v : null),
width: (v) => (/^\d{1,3}(\.\d+)?%$/.test(v) ? v : null),
};
0.3 Sanitize and normalize
sanitize.ts keeps today’s inert DOMParser approach and changes these things:
- Paste cleanup before checking against the schema:
- unwrap Google Docs’
b[id^="docs-internal-guid"]wrapper, which today turns whole pastes bold; - remove Word’s
o:pelements andmso-*styles; - rebuild Word’s paragraph-based lists into real lists (5.4).
- unwrap Google Docs’
- Convert style-based formatting to tags:
font-weight >= 600becomesstrong,italicbecomesem,underlinebecomesu,line-throughbecomess. Today Google Docs bold is lost because all styles are stripped. - Check every element against the schema: keep allowed attributes and styles, rename aliases, unwrap anything unknown.
- Collapse whitespace in text outside
pre(\s+becomes a single space), since the editor will usewhite-space: pre-wrap. sanitize(html, options, { paste }): comment anchors and suggestion markers are removed when pasting.value,setContent(), imports and templates go through it as well. TodayvalueandsetContentinsert unsanitized HTML, which is an XSS risk. Thevaluewatcher is added in 0.9.
normalize.ts brings content to its one canonical form:
export interface NormalizeOptions extends SchemaOptions {
/** Output only: canonical nesting of formats, and runtime-only attributes removed */
output?: boolean;
}
export function normalize(root: ParentNode, options: NormalizeOptions) {
renameAliases(root); // B→STRONG, DIV→P, plain INS→U, plain DEL→S
fixStructure(root); // loose text → P, LI outside a list → UL, blocks out of P, cells text-only
ensureEditableAround(root); // a P after a trailing hr, table or figure, so the caret can get there
fillEmptyBlocks(root); // an empty block holds a <br>
dropEmptyInline(root);
mergeAdjacentInline(root); // <strong>a</strong><strong>b</strong> → <strong>ab</strong>
if (options.output) {
root.querySelectorAll<HTMLElement>(TEXT_BLOCK_SELECTOR).forEach(rebuildInline);
stripRuntime(root); // contenteditable, tabindex, data-selected, data-uploading, trailing hack <br>s
}
}
rebuildInline is what makes output canonical. It flattens a block into pieces of text, each with its set of formats, then rebuilds them in a fixed nesting order. <em><strong>x</strong></em> and <strong><em>x</em></strong> therefore produce the same output.
/** Outermost first */
const MARK_ORDER = ["comment", "insertion", "deletion", "link", "bold", "italic", "underline", "strike", "code", "sub", "sup", "style"];
interface Segment { node: Node; marks: Element[] } // text, <br>, or a non-editable piece, plus shallow copies of its formats
function rebuildInline(block: HTMLElement) {
const segments = flatten(block); // walk, pushing shallow clones of mark elements
block.replaceChildren();
const open: Element[] = [];
for (const { node, marks } of segments) {
const wanted = canonicalMarks(marks); // sorted by MARK_ORDER; style spans merged into one
let keep = 0;
while (keep < open.length && keep < wanted.length && open[keep].cloneNode(false).isEqualNode(wanted[keep])) keep++;
open.length = keep;
let parent: Node = open[keep - 1] ?? block;
for (const mark of wanted.slice(keep)) {
const el = mark.cloneNode(false) as Element;
parent.appendChild(el);
open.push(el);
parent = el;
}
appendMergingText(parent, node);
}
}
When cleanup runs:
- On load,
setContent, paste and import: the fullnormalizeon the content. - After each command:
normalizeAround(root, range)cleans only the blocks the command touched, and keeps the selection in place withkeep/restore. - For output:
getContent, events, the form value, saving, versions and history hashes runnormalize(clone, { output: true })on a copy, cached until the next change. Cleanup never runs on the live content during typing, so the caret never jumps.
orbEditorChange computes its HTML only when read. The cleanup of the copy then runs only for listeners that actually use it:
private emitChange() {
const read = () => this.output();
this.orbEditorChange.emit({
get html() { return read().html; },
get text() { return read().text; },
get isEmpty() { return !read().text.trim(); },
});
}
CSS: add white-space: pre-wrap to .editor-content. Browsers then insert normal spaces instead of , which keeps the output canonical.
0.4 Command list and toolbar
// editing/commands.ts
export interface CommandContext {
host: EditorHost;
root: HTMLElement;
range: Range;
}
export interface Shortcut {
/** A letter, a digit, or a code such as "BracketRight", always with Ctrl or ⌘ */
key: string;
shift?: boolean;
alt?: boolean;
}
export interface Command {
id: string;
label: string;
icon?: (props?: any) => any;
shortcuts?: Shortcut[];
control?: "button" | "toggle" | "select" | "color" | "picker";
/** Options for select controls */
options?: (host: EditorHost) => { value: string; label: string; icon?: (p?: any) => any }[];
/** Pressed state, or the current value. "mixed" when the selection has several. */
state?: (ctx: CommandContext) => boolean | string | null;
enabled?: (ctx: CommandContext) => boolean;
/** Listed in the "/" menu, with extra search words */
slash?: { keywords?: string[] };
/** The `inputType` of the `input` event the command fires (0.9). Defaults to insertReplacementText. */
inputType?: string;
/** Changes content and returns the range to select. UI-only commands return nothing. */
run: (ctx: CommandContext, value?: string) => Range | null | void;
}
export const COMMANDS = new Map<string, Command>();
export const define = (command: Command) => COMMANDS.set(command.id, command);
define({
id: "bold", label: "Bold", icon: BoldIcon, control: "toggle",
shortcuts: [{ key: "b" }],
inputType: "formatBold",
state: ({ root, range }) => isMarkActive(root, range, "strong"),
run: ({ root, range }) => toggleMark(root, range, "strong"),
});
This replaces toolbarGroups, the *_COMMANDS maps, the if-chain in executeCommand, the switch in handleKeyDown, and updatePressed.
Matching shortcuts. Digits, punctuation and anything with Alt match on event.code, because Alt or Shift changes event.key (⌥1 is ¡ on a Mac). Plain letters match on event.key, so they follow the keyboard layout.
export function matches(ev: KeyboardEvent, s: Shortcut) {
const mod = IS_APPLE ? ev.metaKey && !ev.ctrlKey : ev.ctrlKey && !ev.metaKey;
if (!mod || ev.shiftKey !== !!s.shift || ev.altKey !== !!s.alt) return false;
if (/^[a-z]$/i.test(s.key) && !s.alt) return ev.key.toLowerCase() === s.key.toLowerCase();
return ev.code === (/^\d$/.test(s.key) ? `Digit${s.key}` : /^[a-z]$/i.test(s.key) ? `Key${s.key.toUpperCase()}` : s.key);
}
Toolbar prop. It’s a string, so it also works as an HTML attribute:
/**
* The toolbar's controls, in order. `|` separates groups. Commands not
* listed are still available from shortcuts, the menubar and the `/` menu.
*/
@Prop() toolbar =
"undo redo | blockType | quote code | bold italic underline strike | fontFamily fontSize color background | " +
"bulletList orderedList taskList outdent indent | align lineHeight | link media table separator specialCharacter | clearFormatting";
const parseToolbar = (spec: string) =>
spec.split("|").map((group) => group.trim().split(/\s+/).filter((id) => COMMANDS.has(id))).filter((g) => g.length);
Toolbar controls (ui/toolbar.tsx). Toggle and action buttons look as they do today. A dropdown is an orb-button with caret, plus an orb-menu in single mode:
export const SelectControl = ({ command, value, disabled, onChoose }: SelectProps) => [
<orb-button id={`action-${command.id}`} fill="outline" size="sm" caret disabled={disabled}
aria-label={command.label} class="select">
{labelFor(command, value)}
</orb-button>,
<orb-menu for={`action-${command.id}`} mode="single" label={command.label}
onOrbSelect={(ev) => onChoose(command, ev.detail.value)}>
{command.options!(host).map((option) => (
<orb-mi value={option.value} checked={option.value === value}>{option.label}</orb-mi>
))}
</orb-menu>,
];
One Tab stop for the toolbar (role="toolbar"), with arrow keys between controls. The approach matches orb-menubar. One catch: orb-button resets tabIndex whenever its disabled prop changes, so the editor re-applies the roving tab index in componentDidRender.
private syncToolbarFocus() {
const items = this.toolbarItems(); // orb-button hosts, in order
const current = items.find((i) => i.tabIndex === 0 && !i.disabled) ?? items.find((i) => !i.disabled);
items.forEach((i) => (i.tabIndex = i === current ? 0 : -1));
}
// keydown on the toolbar: Left/Right (swapped in RTL), Home, End move focus and the Tab stop
Overflow menu. A ResizeObserver on the toolbar measures each group’s width, caching it the first time. Groups that don’t fit move into a More orb-menu:
- toggle buttons become
orb-mi type="checkbox"; - dropdowns become submenus.
updatePressed becomes updateStates(). It runs state() for every command in the toolbar and stores the results in @State() states: Record<string, boolean | string | null>, re-rendering only when something changed (as today).
0.5 spellcheck prop
/** Underlines misspelled words, using the browser's spell checker */
@Prop() spellcheck = true;
// <div contenteditable … spellcheck={this.spellcheck ? "true" : "false"}>
This overrides the built-in HTMLElement.spellcheck property. On the first build, check that Stencil doesn’t warn about a reserved name. If it does, use check-spelling.
0.6 Undo history rework (editing/history.ts)
Store only the changes. Each step saves the changed slice of HTML; the full HTML is kept once. Images aren’t copied into every step, because a step only contains its own changed slice.
interface Change { at: number; removed: string; added: string }
interface Step { change: Change; before: Selected | null; after: Selected | null }
function diff(a: string, b: string): Change {
let start = 0;
const max = Math.min(a.length, b.length);
while (start < max && a.charCodeAt(start) === b.charCodeAt(start)) start++;
let endA = a.length, endB = b.length;
while (endA > start && endB > start && a.charCodeAt(endA - 1) === b.charCodeAt(endB - 1)) { endA--; endB--; }
return { at: start, removed: a.slice(start, endA), added: b.slice(start, endB) };
}
const revert = (html: string, c: Change) => html.slice(0, c.at) + c.removed + html.slice(c.at + c.added.length);
const reapply = (html: string, c: Change) => html.slice(0, c.at) + c.added + html.slice(c.at + c.removed.length);
export class History {
private html = "";
private done: Step[] = [];
private undone: Step[] = [];
private selected: Selected | null = null;
/** Called with each new step, for saving history across a refresh */
onRecord?: (step: Step, html: string) => void;
constructor(private root: HTMLElement, private limit = 200) {}
reset() { /* html = root.innerHTML, clear both stacks */ }
record() {
const html = this.root.innerHTML;
const selected = takeSelected(this.root);
if (html === this.html) { this.selected = selected; return; }
const step = { change: diff(this.html, html), before: this.selected, after: selected };
this.done.push(step);
if (this.done.length > this.limit) this.done.shift();
this.undone = [];
this.html = html;
this.selected = selected;
this.onRecord?.(step, html);
}
undo() {
const step = this.done.pop();
if (!step) return false;
this.html = revert(this.html, step.change);
this.undone.push(step);
this.show(step.before);
return true;
}
redo() { /* mirror of undo, using reapply and step.after */ }
}
Saving the selection. A plain path of child indexes breaks: the live content often has split text nodes (from splitText), which come back merged after saving and reloading the HTML. Counting characters (today’s approach) fails wherever there’s no text, such as empty cells and non-editable pieces. So a point is stored as a path where each run of adjacent text nodes counts as one child, plus an offset within that run:
export interface Point { path: number[]; offset: number }
export interface Selected { anchor: Point; focus: Point }
/** Children with empty text skipped and adjacent text grouped, the way they'll parse back */
function runs(parent: Node): Node[][] {
const result: Node[][] = [];
for (const child of Array.from(parent.childNodes)) {
if (child.nodeType === Node.TEXT_NODE && !(child as Text).length) continue;
const last = result[result.length - 1];
if (child.nodeType === Node.TEXT_NODE && last?.[0].nodeType === Node.TEXT_NODE) last.push(child);
else result.push([child]);
}
return result;
}
export function toPoint(root: Node, node: Node, offset: number): Point {
const path: number[] = [];
if (node.nodeType === Node.TEXT_NODE) {
const siblings = runs(node.parentNode!);
const index = siblings.findIndex((run) => run.includes(node));
const run = siblings[index] ?? [];
for (const text of run) { if (text === node) break; offset += (text as Text).length; }
path.push(index);
node = node.parentNode!;
} else {
const children = Array.from(node.childNodes);
offset = runs(node).filter((run) => children.indexOf(run[0] as ChildNode) < offset).length;
}
for (let n = node; n !== root; n = n.parentNode!) {
path.unshift(runs(n.parentNode!).findIndex((run) => run[0] === n));
}
return { path, offset };
}
// fromPoint walks the same runs back down; a text run resolves to (textNode, offset within it)
utils/composed.ts selectionOffsets stays as it is for other components. The rich-text History no longer uses character counts.
0.7 Non-editable pieces and caret popups
Non-editable pieces (kind: "atom-*") are used by mentions, tags, placeholders, the TOC, figures and task checkboxes:
- Load: cleanup adds
contenteditable="false"; it’s removed from output. - Caret fixes in
onSelectionChange:- a caret inside a piece moves after it;
- a caret before a task checkbox moves after it;
- an inline piece at the end of a block gets a runtime-only
<br data-orb-trailing>after it, so Safari can place the caret there. Removed from output.
- Deleting: Backspace or Delete next to a piece removes the whole piece (handled in 1.1).
- Clicking a piece selects all of it and sets
data-selected(runtime only) for styling. Delete then removes it.
orb-popover changes. show(event) already opens at a point and moves the popover when called again. For popups that follow the caret, it needs a wider anchor type:
export type Anchor =
| Pick<MouseEvent, "clientX" | "clientY">
| { getBoundingClientRect(): DOMRect; contextElement?: Element };
/**
* Opens the popover. Pass a pointer event, or anything with
* `getBoundingClientRect`, such as a Range, to open it there. Calling it
* again while open moves it.
*/
@Method()
async show(at?: Anchor) {
this.anchor = !at ? undefined
: "getBoundingClientRect" in at ? at
: { getBoundingClientRect: () => new DOMRect(at.clientX, at.clientY) };
if (!this.open) { this.open = true; return; }
this.startPositioning();
}
private get referenceEl() {
return this.anchor ?? this.triggerEl ?? { getBoundingClientRect: () => new DOMRect(0, 0) };
}
Two more changes to orb-popover:
- Without
for, it doesn’t log a warning. While open, it closes on an outsidepointerdownor on Escape (the same listeners as click mode, registered inhandleOpenChange). - A Range anchor passes
contextElement: editorRef, so Floating UI’sautoUpdatewatches the editor’s scroll position and the popup follows the caret instead of drifting.
orb-menu changes:
show(at?: Anchor)gets the same wider anchor type.attachInput(el: HTMLElement | null)lets another element drive the menu while keeping focus. It reuses the search field’s existing logic (setActiveandonSearchKeyDown):- Up and Down move the highlight, Enter chooses, and Escape closes (that already works through the menu’s document-level key listener);
- it sets
el.ariaActiveDescendantElement,ariaExpandedandariaControlsElements = [this.el]; - while an input is attached, the items use listbox roles (
orb-mialready has alistboxprop), as the ARIA combobox pattern requires; show()never moves focus while an input is attached. Today it moves focus into the menu when the user is on the keyboard.
Caret position helper. A collapsed range in an empty block can report an all-zero rectangle, so it falls back to the block’s position:
export function caretAnchor(range: Range, root: HTMLElement) {
return {
contextElement: root,
getBoundingClientRect() {
const rect = range.getClientRects()[0] ?? range.getBoundingClientRect();
if (rect.width || rect.height) return rect;
const block = closestBlock(range.startContainer, root) ?? root;
const b = block.getBoundingClientRect();
return new DOMRect(b.left, b.top, 0, b.height);
},
};
}
0.8 Link popover
This replaces prompt() and alert():
Mod+Kor the toolbar opens anorb-popoverat the selection.- It contains an
orb-textboxwith a URL input (validated withisSafeUrl, error shown throughsetCustomValidity), Apply, Remove and Open. - Placing the caret inside a link shows a small popover with the URL, Edit, Remove and Open. That finally uses the
selectedLinkstate. - With nothing selected, you can enter the link text in the popover too.
0.9 Form field
This follows orb-mask-input, the existing contenteditable form field, built on the same form APIs as orb-checkbox and orb-file-input.
Shared helpers (utils/form.ts)
Two pieces of orb-mask-input move into a shared file so both components use them. orb-mask-input switches to the shared versions; its behavior doesn’t change.
// utils/form.ts
/**
* Browsers word their built-in messages in the user's language, so the
* messages come from a probe input rather than from strings here.
*/
export function browserMessage(configure: (input: HTMLInputElement) => void): string {
const probe = document.createElement("input");
configure(probe);
return probe.validationMessage;
}
/**
* Form-associated elements don't get these from the platform, but forms
* and `orb-textbox` read them from the element.
*/
export function exposeFormProps(el: HTMLElement, internals: ElementInternals, extra: PropertyDescriptorMap = {}) {
Object.defineProperties(el, {
form: { configurable: true, get: () => internals.form },
labels: { configurable: true, get: () => internals.labels },
validity: { configurable: true, get: () => internals.validity },
validationMessage: { configurable: true, get: () => internals.validationMessage },
willValidate: { configurable: true, get: () => internals.willValidate },
checkValidity: { configurable: true, value: () => internals.checkValidity() },
reportValidity: { configurable: true, value: () => internals.reportValidity() },
...extra,
});
}
Component changes
/**
* A rich text editor that's also a form field. The form gets its content as
* HTML, under the element's `name` attribute.
*
* @slot label - The label, instead of the `label` prop
* @slot note - The note, instead of the `note` prop
*
* @part shell - The bordered editor: menubar, toolbar, content and footer
*/
@Component({
tag: "orb-rich-text",
styleUrl: "rich-text.css",
shadow: { delegatesFocus: true },
formAssociated: true,
})
export class RichText extends ReadyController {
@AttachInternals() internals: ElementInternals;
/** Text above the editor */
@Prop() label?: string;
/** Informational message below the editor */
@Prop() note?: string;
/**
* The content, as HTML. It updates as the user edits: right after commands
* like Bold, and after each pause in typing. `getContent()` is always current.
*/
@Prop({ mutable: true }) value = "";
/** The content a form reset returns to. Defaults to the initial `value`. */
@Prop() defaultValue?: string;
/** Requires content before the form can be submitted */
@Prop({ reflect: true }) required = false;
/** Disables the editor. It isn't submitted with the form. */
@Prop({ reflect: true }) disabled = false;
/** Shows the content without allowing edits. Still focusable and submitted with the form. */
@Prop({ reflect: true }) readonly = false;
/** Set while a disabled `fieldset` contains the editor */
@State() formDisabled = false;
@State() userInvalid = false;
private interacted = false;
private customMessage = "";
/** The HTML last written to `value` and the form, so the watcher can tell it from outside changes */
private lastValue = "";
/** The HTML at the last `change` event */
private lastChangeValue = "";
private formListeners?: AbortController;
- No
nameprop. The browser reads the host’snameattribute itself, as withorb-mask-input. RichTextnow extendsReadyController, likecheckbox,file-inputandbutton. ItscomponentDidLoadmust callsuper.componentDidLoad().
Lifecycle and keeping the value in sync
componentWillLoad() {
this.defaultValue ??= this.value;
exposeFormProps(this.el, this.internals);
}
componentDidLoad() {
super.componentDidLoad();
// …existing setup (history, beforeinput listener)
this.replaceContent(this.value); // sanitized and normalized
this.lastChangeValue = this.value;
this.wireAria();
}
/**
* Writes the content to `value` and the form. Runs after commands, after a
* pause in typing, and when focus leaves the editor.
*/
private syncValue() {
const html = this.output().html;
if (html !== this.lastValue) {
this.lastValue = html;
this.value = html;
}
this.internals.setFormValue(html, html);
this.syncValidity();
}
@Watch("value")
onValueChange(value: string) {
// Values written by syncValue are already in the editor.
if (value === this.lastValue) return;
this.replaceContent(value);
}
- Where
syncValueruns:- in
afterChange, which covers commands, undo and redo; - in
saveTyping, so the form value updates at the same moment an undo step is saved for typing; - in the focus-out handler below;
- in
replaceContent.
- in
- Why typing waits for the pause. Each sync runs the full cleanup on a copy of the document, which is too costly on every keystroke for long documents.
- Validity doesn’t wait. The blank check is cheap, so
syncValidity()andsyncStates()also run on everyinput. Submitting straight after typing never sees a stalevalueMissing.
Validation and states
private get isDisabled() {
return this.disabled || this.formDisabled;
}
/** No text, and nothing like an image or table that counts as content */
private isBlank() {
return !this.editorRef.textContent?.trim() && !this.editorRef.querySelector("img, video, iframe, table");
}
private syncValidity() {
// Disabled and readonly fields are left out of constraint validation.
// Phase 5.2 adds the view, comment and preview modes here.
const barred = this.isDisabled || this.readonly;
const valueMissing = !barred && this.required && this.isBlank();
const customError = !barred && this.customMessage !== "";
if (valueMissing || customError) {
const message = customError ? this.customMessage : browserMessage((input) => (input.required = true));
this.internals.setValidity({ valueMissing, customError }, message, this.editorRef);
} else {
this.internals.setValidity({});
}
this.syncStates();
}
private syncStates() {
const { states, validity } = this.internals;
const invalid = !validity.valid;
toggleState(states, "blank", this.isBlank());
toggleState(states, "disabled", this.isDisabled);
toggleState(states, "readonly", this.readonly);
toggleState(states, "invalid", invalid);
toggleState(states, "user-invalid", this.interacted && invalid);
toggleState(states, "user-valid", this.interacted && !invalid);
this.userInvalid = this.interacted && invalid;
}
/** Sets a custom validation error. Pass an empty string to clear it. */
@Method()
async setCustomValidity(message: string) {
this.customMessage = message;
this.syncValidity();
}
/**
* Clears custom errors and the user interaction state, so validation styling
* is hidden until the user interacts with the editor again.
*/
@Method()
async resetValidity() {
this.customMessage = "";
this.interacted = false;
this.syncValidity();
}
@Listen("invalid")
onInvalid() {
this.interacted = true;
this.syncStates();
}
Validation scope: only required and custom validity. minlength and maxlength are left out: browsers only produce their messages after real typing in a native field, so a hidden probe input can’t get them, and the messages would have to be hardcoded in English. Apps can enforce lengths with setCustomValidity.
Form lifecycle callbacks
formAssociatedCallback(form: HTMLFormElement | null) {
this.formListeners?.abort();
if (!form) return;
this.formListeners = new AbortController();
const { signal } = this.formListeners;
// Typing reaches the form after a pause, so submitting during one would send older content.
form.addEventListener("submit", () => this.saveTyping(), { capture: true, signal });
// new FormData(form) doesn't fire submit, so the entry is corrected here instead.
form.addEventListener("formdata", (ev) => {
if (this.typingTimer === undefined) return;
this.saveTyping();
const name = this.el.getAttribute("name");
if (name && !this.isDisabled) ev.formData.set(name, this.value);
}, { signal });
}
formResetCallback() {
this.interacted = false;
this.replaceContent(this.defaultValue ?? ""); // fresh undo history, like setContent
this.lastChangeValue = this.value;
}
formStateRestoreCallback(state: string | File | FormData | null) {
if (typeof state === "string") this.ready.then(() => this.replaceContent(state));
}
formDisabledCallback(disabled: boolean) {
this.formDisabled = disabled;
this.syncValidity();
}
disconnectedCallback() {
// …existing cleanup
this.formListeners?.abort();
}
Caveat: formData.set replaces every entry with that name, so it would overwrite other fields sharing the editor’s name. This only happens with new FormData(form) during a typing pause. Document it.
input and change events
The events match a native field, like orb-mask-input. The content area’s own input event is stopped and replaced by one from the host, so commands like Bold fire input too, not just typing.
private dispatchInput(inputType: string, data: string | null = null) {
this.el.dispatchEvent(new InputEvent("input", { bubbles: true, composed: true, inputType, data }));
}
private handleInput = (ev: InputEvent) => {
ev.stopPropagation();
// …existing: word count, orbEditorChange, saveTypingLater
this.syncValidity();
this.dispatchInput(ev.inputType, ev.data);
};
-
Commands report a standard input type through
Command.inputType(0.4), using the standard names where they exist:formatBold,formatItalic,formatUnderline,formatStrikeThrough,formatJustifyCenter,formatIndent,formatFontColor,formatBackColor,formatFontName,insertOrderedList,insertUnorderedList,insertHorizontalRule,insertLink,formatRemove,historyUndoandhistoryRedo. Commands without one fall back toinsertReplacementText.apply()dispatches the event afterafterChange. -
changefires when focus leaves the whole component, not when it moves to the toolbar, a menu or a dialog inside the editor. When focus moves within the shadow root, the browser reportsrelatedTargetas the host, whichcomposedContainscounts as inside.@Listen("focusout") onFocusOut(ev: FocusEvent) { // Moving to the toolbar, a menu or a dialog in the editor isn't leaving it. if (composedContains(this.el, ev.relatedTarget as Node | null)) return; this.saveTyping(); this.interacted = true; this.syncValue(); if (this.value !== this.lastChangeValue) { this.lastChangeValue = this.value; this.el.dispatchEvent(new Event("change", { bubbles: true, composed: true })); } } -
orbEditorChange,orbEditorFocusandorbEditorBlurstay as they are.
Label, note, error message and accessibility
This follows file-input’s label and note slots and mask-input’s wireAria:
render() {
return (
<Host>
<slot name="label" ref={(el) => (this.labelSlot = el)} onSlotchange={() => this.wireAria()}>
{this.label && <orb-label required={this.required}>{this.label}</orb-label>}
</slot>
<div class="shell" part="shell" /* …rest from 5.1 */>
{/* …menubar, toolbar, content, footer */}
</div>
<slot name="note" ref={(el) => (this.noteSlot = el)} onSlotchange={() => this.wireAria()}>
{this.note && <orb-note>{this.note}</orb-note>}
</slot>
{this.userInvalid && (
<orb-note invalid ref={(el) => (this.errorEl = el)}>{this.internals.validationMessage}</orb-note>
)}
</Host>
);
}
/** The content area has focus, so it carries the label and descriptions */
private wireAria() {
if (!this.editorRef) return;
this.editorRef.ariaLabelledByElements = [
...(this.label || this.labelSlot?.assignedElements().length ? [this.labelSlot] : []),
...(Array.from(this.internals.labels) as Element[]),
];
this.editorRef.ariaDescribedByElements = [this.noteSlot, this.errorEl].filter(Boolean) as Element[];
}
- The content area gets
aria-required,aria-readonly,aria-disabledandaria-invalid(fromuserInvalid), andtabindex={this.isDisabled ? -1 : 0}. label,noteand the error message sit outside.shell, so the border wraps only the editor, as inorb-textbox.- Clicking an outside
<label for="…">focuses the host, anddelegatesFocuspasses focus to the content. - Host
aria-labelandaria-descriptionare copied to the content area by the same attribute observermask-inputuses. - The hardcoded
aria-label="Rich text editor"is now only a fallback, used when nothing else names the editor.
CSS
/**
* @prop --editor-invalid-color: Border color after a failed validation
*/
:host(:state(user-invalid)) .shell {
border-color: var(--editor-invalid-color, /* the danger color orb-textbox uses for .error */);
}
:host(:state(disabled)) .shell {
opacity: 0.5;
pointer-events: none;
}
:state(disabled) replaces the .editor-disabled host class. It also covers a disabled fieldset, which the class didn’t. The other host classes stay.
Tests (tests/rich-text-form.spec.ts)
FormDatahas the editor’s normalized HTML under itsname, including right after typing (both thesubmitand thenew FormData()paths).requiredblocks submission, focuses the content area, and turns on:state(user-invalid)and the error note.- A form reset restores
defaultValueand clears the undo history. - A disabled
fieldsetdisables the editor and leaves it out ofFormData. readonlycontent is still submitted.- Clicking a
<label for>focuses the content area. - In Chromium’s accessibility tree, the name comes from
labeland the description fromnote. inputfires for typing and for toolbar commands, with matchinginputTypes.changefires once when focus leaves the component, and not when focus moves to the toolbar.- Setting
valuefrom code replaces the content. The value the editor writes back doesn’t re-trigger that replacement.
Docs
Add a Forms section to rich-text.md with a live <form> demo (required editor, submit, reset), the name/value/defaultValue behavior, the typing-pause note, and the form states in the accessibility checklist.
0.10 Test helpers (tests/rich-text-utils.ts)
export async function editor(page: Page, html = "", attrs = "") {
await mount(page, `<orb-rich-text ${attrs}></orb-rich-text>`);
const el = page.locator("orb-rich-text");
await el.evaluate((e: any, h) => e.setContent(h), html);
return el;
}
/** Selects the nth occurrence of `text` in the editor */
export const selectText = (page: Page, text: string, nth = 0) =>
page.locator("orb-rich-text").evaluate((host, [text, nth]) => { /* TreeWalker in shadowRoot, setBaseAndExtent */ }, [text, nth] as const);
export const content = (page: Page) =>
page.locator("orb-rich-text").evaluate((e: any) => e.getContent());
Spec files stay flat, matching the existing naming: tests/rich-text-*.spec.ts, one per phase area. They run in all three Playwright projects; WebKit matters most.
Phase 0 is done when:
- the current features behave as they do today;
- the toolbar is built from the command list;
- undo works with changes stored as slices;
- pasting from Google Docs keeps bold and doesn’t turn everything bold;
valueandsetContentare sanitized;- the editor submits with a form and validates
required.
Phase 1: Input and blocks
1.1 Better keyboard features (editing/input.ts)
The principle: let the browser handle typing and deleting inside a block, which is fast and works with input methods (IME) and spellcheck. Take over at block boundaries, at non-editable pieces, and for Enter and Tab.
export type Key =
| "enter" | "shiftEnter" | "backspaceAtStart" | "deleteAtEnd"
| "tab" | "shiftTab" | "arrowUpAtStart" | "arrowDownAtEnd";
/** Returns the range to select, null when handled without a change, or undefined to pass to the next behavior out */
export type Handler = (el: HTMLElement, range: Range, root: HTMLElement) => Range | null | undefined;
export interface Behavior {
/** The element this handles, found by walking out from the caret */
selector: string;
on: Partial<Record<Key, Handler>>;
}
/** Most specific first; added to as features land */
export const BEHAVIORS: Behavior[] = [codeBlock, tableCell, taskItem, listItem, figcaption, quote, heading, paragraph];
export function handleKey(root: HTMLElement, range: Range, key: Key): Range | null | undefined {
for (let node: Node | null = range.startContainer; node && node !== root; node = node.parentNode) {
if (!(node instanceof HTMLElement)) continue;
for (const behavior of BEHAVIORS) {
if (!node.matches(behavior.selector)) continue;
const result = behavior.on[key]?.(node, range, root);
if (result !== undefined) return result;
}
}
return DEFAULTS[key]?.(root, range); // splitBlock, insertBreak, joinBackward, joinForward
}
In the component:
private handleBeforeInput = (event: InputEvent) => {
if (!this.editable || event.isComposing || event.inputType === "insertCompositionText") return;
const range = getRange(this.editorRef);
if (!range) return;
let key: Key | undefined;
switch (event.inputType) {
case "insertParagraph": key = "enter"; break;
case "insertLineBreak": key = "shiftEnter"; break;
case "deleteContentBackward":
case "deleteWordBackward":
case "deleteSoftLineBackward":
if (!range.collapsed) return this.deleteSelection(event, range);
if (atomBefore(range)) return this.deleteAtom(event, "backward");
if (atBlockStart(this.editorRef, range)) key = "backspaceAtStart";
break;
// …forward mirrors backward; insertText runs auto-format rules, pending formats and triggers;
// format* and history* inputs are handled as today
}
if (!key) return;
event.preventDefault();
this.apply(() => handleKey(this.editorRef, range, key!) ?? null);
};
Default behaviors (blocks.ts):
splitBlock(Enter):Range.extractContents()splits the formatting around the caret automatically;- the new block copies alignment, indent and line height, but not
id; - a heading split at its end continues as a paragraph;
- empty halves get a
<br>.
joinBackward(Backspace at the start of a block):- after a paragraph or heading: merges into it;
- after a non-editable block (hr, figure, table): the first press selects it and the second removes it;
- at the start of the document: turns a heading into a paragraph.
deleteSelection: deleting across blocks keeps the structure valid. Tables are emptied cell by cell, never cut apart. Then everything left is joined into the first block.
Shortcuts. All matched from the command list. Mod is Ctrl or ⌘.
| Shortcut | Action |
|---|---|
| Mod+Z, Mod+Shift+Z, Mod+Y | Undo, redo |
| Mod+B / I / U | Bold, italic, underline |
| Mod+Shift+X | Strikethrough |
| Mod+K | Link |
| Mod+Alt+0–6 | Paragraph, headings 1–6 |
| Mod+Shift+7 / 8 / 9 | Numbered, bulleted, task list |
| Mod+Shift+L / E / R / J | Align left, center, right, justify (the Google Docs set) |
| Mod+\ | Clear formatting |
| Mod+] / Mod+[ | Indent, outdent |
| Mod+Enter | Page break |
| Mod+Alt+Enter | Toggle a task |
| Mod+S | Save |
| Mod+P | |
| Mod+Alt+M | Comment |
| Mod+/ | Shortcut help |
Other keyboard features:
- Alt+F10 focuses the toolbar.
- Shortcut help: Mod+/ opens an
orb-overlaylisting the shortcuts, built from the command list. - Tab escape (outside full screen only; see 5.1): Escape with no popup open sets
tabLeaves = trueuntil the next key. Tab then moves focus out instead of being handled. Tab is only taken over inside lists, tables and code blocks, so it never traps focus (WCAG 2.1.2). The help dialog explains this. - Android: rely on
beforeinput, notkeydown, for Enter and Backspace. On Android,keydownoften reportskey: "Unidentified".
1.2 Text style select and h1–h6
- Types:
BlockType = "p" | "h1" | … | "h6" | "pre".blockType()returns the shared type, ornullwhen the selection mixes types. - One
blockTypeselect command, labeled Text style, replaces the three heading and paragraph buttons. Options: Paragraph and Heading 1–6. Quote and code block have their own toggles (1.3, 1.5), so the select doesn’t offer them. Setting a paragraph or heading keeps any quote around the block. - CSS: h3–h6 sizes go in
content.css.
1.3 Block quotes
- HTML:
<blockquote><p>…</p></blockquote>.BLOCKQUOTEmoves from text blocks to containers, so a quote can hold several paragraphs. setQuote(root, range, on), called by thequotetoolbar toggle:- if every selected block is already in the same quote, lift those blocks out, splitting the quote around them;
- otherwise, wrap the selected blocks’ outermost ancestors under a shared parent in a new
blockquote.
quotebehavior:- Enter on an empty last paragraph leaves the quote;
- Backspace at the start of the first paragraph removes the quote.
1.4 Separators
- Insert:
insertBlockAt(root, range, document.createElement("hr")). It splits the current block at the caret, inserts the separator between the halves, and makes sure an editable block follows. - CSS: an
hr[data-selected]outline.
1.5 Code
-
Inline: the
codemark stays in the schema for pasted content and code blocks. There’s no toolbar toggle for inline code. Clear formatting removes it. -
Toolbar: the
codetoggle makes the caret’s block a code block. Clicking it again turns the block back into a paragraph, and thecodeinside it is unwrapped so it doesn’t become inline code. -
HTML for blocks:
<pre><code class="language-ts">…</code></pre>, the form markdown-it produces. Insidepre, cleanup turns<br>into\nand unwraps all formatting. -
codeBlockbehavior:- Enter inserts
\n. When the caret is at the very end, a second\nis added so the new empty line shows; cleanup removes that extra newline from output. - Leaving the block: Enter when the last two lines are empty removes them and creates a paragraph after the block. ArrowDown on the last line creates a paragraph after it if none exists.
- Tab and Shift+Tab indent or outdent the selected lines by two spaces.
- Backspace at the start of an empty block turns it into a paragraph.
- Paste inside is always plain text.
- Formatting commands are disabled inside.
- Enter inserts
-
Language picker: the
codeLanguageselect, shown in the toolbar only while the caret is in a code block. The languages come from thecodeLanguagesproperty, set as a property rather than an attribute. -
Syntax highlighting (
editing/code.ts) uses the CSS Custom Highlight API, so the content itself never changes and undo, the caret and the stored HTML aren’t affected:let prism: Promise<any> | undefined; const loadPrism = () => (prism ??= (async () => { (globalThis as any).Prism = { manual: true }; // don't highlight the page on load return (await import("prismjs")).default; })()); /** Ranges this editor added, by highlight name, so it only removes its own */ const owned = new Map<string, Set<Range>>(); export async function highlightCode(root: HTMLElement) { if (!("highlights" in CSS)) return; const Prism = await loadPrism(); for (const set of owned.values()) for (const r of set) CSS.highlights.get(nameOf(set))?.delete(r); for (const code of root.querySelectorAll<HTMLElement>("pre > code")) { const grammar = Prism.languages[languageOf(code)]; if (!grammar) continue; addTokenRanges(code, Prism.tokenize(code.textContent ?? "", grammar)); // walk tokens → Ranges per type } }- When it runs: 150ms after the last change, only for code blocks that changed.
- Styling:
content.cssmaps::highlight(orb-code-keyword) { color: var(--editor-code-keyword) }and so on. Each color is a documented CSS custom property. - Loading languages: Prism’s language files expect the global
Prism, so they’re loaded on demand withimport("prismjs/components/prism-python"). - Highlight names are global, so each editor instance manages only its own ranges within them.
- Verify that
::highlight()styles inside a shadow root apply in all three engines.
1.6 Indent level
One generic block-style function also replaces setAlignment:
/** Sets a style on the selected blocks. Null removes it. */
export function setBlockStyle(root: HTMLElement, range: Range, prop: StyleProp, value: string | null): Range {
for (const block of blocksIn(root, range)) {
if (value) block.style.setProperty(prop, value);
else block.style.removeProperty(prop);
if (!block.getAttribute("style")) block.removeAttribute("style");
}
return range;
}
const INDENT_EM = 2, MAX_INDENT = 8;
export function changeIndent(root: HTMLElement, range: Range, delta: 1 | -1): Range {
// List items nest instead (1.8). Other blocks step margin-inline-start in 2em steps.
}
1.7 Line height
- Command: a
lineHeightselect with Default, 1, 1.15, 1.5 and 2, usingsetBlockStyle(…, "line-height", v). - CSS:
.editor-content { line-height: var(--editor-line-height, 1.6) }, replacing the hardcoded1.6, documented with@prop.
1.8 Advanced lists
HTML:
<ol start="3" style="list-style-type: lower-alpha">
<li>Item<ul><li>Child</li></ul></li>
</ol>
<ul>
<li style="list-style-type: none"><input type="checkbox" checked> Done task</li>
</ul>
- List items keep holding text directly, as today.
- A task item is an
lithat starts with a checkbox. Cleanup addslist-style-type: noneso it shows correctly anywhere. - GitHub’s
class="task-list-item"anddisabledattributes are removed when importing.
Nesting (lists.ts):
/** Moves each selected item into a list at the end of the item before it */
export function indentItems(root: HTMLElement, range: Range): Range {
const saved = keep(range);
for (const item of outermostItems(root, range)) {
const previous = item.previousElementSibling as HTMLElement | null;
if (previous?.tagName !== "LI") continue; // the first item can't go deeper
const tag = item.parentElement!.tagName;
let sublist = previous.lastElementChild;
if (sublist?.tagName !== tag) previous.append((sublist = document.createElement(tag)));
sublist.append(item); // its own children come along
}
return restore(saved, root) ?? range;
}
/** Moves an item out one level. Items after it become its children, so nothing changes order. */
export function outdentItem(root: HTMLElement, item: HTMLElement) {
const list = item.parentElement!;
const parentItem = list.parentElement;
if (parentItem?.tagName !== "LI") return unwrapListItem(item); // top level: becomes a paragraph
const following = siblingsAfter(item);
if (following.length) {
let sub = item.querySelector<HTMLElement>(`:scope > ${list.tagName}`);
if (!sub) item.append((sub = document.createElement(list.tagName)));
sub.append(...following);
}
parentItem.after(item);
if (!list.children.length) list.remove();
}
Updates to existing functions: listItems, listType and toggleList must handle nesting. Toggling between list types changes only the innermost list.
listItem behavior:
| Key | Action |
|---|---|
| Enter | On an empty item, outdents it; otherwise splitBlock. Content after the caret, including a sublist, moves into the new item. |
| Backspace at start | Outdents |
| Tab / Shift+Tab | Indent / outdent the selected items |
taskItem behavior:
| Key | Action |
|---|---|
| Enter | The new item gets an unchecked checkbox |
| Backspace right after the checkbox | Removes the checkbox, leaving a regular list item |
Toggling a checkbox:
// A canceled click restores the checkbox's previous state after the event,
// so the toggle runs afterward. Some browsers don't let you click form
// controls inside editable content at all, so this always toggles itself.
private onEditorClick = (ev: MouseEvent) => {
const box = (ev.target as Element).closest?.("input[type=checkbox]");
if (!(box instanceof HTMLInputElement) || !this.editorRef.contains(box)) return;
ev.preventDefault();
if (!this.editable) return;
setTimeout(() => this.apply(() => toggleTask(box)));
};
export function toggleTask(box: HTMLInputElement): Range {
const on = !box.hasAttribute("checked");
box.toggleAttribute("checked", on); // the attribute is what innerHTML saves
box.checked = on;
return afterNode(box);
}
- Mousedown on a checkbox is prevented, so the caret doesn’t move.
- Checkboxes get
tabIndex = -1at runtime, removed from output. Mod+Alt+Enter toggles the task the caret is in. - The sanitizer currently removes every
input; the schema (0.2) allows checkboxes inside list items only. - List styles: a
listStyleselect applieslist-style-typeto the list containing the caret, and thestartattribute is editable from it. Continuing numbering from the list above is left out of v1.
Phase 1 tests:
- Enter, Backspace and Tab in each context;
- nesting round-trips;
- checkbox state survives undo and
getContent; - input-method (IME) composition isn’t interrupted (
page.keyboard.insertTextduring composition); - Tab escape;
- one Tab stop in the toolbar.
Phase 2: Inline styling and typing shortcuts
2.1 Font color, family, size, background
/** Splits `el` so `node` is alone in it. Content before and after goes into copies on either side. */
export function splitAround(el: HTMLElement, node: Node): HTMLElement { /* today's unwrapAround, minus the unwrap */ }
export function unwrapAround(el: HTMLElement, node: Node) {
const own = splitAround(el, node);
own.replaceWith(...Array.from(own.childNodes));
}
export function setInlineStyle(root: HTMLElement, range: Range, prop: StyleProp, value: string | null): Range {
const split = splitBoundaries(range);
const nodes = selectedTextNodes(root, split);
if (!nodes.length) return split;
for (const node of nodes) {
let span: HTMLElement | null;
while ((span = closestWithStyle(node, root, prop))) {
const own = splitAround(span, node);
own.style.removeProperty(prop);
if (!own.getAttribute("style")) own.replaceWith(...Array.from(own.childNodes));
}
}
if (value) {
wrapEach(nodes, () => {
const span = document.createElement("span");
span.style.setProperty(prop, value);
return span;
});
}
return spanOf(nodes);
}
/** The value across the selection: one value, null for none, or "mixed" */
export function inlineStyleValue(root: HTMLElement, range: Range, prop: StyleProp): string | null { /* … */ }
-
Typing with nothing selected. Today
pendingFormatsisMap<InlineFormat, boolean>. It becomesMap<string, string | boolean | null>, keyed by"strong"or"style:color", andinsertFormattedTextlearns to wrap text in style spans. -
Props:
/** Font families to choose from. The value is the CSS font stack. */ @Prop() fonts: FontOption[] = DEFAULT_FONTS; // { label, value } /** Font sizes to choose from, in points */ @Prop() fontSizes = "8 9 10 11 12 14 18 24 30 36 48"; /** Swatches in the color pickers */ @Prop() colors: string[] = DEFAULT_PALETTE;Colors are stored as real color values (portable), not theme variables. Font sizes in
ptmap cleanly to DOCX and print. -
Commands:
fontFamilyandfontSizeare selects;colorandbackgroundare color controls. Each shows the current value, or a mixed state when the selection has several. -
Color picker (
ui/pickers.tsx): anorb-popoverwith a swatch grid (arrow-key navigation, one Tab stop), Default (removes the color), and Custom… using<input type="color">. -
Clear formatting removes style spans and marks. Annotations and non-editable pieces stay (decided by
kindin the schema). TodayFORMATTING_TAGSincludesSPANandMARK, which would have deleted comment markers.
2.2 GFM auto-formatting and Markdown paste (editing/rules.ts)
interface BlockRule {
/** The paragraph's text before the caret, when space is typed */
match: RegExp;
apply: (root: HTMLElement, block: HTMLElement, m: RegExpMatchArray) => Range;
}
export const SPACE_RULES: BlockRule[] = [
{ match: /^(#{1,6})$/, apply: (root, b, m) => setBlockType(root, startOf(b), `h${m[1].length}` as BlockType) },
{ match: /^[-*+]$/, apply: (root, b) => toggleList(root, startOf(b), "ul") },
{ match: /^(\d+)[.)]$/, apply: (root, b, m) => setListStart(toggleList(root, startOf(b), "ol"), +m[1]) },
{ match: /^(?:[-*+] )?\[( |x)\]$/i, apply: (root, b, m) => makeTask(root, b, m[1] !== " ") },
{ match: /^>$/, apply: (root, b) => setQuote(root, startOf(b), true) },
];
export const ENTER_RULES: BlockRule[] = [
{ match: /^```([\w+-]*)$/, apply: (root, b, m) => toCodeBlock(root, b, m[1]) },
{ match: /^(?:---|\*\*\*|___)$/, apply: (root, b) => replaceWithSeparator(root, b) },
];
interface InlineRule { match: RegExp; mark: MarkName }
/** Checked against the text before the caret plus the character being typed */
export const INLINE_RULES: InlineRule[] = [
{ match: /(?:^|[^*])\*\*([^*\s](?:[^*]*[^*\s])?)\*\*$/, mark: "bold" },
{ match: /(?:^|[^\w_])__([^_\s](?:[^_]*[^_\s])?)__$/, mark: "bold" },
{ match: /(?:^|[^*])\*([^*\s](?:[^*]*[^*\s])?)\*$/, mark: "italic" },
{ match: /(?:^|[^\w_])_([^_\s](?:[^_]*[^_\s])?)_$/, mark: "italic" },
{ match: /~~([^~\s](?:[^~]*[^~\s])?)~~$/, mark: "strike" },
{ match: /`([^`]+)`$/, mark: "code" },
];
// Autolinks: on space or Enter after /(https?:\/\/[^\s<]+[^\s<.,:;"')\]])$/
-
Rules apply in two undo steps. When a rule matches, the typed character is inserted and recorded as its own step; then the conversion is applied and recorded as a second step. The caret position is saved as
lastRule. Backspace while the caret is still there runshistory.undo(), which brings back the literal text. Any selection change clearslastRule. -
Inline rules stay within one block. Code blocks and inline code are skipped.
-
Markdown paste: when the clipboard has only
text/plainand the text looks like Markdown,convert/markdown.tsrenders it with markdown-it (loaded on first use, as inorb-markdown), then sanitizes and inserts it. Controlled by themarkdown-pasteprop, defaulttrue.const MARKDOWN_HINTS = /^(#{1,6}\s|[-*+]\s|\d+[.)]\s|>\s|```|\|.*\|\s*$|[-*_]{3,}\s*$)|\*\*[^*\n]+\*\*|\[[^\]\n]+\]\([^)\s]+\)/m;
2.3 Special characters and emoji
- Pickers are
orb-popovers opened from the toolbarpickercontrol:- a search field (
orb-textbox); - category tabs;
- a grid with
role="grid"and arrow-key navigation (one Tab stop); - recently used items in
localStorage(orb-rich-text:recent-characters,…:recent-emoji).
- a search field (
- Data:
-
Special characters: a hand-curated list in
ui/special-characters.ts(punctuation, currency, math, arrows, Latin letters with accents, Greek, symbols), each with a name for search. -
Emoji:
emojibase-data, loaded on first use:let emoji: Promise<EmojiEntry[]> | undefined; const loadEmoji = () => (emoji ??= import("emojibase-data/en/compact.json").then((m) => m.default));Check that Stencil’s build can import JSON. Skin tones are left out of v1.
-
- Inserting uses
insertText(root, range, text), which also applies pending formats. The pickers keep the editor’s selection the same way the toolbar does (savedRange). - Shortcodes (
:smile) are a trigger in 4.1.
Phase 3: Structured content
3.1 Tables (editing/tables.ts)
HTML:
<table>
<colgroup><col style="width: 30%"><col style="width: 70%"></colgroup>
<thead><tr><th>Name</th><th>Notes</th></tr></thead>
<tbody><tr><td>Ada</td><td>Line one<br>Line two</td></tr></tbody>
</table>
Styling: add table, colgroup, col, thead, tbody, tr, th and td to the schema. Cells are text blocks. Reuse the shared table styles: content.css imports the generated _tables.scss output, the same way grid.tsx imports tables.generated.css.
Cleaning up pasted tables (including from Excel and Sheets):
- paragraphs inside a cell become lines separated by
<br>; colspan/rowspancells are split into separate cells, since merging isn’t supported in v1;- short rows get padded with empty cells;
- tables with no rows are dropped.
Commands:
export function insertTable(root: HTMLElement, range: Range, rows: number, cols: number): Range {
const table = document.createElement("table");
const head = table.createTHead().insertRow();
for (let c = 0; c < cols; c++) head.append(emptyCell("th"));
const body = table.createTBody();
for (let r = 1; r < rows; r++) {
const row = body.insertRow();
for (let c = 0; c < cols; c++) row.append(emptyCell("td"));
}
insertBlockAt(root, range, table);
return startOf(table.querySelector("th, td")!);
}
const emptyCell = (tag: "td" | "th") => {
const cell = document.createElement(tag);
cell.append(document.createElement("br"));
return cell;
};
export function addRow(table: HTMLTableElement, rowIndex: number, where: "before" | "after"): Range { /* clone shape, empty cells */ }
export function addColumn(table: HTMLTableElement, colIndex: number, where: "before" | "after"): Range { /* per row + <col> */ }
export function deleteRows(table: HTMLTableElement, rows: number[]): Range { /* deletes the table when none are left */ }
export function deleteColumns(table: HTMLTableElement, cols: number[]): Range { /* same */ }
export function toggleHeaderRow(table: HTMLTableElement): Range { /* first row moves between thead (th) and tbody (td) */ }
blocksIn understands cells, so block commands work inside them.
tableCell behavior:
| Key | Action |
|---|---|
| Tab / Shift+Tab | Next or previous cell. Tab in the last cell adds a row. |
| Enter | Line break (<br>) |
| ArrowUp at the first line / ArrowDown at the last line | Same column in the row above or below; leaves the table at its edges |
| Backspace at start / Delete at end | Does nothing, so cells never merge |
Selecting several cells:
interface CellSelection { table: HTMLTableElement; anchor: HTMLTableCellElement; head: HTMLTableCellElement }
function cellsIn({ table, anchor, head }: CellSelection): HTMLTableCellElement[] {
const [r1, r2] = [rowOf(anchor), rowOf(head)].sort((a, b) => a - b);
const [c1, c2] = [anchor.cellIndex, head.cellIndex].sort((a, b) => a - b);
return Array.from(table.rows).slice(r1, r2 + 1).flatMap((row) => Array.from(row.cells).slice(c1, c2 + 1));
}
- Detecting it: in
onSelectionChange, when the two ends of the selection are in different cells of the same table, the editor switches to cell selection. The composed range doesn’t say which end is the anchor;selection.directiondoes (supported in current Chrome, Firefox and Safari). - Showing it: cells get
data-selected(runtime only), and.cell-selecting ::selection { background: transparent }hides the browser’s own selection. - Commands run once per selected cell, using
selectNodeContents(cell). Delete empties the selected cells. Copy writes a<table>fragment.
UI:
- Insert: a toolbar
pickerwith a size grid that expands as you hover, up to 10×10, and also works with arrow keys. - While the caret is in a table: the toolbar shows an extra group (rows, columns, header row, delete).
- Right-click inside a table opens an
orb-menuwith the same commands, viamenu.show(event). - Resizing columns:
interactjshandles in a layer over the content (.editor-overlay, positioned absolutely in.editor-content-wrapper). When a drag ends, the editor setscolwidths in%and records one undo step.
3.2 Media (editing/media.ts)
HTML:
<figure style="text-align: center">
<img src="…" alt="…" width="480">
<figcaption>Optional caption</figcaption>
</figure>
<figure><video src="…" controls></video></figure>
<figure data-embed="youtube">
<iframe src="https://www.youtube-nocookie.com/embed/ID" sandbox="allow-scripts allow-same-origin allow-presentation"
allowfullscreen loading="lazy"></iframe>
</figure>
figureis a non-editable block. Itsfigcaptionis an editable text block nested inside it.- Images pasted inside a paragraph are moved into their own
figure, splitting the paragraph. - Embeds: only from the
embed-providerslist. The sanitizer rebuilds theiframesrcfrom the provider’s parsed ID, never trusting the pasted URL.
API:
/** Uploads a file and returns its URL. Without it, images are embedded as data URLs. */
@Prop() upload?: (file: File) => Promise<string>;
/** File types that can be inserted, like the `accept` attribute */
@Prop() mediaAccept = "image/*";
/** Sites whose videos can be embedded by URL */
@Prop() embedProviders: EmbedProvider[] = [YOUTUBE, VIMEO];
/** Emitted when `upload` fails. The placeholder is removed. */
@Event() orbUploadError: EventEmitter<{ file: File; error: unknown }>;
Inserting files:
private async insertFiles(files: File[], range: Range) {
for (const file of files.filter((f) => isAccepted(f, this.mediaAccept))) { // moved from file-input to utils/files.ts
const preview = URL.createObjectURL(file);
const figure = createMediaFigure(file, preview); // media has data-uploading
this.apply(() => insertBlockAt(this.editorRef, range, figure), { record: false });
try {
const src = this.upload ? await this.upload(file) : await readAsDataUrl(file);
const media = figure.querySelector("img, video")!;
media.setAttribute("src", src);
media.removeAttribute("data-uploading");
this.history.record();
this.afterChange(false);
} catch (error) {
figure.remove();
this.orbUploadError.emit({ file, error });
} finally {
URL.revokeObjectURL(preview);
}
}
}
Sources of files:
- the toolbar button (the existing hidden file input);
- pasted files (
clipboardData.files, e.g. screenshots); - dropped files. For drops, the editor converts the drop point to a caret position with
document.caretPositionFromPoint(x, y, { shadowRoots: [root] }), falling back tocaretRangeFromPoint. Check that WebKit handles the shadow root correctly.
Embeds: Insert > Video by URL asks for a link, and pasting a bare provider link on an empty line converts it.
Selecting media:
- clicking selects the whole figure;
interactjsresize handles appear in the overlay layer, keeping the aspect ratio, and setwidthwhen the drag ends;- a popover offers alt text, a caption toggle, alignment, Replace and Remove.
An embedded iframe would swallow clicks, so a transparent cover sits over it until the figure is selected.
3.3 Document outline and TOC (editing/outline.ts)
-
Heading IDs:
assignHeadingIds(root)runs inafterChangebefore history records. It keeps an existingidif it’s unique; otherwise it creates a slug from the heading text and appends-2,-3… for duplicates. -
Outline panel:
/** Shows a panel listing the document's headings */ @Prop({ reflect: true }) outline = false;- Layout: the editor body becomes
orb-split-view> [orb-split-paneloutline] [orb-split-panel primarycontent] [orb-split-panelcomments (Phase 7)]. - Contents: a
navwith nested lists of buttons, rebuilt after changes with a short delay. The current section is highlighted using anIntersectionObserveron headings within the editor’s scroll area.
- Layout: the editor body becomes
-
TOC block:
- HTML:
<nav data-toc><ol><li><a href="#id">…</a><ol>…</ol></li></ol></nav>, a non-editable block. - Updating: in
afterChange, if a TOC exists and the headings’ signature (level, text and id of each) changed, its contents are rebuilt before the undo step is recorded, so the change and the rebuild are one step.
- HTML:
-
Clicking a heading link in the outline or the TOC is handled in JavaScript, because URL fragments can’t reach into a shadow root:
heading.scrollIntoView({ block: "start" })and the caret moves to the heading’s start.
Phase 4: Inline objects
4.1 / commands, mentions, tags and emoji shortcodes (editing/triggers.ts)
export interface TriggerItem {
id: string;
label: string;
details?: string;
icon?: (props?: any) => any;
}
export interface Trigger {
text: string; // "/", "@", "#", ":", "{{"
label: string; // the menu's accessible name
/** Only at the start of a block, like the "/" menu */
blockStart?: boolean;
/** Whether the search text may contain spaces */
spaces?: boolean;
items(query: string): TriggerItem[] | Promise<TriggerItem[]>;
/** Replaces the trigger and search text with the result. Returns the caret. */
choose(item: TriggerItem, root: HTMLElement, range: Range): Range;
}
interface Session {
trigger: Trigger;
start: Point; // where the trigger text begins
query: string;
items: TriggerItem[];
request: number; // ignores stale async results, like orb-markdown's renderId
}
How a session runs:
- Starting: on
insertText, if the text before the caret now ends with a trigger’s text, and it’s at the start of a line or after a space (and at the start of a block, forblockStarttriggers), a session starts. - On each change: the search text is the text from the end of the trigger text to the caret. The session ends if the caret moves before the trigger, leaves the block, or the search text gets a space (unless
spaces) or exceeds 50 characters. - Fetching items: async item lists wait 150ms after the last keystroke.
Rendering, in the editor’s shadow root:
<orb-menu ref={(el) => (this.triggerMenu = el)} label={session?.trigger.label}
onOrbSelect={(ev) => this.chooseTriggerItem(ev.detail.value)}>
{session?.items.map((item) => (
<orb-mi value={item.id}>
{item.icon && <span slot="icon">{item.icon()}</span>}
{item.label}
{item.details && <span slot="details">{item.details}</span>}
</orb-mi>
))}
</orb-menu>
The editor calls triggerMenu.attachInput(this.editorRef) and triggerMenu.show(caretAnchor(range, root)) (0.7). Escape closes the menu and leaves the typed text as it is.
Built-in triggers:
| Trigger | Items | Inserts |
|---|---|---|
/ |
Commands with slash set, matched on label and keywords |
Runs the command after removing /query |
@ |
mentions?: (query: string) => Promise<MentionItem[]> |
<span data-mention="id">@Label</span>, then emits orbMention |
# |
tags?: (query: string) => Promise<TagItem[]>, plus a “Create #query” item |
<span data-tag="id">#label</span> |
: |
Emoji data, matched on shortcode (needs at least 2 characters) | The emoji character |
{{ |
params (4.2) |
A placeholder |
4.2 Parameters and placeholders
export interface ParamDef { key: string; label: string; sample?: string; description?: string }
/** Placeholders that can be inserted, such as a customer's name in a template */
@Prop() params: ParamDef[] = [];
/** Keys of the placeholders in the document, in order, without repeats */
@Method() async getParams(): Promise<string[]> { /* … */ }
/** The document's HTML with each placeholder replaced by its value, as text. Unknown keys are left as is. */
@Method() async fill(values: Record<string, string>): Promise<string> { /* runs on the output copy */ }
- HTML:
<span data-param="customer.name">Customer name</span>, a non-editable piece. Its text is the label, so it’s readable anywhere. Text and Markdown export write{{customer.name}}; DOCX export writes merge-field text. - Unknown keys: placeholders whose key isn’t in
paramsgetdata-unknown(runtime only) for a warning style. - Insert: a toolbar
paramselect and the{{trigger. - Preview mode (5.2) shows
samplevalues usingfill’s replacement on a read-only copy.
4.3 Templates
export interface TemplateInfo {
id: string;
label: string;
description?: string;
html?: string;
load?: () => Promise<string>;
}
/** Templates offered by File > New from template */
@Prop() templates: TemplateInfo[] = [];
/** Replaces the document with a template, or inserts it at the caret. Undoable. */
@Method() async applyTemplate(id: string, how: "replace" | "insert" = "replace") { /* … */ }
- Picker: an
orb-overlaylisting templates asorb-cards. - Replacing with unsaved changes (Phase 6): the editor asks for confirmation in the overlay first.
- Applying goes through
sanitizeandnormalize, thenapply(), so it’s a single undo step, unlikesetContent, which starts a fresh undo history. Templates can contain placeholders.
Phase 5: Document chrome and formats
5.1 Full screen with menubar
Full screen uses the Popover API. Setting fullscreen doesn’t need a click or keypress, and nothing depends on browser-specific full screen support. Safari has supported popovers since version 17, iPhone included.
Tradeoff: a popover doesn’t make the rest of the page inert the way a modal <dialog> would. The editor makes up for that by keeping focus inside the full-screen view and covering the whole screen. Screen readers in browse mode can still reach content behind it; aria-modal asks them not to, but support varies. If that matters later, showModal() on a <dialog> works the same way and makes the page behind inert automatically.
How it works:
- Wrapper element. Everything the editor renders goes in a
.shellelement inside the shadow root. That includes the menubar, toolbar, split view, content, sidebar, footer, and the editor’s own menus and tooltips. The label, note and error message (0.9) stay outside it. - Going full screen:
- The editor sets
popover="manual"on the shell and callsshowPopover(). - The shell moves to the browser’s top layer, above everything else on the page, with no z-index needed.
manualmeans the browser doesn’t close it on outside clicks or Escape; the editor handles that itself.
- The editor sets
- The attribute is only set while full screen. An element with
popoverset is hidden whenever it isn’t showing, so leaving it on would hide the editor normally. - The host keeps its height. A top-layer element no longer takes up space in its original spot, so without this the page would shift and lose its scroll position.
/** Fills the window, above the rest of the page */
@Prop({ mutable: true, reflect: true }) fullscreen = false;
/** When the menubar shows */
@Prop() menubar: "always" | "fullscreen" | "never" = "fullscreen";
private shellEl!: HTMLElement;
private viewportListeners?: AbortController;
@Method()
async toggleFullscreen() {
this.fullscreen = !this.fullscreen;
}
@Watch("fullscreen")
onFullscreenChange(on: boolean) {
const shell = this.shellEl;
const range = this.takeRange();
if (on && !shell.matches(":popover-open")) {
// The shell leaves the page's layout, so the host holds its place.
this.el.style.setProperty("--editor-placeholder-height", `${this.el.offsetHeight}px`);
shell.popover = "manual";
shell.showPopover();
this.watchViewport();
} else if (!on && shell.matches(":popover-open")) {
shell.hidePopover();
// With the attribute left on, the shell would stay hidden.
shell.removeAttribute("popover");
this.el.style.removeProperty("--editor-placeholder-height");
this.viewportListeners?.abort();
}
// Safari only redraws the caret when the selection changes.
this.editorRef.focus({ preventScroll: true });
selectRange(range, { redraw: true });
}
disconnectedCallback() {
// …existing cleanup
this.viewportListeners?.abort();
}
Following the on-screen keyboard (iPhone). On iOS the on-screen keyboard covers the page instead of resizing it, and 100dvh doesn’t shrink when it opens. The shell follows visualViewport so the toolbar and caret stay visible:
/** Sizes the shell to the visible part of the window, which shrinks when the on-screen keyboard opens */
private watchViewport() {
const viewport = window.visualViewport;
if (!viewport) return;
this.viewportListeners?.abort();
this.viewportListeners = new AbortController();
const sync = () => {
this.shellEl.style.setProperty("--editor-viewport-height", `${viewport.height}px`);
this.shellEl.style.setProperty("--editor-viewport-top", `${viewport.offsetTop}px`);
};
const { signal } = this.viewportListeners;
viewport.addEventListener("resize", sync, { signal });
viewport.addEventListener("scroll", sync, { signal });
sync();
}
Escape and focus. Full screen acts like a modal. Focus stays inside the shell, and Escape exits full screen when no popup is open:
private onShellKeyDown = (ev: KeyboardEvent) => {
if (!this.fullscreen || ev.key !== "Escape") return;
// Dialogs and menus inside the shell handle their own Escape first.
if (ev.defaultPrevented || this.hasOpenPopup()) return;
ev.preventDefault();
this.fullscreen = false;
};
/** Menus, popovers and dialogs the editor opened, not counting tooltips */
private hasOpenPopup() {
const root = this.el.shadowRoot!;
return (
Array.from(root.querySelectorAll("orb-menu, orb-popover")).some((el) => el.matches(":popover-open")) ||
Array.from(root.querySelectorAll("orb-overlay")).some((el) => (el as HTMLOrbOverlayElement).open)
);
}
/** Tab past either end of the shell wraps to the other end */
private onSentinelFocus = (at: "start" | "end") => {
if (at === "start") this.focusLast(); // the content, or the sidebar when it's shown
else this.focusFirst(); // the menubar, or the toolbar
};
-
The “Escape, then Tab to leave” rule from 1.1 doesn’t apply in full screen. In full screen, Escape exits full screen, and Tab can’t leave the shell. Leaving would move focus to page content the shell is covering.
-
Rendering (outline; the label, note and error slots from 0.9 surround the shell):
<div ref={(el) => (this.shellEl = el)} class="shell" part="shell" role={full ? "dialog" : undefined} aria-modal={full ? "true" : undefined} aria-label={full ? "Editor" : undefined} onKeyDown={this.onShellKeyDown} > {full && <span tabindex={0} class="sentinel" onFocus={() => this.onSentinelFocus("start")} />} {this.showMenubar && this.renderMenubar()} {this.toolbarPlacement === "top" && this.renderToolbar()} {/* split view: outline | content | comments */} {this.showWordCount && this.renderFooter()} {/* tooltips, menus, popovers, overlays */} {full && <span tabindex={0} class="sentinel" onFocus={() => this.onSentinelFocus("end")} />} </div>private get showMenubar() { return this.menubar === "always" || (this.menubar === "fullscreen" && this.fullscreen); } -
Exiting puts the caret back in the editor and scrolls the host into view with
scrollIntoView({ block: "nearest" }). The menubar’s View > Full screen item and its toolbar button both calltoggleFullscreen(). There’s no default shortcut.
CSS (rich-text.css). The border, radius and background move from :host to .shell, so the full-screen view doesn’t inherit the inline editor’s border:
/**
* @prop --editor-fullscreen-bg: Background of the editor while it fills the window
* @prop --editor-fullscreen-width: Width of the writing column while it fills the window
*/
:host([fullscreen]) {
height: var(--editor-placeholder-height);
}
.shell {
display: flex;
flex-direction: column;
border: 2px solid var(--editor-border-color);
border-radius: var(--editor-border-radius);
background: var(--editor-bg);
overflow: hidden;
}
/* Overrides the browser's popover styles, which center a box that fits its content. */
.shell:popover-open {
position: fixed;
inset: auto 0;
top: var(--editor-viewport-top, 0);
width: 100vw;
max-width: none;
height: var(--editor-viewport-height, 100dvh);
max-height: none;
margin: 0;
padding: env(safe-area-inset-top) env(safe-area-inset-right) env(safe-area-inset-bottom) env(safe-area-inset-left);
border: 0;
border-radius: 0;
background: var(--editor-fullscreen-bg, Canvas);
color: var(--editor-text-color);
}
.shell:popover-open .editor-content {
max-height: none;
flex: 1;
width: min(100%, var(--editor-fullscreen-width, 816px));
margin-inline: auto;
/* Scrolling past the end doesn't scroll the page behind. */
overscroll-behavior: contain;
}
.sentinel {
position: absolute;
width: 1px;
height: 1px;
overflow: hidden;
clip-path: inset(50%);
}
Other notes:
- Safe-area padding only takes effect if the page’s viewport meta tag includes
viewport-fit=cover. Mention that in the docs. - Stacking:
- the editor’s menus, popovers and tooltips open after the shell, so they stack above it;
orb-overlayusesshowModal(), which also stacks above it, and focus stays inside its dialog;- a popover opened by another component on the page also stacks above it, which is the right behavior for things like toasts.
Menubar: <orb-menubar label="Editor"> built from the command list:
| Menu | Items |
|---|---|
| File | New from template, Open…, Save, Versions ▸, Download as ▸, Page setup…, Print |
| Edit | Undo, Redo, Select all |
| View | Outline, Comments, Word count, Show suggestions, Full screen, HTML source |
| Insert | Image, Video, Table, Separator, Page break, Special character, Emoji, Parameter, TOC |
| Format | Text ▸, Text style ▸, Quote, Code block, Align ▸, Line height ▸, Lists ▸, Clear formatting |
| Table | Shown while in a table |
| Tools | Word count, Spellcheck (toggle) |
| Help | Keyboard shortcuts |
Shortcut text goes in <kbd slot="details">, as the orb-menubar docs do. One orbSelect listener on the menubar runs COMMANDS.get(value). Cut, copy and paste are left out of the menu, because pasting from a menu needs clipboard permission.
Tests for 5.1:
- setting
fullscreenfrom code works without a click; - the page’s scroll position is the same after exiting;
- Escape closes an open menu first, and exits full screen on the second press;
- Tab wraps inside the shell;
- selection and undo history survive entering and exiting.
Check the on-screen keyboard behavior on a real iPhone; Playwright’s WebKit doesn’t emulate visualViewport and the iOS keyboard.
5.2 Interface modes
/**
* - **edit**: Changes apply directly.
* - **suggest**: Changes are marked as suggestions to accept or reject.
* - **comment**: Can add comments, but not edit.
* - **view**: Read-only.
* - **preview**: Read-only, with placeholders showing sample values.
*/
@Prop({ reflect: true }) mode: "edit" | "suggest" | "comment" | "view" | "preview" = "edit";
/** Where the formatting controls appear */
@Prop() toolbarPlacement: "top" | "floating" | "none" = "top";
private get editable() {
return !this.isDisabled && !this.readonly && (this.mode === "edit" || this.mode === "suggest");
}
readonlystays as a standard form attribute (0.9).mode="view"andreadonlybehave the same for editing.view,commentandprevieware left out of validation insyncValidity, asreadonlyis.- Floating toolbar: an
orb-popoveratcaretAnchor(selection), shown while text is selected. It uses the same control rendering as the top toolbar. - HTML source view: View > HTML source swaps the content for a
<textarea>with the normalized output. Switching back sanitizes, normalizes and applies it as one undo step. - Commands have
enabled()checks against the mode: for example, comment commands only incomment,editorsuggest.
5.3 Print, page setup, page breaks, margins, header and footer
Pages are print only. There is no on-screen page layout.
HTML: page settings are a hidden, non-editable block kept first in the content, so undo, saving and versions include them automatically:
<div hidden data-orb-page data-size="letter" data-orientation="portrait"
data-margins="1in 1in 1in 1in"
data-header-center="{title}" data-footer-right="Page {page} of {pages}"></div>
- The component keeps the settings in a
@State() page: PageSettings, read from that block after load and after undo or redo. - Cleanup re-creates the block from state if a delete removes it.
- Default settings produce no block at all.
HTML: page breaks: <hr data-page-break style="break-after: page">. The inline style makes it work outside the editor too. In the editor, CSS draws a dashed line labeled “Page break”. Mod+Enter inserts one. Handling otherwise matches separators (1.4).
Page setup: an orb-overlay with paper size (Letter, Legal, A4, A5), orientation, four margins, and left, center and right text for the header and footer. A note explains {page}, {pages}, {title} and {date}. Applying is one undo step.
Printing (convert/print.ts). It prints from a hidden iframe because @page rules don’t work inside a shadow root, and printing the whole page would include everything else on it:
@Method()
async print() {
const html = this.output().html;
const frame = Object.assign(document.createElement("iframe"), { title: "Print" });
frame.style.cssText = "position:fixed;width:0;height:0;border:0;visibility:hidden";
frame.srcdoc = `<!doctype html><html><head><title>${escapeHtml(this.docTitle)}</title>
<style>${contentStyles}${pageRules(this.page, this.docTitle)}</style></head><body>${html}</body></html>`;
document.body.append(frame);
await new Promise((resolve) => frame.addEventListener("load", resolve, { once: true }));
await Promise.all(Array.from(frame.contentDocument!.images, (img) => img.decode().catch(() => {})));
frame.contentWindow!.addEventListener("afterprint", () => frame.remove(), { once: true });
frame.contentWindow!.print();
}
contentStylesisimport contentStyles from "./content.css", followinggrid.tsx.- Mod+P inside the editor calls
print(). - A new
doc-titleprop provides{title}.
Page rules:
function pageRules(p: PageSettings, title: string) {
const box = (text?: string) => (text ? `content: ${toCssContent(text, title)};` : "");
return `@page {
size: ${p.size} ${p.orientation};
margin: ${p.margins};
@top-left { ${box(p.headerLeft)} } @top-center { ${box(p.headerCenter)} } @top-right { ${box(p.headerRight)} }
@bottom-left { ${box(p.footerLeft)} } @bottom-center { ${box(p.footerCenter)} } @bottom-right { ${box(p.footerRight)} }
}`;
}
// toCssContent("Page {page} of {pages}") → "\"Page \" counter(page) \" of \" counter(pages)"
Recent Chrome supports @page margin boxes. Check Firefox and Safari. Where they’re unsupported, pages print without a header and footer; margins and size still apply.
5.4 Import and export
export type ExportFormat = "html" | "text" | "markdown" | "docx" | "json";
export type ImportFormat = "html" | "text" | "markdown" | "docx";
export interface ExportOptions {
/** For formats that can't store suggestions. HTML and DOCX keep them. */
suggestions?: "accept" | "reject";
}
/** The document in another format. DOCX is a Blob, JSON is an object, the rest are strings. */
@Method()
async exportAs(format: ExportFormat, options: ExportOptions = {}): Promise<string | Blob | DocNode> {
const doc = this.outputDocument(options); // normalized copy, suggestions resolved if asked
switch (format) {
case "html": return doc.innerHTML;
case "text": return toText(doc);
case "markdown": return (await import("./convert/markdown")).toMarkdown(doc);
case "json": return (await import("./convert/json")).toJSON(doc);
case "docx": return (await import("./convert/docx")).toDocx(doc, this.page);
}
}
/** Replaces the document, or inserts at the caret, from another format. Undoable. */
@Method()
async importFrom(format: ImportFormat, data: string | Blob, { replace = true } = {}) { /* … */ }
/** Emitted by File > Download as. Call preventDefault() to handle the file yourself. */
@Event({ cancelable: true }) orbExport: EventEmitter<{ format: ExportFormat; data: string | Blob | DocNode }>;
- Markdown (
convert/markdown.ts):- Import: markdown-it with GFM tables and strikethrough (both built in). Task-list items are found after rendering: list items starting with
[ ]or[x]become checkboxes. - Export: a hand-written converter that walks the schema:
- paragraphs, headings, quotes, nested lists and tasks, fenced code with its language,
---, images, links and the bold/italic/strike/code marks; - tables become GFM tables, using
<br>inside cells; - Markdown special characters in text are escaped;
- underline, colors, fonts, alignment, indent, line height, page settings and comments are dropped (lossy, documented).
- paragraphs, headings, quotes, nested lists and tasks, fenced code with its language,
- Import: markdown-it with GFM tables and strikethrough (both built in). Task-list items are found after rendering: list items starting with
- DOCX:
-
Import: mammoth to HTML, then sanitize and normalize. mammoth keeps structure (headings, lists, tables, images) and drops direct formatting such as colors; document this.
-
Export: the
docxlibrary, walking the schema:- paragraphs and headings with
HeadingLevel; - text runs with bold, italics, underline, strike, color, size (in half-points), font and shading;
- lists through a numbering configuration;
- tables, images (
ImageRunfrom data URLs or fetched URLs; failures become alt text), hyperlinks and page breaks; - section page size and margins;
- headers and footers with
PageNumberfields.
Comments and suggestions map to
docxcomments and to inserted/deleted text runs. Verify the library supports both when building Phase 7. - paragraphs and headings with
-
- JSON: a plain tree of
{ type, attrs?, marks?, text?, children? }derived from the schema.getJSON()is shorthand for it. - PDF: File > Download as > PDF calls
print(). - Pasting from Word (
sanitize.ts):p.MsoListParagraph*withmso-list: lN levelMstyles become real nested lists. Thespan[style*="mso-list:Ignore"]bullet text is removed. - File > Open… accepts
.md,.markdown,.docx,.html,.htmand.txtthrough the existing hidden file input, choosing the format from the extension. - Optional
form-format="html" | "markdown" | "text"prop chooses what the form submits (0.9). Markdown needs its converter loaded before the first sync. HTML stays the default. - Dependencies:
markdown-itis already there. Addmammoth,docx,prismjs,emojibase-dataanddiff(jsdiff). Likemarkdown-it, they’re dev dependencies, imported withimport()so each becomes its own chunk.
Phase 6: Saving and history
6.1 Save and unsaved state
/** Shows a Save button in the toolbar */
@Prop() showSave = false;
/**
* Saves the document. While its promise is pending, the button shows a loading
* state. The document is marked saved only if it resolves. Without it, the
* document is marked saved as soon as `orbSave` is emitted.
*/
@Prop() save?: (content: SaveDetail) => Promise<void> | void;
/** Emitted when the user saves, from the button or Mod+S. Call preventDefault() to cancel. */
@Event({ cancelable: true }) orbSave: EventEmitter<SaveDetail>;
/** Emitted when the document becomes saved or unsaved */
@Event() orbDirtyChange: EventEmitter<boolean>;
@State() saving = false;
private savedHtml = "";
/** Marks the current content as saved, such as after saving it yourself */
@Method()
async markSaved() {
this.savedHtml = this.output().html;
this.syncDirty();
}
private async runSave() {
if (this.saving) return;
const detail = { html: this.output().html, text: this.output().text };
if (this.orbSave.emit(detail).defaultPrevented) return;
if (!this.save) return this.markSaved();
this.saving = true;
try {
await this.save(detail);
this.savedHtml = detail.html; // what was saved, even if typing continued
} finally {
this.saving = false;
this.syncDirty();
}
}
private syncDirty() {
const dirty = this.output().html !== this.savedHtml;
if (dirty === this.internals.states.has("dirty")) return;
toggleState(this.internals.states, "dirty", dirty);
this.orbDirtyChange.emit(dirty);
}
- The Save button is an
orb-buttonwithpending={this.saving}. A dot shows while there are unsaved changes. savedHtmlstarts as the output after loadingvalueorsetContent.orbEditorChangekeeps firing on every edit;orbSaveis the separate save event.- A form reset (0.9) doesn’t mark the document saved; unsaved state is still compared against the last save.
6.2 Versions and compare
export interface VersionInfo { id: string; label: string; date?: string; author?: string }
/** Earlier versions, newest first, shown in the toolbar's Versions menu */
@Prop() versions: VersionInfo[] = [];
/** Returns a version's HTML */
@Prop() loadVersion?: (id: string) => Promise<string>;
/** Emitted after a version is restored into the editor */
@Event() orbVersionRestore: EventEmitter<{ id: string }>;
@State() preview?: { version: VersionInfo; html: string; compare: boolean };
- Versions menu: an
orb-menulisting versions, each with anorb-relative-timeinslot="details". - Previewing a version:
- the editing area is replaced by a read-only view of that version (sanitized and normalized);
- the toolbar is replaced by a bar: “Viewing label” with Restore, Compare with current, and Back;
- undo history and the live content aren’t touched.
- Restore brings the version in as one undo step through
apply(), and emitsorbVersionRestore. The document becomes unsaved. - Compare (
convert/diff.ts, using jsdiff loaded on first use):- flatten both documents into blocks, each with a signature (tag, attributes, inline HTML);
- use
diffArraysto find added, removed and changed blocks; - for changed text blocks, use
diffWordsWithSpaceon the text for word-level changes; - render with the same styling as suggestions. A changed block with the same text is marked “formatting changed”.
6.3 Undo history across refresh (editing/history-store.ts)
/** Identifies the document, so its undo history can be restored after a refresh. Unique per document. */
@Prop() historyKey?: string;
/**
* Keeps undo history in IndexedDB while this tab is open, so it survives a
* refresh. Requires `history-key`. The history is written to disk; leave this
* off for sensitive documents on shared computers.
*/
@Prop() persistHistory = false;
/** Deletes this document's saved undo history, such as on logout */
@Method() async clearHistory() { /* … */ }
The prop is history-key, not key, because React and Stencil reserve key in JSX and never pass it to the element. If two editors on the same page share a history-key, log a warning.
Storage layout: database orb-rich-text, with two stores:
docs, keyed by${session}:${historyKey}:{ session, lastSeen, base, baseIndex, headHash, index };steps, keyed by[docKey, index]: one change step each.
New steps are written one at a time, so each write is small. When steps fall past the limit, they’re applied into base in batches of 50. The whole history is loaded when the editor starts, so undo stays synchronous.
Tab sessions and cleanup. IndexedDB is shared by every tab on the site, but sessionStorage belongs to a single tab, so cleanup can’t rely on sessionStorage alone or it would delete other tabs’ history. Each tab holds a Web Lock named after its session ID; locks are released automatically when a tab closes.
const SESSION = "orb-rich-text:session";
const GRACE_MS = 5 * 60_000;
/** This tab's id. Survives a refresh, but not a closed tab. A duplicated tab gets a new one. */
async function claimSession(): Promise<string> {
for (let attempt = 0; attempt < 2; attempt++) {
const id = (attempt === 0 && sessionStorage.getItem(SESSION)) || uid();
const got = await new Promise<boolean>((resolve) =>
navigator.locks.request(`orb-rich-text:${id}`, { ifAvailable: true }, (lock) => {
resolve(!!lock);
return lock ? new Promise(() => {}) : undefined; // held until the tab closes
}),
);
if (got) { sessionStorage.setItem(SESSION, id); return id; }
}
throw new Error("No session");
}
/** Deletes histories whose tab is closed. The grace period covers the gap during a refresh. */
async function collectGarbage(db: IDBDatabase) {
const held = new Set((await navigator.locks.query()).held?.map((lock) => lock.name));
// delete docs (and their steps) where !held.has(`orb-rich-text:${doc.session}`) && Date.now() - doc.lastSeen > GRACE_MS
}
- Duplicated tabs: Chrome copies sessionStorage when duplicating a tab. The copy finds its ID’s lock already held and creates a new ID.
- Restoring: on load, rebuild the HTML from
baseplus the steps. If its hash doesn’t match the normalizedvaluethe editor was given, throw the stored history away. Content restored by the browser (formStateRestoreCallback, 0.9) goes through the same check. uid()inutils/ids.tsusescrypto.randomUUID, with agetRandomValuesfallback for pages not served over HTTPS.- Fallbacks: if IndexedDB or Web Locks aren’t available, or storage is full, history stays in memory. The editor warns once in the console.
- Writes happen from
History.onRecord, pluslastSeenupdates when the page is hidden or closed (visibilitychangeandpagehide). - Tests: Playwright can test the multi-tab cases with several pages in one browser context.
Phase 7: Collaboration
Comments and suggested changes only. No real-time collaboration.
7.1 Comments
export interface Author { id: string; name: string; color?: string }
export interface CommentThread {
id: string;
author: Author;
date: string;
body: string;
resolved?: boolean;
replies?: { id: string; author: Author; date: string; body: string }[];
}
/** Who's editing. Used for comments and suggestions. */
@Prop() author?: Author;
/** Comment threads. Their anchors are stored in the HTML. */
@Prop({ mutable: true }) comments: CommentThread[] = [];
/** Shows the comments sidebar */
@Prop({ reflect: true }) commentsPanel = true;
@Event({ cancelable: true }) orbCommentAdd: EventEmitter<CommentThread>;
@Event({ cancelable: true }) orbCommentReply: EventEmitter<{ threadId: string; reply: CommentReply }>;
@Event({ cancelable: true }) orbCommentResolve: EventEmitter<{ threadId: string; resolved: boolean }>;
@Event({ cancelable: true }) orbCommentDelete: EventEmitter<{ threadId: string }>;
-
Data flow: the editor updates
commentsitself and emits an event; if the event is canceled, it reverts. The app stores the thread data; the anchors live in the HTML. -
HTML:
<span data-comment="c1 c2">. A list of IDs handles overlapping comments:export function addAnchor(root: HTMLElement, range: Range, id: string): Range { const split = splitBoundaries(range); const nodes = selectedTextNodes(root, split); for (const node of nodes) { const existing = closestMatching(node, root, "span[data-comment]"); if (existing) { const own = splitAround(existing, node); own.dataset.comment = `${own.dataset.comment} ${id}`; } else { wrapEach([node], () => Object.assign(document.createElement("span"), { dataset: { comment: id } })); } } mergeAdjacentAnchors(root); return spanOf(nodes); } export function removeAnchor(root: HTMLElement, id: string) { // remove id from each list; unwrap spans left without ids } -
Typing at the end of a comment inserts outside it, using the same
splitOutas pending formats, so comments don’t grow as you type. -
Clear formatting leaves comment anchors alone (
kind: "annotation"). Anchors are stripped from pasted content. -
Highlighting:
content.cssstylesspan[data-comment]with--editor-comment-bg;- the active thread’s anchors get
data-active, and resolved onesdata-resolved; both are runtime-only attributes set fromcomments.
-
Sidebar (
ui/sidebar.tsx): in the rightorb-split-panel.- Positioning: each card’s top matches its anchor’s position in the scrolling content. Overlapping cards are pushed down, and the active card is pulled level with its text. Recalculated on change, scroll and resize.
- Card contents: author,
orb-relative-time, body, replies, a replyorb-textbox(textarea), Resolve, and Delete (own comments only). - Narrow editors (under 600px): no sidebar. Clicking highlighted text opens the thread in a popover.
- Orphaned comments (anchor text deleted) show in a “Detached” section.
-
Adding a comment: the
commentcommand (Mod+Alt+M) needs selected text. It anchors a draft id and focuses a draft card; submitting emitsorbCommentAdd, and canceling removes the anchor. -
Comment mode: the content is read-only, but text can still be selected, and
getRangeworks on read-only content.
7.2 Suggested changes
HTML:
<ins data-suggestion="s1" data-author="u1" data-author-name="Ada" data-date="2026-11-17T10:00:00Z">new text</ins>
<del data-suggestion="s2" data-author="u1" data-author-name="Ada" data-date="…">old text</del>
Underline and strikethrough are identified as u and s only. Plain ins and del from outside sources are converted to u and s when pasted (0.2–0.3).
Editing in mode="suggest" (in the beforeinput handler):
export function suggestInsert(root: HTMLElement, range: Range, text: string, author: Author): Range {
if (!range.collapsed) range = suggestDelete(root, range, author, "forward");
const own = ownInsertionAt(root, range, author); // an <ins> by this author the caret is in or right after
if (own) return insertTextAt(range, text);
const at = splitOut(root, range, ["DEL"]); // never type inside a deletion
const ins = suggestionElement("ins", author);
ins.textContent = text;
at.insertNode(ins);
return endOf(ins);
}
export function suggestDelete(root: HTMLElement, target: Range, author: Author, direction: "backward" | "forward"): Range {
const split = splitBoundaries(target);
const nodes = selectedTextNodes(root, split);
for (const node of nodes) {
const ins = closestMatching(node, root, "ins[data-suggestion]");
if (ins?.dataset.author === author.id) { node.remove(); removeIfEmpty(ins); continue; } // your own insert: really delete
if (closestMatching(node, root, "del[data-suggestion]")) continue; // already deleted
wrapSuggestion(node, "del", author); // joins an adjacent deletion by the same author
}
return direction === "backward" ? startOf(nodes[0]) : endOf(nodes[nodes.length - 1]);
}
- What’s being deleted comes from
event.getTargetRanges(). It already covers word and line deletes, so the editor doesn’t work out ranges itself. - Joining adjacent suggestions:
wrapSuggestionmerges with a neighboring suggestion when the author matches, keeping that suggestion’s ID.wrapEach’s exact-attribute comparison would never match, because IDs and dates differ. - Paste marks the selection as deleted, then wraps the pasted text in
ins. - Input methods (IME): text being composed can’t be intercepted (
insertCompositionTextisn’t cancelable). Oncompositionend, the editor wraps the composed text inins, using the position saved atcompositionstart. - v1 scope: paragraph splits and formatting commands apply directly. This is documented.
Accepting and rejecting:
export function resolveSuggestion(root: HTMLElement, id: string, accept: boolean) {
for (const el of root.querySelectorAll<HTMLElement>(`[data-suggestion="${CSS.escape(id)}"]`)) {
const keep = (el.tagName === "INS") === accept;
if (keep) el.replaceWith(...Array.from(el.childNodes));
else el.remove();
}
}
- Commands: accept or reject the suggestion at the caret, accept all, reject all. They also appear on sidebar cards (“Ada suggested: Delete ‘old text’” with ✓ and ✗).
- Events:
orbSuggestionAcceptandorbSuggestionReject({ id }), after the change. - Display:
insis underlined anddelstruck through, in the author’s color;- author colors come from
author.coloror a hue derived from a hash of the author’s id; - View > Show suggestions off hides
deland removes theinsstyling.
- Counts and text export: word count,
getText()and lossy exports respectExportOptions.suggestions, defaulting to"reject".
Testing and docs, in every phase
- Playwright:
tests/rich-text-*.spec.tsin Chromium, Firefox and WebKit. Each feature gets:- output tests through
getContent(normalized); - keyboard tests with
page.keyboard; - undo round-trips (do something, undo, compare the HTML; redo, compare again);
- a paste test (
ClipboardEventwith aDataTransfer) for anything with a paste path.
- output tests through
- Accessibility: roles checked through the Chromium accessibility-tree helper in
menu.spec.ts. rich-text.mdgets a section and a live demo per feature, a Manual test list, a keyboard table, and an accessibility checklist, in themenubar.mdformat.- CSS custom properties each feature adds are documented at the top of
rich-text.cssorcontent.css.
Not in this plan
- writing assistants (only
spellcheckis included); shelved for now; - on-screen page layout;
- merging table cells;
- real-time collaboration;
- recording formatting changes and paragraph splits as suggestions;
minlength/maxlengthvalidation (apps can usesetCustomValidity);- a
labelsprop for translating the UI (all strings are English today; worth planning separately).
Where to start
A good first slice is the module split (0.1) plus the schema and cleanup step (0.2–0.3). It’s mostly moving existing code around, and it fixes the paste bugs right away.
Properties
codeLanguages
| Description | The languages offered for code blocks. Set it as a property. A language the highlighter doesn’t know is offered, but its code isn’t colored. |
|---|---|
| Attribute | – |
| Type | string[] |
| Default | [...DEFAULT_LANGUAGES] |
colors
| Description | The swatches in the color pickers. Set it as a property. |
|---|---|
| Attribute | – |
| Type | string[] |
| Default | [ "#000000", "#434343", "#666666", "#999999", "#b7b7b7", "#cccccc", "#d9d9d9", "#ffffff", "#e06666", "#f6b26b", "#ffd966", "#93c47d", "#76a5af", "#6fa8dc", "#8e7cc3", "#c27ba0", ] |
defaultValue
| Description | The content a form reset returns to. Defaults to the initial value. |
|---|---|
| Attribute | default-value |
| Type | string |
| Default | undefined |
disabled
| Description | Disables the editor. It isn’t submitted with the form. |
|---|---|
| Attribute | disabled |
| Type | boolean |
| Default | false |
fontSizes
| Description | The font sizes in points that the size picker offers, separated by spaces |
|---|---|
| Attribute | font-sizes |
| Type | string |
| Default | "8 9 10 11 12 14 18 24 30 36 48" |
fonts
| Description | The fonts the font picker offers. Set it as a property. “Default” is always offered first, and removes the font. |
|---|---|
| Attribute | – |
| Type | FontOption[] |
| Default | [ { label: "Arial", value: "Arial, sans-serif" }, { label: "Georgia", value: "Georgia, serif" }, { label: "Times New Roman", value: '"Times New Roman", serif' }, { label: "Courier New", value: '"Courier New", monospace' }, { label: "Verdana", value: "Verdana, sans-serif" }, { label: "Trebuchet MS", value: '"Trebuchet MS", sans-serif' }, ] |
label
| Description | Text above the editor |
|---|---|
| Attribute | label |
| Type | string |
| Default | undefined |
markdownPaste
| Description | Renders plain text that looks like Markdown when it’s pasted, such as a heading, a list or bold. When off, such text pastes as it is. |
|---|---|
| Attribute | markdown-paste |
| Type | boolean |
| Default | true |
maxHeight
| Description | The largest height of the writing area, after which it scrolls |
|---|---|
| Attribute | max-height |
| Type | string |
| Default | "500px" |
minHeight
| Description | The smallest height of the writing area |
|---|---|
| Attribute | min-height |
| Type | string |
| Default | "200px" |
note
| Description | Informational message below the editor |
|---|---|
| Attribute | note |
| Type | string |
| Default | undefined |
placeholder
| Description | Shown while the editor is empty |
|---|---|
| Attribute | placeholder |
| Type | string |
| Default | "Start typing..." |
readonly
| Description | Shows the content without allowing edits. Still focusable and submitted with the form. |
|---|---|
| Attribute | readonly |
| Type | boolean |
| Default | false |
ready
| Description | A promise that resolves when the component has completed it’s initial render |
|---|---|
| Attribute | – |
| Type | Promise<unknown> |
| Default | new Promise((res) => (this.#resolve = res)) |
required
| Description | Requires content before the form can be submitted |
|---|---|
| Attribute | required |
| Type | boolean |
| Default | false |
showWordCount
| Description | Shows the word and character counts below the editor |
|---|---|
| Attribute | show-word-count |
| Type | boolean |
| Default | true |
spellcheck
| Description | Underlines misspelled words, using the browser’s spell checker |
|---|---|
| Attribute | spellcheck |
| Type | boolean |
| Default | true |
toolbar
| Description | The toolbar’s controls, in order. | separates groups. Commands not listed are still available from keyboard shortcuts. Groups that don’t fit move into a More menu. |
|---|---|
| Attribute | toolbar |
| Type | string |
| Default | DEFAULT_TOOLBAR |
value
| Description | The content, as HTML. It updates as the user edits: right after commands like Bold, and after each pause in typing. getContent() is always current. |
|---|---|
| Attribute | value |
| Type | string |
| Default | "" |
Events
orbEditorBlur
| Description | Emits when the content area loses focus, including to the toolbar |
|---|---|
| Type | CustomEvent<FocusEvent> |
orbEditorChange
| Description | Emits after each change, with the saved HTML and text. Both are computed only when read. |
|---|---|
| Type | CustomEvent<EditorChangeEvent> |
orbEditorFocus
| Description | Emits when the content area gains focus |
|---|---|
| Type | CustomEvent<FocusEvent> |
Methods
clear
| Description | Removes all content. The undo history starts over. |
|---|---|
| Signature | clear() => Promise<void> |
getContent
| Description | The content as canonical HTML, the form of the saved value |
|---|---|
| Signature | getContent() => Promise<string> |
getText
| Description | The content as plain text, with a line per block |
|---|---|
| Signature | getText() => Promise<string> |
resetValidity
| Description | Clears custom errors and the user interaction state, so validation styling is hidden until the user interacts with the editor again. |
|---|---|
| Signature | resetValidity() => Promise<void> |
setContent
| Description | Replaces the content with html, which is cleaned before it’s shown. The undo history starts over, and no input event fires. |
|---|---|
| Signature | setContent(html: string) => Promise<void> |
| Parameters | html (string) |
setCustomValidity
| Description | Sets a custom validation error. Pass an empty string to clear it. |
|---|---|
| Signature | setCustomValidity(message: string) => Promise<void> |
| Parameters | message (string) |
Slots
| Slot | Description |
|---|---|
"label" |
The label, instead of the label prop |
"note" |
The note, instead of the note prop |
Shadow Parts
| Part | Description |
|---|---|
"content" |
The writing area |
"footer" |
The word and character counts |
"shell" |
The bordered editor: toolbar, content and footer |
"toolbar" |
The row of formatting controls |
CSS Custom Properties
| Name | Description |
|---|---|
--editor-bg |
Background of the writing area |
--editor-border-color |
Border around the editor and between its sections |
--editor-border-radius |
Corner radius of the editor |
--editor-button-active |
Background of a pressed toolbar button, such as Bold while bold text is selected |
--editor-code-bg |
Background of code blocks and inline code |
--editor-code-comment |
Color of comments in code |
--editor-code-function |
Color of function names in code |
--editor-code-keyword |
Color of keywords in code |
--editor-code-number |
Color of numbers and constants in code |
--editor-code-operator |
Color of operators and punctuation in code |
--editor-code-property |
Color of properties, tags and variables in code |
--editor-code-string |
Color of strings in code |
--editor-code-type |
Color of types, classes and built-ins in code |
--editor-focus-color |
Border and focus ring color while the editor has focus, and link color |
--editor-footer-color |
Word count text color |
--editor-invalid-color |
Border color after a failed validation |
--editor-line-height |
Line height of the writing area |
--editor-muted-color |
Placeholder and blockquote text color |
--editor-picker-hover-bg |
Hovered background of a picker cell, tab or button, in the special characters, emoji and color pickers |
--editor-text-color |
Text color |
--editor-toolbar-bg |
Background of the toolbar and footer |
Dependencies
Depends on
- orb-label
- orb-button-group
- orb-button
- orb-note
- orb-tooltip
- orb-menu
- orb-mi
- orb-overlay
- orb-popover
- orb-textbox