@lyads/visual-editor 0.0.0-stage → 1.0.1

package/dist/core/document.d.ts

@@ -0,0 +1,99 @@
+import * as v from 'valibot';
+import type { HtmlNodeType } from './html-content-model';
+export type DocumentKind = 'email' | 'page';
+export type EditorMode = 'visual' | 'html';
+export interface NodeMetadata {
+    readonly blockType?: string;
+    readonly sourceStart?: number;
+    readonly sourceEnd?: number;
+    readonly namespace?: string;
+    /**
+     * How a comment was written: `<!--` for a regular comment, or the opener of the bogus
+     * comment the parser read (`<![if !mso]>`, `<?xml ... ?>`, `</3>`). Absent on old documents.
+     */
+    readonly commentOpener?: CommentOpener;
+}
+export type CommentOpener = '<!--' | '<!' | '<?' | '</';
+export interface DocumentNode {
+    readonly id: string;
+    readonly type: HtmlNodeType;
+    readonly tag?: string;
+    readonly value?: string;
+    readonly attrs?: Readonly<Record<string, string>>;
+    readonly children?: readonly DocumentNode[];
+    readonly metadata?: NodeMetadata;
+}
+export interface EditorDocumentData {
+    readonly schemaVersion: 1;
+    readonly id: string;
+    readonly kind: DocumentKind;
+    readonly revision: number;
+    readonly title: string;
+    readonly nodes: readonly DocumentNode[];
+    readonly css: string;
+}
+export interface SourceInput {
+    readonly html: string;
+    readonly css: string;
+}
+/**
+ * `error` refuses the operation. `warning` tells the author something was removed or
+ * rewritten. `info` describes what the document holds and was kept as written.
+ */
+export type DiagnosticSeverity = 'error' | 'warning' | 'info';
+export interface Diagnostic {
+    readonly code: string;
+    readonly severity: DiagnosticSeverity;
+    readonly messageKey: string;
+    /** First node the notice refers to, when it still exists in the document. */
+    readonly nodeId?: string;
+    /** Occurrences grouped under this code; absent means one. */
+    readonly count?: number;
+}
+export interface ImportResult {
+    readonly document?: EditorDocumentData;
+    readonly diagnostics: readonly Diagnostic[];
+    /**
+     * The validated aggregate `document` was read from, when the codec has it: a policy given it
+     * checks the content again without parsing the schema a second time.
+     */
+    readonly validated?: EditorDocument;
+}
+export declare const DOCUMENT_LIMITS: Readonly<{
+    nodes: 50000;
+    totalNodes: 150000;
+    depth: 256;
+    sourceBytes: 2000000;
+    cssBytes: 500000;
+    jsonBytes: 64000000;
+    attributesPerNode: 256;
+    attributeLength: 16384;
+    documentAttributeLength: 2000000;
+}>;
+/** Every element the HTML parser and serializer treat as void, obsolete ones included. */
+export declare const HTML_VOID_ELEMENTS: readonly string[];
+export declare const DocumentNodeSchema: v.GenericSchema<DocumentNode>;
+export declare const EditorDocumentSchema: v.GenericSchema<EditorDocumentData>;
+export declare class DocumentValidationError extends Error {
+    readonly code: string;
+    constructor(code: string);
+}
+/** The aggregate owns a validated snapshot. Callers only receive independent copies. */
+export declare class EditorDocument {
+    #private;
+    private constructor();
+    static from(data: unknown): EditorDocument;
+    get id(): string;
+    get kind(): DocumentKind;
+    get revision(): number;
+    snapshot(): EditorDocumentData;
+    withChanges(change: Partial<Pick<EditorDocumentData, 'title' | 'nodes' | 'css'>>): EditorDocument;
+    /** UTF-8 size of the serialized snapshot, for budgets which bound what is retained. */
+    serializedBytes(): number;
+    /** Only the revision changes: the validated tree is not parsed a second time. */
+    withRevision(revision: number): EditorDocument;
+    private clone;
+    private static assertBounded;
+    private static normalizeText;
+    private static assertTree;
+}

package/dist/core/history.d.ts

@@ -0,0 +1,26 @@
+import type { EditorDocument } from './document';
+/** What a history keeps: an immutable, validated document which knows its serialized size. */
+export interface HistoryEntry {
+    serializedBytes(): number;
+}
+/**
+ * One history per editing session. A new branch discards only the redo branch. The HTML
+ * document (schema 1) and the block piece (schema 2) use the same history.
+ */
+export declare class DocumentHistory<T extends HistoryEntry = EditorDocument> {
+    #private;
+    /**
+     * A document inside the import limits can serialize to about 30 MB of JSON, and its history
+     * has to hold it at least twice.
+     */
+    constructor(maxEntries?: number, maxBytes?: number);
+    get canUndo(): boolean;
+    get canRedo(): boolean;
+    get size(): number;
+    get retainedBytes(): number;
+    push(document: T): void;
+    current(): T | undefined;
+    undo(): T | undefined;
+    redo(): T | undefined;
+    reset(document?: T): void;
+}

