@texuli/core 0.1.0-next.0 → 0.1.0-next.1

package/dist/editor/model.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `@texuli/core/editor-model`: the rich text editor document model (ADR-003).
+ * Types and caps, the closed vocabularies, constructors, normalization,
+ * validation, the untrusted loader, selection helpers, grapheme and word
+ * boundaries, and the nested inline interchange shape. Framework-free.
+ */
+export { blockLength, blockText, createEditorIds, type EditorAncestor, type EditorIdSource, type EditorLocation, editorBlockCount, editorCharCount, editorLeaves, editorPlainText, emptyEditorDocument, isTextBlock, isVoidBlock, locateBlock, nextEditorId, normalizeDocument, paragraph, removeBlocks, replaceBlock, replaceItem, validateEditorDocument, } from './document.js';
+export { graphemeBoundaries, nextGrapheme, nextWord, previousGrapheme, previousWord, snapToGrapheme, } from './graphemes.js';
+export { cleanText, hasMark, inheritedMarks, inlineLength, inlineText, markKey, normalizeInline, sliceInline, sortMarks, textToInline, } from './inline.js';
+export { type EditorLoadOptions, type EditorLoadResult, loadEditorDocument } from './load.js';
+export { caret, clampSelection, type EditorRangePoint, isCollapsed, nodeSelection, selectAll, selectionRange, startSelection, textSelection, } from './selection.js';
+export { type EditorInlineNode, inlineFromTree, inlineToTree } from './tree.js';
+export { EDITOR_BLOCK_TYPES, EDITOR_LIMITS, EDITOR_MARK_ORDER, type EditorBlock, type EditorBlockId, type EditorBlockType, type EditorCodeBlock, type EditorDivider, type EditorDocument, type EditorHeading, type EditorHeadingLevel, type EditorInline, type EditorIssue, type EditorIssueCode, type EditorLimits, type EditorList, type EditorListItem, type EditorListKind, type EditorMark, type EditorMarkType, type EditorMedia, type EditorParagraph, type EditorPoint, type EditorQuote, type EditorRichBlock, type EditorSelection, type EditorState, type EditorTextBlock, type EditorTransformResult, } from './types.js';

package/dist/editor/model.js

@@ -0,0 +1,13 @@
+/**
+ * `@texuli/core/editor-model`: the rich text editor document model (ADR-003).
+ * Types and caps, the closed vocabularies, constructors, normalization,
+ * validation, the untrusted loader, selection helpers, grapheme and word
+ * boundaries, and the nested inline interchange shape. Framework-free.
+ */
+export { blockLength, blockText, createEditorIds, editorBlockCount, editorCharCount, editorLeaves, editorPlainText, emptyEditorDocument, isTextBlock, isVoidBlock, locateBlock, nextEditorId, normalizeDocument, paragraph, removeBlocks, replaceBlock, replaceItem, validateEditorDocument, } from "./document.js";
+export { graphemeBoundaries, nextGrapheme, nextWord, previousGrapheme, previousWord, snapToGrapheme, } from "./graphemes.js";
+export { cleanText, hasMark, inheritedMarks, inlineLength, inlineText, markKey, normalizeInline, sliceInline, sortMarks, textToInline, } from "./inline.js";
+export { loadEditorDocument } from "./load.js";
+export { caret, clampSelection, isCollapsed, nodeSelection, selectAll, selectionRange, startSelection, textSelection, } from "./selection.js";
+export { inlineFromTree, inlineToTree } from "./tree.js";
+export { EDITOR_BLOCK_TYPES, EDITOR_LIMITS, EDITOR_MARK_ORDER, } from "./types.js";

package/dist/editor/selection.d.ts

@@ -0,0 +1,27 @@
+import type { EditorBlockId, EditorDocument, EditorPoint, EditorSelection } from './types.js';
+/** A collapsed text selection (a caret) at `offset` in `block`. */
+export declare const caret: (block: EditorBlockId, offset?: number) => EditorSelection;
+/** A text selection from `anchor` to `focus` (either order). */
+export declare const textSelection: (anchor: EditorPoint, focus?: EditorPoint) => EditorSelection;
+/** Select the void block (divider, media) `block`. */
+export declare const nodeSelection: (block: EditorBlockId) => EditorSelection;
+export declare const isCollapsed: (selection: EditorSelection) => boolean;
+/** A point in document order: the leaf index, then the offset. */
+export interface EditorRangePoint extends EditorPoint {
+    index: number;
+}
+/** The ordered ends of a selection, or `null` when it points outside the document. */
+export declare function selectionRange(doc: EditorDocument, selection: EditorSelection): {
+    from: EditorRangePoint;
+    to: EditorRangePoint;
+} | null;
+/**
+ * A selection that is valid in `doc`: points inside text blocks, offsets
+ * clamped and snapped to grapheme boundaries. A selection on a missing block
+ * falls back to the start of the first text block (or the first leaf).
+ */
+export declare function clampSelection(doc: EditorDocument, selection: EditorSelection): EditorSelection;
+/** A caret at the start of the document. */
+export declare function startSelection(doc: EditorDocument): EditorSelection;
+/** Select the whole document (first text block start to last text block end). */
+export declare function selectAll(doc: EditorDocument): EditorSelection;

