bun-docx 0.16.0 → 0.18.0

package/README.md

@@ -184,17 +184,19 @@ docx edit   FILE --at LOCATOR <content>                   # LOCATOR = pN | pN:S-
 docx delete FILE --at LOCATOR                             # LOCATOR = pN | pN-pM | tN | sN | tN:rRcC:pK (cell paragraph)
 docx sections FILE [--at LOCATOR] [--columns N] [--type T] [--orientation O] [--size SIZE] [--margins M]   # LOCATOR = pN-pM | pN (wrap a range in N columns) | sN (edit one section's columns/type/page geometry). Multi-column layout AND page setup live HERE. PAGE GEOMETRY (margins/orientation/size) with NO --at applies to the WHOLE document (every section); --at sN targets one. Columns/type need --at.
 docx styles set-default-font FILE "Font Name" [--size N] [--all]   # document-wide font: sets styles.xml docDefaults + theme major/minor; --all also repoints styles/runs that pin their own font
-docx replace FILE PATTERN REPLACEMENT [--regex] [--ignore-case] [--all] [--limit N] [--current | --baseline] [--exact] [--track] [--dry-run]
+docx replace FILE PATTERN REPLACEMENT [--at pN] [--regex] [--ignore-case] [--all] [--limit N] [--current | --baseline] [--exact] [--track] [--dry-run]
 #   Keeps the run's formatting (bold/font) and any tabs — the no-rebuild way to fill a
 #   formatted/tabbed template line (e.g. "**Org Name**⇥Date"); don't hand-build --runs to refill it.
-#   A span edit (find → edit --at pN:S-E --text NEW) does the same by locator.
+#   --at pN (or a cell paragraph tT:rRcC:pN) CONFINES the replace to one paragraph — use it when the
+#   SAME placeholder repeats across the doc (a résumé's "City, State" in every entry) and you want THE
+#   one in a specific paragraph, instead of find → edit --at pN:S-E span surgery. Batch entries take "at" too.
 
 # Batch — apply many changes from ONE read (no re-reading between edits). Keys
 # on each JSONL line mirror the command's flags; all locators address the doc as
 # read. insert/edit also accept --batch - to read JSONL from stdin.
 docx edit    FILE --batch fills.jsonl       # { at, <one of: text|clear|markdown|runs|code|task>, style?, … }
 docx insert  FILE --batch additions.jsonl   # { after|before, <content>, style?, color?, … }
-docx replace FILE --batch script.jsonl      # { pattern, replacement, regex?, all?, limit?, … } applied in order
+docx replace FILE --batch script.jsonl      # { pattern, replacement, at?, regex?, all?, limit?, … } applied in order ("at" scopes that entry to one paragraph)
 docx delete  FILE --batch drop.jsonl        # { at } per line — whole blocks (pN/tN/cell), resolved live-first
 
 # All four of insert/edit/delete/replace accept --track to record that one
@@ -281,16 +283,33 @@ docx tables set-widths    FILE --at tN --widths "25%,25%,50%" | "1440,..." | aut
 docx tables merge         FILE --at tN:rR1cC1-rR2cC2
 docx tables unmerge       FILE --at tN:rRcC
 docx tables borders       FILE --at tN [--style single|double|none] [--size N] [--color HEX]
+docx tables format        FILE --at LOCATOR [--shade HEX|NAME] [--valign top|center|bottom]
+                          [--halign left|center|right|justify] [--cell-borders SIDES]
+                          [--align left|center|right] [--style ID] [--row-height M] [--repeat-header]
+
+docx lists set            FILE --at pN [--start N] [--format FMT] [--restart] [--continue]
+                          # renumber a NUMBERED list (--at = any item; applies to the whole list).
+                          # FMT = decimal | lower-alpha | upper-alpha | lower-roman | upper-roman.
+                          # --restart splits a fresh list off here; --continue picks up the previous
+                          # list's numbering instead of restarting. Untracked (Word records no revision).
 
 docx track-changes on|off FILE
+docx track-changes list   FILE [--json]
 docx track-changes accept FILE (--at tcN [--at tcM ...] | --at revN | --all)
 docx track-changes reject FILE (--at tcN [--at tcM ...] | --at revN | --all)