package/dist/core/html-content-model.d.ts

@@ -0,0 +1,32 @@
+export type HtmlNodeType = 'element' | 'text' | 'comment' | 'doctype';
+export interface HtmlContentNode {
+    readonly type: HtmlNodeType;
+    readonly tag?: string;
+    readonly value?: string;
+}
+/** Structural constraints prevent HTML parsers from silently relocating or dropping nodes. */
+export declare class HtmlContentModel {
+    private readonly requiredParents;
+    private readonly structuralChildren;
+    /** Parents the HTML parser itself guarantees; anything else it accepts where it was written. */
+    private readonly parserParents;
+    /** Children the parser leaves inside these parents instead of moving them elsewhere. */
+    private readonly parserChildren;
+    /** HTML elements whose content the tokenizer reads as text, never as markup. */
+    private readonly rawText;
+    /**
+     * Whether a tree an HTML parser produced may hold this child. It is the integrity rule of
+     * a stored document: looser than `accepts`, which governs what editing commands may build.
+     */
+    parses(parentTag: string | undefined, child: HtmlContentNode): boolean;
+    /**
+     * Elements whose single text child is their source, written back verbatim: the raw text
+     * elements of HTML, `template`, and whole inline `svg` / `math` islands.
+     */
+    holdsSource(tag: string): boolean;
+    /** Markup kept as an opaque block of source rather than as a subtree. */
+    isSourceIsland(tag: string): boolean;
+    accepts(parentTag: string | undefined, child: HtmlContentNode): boolean;
+    acceptsChildren(parentTag: string, children: readonly HtmlContentNode[]): boolean;
+    isStructuralContainer(tag: string): boolean;
+}

package/dist/core/html-escape.d.ts

@@ -0,0 +1,2 @@
+/** Escapes a value for an HTML text node or a double-quoted attribute. */
+export declare function escapeHtml(value: string): string;

package/dist/core/rich-text-format.d.ts

@@ -0,0 +1,14 @@
+export declare const RICH_TEXT_FORMATS: readonly ["bold", "italic", "underline", "strike", "link"];
+export type RichTextFormat = (typeof RICH_TEXT_FORMATS)[number];
+export type RichTextDecorationLine = 'underline' | 'line-through';
+export declare const RICH_TEXT_ORIGIN_ATTRIBUTE = "data-editor-rich-origin";
+export declare const RICH_TEXT_REMOVED_ATTRIBUTE = "data-editor-rich-removed";
+/** Canonical semantic-mark removal transitions and their fixed visual resets. */
+export declare class RichTextFormatPolicy {
+    formatForTag(tag: string | undefined): RichTextFormat | undefined;
+    isFormat(value: unknown): value is RichTextFormat;
+    canRemove(originalTag: string | undefined, replacementTag: string | undefined, format: unknown): boolean;
+    resets(format: RichTextFormat): Readonly<Record<string, string>>;
+    decorationFor(format: RichTextFormat): RichTextDecorationLine | undefined;
+    removedAttributes(format: RichTextFormat): readonly string[];
+}

package/dist/core/rich-text-markup.d.ts

@@ -0,0 +1,28 @@
+import type { DocumentNode } from './document';
+/**
+ * `block`: paragraphs, lists, headings and quotes (the HTML document and the text and footer
+ * blocks). `inline`: one line of formatted text with links (heading block). `button`: formatted
+ * text without links, since the button is the link.
+ */
+export type RichTextMode = 'block' | 'inline' | 'button';
+export type RichTextMarkupViolation = 'tag' | 'attribute' | 'style' | 'node';
+export interface RichTextMarkupCheck {
+    /** Attributes the caller adds to every element, e.g. the origin marks of schema 1. */
+    readonly extraAttributes?: readonly string[];
+    /** Whether a `style` attribute holds only the declarations a rich text may carry. */
+    style(value: string): boolean;
+    /** A further rule for one element; false makes the tree invalid. */
+    element?(node: DocumentNode): boolean;
+}
+/**
+ * The single rule of the markup a rich-text projection may hold once it is imported: which
+ * elements each mode accepts and which attributes each element keeps. The in-place editing of
+ * the HTML document (schema 1) and the texts of the block pieces (schema 2) both apply it.
+ */
+export declare class RichTextMarkup {
+    tags(mode: RichTextMode): ReadonlySet<string>;
+    /** The attributes an element of the projection keeps besides `style`. */
+    semanticAttributes(tag: string): readonly string[];
+    /** The first rule the tree breaks, or undefined when all of it follows the mode. */
+    violation(nodes: readonly DocumentNode[], mode: RichTextMode, check: RichTextMarkupCheck): RichTextMarkupViolation | undefined;
+}