package/dist/editor/selection.js

@@ -0,0 +1,85 @@
+import { blockLength, blockText, editorLeaves, isTextBlock } from "./document.js";
+import { snapToGrapheme } from "./graphemes.js";
+/** A collapsed text selection (a caret) at `offset` in `block`. */
+export const caret = (block, offset = 0) => ({
+    kind: 'text',
+    anchor: { block, offset },
+    focus: { block, offset },
+});
+/** A text selection from `anchor` to `focus` (either order). */
+export const textSelection = (anchor, focus = anchor) => ({
+    kind: 'text',
+    anchor,
+    focus,
+});
+/** Select the void block (divider, media) `block`. */
+export const nodeSelection = (block) => ({ kind: 'node', block });
+export const isCollapsed = (selection) => selection.kind === 'text' &&
+    selection.anchor.block === selection.focus.block &&
+    selection.anchor.offset === selection.focus.offset;
+/** The ordered ends of a selection, or `null` when it points outside the document. */
+export function selectionRange(doc, selection) {
+    const leaves = editorLeaves(doc);
+    const indexOf = (id) => leaves.findIndex(({ block }) => block.id === id);
+    if (selection.kind === 'node') {
+        const index = indexOf(selection.block);
+        if (index === -1)
+            return null;
+        const point = { block: selection.block, offset: 0, index };
+        return { from: point, to: point };
+    }
+    const a = { ...selection.anchor, index: indexOf(selection.anchor.block) };
+    const f = { ...selection.focus, index: indexOf(selection.focus.block) };
+    if (a.index === -1 || f.index === -1)
+        return null;
+    const forward = a.index < f.index || (a.index === f.index && a.offset <= f.offset);
+    return forward ? { from: a, to: f } : { from: f, to: a };
+}
+const firstText = (doc) => editorLeaves(doc).find(({ block }) => isTextBlock(block))?.block;
+function clampPoint(doc, point) {
+    const leaf = editorLeaves(doc).find(({ block }) => block.id === point.block)?.block;
+    if (!leaf || !isTextBlock(leaf))
+        return null;
+    const offset = Math.max(0, Math.min(blockLength(leaf), Math.trunc(point.offset) || 0));
+    return { block: leaf.id, offset: snapToGrapheme(blockText(leaf), offset) };
+}
+/**
+ * A selection that is valid in `doc`: points inside text blocks, offsets
+ * clamped and snapped to grapheme boundaries. A selection on a missing block
+ * falls back to the start of the first text block (or the first leaf).
+ */
+export function clampSelection(doc, selection) {
+    if (selection.kind === 'node') {
+        const leaf = editorLeaves(doc).find(({ block }) => block.id === selection.block)?.block;
+        if (leaf && !isTextBlock(leaf))
+            return selection;
+    }
+    else {
+        const anchor = clampPoint(doc, selection.anchor);
+        const focus = clampPoint(doc, selection.focus);
+        if (anchor && focus) {
+            const same = anchor.offset === selection.anchor.offset && focus.offset === selection.focus.offset;
+            return same ? selection : textSelection(anchor, focus);
+        }
+    }
+    return startSelection(doc);
+}
+/** A caret at the start of the document. */
+export function startSelection(doc) {
+    const text = firstText(doc);
+    if (text)
+        return caret(text.id);
+    const leaf = editorLeaves(doc)[0]?.block;
+    return nodeSelection(leaf.id);
+}
+/** Select the whole document (first text block start to last text block end). */
+export function selectAll(doc) {
+    const texts = editorLeaves(doc)
+        .map(({ block }) => block)
+        .filter(isTextBlock);
+    const first = texts[0];
+    const last = texts.at(-1);
+    if (!first || !last)
+        return startSelection(doc);
+    return textSelection({ block: first.id, offset: 0 }, { block: last.id, offset: blockLength(last) });
+}

package/dist/editor/transforms.d.ts