-# A del+ins REPLACE pair shares a "group": "revN" in `list`; `--at revN` accepts/rejects
-# both halves in one call (no re-list between them — tcN ids renumber after each accept).
+docx track-changes apply  FILE [--accept H ...] [--reject H ...]
+# `list` defaults to a text table, one LOGICAL change per line (revN collapses a del+ins
+# pair onto one line); `--json` for the raw array. A del+ins REPLACE pair shares a
+# "group": "revN"; `--at revN` accepts/rejects both halves in one call.
+# To FINALIZE a review (accept some, reject the rest), use `apply` — it takes both decision
+# lists in ONE call, resolved against the original ids, so nothing renumbers mid-operation
+# and the file is never left half-finalized. Doing it as separate accept then reject calls
+# renumbers the ids between them. After a subset accept/reject/apply, the confirmation
+# re-lists what remains with its renumbered handles.
 ```
 
 > **One rule to memorize: addressing an existing thing is always `--at`.**
-> `comments reply/resolve/delete`, `footnotes/endnotes edit/delete`, `images extract/replace/delete`, `hyperlinks replace/delete`, `tables *`, `track-changes accept/reject`, `edit`, and `delete` all take `--at LOCATOR`. The exceptions are positional or directional by nature: `insert` uses `--after`/`--before LOCATOR` (or `--at-start`/`--at-end` for the document boundaries, no locator); `read` slices with `--from`/`--to LOCATOR`; `wc` takes a positional `[LOCATOR]`; `find`/`replace` take a positional `QUERY`/`PATTERN`. `images extract --to DIR` is an *output directory*, not a locator.
+> `comments reply/resolve/delete`, `footnotes/endnotes edit/delete`, `images extract/replace/delete`, `hyperlinks replace/delete`, `tables *`, `track-changes accept/reject`, `edit`, and `delete` all take `--at LOCATOR`. The exceptions are positional or directional by nature: `insert` uses `--after`/`--before LOCATOR` (or `--at-start`/`--at-end` for the document boundaries, no locator); `read` slices with `--from`/`--to LOCATOR`; `wc` takes a positional `[LOCATOR]`; `find`/`replace` take a positional `QUERY`/`PATTERN` (and `replace` accepts an optional `--at pN` to *confine* the substitution to one paragraph). `images extract --to DIR` is an *output directory*, not a locator.
 
 ## Output contract
 
@@ -420,6 +439,8 @@ docx track-changes accept doc.docx --at tc0 --at tc2   # or --all
 
 **Edit & create styles.** `docx styles set FILE --at Heading1 --color 1F4E79 --size 16 --bold` rewrites the *style definition* in `word/styles.xml`, so every paragraph or run that uses the style picks up the change at once ("make all Heading 1s green") — the same run-/paragraph-formatting flags as `edit` (color/font/size/highlight/underline/caps + alignment/spacing/indentation for paragraph styles). `docx styles create FILE Callout --color C00000 --bold` mints a new paragraph or character style that `insert/edit --style Callout` can then apply. Editing an un-materialized built-in (`--at Heading3` on a doc that never used it) provisions it first; a paragraph with its own *direct* formatting keeps it (the override wins — the definition edit never touches the body). Style edits are **not** tracked changes even under track-changes — matching Word, which applies style-definition edits to `styles.xml` directly with no redline.
 
+**List numbering.** `docx lists set FILE --at p12 --start 5` makes a numbered list begin at 5; `--format upper-roman` (or `lower-alpha`/`upper-alpha`/`lower-roman`) switches the glyph; `--restart` splits a fresh list off at that item; `--continue` makes a list pick up the previous list's numbering instead of restarting. `--at` names any item — the change applies to the whole list. The start round-trips through the markdown ordinal (the body reads `5. 6. 7.`); the glyph and any continue link, which GFM can't express, surface as a deviation-only `<!-- docx:list p12 format="upper-roman" -->` / `<!-- docx:list p20 continues -->` hint (dropped on import, like every `docx:` note — `read --ast` carries `list.start`/`list.format` losslessly). Untracked, matching Word, which records no revision for a list-numbering change.
+
 **Run formatting beyond bold/italic.** Properties markdown has no native syntax for — text color, theme color, highlight, shading, underline (all 18 styles + color), super/subscript, small/all caps, font, and size — are emitted as the **HTML a markdown reader actually renders**, so the output looks right in GitHub, VS Code, Obsidian, and browsers (Pandoc `[text]{…}` spans render as literal brackets in all of those). `read` emits semantic tags where they exist — `<mark>overdue</mark>`, `<sup>x</sup>`, `<sub>2</sub>` — a `<span style="color:#C00000">…</span>` for the CSS-expressible properties, and `data-*` attributes for the OOXML-only ones CSS can't express (theme colors, underline styles); `insert/edit --markdown` parses them back losslessly, and a leading `<!-- docx:base font="Arial" size="8pt" -->` note declares the document's dominant font/size once so the body isn't buried in per-run repetition. Bold/italic/strike/code/links stay native (`**`/`*`/`~~`/`` ` ``/`[](…)`). Because the inline-surgery transform scans whole sibling sequences, a CriticMarkup marker or span can straddle other formatting — `{++**bold insertion**++}` is tracked correctly. An invalid enum value (e.g. a bogus highlight name) fails with a clear error rather than silently vanishing. Inserted plain content inherits the surrounding paragraph's font/size so it blends in.
 
 **Visual verification.** `docx render` is the only command that needs an external runtime: it drives Microsoft Word (macOS via `osascript`, Windows via PowerShell COM — the ground-truth renderer) or LibreOffice (`soffice`, cross-platform) to produce a PDF, then rasterizes in-process via the bundled `@hyzyla/pdfium` WASM package — no poppler/pdftoppm/ImageMagick needed. Agents that consume PNGs use this to verify edits, diff accept/reject before-vs-after, or generate screenshots.