@lyfie/luthor-headless 2.3.6 → 2.5.0

package/README.md

@@ -1,12 +1,12 @@
 <div align="center">
-  <img src="https://raw.githubusercontent.com/lyfie-app/luthor/main/apps/web/public/luthor-logo-horizontal.png" alt="Luthor" width="360" />
+  <img src="https://raw.githubusercontent.com/lyfie-org/luthor/main/apps/web/public/luthor-logo-horizontal.png" alt="Luthor" width="360" />
   <h1>@lyfie/luthor-headless</h1>
   <p><strong>Headless, extension-first rich text editor runtime for React on top of Lexical.</strong></p>
 </div>
 
 <div align="center">
 
-[![Project Status](https://img.shields.io/badge/status-active%20development-orange?style=flat-square)](https://github.com/lyfie-org/luthor)
+[![Project Status](https://img.shields.io/badge/status-stable%20release%20%7C%20internal%20QA-yellowgreen?style=flat-square)](https://github.com/lyfie-org/luthor)
 [![Stability](https://img.shields.io/badge/stable%20release-expected%20soon-blue?style=flat-square)](https://github.com/lyfie-org/luthor/releases)
 
 [![npm version](https://img.shields.io/npm/v/@lyfie/luthor-headless?style=flat-square)](https://www.npmjs.com/package/@lyfie/luthor-headless)
@@ -14,7 +14,7 @@
 [![bundle size](https://img.shields.io/bundlephobia/minzip/@lyfie/luthor-headless?style=flat-square)](https://bundlephobia.com/package/@lyfie/luthor-headless)
 [![types](https://img.shields.io/npm/types/@lyfie/luthor-headless?style=flat-square)](https://www.npmjs.com/package/@lyfie/luthor-headless)
 [![license](https://img.shields.io/npm/l/@lyfie/luthor-headless?style=flat-square)](https://github.com/lyfie-org/luthor/blob/main/LICENSE)
-[![last commit](https://img.shields.io/github/last-commit/lyfie-app/luthor/main?style=flat-square)](https://github.com/lyfie-org/luthor/commits/main)
+[![last commit](https://img.shields.io/github/last-commit/lyfie-org/luthor/main?style=flat-square)](https://github.com/lyfie-org/luthor/commits/main)
 
 </div>
 

package/dist/index.d.ts

@@ -427,37 +427,41 @@ declare function isLuthorTheme(theme: any): theme is LuthorTheme;
 declare function clearLexicalSelection(editor: LexicalEditor): void;
 declare function resolveLinkNodeKeyFromAnchor(editor: LexicalEditor, anchorEl: HTMLAnchorElement): string | null;
 
-type JsonTextNode = {
-    type: "text";
-    version: 1;
-    text: string;
-    detail: 0;
-    format: 0;
-    mode: "normal";
-    style: "";
-};
-type JsonParagraphNode = {
-    type: "paragraph";
-    version: 1;
-    format: "";
-    indent: 0;
-    direction: null;
-    children: JsonTextNode[];
-};
-type JsonRootNode = {
-    type: "root";
-    version: 1;
-    format: "";
-    indent: 0;
-    direction: null;
-    children: JsonParagraphNode[];
-};
+type JsonRecord = Record<string, unknown>;
 type JsonDocument = {
-    root: JsonRootNode;
+    root: JsonRecord;
 };
+type BridgeMode = "markdown" | "html";
+type MetadataEnvelope = {
+    id: string;
+    type: string;
+    path: number[];
+    node: JsonRecord;
+    fallback: string;
+};
+type PreparedBridgeDocument = {
+    document: JsonDocument;
+    envelopes: MetadataEnvelope[];
+};
+type ExtractedMetadataEnvelopes = {
+    content: string;
+    envelopes: MetadataEnvelope[];
+    warnings: string[];
+};
+declare function prepareDocumentForBridge(input: unknown, options: {
+    mode: BridgeMode;
+    supportedNodeTypes: ReadonlySet<string>;
+}): PreparedBridgeDocument;
+declare function appendMetadataEnvelopes(content: string, envelopes: readonly MetadataEnvelope[]): string;
+declare function extractMetadataEnvelopes(content: string): ExtractedMetadataEnvelopes;
+declare function rehydrateDocumentFromEnvelopes(document: JsonDocument, envelopes: readonly MetadataEnvelope[]): JsonDocument;
+
 declare function markdownToJSON(markdown: string): JsonDocument;
 declare function jsonToMarkdown(input: unknown): string;
 
+declare function htmlToJSON(html: string): JsonDocument;
+declare function jsonToHTML(input: unknown): string;
+
 /**
  * Commands exposed by text format extensions.
  * Generates toggle commands for text formatting (e.g., toggleBold, toggleItalic).
@@ -1110,8 +1114,14 @@ declare class ContextMenuManager {
             y: number;
         };
         renderer?: ContextMenuRenderer;
+        anchor?: {
+            element: HTMLElement;
+            offsetX: number;
+            offsetY: number;
+        };
     }): void;
     hideMenu(): void;
+    repositionMenuFromAnchor(): void;
     getCurrentMenu(): {
         items: ContextMenuItem[];
         position: {
@@ -1119,9 +1129,16 @@ declare class ContextMenuManager {
             y: number;
         };
         renderer?: ContextMenuRenderer;
+        anchor?: {
+            element: HTMLElement;
+            offsetX: number;
+            offsetY: number;
+        };
     } | null;
+    getPortalContainer(): HTMLElement | null;
     subscribe(listener: (menu: typeof this.currentMenu) => void): () => void;
     private notifyListeners;
+    private resolveAnchoredMenuConfig;
 }
 /**
  * Context menu extension - provides a clean, registry-based context menu system
@@ -1223,6 +1240,23 @@ declare class TableExtension extends BaseExtension<"table", TableConfig, TableCo
  */
 declare const tableExtension: TableExtension;
 
+declare const ORDERED_LIST_PATTERNS: {
+    readonly "decimal-alpha-roman": readonly ["decimal", "lower-alpha", "lower-roman"];
+    readonly "decimal-hierarchical": readonly ["decimal"];
+    readonly "upper-roman-upper-alpha": readonly ["upper-roman", "upper-alpha", "decimal", "lower-alpha", "decimal", "lower-alpha", "lower-roman", "lower-alpha", "lower-roman"];
+    readonly "upper-alpha-lower-alpha": readonly ["upper-alpha", "lower-alpha", "lower-roman", "decimal", "lower-alpha", "lower-roman", "decimal", "lower-alpha", "lower-roman"];
+    readonly "decimal-leading-zero-alpha": readonly ["decimal-leading-zero", "lower-alpha", "lower-roman", "decimal", "lower-alpha", "lower-roman", "decimal", "lower-alpha", "lower-roman"];
+};
+declare const UNORDERED_LIST_PATTERNS: {
+    readonly "disc-circle-square": readonly ["disc", "circle", "square"];
+    readonly "arrow-diamond-disc": readonly ["\"▸\"", "\"◆\"", "disc"];
+    readonly "square-square-square": readonly ["square", "square", "square"];
+    readonly "arrow-circle-square": readonly ["\"▸\"", "circle", "square"];
+};
+type OrderedListPattern = keyof typeof ORDERED_LIST_PATTERNS;
+type UnorderedListPattern = keyof typeof UNORDERED_LIST_PATTERNS;
+type OrderedListSuffix = "dot" | "paren";
+type CheckListVariant = "strikethrough" | "plain";
 /**
  * Commands exposed by the list extension.
  */
@@ -1241,6 +1275,20 @@ type ListCommands = {
     insertNestedUnorderedList: () => void;
     /** Create a nested numbered list at the current selection */
     insertNestedOrderedList: () => void;
+    /** Apply an ordered list pattern to the selected list tree */
+    setOrderedListPattern: (pattern: OrderedListPattern) => void;
+    /** Toggle ordered list marker suffix between "1." and "1)" */
+    setOrderedListSuffix: (suffix: OrderedListSuffix) => void;
+    /** Apply an unordered list marker pattern to the selected list tree */
+    setUnorderedListPattern: (pattern: UnorderedListPattern) => void;
+    /** Switch checklist behavior between strike and plain text */
+    setCheckListVariant: (variant: CheckListVariant) => void;
+    /** Rebuild list style tokens after state import/rehydration */
+    rehydrateListStyles: () => void;
+};
+type ListExtensionConfig = {
+    /** Maximum lexical list depth including the top-level list. */
+    maxDepth?: number;
 };
 /**
  * List extension for managing ordered and unordered lists.
@@ -1276,7 +1324,7 @@ type ListCommands = {
  * }
  * ```
  */
-declare class ListExtension extends BaseExtension<"list", any, ListCommands, {
+declare class ListExtension extends BaseExtension<"list", ListExtensionConfig, ListCommands, {
     unorderedList: () => Promise<boolean>;
     orderedList: () => Promise<boolean>;
     checkList: () => Promise<boolean>;
@@ -1284,7 +1332,8 @@ declare class ListExtension extends BaseExtension<"list", any, ListCommands, {
     /**
      * Creates a new list extension instance.
      */
-    constructor();
+    constructor(config?: ListExtensionConfig);
+    private getMaxListDepth;
     /**
      * Registers the extension with Lexical.
      * No special registration needed because Lexical handles list commands.
@@ -1312,6 +1361,13 @@ declare class ListExtension extends BaseExtension<"list", any, ListCommands, {
      * @returns Object containing list toggle commands
      */
     getCommands(editor: LexicalEditor): ListCommands;
+    private applyOrderedPattern;
+    private applyOrderedSuffix;
+    private applyUnorderedPattern;
+    private applyCheckListVariant;
+    private syncListNodeStyles;
+    private convertTopListType;
+    private handleOrderedListShortcut;
     /**
      * Returns state query functions for list state.
      *
@@ -1388,6 +1444,7 @@ type CodeExtensionConfig = BaseExtensionConfig & CodeHighlightProviderConfig & {
  * ```
  */
 declare class CodeExtension extends BaseExtension<"code", CodeExtensionConfig, CodeCommands, CodeStateQueries, ReactNode[]> {
+    private static readonly MAX_CODE_TAB_DEPTH;
     private codeHighlightProviderPromise;
     constructor();
     /**
@@ -1444,6 +1501,7 @@ declare class CodeExtension extends BaseExtension<"code", CodeExtensionConfig, C
      * @returns Current format or null
      */
     private getCurrentFormatSync;
+    private hasReachedCodeTabLimit;
 }
 declare const codeExtension: CodeExtension;
 
@@ -1506,6 +1564,7 @@ declare const codeIntelligenceExtension: CodeIntelligenceExtension;
  */
 declare class CodeFormatExtension extends TextFormatExtension<"code"> {
     constructor();
+    register(editor: LexicalEditor): () => void;
 }
 declare const codeFormatExtension: CodeFormatExtension;
 
@@ -2153,6 +2212,9 @@ declare const richTextExtension: RichTextExtension;
 type RichTextComponentProps = SharedRichTextProps;
 declare const RichText: React__default.FC<RichTextComponentProps>;
 
+type TabIndentConfig = {
+    maxListDepth?: number;
+};
 /**
  * TabIndentExtension - Adds universal Tab/Shift+Tab indentation support
  *
@@ -2167,8 +2229,8 @@ declare const RichText: React__default.FC<RichTextComponentProps>;
  * const extensions = [tabIndentExtension];
  * ```
  */
-declare class TabIndentExtension extends BaseExtension<"tabIndent", Record<string, never>, Record<string, never>, Record<string, never>, ReactNode[]> {
-    constructor();
+declare class TabIndentExtension extends BaseExtension<"tabIndent", TabIndentConfig, Record<string, never>, Record<string, never>, ReactNode[]> {
+    constructor(config?: TabIndentConfig);
     /**
      * Register the extension with Lexical
      * @param editor - Lexical editor instance
@@ -2182,9 +2244,17 @@ declare class TabIndentExtension extends BaseExtension<"tabIndent", Record<strin
      */
     private isInCodeBlock;
     /**
-     * Check if a node is within a checklist list item.
+     * Check whether current list depth reached the configured max depth.
      */
-    private isInCheckList;
+    private isListAtMaxDepth;
+    /**
+     * Check whether current block indent reached the configured max depth.
+     */
+    private isBlockAtMaxIndent;
+    private resolveTabContext;
+    private findNearestListNode;
+    private findNearestListItemNode;
+    private hasReachedTextTabLimit;
 }
 declare const tabIndentExtension: TabIndentExtension;
 
@@ -2246,6 +2316,7 @@ declare class EmojiExtension extends BaseExtension<"emoji", EmojiConfig, EmojiCo
     private position;
     private suggestions;
     private activeMatch;
+    private viewportRafId;
     private applyingAutoReplace;
     private catalogAdapter;
     private hasExplicitCatalogConfig;
@@ -2497,6 +2568,7 @@ declare class SlashCommandExtension extends BaseExtension<"slashCommand", SlashC
     private query;
     private position;
     private activeMatch;
+    private viewportRafId;
     constructor(config?: SlashCommandConfig);
     register(editor: LexicalEditor): () => void;
     getCommands(editor: LexicalEditor): SlashCommandCommands;
@@ -2516,11 +2588,14 @@ declare class SlashCommandExtension extends BaseExtension<"slashCommand", SlashC
 }
 declare const slashCommandExtension: SlashCommandExtension;
 
-type EnterKeyBehaviorCommands = Record<string, never>;
+type EnterKeyBehaviorCommands = {
+    insertHardBreak: () => void;
+};
 type EnterKeyBehaviorStateQueries = Record<string, never>;
 declare class EnterKeyBehaviorExtension extends BaseExtension<"enterKeyBehavior", BaseExtensionConfig, EnterKeyBehaviorCommands, EnterKeyBehaviorStateQueries> {
     constructor();
     register(editor: LexicalEditor): () => void;
+    getCommands(editor: LexicalEditor): EnterKeyBehaviorCommands;
     private findQuoteNode;
     private findCodeNode;
     private findDirectQuoteChild;
@@ -2528,4 +2603,4 @@ declare class EnterKeyBehaviorExtension extends BaseExtension<"enterKeyBehavior"
 }
 declare const enterKeyBehaviorExtension: EnterKeyBehaviorExtension;
 
-export { type Alignment, type BaseCommands, BaseExtension, type BaseExtensionConfig, BaseProvider, BlockFormatExtension, BoldExtension, CodeExtension, type CodeExtensionConfig, CodeFormatExtension, type CodeHighlightProvider, type CodeHighlightProviderConfig, type CodeIntelligenceCommands, type CodeIntelligenceConfig, CodeIntelligenceExtension, type CodeLanguageOptionsConfig, type CodeLanguageOptionsMode, type CommandPaletteCommands, CommandPaletteExtension, type CommandPaletteItem, type CommandPaletteStateQueries, type ContextMenuCommands, type ContextMenuConfig, ContextMenuExtension, type ContextMenuItem, type ContextMenuStateQueries, DraggableBlockExtension, type DraggableCommands, type DraggableConfig, type DraggableStateQueries, type EditorConfig, type EditorContextType, type EmojiCatalogAdapter, type EmojiCatalogItem, type EmojiCommands, type EmojiConfig, EmojiExtension, type EmojiStateQueries, type EmojiSuggestionState, EnterKeyBehaviorExtension, type Extension, ExtensionCategory, type ExtractCommands, type ExtractNames, type ExtractPlugins, type ExtractStateQueries, type FloatingCommands, type FloatingConfig, type FloatingStateQueries, FloatingToolbarExtension, type FontCssLoadStrategy, type FontFamilyConfig, FontFamilyExtension, type FontFamilyOption, type FontSizeConfig, FontSizeExtension, type FontSizeOption, HistoryExtension, HorizontalRuleExtension, IframeEmbedExtension, type ImageCommands, type ImageComponentProps, ImageExtension, type ImageExtensionConfig, type ImagePayload, type ImageStateQueries, ItalicExtension, type JsonDocument, LIGHTWEIGHT_EMOJI_CATALOG, LUTHOR_EDITOR_THEME_TOKENS, type LexicalNodeRegistration, type LineHeightConfig, LineHeightExtension, type LineHeightOption, LinkExtension, ListExtension, type LuthorEditorThemeOverrides, type LuthorEditorThemeToken, type LuthorTheme, RichText, type RichTextComponentProps, type RichTextConfig, type SerializedImageNode, type SlashCommandCommands, type SlashCommandConfig, SlashCommandExtension, type SlashCommandItem, type SlashCommandMenuState, type SlashCommandStateQueries, StrikethroughExtension, SubscriptExtension, SuperscriptExtension, TabIndentExtension, type TableConfig, TableExtension, type TextColorConfig, TextColorExtension, type TextColorOption, TextFormatExtension, type TextHighlightConfig, TextHighlightExtension, type TextHighlightOption, type ToolbarItem, UnderlineExtension, YouTubeEmbedExtension, blockFormatExtension, boldExtension, clearLexicalSelection, codeExtension, codeFormatExtension, codeIntelligenceExtension, commandPaletteExtension, contextMenuExtension, createCustomNodeExtension, createEditorSystem, createEditorThemeStyleVars, createExtension, defaultLuthorTheme, draggableBlockExtension, emojiExtension, enterKeyBehaviorExtension, floatingToolbarExtension, fontFamilyExtension, fontSizeExtension, historyExtension, horizontalRuleExtension, iframeEmbedExtension, imageExtension, isLuthorTheme, italicExtension, jsonToMarkdown, lineHeightExtension, linkExtension, listExtension, markdownToJSON, mergeThemes, resolveLinkNodeKeyFromAnchor, richTextExtension, slashCommandExtension, strikethroughExtension, subscriptExtension, superscriptExtension, tabIndentExtension, tableExtension, textColorExtension, textHighlightExtension, underlineExtension, useBaseEditor, youTubeEmbedExtension };
+export { type Alignment, type BaseCommands, BaseExtension, type BaseExtensionConfig, BaseProvider, BlockFormatExtension, BoldExtension, type BridgeMode, CodeExtension, type CodeExtensionConfig, CodeFormatExtension, type CodeHighlightProvider, type CodeHighlightProviderConfig, type CodeIntelligenceCommands, type CodeIntelligenceConfig, CodeIntelligenceExtension, type CodeLanguageOptionsConfig, type CodeLanguageOptionsMode, type CommandPaletteCommands, CommandPaletteExtension, type CommandPaletteItem, type CommandPaletteStateQueries, type ContextMenuCommands, type ContextMenuConfig, ContextMenuExtension, type ContextMenuItem, type ContextMenuStateQueries, DraggableBlockExtension, type DraggableCommands, type DraggableConfig, type DraggableStateQueries, type EditorConfig, type EditorContextType, type EmojiCatalogAdapter, type EmojiCatalogItem, type EmojiCommands, type EmojiConfig, EmojiExtension, type EmojiStateQueries, type EmojiSuggestionState, EnterKeyBehaviorExtension, type Extension, ExtensionCategory, type ExtractCommands, type ExtractNames, type ExtractPlugins, type ExtractStateQueries, type ExtractedMetadataEnvelopes, type FloatingCommands, type FloatingConfig, type FloatingStateQueries, FloatingToolbarExtension, type FontCssLoadStrategy, type FontFamilyConfig, FontFamilyExtension, type FontFamilyOption, type FontSizeConfig, FontSizeExtension, type FontSizeOption, HistoryExtension, HorizontalRuleExtension, IframeEmbedExtension, type ImageCommands, type ImageComponentProps, ImageExtension, type ImageExtensionConfig, type ImagePayload, type ImageStateQueries, ItalicExtension, type JsonDocument, LIGHTWEIGHT_EMOJI_CATALOG, LUTHOR_EDITOR_THEME_TOKENS, type LexicalNodeRegistration, type LineHeightConfig, LineHeightExtension, type LineHeightOption, LinkExtension, ListExtension, type LuthorEditorThemeOverrides, type LuthorEditorThemeToken, type LuthorTheme, type MetadataEnvelope, type PreparedBridgeDocument, RichText, type RichTextComponentProps, type RichTextConfig, type SerializedImageNode, type SlashCommandCommands, type SlashCommandConfig, SlashCommandExtension, type SlashCommandItem, type SlashCommandMenuState, type SlashCommandStateQueries, StrikethroughExtension, SubscriptExtension, SuperscriptExtension, TabIndentExtension, type TableConfig, TableExtension, type TextColorConfig, TextColorExtension, type TextColorOption, TextFormatExtension, type TextHighlightConfig, TextHighlightExtension, type TextHighlightOption, type ToolbarItem, UnderlineExtension, YouTubeEmbedExtension, appendMetadataEnvelopes, blockFormatExtension, boldExtension, clearLexicalSelection, codeExtension, codeFormatExtension, codeIntelligenceExtension, commandPaletteExtension, contextMenuExtension, createCustomNodeExtension, createEditorSystem, createEditorThemeStyleVars, createExtension, defaultLuthorTheme, draggableBlockExtension, emojiExtension, enterKeyBehaviorExtension, extractMetadataEnvelopes, floatingToolbarExtension, fontFamilyExtension, fontSizeExtension, historyExtension, horizontalRuleExtension, htmlToJSON, iframeEmbedExtension, imageExtension, isLuthorTheme, italicExtension, jsonToHTML, jsonToMarkdown, lineHeightExtension, linkExtension, listExtension, markdownToJSON, mergeThemes, prepareDocumentForBridge, rehydrateDocumentFromEnvelopes, resolveLinkNodeKeyFromAnchor, richTextExtension, slashCommandExtension, strikethroughExtension, subscriptExtension, superscriptExtension, tabIndentExtension, tableExtension, textColorExtension, textHighlightExtension, underlineExtension, useBaseEditor, youTubeEmbedExtension };