@@ -0,0 +1,93 @@
+import { type HrefTrust } from '../url/safe-href.js';
+import { type EditorIdSource } from './document.js';
+import { type EditorBlock, type EditorBlockId, type EditorDocument, type EditorHeadingLevel, type EditorLimits, type EditorListKind, type EditorMarkType, type EditorState, type EditorTextBlock, type EditorTransformResult } from './types.js';
+export interface EditorTransformOptions {
+    newId?: EditorIdSource;
+    /** Lower caps for this editor (a blocks `text` field holds 4,000 characters). */
+    limits?: Partial<EditorLimits>;
+}
+declare const textLeaf: (doc: EditorDocument, id: EditorBlockId) => EditorTextBlock | undefined;
+/**
+ * Type `text` at the selection (replacing a range). Rich blocks give the text
+ * the stored marks, else the marks before the caret; `\n` becomes a break.
+ * Code keeps newlines and tabs. Unsafe characters are stripped.
+ */
+export declare function insertText(state: EditorState, text: string, options?: EditorTransformOptions): EditorTransformResult;
+/** Shift+Enter: a break in rich blocks, a newline in code. */
+export declare function insertBreak(state: EditorState, options?: EditorTransformOptions): EditorTransformResult;
+/** Delete the selection (a range or a selected void block). */
+export declare function deleteSelection(state: EditorState, options?: EditorTransformOptions): EditorTransformResult;
+export type EditorDeleteUnit = 'grapheme' | 'word' | 'line';
+/** Backspace: delete before the caret, or apply the block-start rules (lift, join, select a void block). */
+export declare const deleteBackward: (state: EditorState, unit?: EditorDeleteUnit, options?: EditorTransformOptions) => EditorTransformResult;
+/** Delete: delete after the caret, or join the next block. */
+export declare const deleteForward: (state: EditorState, unit?: EditorDeleteUnit, options?: EditorTransformOptions) => EditorTransformResult;
+/** Shift+Tab in a list: move the caret's item out one level. */
+export declare function liftListItem(state: EditorState, options?: EditorTransformOptions): EditorTransformResult;
+/** Tab in a list: nest the caret's item under the previous item. */
+export declare function sinkListItem(state: EditorState, options?: EditorTransformOptions): EditorTransformResult;
+/** Mod+Enter: check or uncheck the caret's todo item. */
+export declare function toggleTodo(state: EditorState, options?: EditorTransformOptions): EditorTransformResult;
+/**
+ * Enter. Splits the block; in list items continues the list (an empty item
+ * lifts out); an empty last paragraph of a quote leaves it; at the end of a
+ * heading the new block is a paragraph; in code it inserts a newline, and an
+ * empty last line leaves the code block.
+ */
+export declare function splitBlock(state: EditorState, options?: EditorTransformOptions): EditorTransformResult;
+/** Make the selected text blocks paragraphs, headings or code. A list item's first block stays a paragraph. */
+export declare function setBlockType(state: EditorState, type: 'paragraph' | 'heading' | 'code', level?: EditorHeadingLevel, options?: EditorTransformOptions): EditorTransformResult;
+/**
+ * Bullet, ordered or todo list. Inside a list of that kind the selected items
+ * leave it; inside another kind the list changes kind; elsewhere the selected
+ * paragraphs and headings become items.
+ */
+export declare function toggleList(state: EditorState, kind: EditorListKind, options?: EditorTransformOptions): EditorTransformResult;
+/** Wrap the selected blocks in a quote, or unwrap the quote around the caret. */
+export declare function toggleQuote(state: EditorState, options?: EditorTransformOptions): EditorTransformResult;
+/**
+ * Toggle a mark over the selection (removed when every eligible character has
+ * it). At a caret it toggles the stored marks for the next typed text. Code
+ * text takes only `link` besides `code`.
+ */
+export declare function toggleMark(state: EditorState, type: Exclude<EditorMarkType, 'link'>, options?: EditorTransformOptions): EditorTransformResult;
+export interface SetLinkOptions extends EditorTransformOptions {
+    /** URL policy tier. Default `untrusted`; pasted and typed URLs stay untrusted. */
+    trust?: HrefTrust;
+    /** At a caret: insert this text as the link. */
+    text?: string;
+}
+/**
+ * Link the selection to `href`, which must pass `safeHref` at `trust`
+ * (`untrusted` by default) or the edit is refused. At a caret, updates the
+ * link around it, or inserts `options.text` as a new link.
+ */
+export declare function setLink(state: EditorState, href: string, options?: SetLinkOptions): EditorTransformResult;
+/** Remove links from the selection, or the whole link around the caret. */
+export declare function removeLink(state: EditorState, options?: EditorTransformOptions): EditorTransformResult;
+export type EditorVoidInsert = {
+    type: 'divider';
+} | {
+    type: 'media';
+    ref: string;
+    alt?: string;
+};
+/** Insert a divider or a media reference at the caret; the caret moves to the text after it. */
+export declare function insertBlock(state: EditorState, insert: EditorVoidInsert, options?: EditorTransformOptions): EditorTransformResult;
+/**
+ * Paste: replace the selection with `fragment` (a loaded document or blocks,
+ * already sanitized by `loadEditorDocument`, `fromMarkdown` or the paste
+ * import). One paragraph pastes inline; several blocks split the caret block
+ * around them. Blocks that would nest too deep become plain paragraphs, and
+ * blocks past the size caps are cut, each with a diagnostic.
+ */
+export declare function replaceSelection(state: EditorState, fragment: EditorDocument | readonly EditorBlock[], options?: EditorTransformOptions): EditorTransformResult;
+/**
+ * Apply what an input method composed: the block's text as the DOM shows it
+ * after `compositionend` (breaks as `\n`) is diffed against the model, and the
+ * one changed span is replaced as a single edit.
+ */
+export declare function applyComposition(state: EditorState, blockId: EditorBlockId, domText: string, options?: EditorTransformOptions): EditorTransformResult;
+/** Move the caret's block (or its list item) one place up or down among its siblings. */
+export declare function moveBlock(state: EditorState, direction: 'up' | 'down', options?: EditorTransformOptions): EditorTransformResult;
+export { textLeaf as editorTextBlock };