bun-docx 0.4.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +44 -5
  2. package/dist/index.js +1834 -381
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -31,8 +31,8 @@ bunx bun-docx read doc.docx
31
31
 
32
32
  ```sh
33
33
  docx create FILE [--title T] [--author A] [--text "..."]
34
- docx read FILE
35
- docx insert FILE --after p3 --text "..." [--style HeadingN] [--color HEX] [--bold] [--italic]
34
+ docx read FILE [--markdown [--from pN] [--to pN] [--changes] [--comments]]
35
+ docx insert FILE --after p3 --text "..." [--style HeadingN] [--color HEX] [--bold] [--italic] [--url URL]
36
36
  docx insert FILE --after p3 --runs '[{"type":"text","text":"X","bold":true}]'
37
37
  docx edit FILE --at p3 --text "..." | --runs '[...]'
38
38
  docx delete FILE --at p3
@@ -50,6 +50,11 @@ docx images list FILE
50
50
  docx images extract FILE --to ./media [--id imgN]
51
51
  docx images replace FILE --at imgN --with ./new.png
52
52
 
53
+ docx hyperlinks list FILE
54
+ docx hyperlinks add FILE --at pN:S-E --url URL
55
+ docx hyperlinks replace FILE --at linkN --with URL
56
+ docx hyperlinks delete FILE --at linkN
57
+
53
58
  docx track-changes FILE on|off
54
59
  docx info schema [--ts]
55
60
  docx info locators [--json]
@@ -59,6 +64,37 @@ Every command has `--help`. Mutating commands accept `--dry-run` and `-o/--outpu
59
64
 
60
65
  When `<w:trackChanges/>` is set in the doc (toggle via `docx track-changes FILE on`), `insert`/`edit`/`delete`/`replace` automatically emit `<w:ins>`/`<w:del>` markers attributed to `$DOCX_AUTHOR` (default `docx-cli`). To make a one-off untracked edit, flip the flag off, edit, then flip it back on. `find` results inside tracked-change wrappers carry a `trackedChanges` array so agents can decide what to do with hits in pending insertions/deletions.
61
66
 