package/dist/core/section-layout.d.ts

@@ -0,0 +1,83 @@
+import * as v from 'valibot';
+import type { DocumentKind, DocumentNode, EditorDocumentData } from './document';
+export declare const SECTION_LAYOUT_LIMITS: Readonly<{
+    columns: 4;
+    weight: 12;
+}>;
+export declare const SECTION_STACKING: readonly ["normal", "reverse", "none"];
+export declare const SECTION_BREAKPOINTS: readonly [480, 640, 768];
+export declare const SECTION_LAYOUT_PRESETS: readonly [{
+    readonly id: "single";
+    readonly ratios: readonly [1];
+    readonly titleKey: "properties.oneColumn";
+}, {
+    readonly id: "equal2";
+    readonly ratios: readonly [1, 1];
+    readonly titleKey: "properties.twoColumns";
+}, {
+    readonly id: "wideLeft";
+    readonly ratios: readonly [2, 1];
+    readonly titleKey: "properties.widerLeft";
+}, {
+    readonly id: "wideRight";
+    readonly ratios: readonly [1, 2];
+    readonly titleKey: "properties.widerRight";
+}, {
+    readonly id: "equal3";
+    readonly ratios: readonly [1, 1, 1];
+    readonly titleKey: "properties.threeColumns";
+}, {
+    readonly id: "equal4";
+    readonly ratios: readonly [1, 1, 1, 1];
+    readonly titleKey: "properties.fourColumns";
+}];
+export type SectionStacking = (typeof SECTION_STACKING)[number];
+export type SectionBreakpoint = (typeof SECTION_BREAKPOINTS)[number];
+export type SectionLayoutReason = 'unsupported-structure' | 'invalid-settings' | 'column-not-empty' | 'identity-bearing-column' | 'readonly' | 'unavailable';
+export interface SectionLayoutSettings {
+    readonly ratios: readonly number[];
+    readonly stacking: SectionStacking;
+    readonly breakpoint: SectionBreakpoint;
+}
+export interface SectionLayoutPatch {
+    readonly ratios?: readonly number[];
+    readonly stacking?: SectionStacking;
+    readonly breakpoint?: SectionBreakpoint;
+}
+export interface SectionLayoutContext extends SectionLayoutSettings {
+    readonly id: string;
+    readonly kind: DocumentKind;
+    readonly columnIds: readonly string[];
+    readonly removableColumnIds: readonly string[];
+    readonly editable: boolean;
+    readonly reason?: SectionLayoutReason;
+}
+export interface SectionLayoutProjection {
+    readonly section: DocumentNode;
+    readonly columns: readonly DocumentNode[];
+    readonly contentParent?: DocumentNode;
+    readonly shell?: readonly DocumentNode[];
+}
+export declare const SectionLayoutSettingsSchema: v.StrictObjectSchema<{
+    readonly ratios: v.SchemaWithPipe<readonly [v.ArraySchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>, v.MaxValueAction<number, 12, undefined>]>, undefined>, v.MinLengthAction<number[], 1, undefined>, v.MaxLengthAction<number[], 4, undefined>]>;
+    readonly stacking: v.PicklistSchema<readonly ["normal", "reverse", "none"], undefined>;
+    readonly breakpoint: v.PicklistSchema<readonly [480, 640, 768], undefined>;
+}, undefined>;
+export declare const SectionLayoutPatchSchema: v.StrictObjectSchema<{
+    readonly ratios: v.ExactOptionalSchema<v.SchemaWithPipe<readonly [v.ArraySchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>, v.MaxValueAction<number, 12, undefined>]>, undefined>, v.MinLengthAction<number[], 1, undefined>, v.MaxLengthAction<number[], 4, undefined>]>, undefined>;
+    readonly stacking: v.ExactOptionalSchema<v.PicklistSchema<readonly ["normal", "reverse", "none"], undefined>, undefined>;
+    readonly breakpoint: v.ExactOptionalSchema<v.PicklistSchema<readonly [480, 640, 768], undefined>, undefined>;
+}, undefined>;
+/** Structural projection only: an imported marker never grants a mutation by itself. */
+export declare class SectionLayoutPolicy {
+    hasClass(node: DocumentNode, name: string): boolean;
+    projection(document: EditorDocumentData, id: string): SectionLayoutProjection | undefined;
+    columnBody(column: DocumentNode): DocumentNode | undefined;
+    context(document: EditorDocumentData, id: string): SectionLayoutContext | undefined;
+    removalReason(column: DocumentNode, kind: DocumentKind): SectionLayoutReason | undefined;
+    settings(current: SectionLayoutContext, patch: SectionLayoutPatch): SectionLayoutSettings;
+    attributes(settings: SectionLayoutSettings): Readonly<Record<string, string>>;
+    elements(node: DocumentNode): readonly DocumentNode[];
+    private onlyElement;
+    private path;
+}