Docx Editor

Major Changes

• 6272b32: # 1.0.0

  First multi-package, multi-framework release. The monolithic @eigenpal/docx-js-editor is split into a framework-agnostic core and per-framework adapters, Vue 3 ships as a first-class adapter alongside React, and the license moves to Apache 2.0 across all packages.

  Package restructure (breaking)

  | Old import | New import |
  | ------------------------------------------ | ----------------------------------------- |
  | @eigenpal/docx-js-editor | @eigenpal/docx-editor-react |
  | @eigenpal/docx-js-editor/react | @eigenpal/docx-editor-react |
  | @eigenpal/docx-editor-react/core | @eigenpal/docx-editor-core |
  | @eigenpal/docx-editor-react/headless | @eigenpal/docx-editor-core/headless |
  | @eigenpal/docx-editor-react/core-plugins | @eigenpal/docx-editor-core/core-plugins |
  | @eigenpal/docx-editor-react/mcp | @eigenpal/docx-editor-agents/mcp |
  | @eigenpal/docx-editor-react/i18n/*.json | @eigenpal/docx-editor-i18n/*.json |

  The old @eigenpal/docx-js-editor package stays on 0.x for legacy maintenance — no 1.x compatibility shim ships. Framework-agnostic utilities (e.g. createEmptyDocument) move to core:

  - import { DocxEditor, createEmptyDocument } from '@eigenpal/docx-js-editor';
  + import { DocxEditor } from '@eigenpal/docx-editor-react';
  + import { createEmptyDocument } from '@eigenpal/docx-editor-core';
  

  Vue 3 adapter (@eigenpal/docx-editor-vue)

  The Vue package becomes a real adapter (previously a stub). Public API mirrors React:

  • <DocxEditor> with matching prop surface
  • useDocxEditor composable + renderAsync for the Node.js path
  • /ui, /composables, /dialogs, /plugin-api, /styles subpaths

  Parity gates cover insert-table, find/replace, page-setup, context menus, image overlay (resize/move/rotate/aspect-locked corners, dimension tooltip), advanced cell/row options (margins, height rule, text direction, no-wrap), menu-bar icons + shortcuts + carets, toolbar pickers, and the agent UI surface.

  Shared i18n package (@eigenpal/docx-editor-i18n)

  Locale strings move out of @eigenpal/docx-editor-react into a dedicated package consumed by both adapters from a single source.

  - import de from '@eigenpal/docx-editor-react/i18n/de.json';
  + import de from '@eigenpal/docx-editor-i18n/de.json';
  

  The defaultLocale value (English) is still re-exported from the adapter packages, unchanged.

  Agent UI relocation (breaking)

  AgentPanel, AgentChatLog, AgentComposer, AgentSuggestionChip, AgentTimeline no longer ship from @eigenpal/docx-editor-react. They live at:

  • @eigenpal/docx-editor-agents/react — React components + useAgentChat
  • @eigenpal/docx-editor-agents/vue — Vue 3 twins, plus AIContextMenu and AIResponsePreview
  • @eigenpal/docx-editor-agents/ai-sdk/react / /ai-sdk/vue — @ai-sdk/* adapters
  • @eigenpal/docx-editor-agents/bridge — React-free createEditorBridge, agentTools, executeToolCall, getToolSchemas, createReviewerBridge. Safe for headless / Vue / Node.

  - import { AgentPanel, AgentChatLog } from '@eigenpal/docx-editor-react';
  + import { AgentPanel, AgentChatLog } from '@eigenpal/docx-editor-agents/react';
  

  The agent components no longer call useTranslation directly — pass localized *Label props instead. <DocxEditor>'s built-in agent panel slot still forwards localized strings automatically.

  Accessibility polish on the agent surface: keyboard-operable resize handle, Escape-dismissable context menu, live-region chat log, WCAG AA contrast on response previews.

  Toolbar naming unified (breaking)

  The standalone formatting bar is Toolbar on both adapters. The old "classic" single-row Toolbar (with File/Format/Insert menus baked in) is removed — compose EditorToolbar.MenuBar + EditorToolbar.Toolbar for that layout.

  | Old (React) | New (React + Vue) |
  | ------------------------------ | ----------------------- |
  | FormattingBar | Toolbar |
  | Classic Toolbar (with menus) | EditorToolbar |
  | EditorToolbar.FormattingBar | EditorToolbar.Toolbar |

  Vue: BasicToolbar / FormattingBar aliases removed; EditorToolbar's formatting-bar slot is now toolbar. Vue's table border-color and cell-fill pickers now use the advanced color picker matching React. Vue MenuDropdown's showChevron default flips from true to false — pass :show-chevron="true" explicitly to keep the caret.

  showPrintButton prop removed (breaking)

  Removed from <DocxEditor> and <Toolbar> on both adapters; the Vue <Toolbar> print event is gone with it. onPrint callback stays.

  - <DocxEditor showPrintButton onPrint={handlePrint} />
  + <DocxEditor onPrint={handlePrint} />
  

  To hide File > Print, omit onPrint. Programmatic print still works via ref.current.print() / editorRef.value.print().

  License moves to Apache 2.0

  All published packages relicense to Apache 2.0. Notably: @eigenpal/docx-editor-agents was AGPL-3.0-or-later — the relicense lifts copyleft obligations on agent embedders.

• fd1f9de: @eigenpal/docx-editor-i18n ships its public surface as named exports from the package root. One import path, IDE-discoverable, tree-shakeable.

  import {
    // Locale data — typed
    en,
    de,
    pl,
    tr,
    he,
    ptBR,
    zhCN,
    // Runtime lookup by BCP-47 tag
    locales,
    // Types
    type LocaleStrings,
    type Translations,
    type TranslationKey,
    type LocaleCode,
  } from '@eigenpal/docx-editor-i18n';
  

  en is typed as LocaleStrings (source of truth, 100% coverage). Every other locale is PartialLocaleStrings (null leaves fall back to English). Hyphenated locale codes use camelCase identifiers (ptBR, zhCN); the locales record keeps BCP-47 keys ('pt-BR', 'zh-CN') for runtime lookup.

  The package is marked sideEffects: false, so importing one locale from the root tree-shakes the rest. Verified with esbuild: a consumer importing only en ships ~26KB.

  Breaking from earlier (unpublished) shape: the ./<locale>.json subpath exports are gone. Everything goes through the root. The LocaleStrings, Translations, PartialLocaleStrings, and TranslationKey types are no longer re-exported from -react or -vue. Runtime exports from the adapters (LocaleProvider, useTranslation, provideLocale, i18nPlugin, createTranslator, defaultLocale) are unchanged.

Patch Changes

• c395aa6: Render anchored DOCX text boxes with square text wrapping instead of converting them into standalone blocks.

• 0187af2: Emit consumer-friendly JSON docs at docs/json/<pkg-slug>/<subpath>.json for every @public export across the published packages. Companion to the existing etc/<slug>.api.md snapshots — same source of truth (API Extractor), different output shape: instead of human-readable Markdown, the JSON is structured for a docs site to render any layout it wants. Includes per-export source-link URLs into the GitHub source tree, type-reference canonical IDs for cross-page linking, and TSDoc summaries/remarks/examples parsed out of the source.

  New tooling: bun run docs:json regenerates, bun run docs:check (in CI) fails on drift. Contract documented in CLAUDE.md under ### Docs JSON. No runtime change to any published package.

• 9d4d30e: Anchor hyperlink popup to its link on scroll; close Vue popup on outside click.

• 5d11c1a: Fix dense footnote rendering at page bottom

• bba58e4: Internal refactor: continue the DocxEditor.tsx cap effort. Extract the 432-LOC useImperativeHandle block into a useDocxEditorRefApi hook (preserves the dep array byte-for-byte so the editor-contract gate stays green). Pull the floating-overlay block (hyperlink popup, text + image context menus, toast container) into DocxEditorOverlays. Pull the lazy-loaded Suspense dialog block into DocxEditorDialogs — the lazy() import sites move with the JSX so the dialog code-split chunk is owned by the new component. Memoize the 60-line onSelectionChange closure on the PagedEditor mount. DocxEditor.tsx now 3724 → 3183 LOC. No public API change.

• 5a4ef95: Internal refactor: continue the DocxEditor.tsx cap effort, mirroring Vue's hook decomposition. Three more domain hooks extracted: useContextMenus (right-click text + image menus, contextMenuItems memo, handleContextMenuAction switch — comment-state writes routed through an onAddComment callback), useCommentManagement (controlled/uncontrolled comments routing, floating add-comment button position, new-comment workflow state, commentsRef mirror, orphaned-comments debouncer), and useCommentLifecycle (thread comments under overlapping tracked changes, auto-open sidebar on documents with existing tracked changes). DocxEditor.tsx 2634 → 2234 LOC. No public API change.

• cff5be4: Internal refactor: continue the DocxEditor.tsx cap effort by splitting the JSX render tree. Two new child components: DocxEditorToolbar (wraps the EditorToolbar with its 30+ props plus the title-bar slots and trailing extras) and DocxEditorPagedArea (PagedEditor mount, sidebar overlay, floating add-comment button, inline header/footer editor). DocxEditor.tsx 1972 → 1815 LOC. No public API change.

• 6ff5d22: Internal refactor: split DocxEditor.tsx (5158 → 3712 LOC, -28%) into focused hooks under components/DocxEditor/hooks/ — useOutlineSidebar, useKeyboardShortcuts, useFileIO, usePageSetupControls, useHyperlinkActions, useFindReplaceBridge, useFormattingActions, useImageActions — plus 6 micro-components (CommentsSidebarToggle, LocalizedAgentPanel, PageIndicator, AgentPanelToggle, OutlineToggleButton, EditingModeDropdown) and a commentFactories module that hides the shared comment/revision ID counter behind getNextCommentId/bumpNextCommentIdAbove helpers. No public API change.

• 999a48d: Internal refactor: split PagedEditor.tsx (3230 → 775 LOC) into focused hooks under components/DocxEditor/hooks/ — useLayoutPipeline, useSelectionOverlay, useImageInteractions, usePagedScrollApi, usePagesPointer, usePagedEditorRefApi, useLayoutTriggers — plus pure helpers domSelection.ts + tableResize.ts. No public API change.

• 348fa6b: API Extractor snapshots for the 6 published subpaths of @eigenpal/docx-editor-react (root, /ui, /hooks, /dialogs, /plugin-api, /styles) and @eigenpal/docx-editor-vue (root, /ui, /composables, /dialogs, /plugin-api, /styles). CI now fails on undocumented public-surface drift via bun run api:check.

  Adds etc/parity.contract.json — the cross-adapter parity contract listing which DocxEditorProps fields and DocxEditorRef members are paired between React and Vue, which are deliberately deferred in Vue, and which are Vue-exclusive. bun run check:parity-contract (also gated in CI) parses both snapshots and fails on any drift the contract doesn't acknowledge. Adding a new prop or ref method to either adapter forces an explicit classification in the contract.

  Vue composables now declare named Use*Return interfaces (UseClipboardReturn, UseFindReplaceReturn, UseSelectionHighlightReturn, UseTableSelectionReturn, UseHistoryReturn, UseTableResizeReturn, UseDragAutoScrollReturn, UseVisualLineNavigationReturn, UseDocxEditorReturn). Before this change the composables returned anonymous object literals that recursively expanded core's internal types in the published .d.ts, inflating etc/composables.api.md to 3,526 lines and locking core's internal Run/Comment shape into Vue's public contract. Named returns drop the snapshot to ~450 lines and decouple Vue's surface from core's internals.

  Vue's useTableSelection no longer exposes manager: TableSelectionManager in its return — it was unused by any internal consumer and leaked core's TableSelectionManager class as part of Vue's public surface.

  Side effect for @eigenpal/docx-editor-vue: the build no longer writes workspace-relative source paths (e.g. ../../core/src/core.ts) into published declarations. Those paths were valid in this repo but unresolvable once installed from npm; setting pathsToAliases: false on the dts plugin keeps the package names (@eigenpal/docx-editor-core, @eigenpal/docx-editor-i18n) intact in dist/*.d.ts.

  No runtime change for either package.

• 29f9575: Preserve fields, nested SDTs, and math inside <w:sdt> content controls so docProps-bound titles wrapped in SDT render correctly.

• 491ec9a: Preserve fields, nested SDTs, and math inside inline SDT content on save. Completes #482 by mirroring its parser-side widening in the serializer and PM → Document converter so docProps-bound title fields survive a full load → edit → save round-trip.

• 5a30387: Inherit header/footer references and titlePg from earlier sections per ECMA-376 §17.6. Fixes templates that set these on the cover sectPr only.

• 7c3f2e1: Internal Vue refactor: extract useImageActions, useContextMenus, usePagesPointer, useSelectionSync, and useDocxEditorRefApi composables from DocxEditorVue.vue. No public API change.

• 9233c6e: Internal: DocxEditorVue.vue now under the 1000-LOC cap (897). Split template into DocxEditorMenuBar, DocxEditorDialogs, DocxEditorOverlays; extracted useMenuActions, useCommentLifecycle, useDocumentLifecycle composables; moved styles to a co-located .css file. No public-API change.

• 372cab6: vue: internal source restructure for React parity — DocxEditorVue.vue → DocxEditor.vue, root-level docx-editor-props.ts / editor-mode.ts / editor-ref.ts consolidated into components/DocxEditor/types.ts, orchestration files nested under components/DocxEditor/. No public API change.

• Updated dependencies [6272b32]

• Updated dependencies [c5125ff]

• Updated dependencies [76093f9]

• Updated dependencies [c5125ff]

• Updated dependencies [348fa6b]

• Updated dependencies [0187af2]

• Updated dependencies [6b8f1fb]

• Updated dependencies [61983ca]

• Updated dependencies [f7b8dc7]

• Updated dependencies [b2230a3]

• Updated dependencies [8836214]

  • @eigenpal/[email protected]
  • @eigenpal/[email protected]
  • @eigenpal/[email protected]