docs-web-editor

0.1.1 experimental. Embeddable .docx editor for React 18/19. Open, edit, and save Office Open XML in the browser. Not a Microsoft Word substitute; complex documents may round-trip with known gaps (SmartArt read-only, OLE passthrough).

Author: LuckyPower_7

See CHANGELOG.md for per-version release notes (shipped with the npm package).

Install

npm install docs-web-editor

From a local tarball (before or instead of the registry)

# in the repo root
npm run pack -w docs-web-editor
# → packages/docs-editor/docs-web-editor-0.1.0.tgz

# in your host app
npm install /absolute/path/to/docs-web-editor-0.1.0.tgz

From the monorepo path (dev only)

{
  "dependencies": {
    "docs-web-editor": "file:../path/to/repo/packages/docs-editor"
  }
}

Host must run npm run build -w docs-web-editor first so dist/ exists.

Peer dependencies

• react ^18.3.0 || ^19.0.0
• react-dom ^18.3.0 || ^19.0.0

Usage

import { useRef } from 'react'
import { DocsEditor, type DocsEditorHandle } from 'docs-web-editor'
import 'docs-web-editor/style.css'

export function Page() {
  const ref = useRef<DocsEditorHandle>(null)
  return (
    <div style={{ height: '100vh' }}>
      <button type="button" onClick={() => void ref.current?.openLocalFile()}>
        Open
      </button>
      <button type="button" onClick={() => void ref.current?.save()}>
        Save
      </button>
      <DocsEditor
        ref={ref}
        locale="zh"
        blank
        saveMode="both"
        skin={{
          theme: 'light',
          cssVars: {
            '--accent': '#2b579a',
            '--accent-dark': '#1e3f6f',
            '--accent-soft': '#e8f1fb',
          },
        }}
        onSave={async (bytes, meta) => {
          // upload bytes / write to your backend
          console.log(meta.fileName, bytes.byteLength)
        }}
      />
    </div>
  )
}

Notes

• Peer: react / react-dom ^18.3.0 || ^19.0.0
• The published bundle includes docx-engine, TipTap, UI, and font assets. Only React is peer-external.
• The editor shell loads first; TipTap / docx-engine land in dist/chunks/* via dynamic import (faster first paint).
• Lib CSS keeps fonts as separate assets/font-*.ttf|woff2 files (not base64).
• AI / encryption / Electron features are not included.
• Prefer a full-height container; the editor fills 100% of its parent.
• getDocx() serializes the live document; isDirty() / onDirtyChange track unsaved edits.
• Set showFileChrome={false} when the host provides its own Open/Save UI.
• Use saveMode="callback" in embed hosts so save does not trigger a browser download.
• Read/preview mode: set defaultReadMode / controlled readMode + onReadModeChange, or call ref.setReadMode(true) (hides the ribbon).
• TOC: ref.updateToc() refreshes an existing TOC; ref.insertToc({ afterBlockIndex: -1 }) inserts at the start. Both return { ok, reason? }.
• Captions: ref.updateCaptions() renumbers SEQ figure/table titles in body order; ref.insertCaption({ label: '图', text: '…' }) inserts one. Does not update cross-references or Table of Figures.
• Chrome CSS / theme / lang are scoped to .docs-editor-root (does not rewrite host html/body).
• Smoke host: npm run dev -w docs-web-embed-react18 (port 8038) — Open S01 / S01 round-trip.
• License: Apache-2.0 (code). Bundled fonts and libraries: NOTICE, LICENSE-OFL.txt, THIRD_PARTY_LICENSES.md.

Releasing

1. Edit CHANGELOG.md → fill bullets under ## [Unreleased] (### Added / ### Changed / ### Fixed).
2. From repo root:

# bump + rewrite CHANGELOG + build (no publish)
npm run release:editor -- patch

# bump + build + publish (add --otp=… if 2FA)
npm run release:editor -- patch --publish
# or: npm run release:editor -- minor --publish --otp=123456

Empty Unreleased sections are skipped; if there are no bullets, the script aborts so you cannot publish a blank changelog entry.

Caption SEQ renumber is gated by npm run smoke:caption (also run automatically by release:editor before build).