@yurikilian/lex4 0.1.1 → 0.2.0

package/README.md

@@ -22,19 +22,23 @@ A paginated document editor built as a **reusable React library** on top of [Met
 
 <div align="center">
 
-![Editor with formatted content](docs/screenshots/editor-with-content.png)
+![Editor with formatted content](https://raw.githubusercontent.com/yurikilian/lex4/main/docs/screenshots/editor-with-content.png)
 
 </div>
 
 ## ✨ Features
 
-- **True A4 pagination** — every page is exactly 794 × 1123 CSS pixels (210mm × 297mm at 96 DPI)
+- **True A4 pagination** — every page is exactly 794 × 1123 CSS pixels (210 mm × 297 mm at 96 DPI)
 - **Automatic content flow** — overflow splits at block boundaries, underflow pulls content back
 - **Rich text formatting** — bold, italic, underline, strikethrough, alignment, lists, indentation
 - **Headers & footers** — global toggle with per-page editable regions and page counters
-- **Multiple font families** — Arial, Times New Roman, Courier New, Georgia, Verdana and more
+- **Multiple font families** — Inter, Arial, Times New Roman, Courier New, Georgia, Verdana and more
+- **Font size control** — per-selection font size with AST-level preservation
 - **Session history sidebar** — Word-style action timeline with full undo/redo
-- **Serializable document model** — typed AST export/import for backend persistence
+- **Extension architecture** — opt-in features via composable extensions (`astExtension`, `variablesExtension`)
+- **Document AST export** — clean, versioned, Lexical-independent AST for backend DOCX/PDF rendering
+- **Variables & placeholders** — insert dynamic tokens like `{{customer.name}}` with metadata export
+- **i18n support** — all UI strings externalized; override any subset for localization
 - **Read-only mode** — disable editing while keeping the document viewable
 - **Zero config** — drop in the component and start editing
 
@@ -43,28 +47,28 @@ A paginated document editor built as a **reusable React library** on top of [Met
 <details>
 <summary><strong>Empty Editor</strong> — clean A4 page ready for editing</summary>
 
-![Empty editor](docs/screenshots/editor-empty.png)
+![Empty editor](https://raw.githubusercontent.com/yurikilian/lex4/main/docs/screenshots/editor-empty.png)
 
 </details>
 
 <details>
 <summary><strong>Headers & Footers</strong> — global toggle with editable regions</summary>
 
-![Editor with headers and footers](docs/screenshots/editor-header-footer.png)
+![Editor with headers and footers](https://raw.githubusercontent.com/yurikilian/lex4/main/docs/screenshots/editor-header-footer.png)
 
 </details>
 
 <details>
 <summary><strong>Multi-Page Document</strong> — automatic content flow across pages</summary>
 
-![Multi-page document](docs/screenshots/editor-multi-page.png)
+![Multi-page document](https://raw.githubusercontent.com/yurikilian/lex4/main/docs/screenshots/editor-multi-page.png)
 
 </details>
 
 <details>
 <summary><strong>Toolbar</strong> — full formatting controls</summary>
 
-![Toolbar](docs/screenshots/toolbar.png)
+![Toolbar](https://raw.githubusercontent.com/yurikilian/lex4/main/docs/screenshots/toolbar.png)
 
 </details>
 
@@ -80,10 +84,10 @@ yarn add @yurikilian/lex4
 
 ### Peer Dependencies
 
-The library requires React 18+ and Lexical 0.22+ as peer dependencies:
+The library requires React 18+ as a peer dependency. Lexical packages are bundled.
 
 ```bash
-npm install react react-dom lexical @lexical/react @lexical/rich-text @lexical/list @lexical/history @lexical/selection @lexical/utils @lexical/clipboard @lexical/html
+npm install react react-dom
 ```
 
 ## 🚀 Quick Start
@@ -101,22 +105,48 @@ function App() {
 }
 ```
 
-### With Initial Document
+### With Extensions
+
+Extensions add opt-in capabilities. The two built-in extensions are `astExtension` (document AST export) and `variablesExtension` (dynamic variable placeholders):
 
 ```tsx
-import { Lex4Editor, createEmptyDocument } from '@yurikilian/lex4';
+import { useRef, useMemo } from 'react';
+import {
+  Lex4Editor,
+  Lex4EditorHandle,
+  astExtension,
+  variablesExtension,
+  VariableDefinition,
+} from '@yurikilian/lex4';
 import '@yurikilian/lex4/style.css';
 
+const variables: VariableDefinition[] = [
+  { key: 'customer.name', label: 'Customer Name', group: 'Customer', valueType: 'string' },
+  { key: 'proposal.date', label: 'Proposal Date', group: 'Proposal', valueType: 'date' },
+];
+
 function App() {
-  const initialDoc = createEmptyDocument();
+  const editorRef = useRef<Lex4EditorHandle>(null);
+
+  const extensions = useMemo(() => [
+    astExtension(),
+    variablesExtension(variables),
+  ], []);
+
+  const handleSave = () => {
+    const ast = editorRef.current?.getDocumentAst();
+    console.log(JSON.stringify(ast, null, 2));
+  };
 
   return (
-    <Lex4Editor
-      initialDocument={initialDoc}
-      headerFooterEnabled={true}
-      onDocumentChange={(doc) => saveToBackend(doc)}
-      onHeaderFooterToggle={(enabled) => console.log('Headers:', enabled)}
-    />
+    <>
+      <Lex4Editor
+        ref={editorRef}
+        extensions={extensions}
+        onDocumentChange={(doc) => console.log(doc)}
+      />
+      <button onClick={handleSave}>Export AST</button>
+    </>
   );
 }
 ```
@@ -143,9 +173,57 @@ The main editor component. Drop it into any React application.
 | `headerFooterEnabled` | `boolean` | `false` | Initial header/footer toggle state |
 | `onHeaderFooterToggle` | `(enabled: boolean) => void` | — | Called when the user toggles headers/footers |
 | `readOnly` | `boolean` | `false` | Disable editing (view-only mode) |
+| `extensions` | `Lex4Extension[]` | `[]` | Extensions to load (e.g., `astExtension()`, `variablesExtension(defs)`) |
+| `translations` | `DeepPartial<Lex4Translations>` | English | Partial i18n overrides, deep-merged with defaults |
+| `onSave` | `(payload: { ast, json }) => void` | — | Called when the host app triggers a save |
 | `captureHistoryShortcutsOnWindow` | `boolean` | `true` | Capture ⌘Z/⌘⇧Z at the window level |
 | `className` | `string` | — | Additional CSS class for the editor root |
 
+### Extensions
+
+Extensions are opt-in feature modules that add capabilities to the editor without coupling.
+
+#### `astExtension()`
+
+Adds document AST export. Contributes imperative handle methods:
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `getDocumentAst()` | `() => DocumentAst` | Returns the document as a clean, typed AST |
+| `getDocumentJson()` | `() => string` | Returns the AST serialized as formatted JSON |
+| `buildSavePayload(opts?)` | `(opts?) => SaveDocumentRequest` | Wraps the AST into a REST-ready payload |
+
+```tsx
+const extensions = [astExtension()];
+// then via ref:
+const ast = editorRef.current?.getDocumentAst();
+```
+
+#### `variablesExtension(definitions)`
+
+Adds variable placeholders — dynamic tokens rendered as non-editable chips in the editor and preserved as structured nodes in the exported AST.
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `insertVariable(key)` | `(key: string) => void` | Inserts a variable at the current cursor position |
+| `refreshVariables(defs)` | `(defs: VariableDefinition[]) => void` | Updates the available variable definitions |
+
+Also adds:
+- **Toolbar button** — variable picker dropdown for inserting variables inline
+- **Side panel toggle** — opens a searchable variable panel on the right
+- **Variable node** — custom Lexical node rendered as a non-editable chip
+
+```tsx
+const variables: VariableDefinition[] = [
+  { key: 'customer.name', label: 'Customer Name', group: 'Customer', valueType: 'string' },
+  { key: 'proposal.date', label: 'Proposal Date', group: 'Proposal', valueType: 'date' },
+];
+
+const extensions = [variablesExtension(variables)];
+```
+
+In the exported AST, variables appear as `{ type: "variable", key: "customer.name" }` nodes within block content, and their definitions appear under `metadata.variables`.
+
 ### Types
 
 ```ts
@@ -206,6 +284,123 @@ These hooks are exported for advanced use cases where you need to build custom p
 | `useOverflowDetection` | Monitors content height and triggers reflow when content exceeds the page body |
 | `useHeaderFooter` | Header/footer state management and chrome template application |
 
+## 🌐 i18n (Internationalization)
+
+All 59 UI strings are externalized and can be overridden via the `translations` prop. No external i18n library is forced on consumers.
+
+### Basic Override
+
+```tsx
+<Lex4Editor
+  translations={{
+    toolbar: { undo: 'Desfazer', redo: 'Refazer', bold: 'Negrito (Ctrl+B)' },
+    header: { placeholder: 'Cabeçalho' },
+    footer: { placeholder: 'Rodapé' },
+  }}
+/>
+```
+
+### Bridge with i18next
+
+If your app already uses `i18next`, bridge it:
+
+```tsx
+import { useTranslation } from 'react-i18next';
+
+function App() {
+  const { t } = useTranslation();
+
+  return (
+    <Lex4Editor
+      translations={{
+        toolbar: {
+          undo: t('editor.undo'),
+          redo: t('editor.redo'),
+          bold: t('editor.bold'),
+        },
+      }}
+    />
+  );
+}
+```
+
+### Available String Keys
+
+| Section | Keys | Examples |
+|---------|------|---------|
+| `toolbar` | 16 | `undo`, `redo`, `bold`, `italic`, `alignLeft`, `numberedList`, ... |
+| `history` | 4 + 20 actions | `title`, `empty`, `actions.boldApplied`, `actions.fontChanged`, ... |
+| `variables` | 8 | `title`, `available`, `searchPlaceholder`, `openPanel`, ... |
+| `header` / `footer` | 1 each | `placeholder` |
+| `sidebar` | 1 | `close` |
+
+Dynamic strings use `{{key}}` interpolation: `"Font changed to {{value}}"`.
+
+Import `DEFAULT_TRANSLATIONS` and `Lex4Translations` to see the full shape:
+
+```tsx
+import { DEFAULT_TRANSLATIONS } from '@yurikilian/lex4';
+import type { Lex4Translations } from '@yurikilian/lex4';
+```
+
+## 📝 Document AST
+
+The AST is a **clean, versioned, Lexical-independent** structure designed for backend consumption (e.g., DOCX/PDF generation). It preserves semantic structure, formatting marks, font choices, header/footer layout, A4 page metadata, and variable references.
+
+> **Requires `astExtension()`** — the AST export is opt-in via the extension system.
+
+```ts
+// Export via imperative ref
+const ast = editorRef.current?.getDocumentAst();
+
+// Or build a REST payload
+const payload = editorRef.current?.buildSavePayload({
+  exportTarget: 'pdf',
+  documentId: 'doc-123',
+});
+
+await fetch('/api/documents/export', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify(payload),
+});
+```
+
+### AST Shape (top-level)
+
+```ts
+interface DocumentAst {
+  version: '1.0.0';
+  page: {
+    format: 'A4';
+    widthMm: 210;
+    heightMm: 297;
+    margins: { topMm, rightMm, bottomMm, leftMm };
+  };
+  headerFooter: {
+    enabled: boolean;
+    pageCounterMode: 'none' | 'header' | 'footer' | 'both';
+    defaultHeader: ContentAst | null;
+    defaultFooter: ContentAst | null;
+  };
+  pages: PageAst[];
+  metadata: {
+    variables: Record<string, VariableDefinitionAst>;
+  };
+}
+```
+
+### REST Payload
+
+```ts
+interface SaveDocumentRequest {
+  document: DocumentAst;
+  exportTarget?: 'pdf' | 'docx';
+  documentId?: string;
+  metadata?: Record<string, string>;
+}
+```
+
 ## 🏗️ Architecture
 
 ### Multi-Editor Discrete Page Model
@@ -214,7 +409,7 @@ Unlike most web-based "paginated" editors that use a single editor with CSS visu
 
 <div align="center">
 
-![Component tree](docs/screenshots/arch-component-tree.png)
+![Component tree](https://raw.githubusercontent.com/yurikilian/lex4/main/docs/screenshots/arch-component-tree.png)
 
 </div>
 
@@ -224,10 +419,27 @@ The pagination engine is built as **pure functions** that transform page state a
 
 <div align="center">
 
-![Content flow](docs/screenshots/arch-content-flow.png)
+![Content flow](https://raw.githubusercontent.com/yurikilian/lex4/main/docs/screenshots/arch-content-flow.png)
 
 </div>
 
+### Extension Architecture
+
+Features are added via composable extensions that can contribute nodes, plugins, toolbar items, side panels, context providers, and imperative handle methods:
+
+```ts
+interface Lex4Extension {
+  name: string;
+  nodes?: Klass<LexicalNode>[];        // custom Lexical nodes
+  bodyPlugins?: React.ComponentType[];  // plugins per page editor
+  toolbarItems?: React.ComponentType[]; // toolbar UI additions
+  sidePanel?: React.ComponentType;      // right-side panel
+  provider?: React.ComponentType<...>;  // context provider wrapper
+  themeOverrides?: Partial<EditorThemeClasses>;
+  handleMethods?: (ctx) => Record<string, Function>;
+}
+```
+
 ### Key Invariants
 
 - Every page is **exactly** A4 (794 × 1123 px at 96 DPI) — no dynamic heights
@@ -241,21 +453,25 @@ The pagination engine is built as **pure functions** that transform page state a
 ```
 lex4/
 ├── packages/
-│   └── editor/               # lex4 — the publishable library
+│   └── editor/               # @yurikilian/lex4 — the publishable library
 │       ├── src/
+│       │   ├── ast/          # AST types, serializers, block/inline mappers, payload builder
 │       │   ├── components/   # React components (Lex4Editor, PageView, Toolbar, etc.)
 │       │   ├── constants/    # A4 dimensions, layout math
 │       │   ├── context/      # DocumentProvider, document reducer, actions
 │       │   ├── engine/       # Pagination logic — pure functions (reflow, overflow, paginate)
+│       │   ├── extensions/   # Extension system, astExtension, variablesExtension
 │       │   ├── hooks/        # usePagination, useOverflowDetection, useHeaderFooter
+│       │   ├── i18n/         # Translations types, defaults, context provider
 │       │   ├── lexical/      # Editor config, plugins (paste, history), custom commands
 │       │   ├── types/        # TypeScript interfaces (Lex4Document, PageState, etc.)
-│       │   └── utils/        # Editor state manipulation helpers
+│       │   ├── utils/        # Editor state manipulation helpers
+│       │   └── variables/    # VariableNode, VariablePlugin, VariableProvider
 │       └── dist/             # Built output (ESM + CJS + types + CSS)
 ├── demo/                     # Demo app (deployed to GitHub Pages)
 ├── e2e/                      # Playwright end-to-end tests
 ├── .github/workflows/        # CI, npm publish, GitHub Pages deployment
-└── docs/screenshots/         # Auto-generated screenshots for README
+└── docs/screenshots/         # Screenshots for README
 ```
 
 ## 🛠️ Development
@@ -312,8 +528,8 @@ pnpm --filter e2e test:ui
 
 | Category | Framework | Count | Description |
 |----------|-----------|-------|-------------|
-| Unit | Vitest | 89 | Engine logic, reducers, utilities, component rendering |
-| E2E | Playwright | 80 | Full user flows — typing, formatting, pagination, header/footer, history |
+| Unit | Vitest | 178 | Engine logic, reducers, AST serializers, i18n, variable nodes |
+| E2E | Playwright | 118 | Full user flows — typing, formatting, pagination, header/footer, variables, theme, i18n |
 
 ## 🔧 Build & Bundle
 
@@ -327,7 +543,7 @@ The library is built with **Vite in library mode**, producing:
 | CSS | `dist/style.css` | Compiled Tailwind styles |
 | Source maps | `dist/*.map` | Debugging support |
 
-React, ReactDOM, and all `@lexical/*` packages are **externalized** — they are not bundled and must be provided by the consuming application.
+React and ReactDOM are **externalized** — they are not bundled and must be provided by the consuming application. Lexical packages are bundled as direct dependencies.
 
 ## 🚢 Publishing to npm
 

package/dist/ast/block-mapper.d.ts

@@ -0,0 +1,24 @@
+import { BlockNodeAst } from './types';
+/** Generic serialized Lexical element node shape. */
+interface SerializedElementNode {
+    type: string;
+    children?: SerializedElementNode[];
+    format?: number | string;
+    indent?: number;
+    direction?: string;
+    tag?: string;
+    listType?: string;
+    start?: number;
+    value?: number;
+    [key: string]: unknown;
+}
+/**
+ * Maps a single serialized Lexical block node to an AST block node.
+ */
+export declare function mapBlockNode(node: SerializedElementNode): BlockNodeAst;
+/**
+ * Maps an array of serialized Lexical block nodes to AST block nodes.
+ */
+export declare function mapBlockNodes(nodes: SerializedElementNode[]): BlockNodeAst[];
+export {};
+//# sourceMappingURL=block-mapper.d.ts.map

package/dist/ast/block-mapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"block-mapper.d.ts","sourceRoot":"","sources":["../../src/ast/block-mapper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACV,YAAY,EAQb,MAAM,SAAS,CAAC;AASjB,qDAAqD;AACrD,UAAU,qBAAqB;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,qBAAqB,EAAE,CAAC;IACnC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAmBD;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,qBAAqB,GAAG,YAAY,CAiBtE;AAuED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,qBAAqB,EAAE,GAAG,YAAY,EAAE,CAE5E"}

package/dist/ast/content-mapper.d.ts

@@ -0,0 +1,16 @@
+import { SerializedEditorState } from 'lexical';
+import { BlockNodeAst, ContentAst } from './types';
+/**
+ * Converts a Lexical SerializedEditorState into a ContentAst.
+ *
+ * Returns null if the state is null/undefined (e.g. disabled header).
+ */
+export declare function mapEditorStateToContent(state: SerializedEditorState | null | undefined): ContentAst | null;
+/**
+ * Converts a Lexical SerializedEditorState to flat BlockNodeAst[].
+ *
+ * Used for body content where we need the array directly
+ * rather than wrapped in a ContentAst.
+ */
+export declare function mapEditorStateToBlocks(state: SerializedEditorState | null | undefined): BlockNodeAst[];
+//# sourceMappingURL=content-mapper.d.ts.map

package/dist/ast/content-mapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-mapper.d.ts","sourceRoot":"","sources":["../../src/ast/content-mapper.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AACrD,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAGxD;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,qBAAqB,GAAG,IAAI,GAAG,SAAS,GAC9C,UAAU,GAAG,IAAI,CAOnB;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,qBAAqB,GAAG,IAAI,GAAG,SAAS,GAC9C,YAAY,EAAE,CAMhB"}

package/dist/ast/document-serializer.d.ts

@@ -0,0 +1,11 @@
+import { DocumentAst } from './types';
+import { Lex4Document } from '../types/document';
+import { VariableDefinition } from '../variables/types';
+/**
+ * Serializes a Lex4Document into a clean, backend-friendly DocumentAst.
+ *
+ * @param document - The current editor document state
+ * @param variableDefinitions - Optional variable definitions for metadata
+ */
+export declare function serializeDocument(document: Lex4Document, variableDefinitions?: VariableDefinition[]): DocumentAst;
+//# sourceMappingURL=document-serializer.d.ts.map

package/dist/ast/document-serializer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-serializer.d.ts","sourceRoot":"","sources":["../../src/ast/document-serializer.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,WAAW,EAIZ,MAAM,SAAS,CAAC;AAEjB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAM7D;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,YAAY,EACtB,mBAAmB,GAAE,kBAAkB,EAAO,GAC7C,WAAW,CAiCb"}

package/dist/ast/index.d.ts

@@ -0,0 +1,9 @@
+export type { DocumentAst, PageFormatAst, MarginsAst, HeaderFooterConfigAst, DocumentMetadataAst, PageAst, ContentAst, BlockNodeAst, Alignment, ParagraphAst, HeadingAst, ListAst, ListItemAst, BlockQuoteAst, InlineNodeAst, TextMarks, TextRunAst, VariableAst, LineBreakAst, VariableDefinitionAst, SaveDocumentRequest, } from './types';
+export { AST_VERSION } from './types';
+export { mapInlineNode, mapInlineNodes, decodeFormatBitmask, extractFontFamily, extractFontSizePt, buildTextMarks, } from './inline-mapper';
+export { mapBlockNode, mapBlockNodes } from './block-mapper';
+export { mapEditorStateToContent, mapEditorStateToBlocks } from './content-mapper';
+export { serializeDocument } from './document-serializer';
+export { buildSavePayload, serializeDocumentJson } from './payload-builder';
+export type { PayloadOptions } from './payload-builder';
+//# sourceMappingURL=index.d.ts.map

package/dist/ast/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ast/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,WAAW,EACX,aAAa,EACb,UAAU,EACV,qBAAqB,EACrB,mBAAmB,EACnB,OAAO,EACP,UAAU,EACV,YAAY,EACZ,SAAS,EACT,YAAY,EACZ,UAAU,EACV,OAAO,EACP,WAAW,EACX,aAAa,EACb,aAAa,EACb,SAAS,EACT,UAAU,EACV,WAAW,EACX,YAAY,EACZ,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAEtC,OAAO,EACL,aAAa,EACb,cAAc,EACd,mBAAmB,EACnB,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,GACf,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC7D,OAAO,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AACnF,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAC5E,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/ast/inline-mapper.d.ts

@@ -0,0 +1,41 @@
+import { InlineNodeAst, TextMarks } from './types';
+import { SerializedVariableNode } from '../variables/variable-node';
+/** Serialized Lexical text node shape (subset of fields we need). */
+interface SerializedTextNode {
+    type: 'text';
+    text: string;
+    format: number;
+    style?: string;
+    [key: string]: unknown;
+}
+interface SerializedLineBreak {
+    type: 'linebreak';
+    [key: string]: unknown;
+}
+type SerializedInlineNode = SerializedTextNode | SerializedVariableNode | SerializedLineBreak;
+/**
+ * Decodes Lexical's format bitmask into named boolean marks.
+ */
+export declare function decodeFormatBitmask(format: number): Pick<TextMarks, 'bold' | 'italic' | 'underline' | 'strikethrough'>;
+/**
+ * Extracts font-family from a CSS style string.
+ */
+export declare function extractFontFamily(style: string): string | undefined;
+/**
+ * Extracts font-size (in pt) from a CSS style string.
+ */
+export declare function extractFontSizePt(style: string): number | undefined;
+/**
+ * Builds TextMarks from a Lexical format bitmask and style string.
+ */
+export declare function buildTextMarks(format: number, style?: string): TextMarks | undefined;
+/**
+ * Maps a single serialized Lexical inline node to an AST inline node.
+ */
+export declare function mapInlineNode(node: SerializedInlineNode): InlineNodeAst;
+/**
+ * Maps an array of serialized Lexical inline nodes to AST inline nodes.
+ */
+export declare function mapInlineNodes(nodes: SerializedInlineNode[]): InlineNodeAst[];
+export {};
+//# sourceMappingURL=inline-mapper.d.ts.map

package/dist/ast/inline-mapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inline-mapper.d.ts","sourceRoot":"","sources":["../../src/ast/inline-mapper.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAyC,MAAM,SAAS,CAAC;AAC/F,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AAQzE,qEAAqE;AACrE,UAAU,kBAAkB;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,UAAU,mBAAmB;IAC3B,IAAI,EAAE,WAAW,CAAC;IAClB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,KAAK,oBAAoB,GAAG,kBAAkB,GAAG,sBAAsB,GAAG,mBAAmB,CAAC;AAE9F;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,QAAQ,GAAG,WAAW,GAAG,eAAe,CAAC,CAOtH;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGnE;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGnE;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAYpF;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,oBAAoB,GAAG,aAAa,CAYvE;AAsBD;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,oBAAoB,EAAE,GAAG,aAAa,EAAE,CAE7E"}

package/dist/ast/payload-builder.d.ts

@@ -0,0 +1,18 @@
+import { DocumentAst, SaveDocumentRequest } from './types';
+export interface PayloadOptions {
+    /** Target export format */
+    exportTarget?: 'pdf' | 'docx';
+    /** External document identifier */
+    documentId?: string;
+    /** Additional metadata for the backend */
+    metadata?: Record<string, string>;
+}
+/**
+ * Builds a SaveDocumentRequest payload from a DocumentAst.
+ */
+export declare function buildSavePayload(ast: DocumentAst, options?: PayloadOptions): SaveDocumentRequest;
+/**
+ * Serializes a DocumentAst to a JSON string.
+ */
+export declare function serializeDocumentJson(ast: DocumentAst): string;
+//# sourceMappingURL=payload-builder.d.ts.map

package/dist/ast/payload-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payload-builder.d.ts","sourceRoot":"","sources":["../../src/ast/payload-builder.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAEhE,MAAM,WAAW,cAAc;IAC7B,2BAA2B;IAC3B,YAAY,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IAC9B,mCAAmC;IACnC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,WAAW,EAChB,OAAO,CAAC,EAAE,cAAc,GACvB,mBAAmB,CAOrB;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,WAAW,GAAG,MAAM,CAE9D"}

package/dist/ast/types.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Document AST types — the backend integration contract.
+ *
+ * These types define the clean, Lexical-independent AST
+ * that consumers receive when calling getDocumentAst().
+ * Backend teams can use these types directly without any
+ * knowledge of Lexical or React internals.
+ *
+ * @version 1.0.0
+ */
+export declare const AST_VERSION: "1.0.0";
+export interface DocumentAst {
+    version: typeof AST_VERSION;
+    page: PageFormatAst;
+    headerFooter: HeaderFooterConfigAst;
+    pages: PageAst[];
+    metadata: DocumentMetadataAst;
+}
+export interface PageFormatAst {
+    format: 'A4';
+    widthMm: number;
+    heightMm: number;
+    margins: MarginsAst;
+}
+export interface MarginsAst {
+    topMm: number;
+    rightMm: number;
+    bottomMm: number;
+    leftMm: number;
+}
+export interface HeaderFooterConfigAst {
+    enabled: boolean;
+    pageCounterMode: 'none' | 'header' | 'footer' | 'both';
+    defaultHeader: ContentAst | null;
+    defaultFooter: ContentAst | null;
+}
+export interface DocumentMetadataAst {
+    variables: Record<string, VariableDefinitionAst>;
+}
+export interface PageAst {
+    pageIndex: number;
+    body: BlockNodeAst[];
+    header: ContentAst | null;
+    footer: ContentAst | null;
+}
+export interface ContentAst {
+    blocks: BlockNodeAst[];
+}
+export type BlockNodeAst = ParagraphAst | HeadingAst | ListAst | BlockQuoteAst;
+export type Alignment = 'left' | 'center' | 'right' | 'justify';
+export interface ParagraphAst {
+    type: 'paragraph';
+    alignment?: Alignment;
+    indent?: number;
+    children: InlineNodeAst[];
+}
+export interface HeadingAst {
+    type: 'heading';
+    level: 1 | 2 | 3 | 4 | 5;
+    alignment?: Alignment;
+    children: InlineNodeAst[];
+}
+export interface ListAst {
+    type: 'list';
+    listType: 'ordered' | 'unordered';
+    items: ListItemAst[];
+}
+export interface ListItemAst {
+    type: 'list-item';
+    children: InlineNodeAst[];
+    nestedList?: ListAst;
+}
+export interface BlockQuoteAst {
+    type: 'blockquote';
+    children: InlineNodeAst[];
+}
+export type InlineNodeAst = TextRunAst | VariableAst | LineBreakAst;
+export interface TextMarks {
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    strikethrough?: boolean;
+    fontFamily?: string;
+    fontSize?: number;
+}
+export interface TextRunAst {
+    type: 'text';
+    text: string;
+    marks?: TextMarks;
+}
+export interface VariableAst {
+    type: 'variable';
+    key: string;
+    marks?: TextMarks;
+}
+export interface LineBreakAst {
+    type: 'linebreak';
+}
+export interface VariableDefinitionAst {
+    key: string;
+    label: string;
+    description?: string;
+    valueType?: 'string' | 'number' | 'date' | 'boolean';
+    group?: string;
+}
+export interface SaveDocumentRequest {
+    document: DocumentAst;
+    exportTarget?: 'pdf' | 'docx';
+    documentId?: string;
+    metadata?: Record<string, string>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/ast/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/ast/types.ts"],"names":[],"mappings":"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"}