67
+ ### Markdown rendering
68
+
69
+ `docx read FILE --markdown` renders the document body as GitHub-flavored Markdown instead of JSON. Useful when you (or an LLM) want to skim a doc quickly without parsing the AST. Each rendered paragraph is followed by an HTML comment with its locator (`<!-- p3 -->`) so the markdown is invisible-pinned: humans see clean prose in a renderer, agents parse the locators from raw text.
70
+
71
+ - Headings → `#`/`##`/`###` based on `style="HeadingN"`
72
+ - Lists → `- ` indented per `level`
73
+ - Bold/italic/strike → `**…**` / `*…*` / `~~…~~`; underline → `<u>…</u>`
74
+ - Run color → `<span style="color:#hex">…</span>`; highlight → `<span style="background-color:NAME">…</span>`
75
+ - Hyperlinks → `[text](url)`
76
+ - Images → `![alt](imgN)`
77
+ - Tables → GitHub pipe tables; multi-paragraph cells joined with `<br>`; per-cell-paragraph locators inline
78
+ - Section breaks → `---`
79
+ - Equations (`<m:oMath>`/`<m:oMathPara>`) → `` `equation: text` `` (concatenated `<m:t>` plaintext; structure like sub/sup/fractions collapses to literal characters — degraded but readable)
80
+ - Footnotes / endnotes → inline `[^fnN]` / `[^enN]` refs with GFM footnote definitions at end of output
81
+ - Charts / SmartArt / shapes / other non-picture drawings → `` `[chart]` `` / `` `[smartart]` `` / `` `[shape]` `` / `` `[drawing]` `` placeholders
82
+
83
+ `--from LOC` and `--to LOC` slice by top-level block (both inclusive). Accepts paragraph, table, cell, span, and range locators; cell/span/range collapse to their enclosing top-level block. Comment/image/hyperlink locators are rejected.
84
+
85
+ `--changes` renders tracked insertions and deletions as `<ins>`/`<del>` instead of producing the accepted view (which silently drops deletions and inlines insertions).
86
+
87
+ `--comments` appends a GFM footnote reference (`[^cN]`) at the end of each commented span and emits one footnote definition per comment at the end of the output:
88
+
89
+ ```
90
+ … some commented text[^c0] …
91
+
92
+ [^c0]: "commented span" — Author Name (2024-01-15T...): comment body
93
+ [^c1]: "another span" — Author Name (2024-01-15T...) ↳ c0: reply body
94
+ ```
95
+
96
+ Footnotes/endnotes (the document's own `<w:footnoteReference>` / `<w:endnoteReference>`) are rendered unconditionally — `[^fn1]` / `[^en1]` inline + `[^fn1]: body` definitions at the end of the output, alongside any `--comments` footnotes. They use `fn`/`en` prefixes so the namespaces don't collide.
97
+
62
98
  ### Locators
63
99
 
64
100
  ```
@@ -66,7 +102,7 @@ pN paragraph N (e.g., p3)
66
102
  pN:S-E characters S..E within paragraph N
67
103
  pN:S-pM:E cross-paragraph range
68
104
  tN table N; tN:rRcC for cell at row R, col C
69
- cN, imgN comment / image ids
105
+ cN, imgN, linkN comment / image / hyperlink ids
70
106
  ```
71
107
 
72
108
  Run `docx info locators` for the full reference.
@@ -99,19 +135,20 @@ src/
99
135
  help.ts # top-level --help
100
136
  respond.ts # JSON ack / structured error helpers
101
137
  create/ # create FILE
102
- read/ # read FILE
138
+ read/ # read FILE [--markdown ...] (markdown.ts renderer)
103
139
  insert/ # insert FILE (uses ./emit Paragraph component)
104
140
  edit/ # edit FILE
105
141
  delete/ # delete FILE
106
142
  comments/ # add | reply | resolve | delete | list
107
143
  images/ # list | extract | replace
144
+ hyperlinks/ # add | list | replace | delete
108
145
  track-changes/ # FILE on|off
109
146
  info/ # schema | locators (reference output)
110
147
  core/
111
148
  package/ # JSZip open/close, named-part read/write
112
149
  parser/ # XmlNode class + parse/serialize + JSX factory
113
150
  jsx/ # h, Fragment, namespaces (w, r, a, wp, pic, ...)
114
- ast/ # types + DocView + XML→AST reader
151
+ ast/ # types + DocView + XML→AST reader (text.ts: shared paragraph helpers)
115
152
  locators/ # parse "p3:5-20" + resolve to refs
116
153
  tests/
117
154
  core/, cli/, integration/
@@ -137,6 +174,8 @@ tests/
137
174
 
138
175
  **Cross-format image replacement.** `images replace --at img0 --with new.png` detects the new MIME type via `Bun.file().type`, renames the part (`word/media/image1.jpeg` → `word/media/image1.png`), rewrites the relationship `Target`, and ensures `[Content_Types].xml` has a `<Default>` for the new extension.
139
176
 
177
+ **Hyperlink CRUD.** `hyperlinks list` enumerates `<w:hyperlink>` elements with positional `linkN` ids; `hyperlinks add --at p3:5-20 --url URL` wraps an existing span (splitting runs at offsets); `hyperlinks replace --at link0 --with URL` updates the rels `Target`, allocating a new rId if the existing one is shared so siblings stay pointed at the original URL; `hyperlinks delete --at link0` unwraps the link (text survives) and prunes the rels entry when no longer referenced.
178
+
140
179
  ## CI
141
180
 
142
181
  GitHub Actions (`.github/workflows/ci.yml`) runs four jobs on push to `main` and on PRs: