# Using docxcraft from an agent
## Read in this order
1. [README](../README.md): source setup, complete examples and scope.
2. [basic example](../examples/basic.rs) and [chart example](../examples/chart.rs).
3. [src/lib.rs](../src/lib.rs): public module names.
4. The relevant module and its unit tests; [tests/export.rs](../tests/export.rs)
checks real DOCX contents and the embedded chart workbook.
This is an independent Rust library. The caller supplies data and chooses output
paths; there is no Reporsa report schema, model call or database integration.
## Construction and ownership
Use these module paths and signatures; do not infer a common API from a sibling
Office crate:
```text
docxcraft::document::Document::new(locale: &String) -> Document
docxcraft::paragraph::Paragraph::new(text: String) -> Paragraph
Document::add_paragraph(&mut self, paragraph: Paragraph)
Document::add_table(&mut self, table: Table)
Document::add_chart(&mut self, chart: Chart)
Document::save(&self, path: &str) -> anyhow::Result<()>
```
Create `let locale = String::from("en");` and pass `&locale` to `Document::new`.
The document owns content passed to `add_*`, preserving insertion order.
Paragraph builders such as `with_bold(bool)` and `with_size(u32)` consume and
return the paragraph. Paragraph font size is in points. Use flow content rather
than copying slide x/y coordinates into paragraph fields.
`TableRow::add_cell` takes one `TableCell`. `Table::add_row` takes a
`TableRow`, rather than the vector used in `pptxcraft`.
`Markdown::new` takes a `String`.
`Image::from_svg_string` takes exactly two `String` arguments: SVG and alt text.
For editable Office drawing conversion, inspect `EditableSvgGroup` instead of
assuming image insertion converts every SVG element to editable shapes.
There is no public document-loading API or `Document::save_to_buffer`.
`save` uses `File::create` and can overwrite an existing file. Create the
parent directory first and propagate failures with `?` or add caller context.
## Chart input
The entry point in [chart.rs](../src/chart.rs) is:
```text
Chart::from_echart_option(
title: &str,
option: &str,
theme: Option<serde_json::Value>,
) -> anyhow::Result<Chart>
```
Pass serialized JSON text, not JavaScript source, a filename or a JSON value.
`None` selects the default theme. A small category chart uses:
```json
{
"xAxis": { "type": "category", "data": ["Q1", "Q2"] },
"yAxis": { "type": "value" },
"series": [{ "name": "Revenue", "type": "bar", "data": [120, 180] }]
}
```
The bar series above produces a vertical column chart. This shape is a tested
example, not a complete ECharts schema. Other chart families use different input
shapes; read the corresponding parser branches and tests before constructing them.
No ECharts JavaScript engine is used. The output contains native chart XML and
an embedded XLSX workbook generated with `xlsxcraft`.
Validate source data before conversion. In particular, align category and series
lengths, provide valid finite numbers and handle missing values explicitly.
Some parser paths substitute zero instead of reporting an invalid value.
Do not assume arbitrary ECharts options, callbacks or CSS are supported.
## Repository map
| `src/document.rs` | Content order, DOCX ZIP parts and relationships |
| `src/paragraph.rs`, `src/table.rs` | Text and table XML |
| `src/chart.rs` | Chart input, native XML and embedded workbook data |
| `src/image.rs`, `src/editable_svg.rs` | Media and SVG subset conversion |
| `src/markdown.rs`, `src/html_paragraph.rs` | Rich-text conversion |
| `assets/` | Bundled Word XML templates required at compile time |
| `tests/export.rs` | End-to-end package and chart-data regression |
| `examples/` | Runnable consumer programs |
Keep all referenced templates in Cargo's package include list. The crate needs
no sibling source checkout after its required `xlsxcraft` version is published.
For pre-release local builds, follow the README's Cargo override instructions.
## Verify a change
```bash
cargo fmt --all -- --check
cargo test
cargo check --examples
cargo run --example basic
cargo run --example chart
cargo doc --no-deps
cargo package --list
```
Run from this repository's root. `cargo test` includes README Rust code blocks
because `src/lib.rs` includes the README as crate documentation.
Examples write only to `target/examples/`. For an export regression, open the
ZIP and inspect `word/document.xml`, chart XML, relationships and embedded XLSX
data, following `tests/export.rs`. Use temporary paths in tests.
Compilation, XML assertions and an actual viewer check are different evidence.
Report which you performed; inspect complex pagination and drawings in the intended
viewer before claiming visual fidelity.
## Troubleshooting
| Cargo cannot resolve `xlsxcraft` before publication | Configure the local patch at the Cargo invocation root |
| Missing glyphs or unexpected line/page breaks | Viewer fonts, locale and paragraph settings |
| Chart values appear as zero | Original numeric values and category/series lengths |
| SVG/HTML appearance differs | The converter's supported subset; browser CSS is not reproduced |
| Save fails | Existing parent directory, path permissions and whether a viewer locks the file |
## Licensing and dependency changes
Read [THIRD_PARTY.md](../THIRD_PARTY.md) and [LICENSING.md](../LICENSING.md)
when changing dependencies or distribution. Generate a fresh dependency/notice
inventory with `cargo run --example license_inventory -- --check-package`.
The maintainer utility is outside the consumer examples, at
`tools/license_inventory.rs`; it writes under `target/license-inventory/`.
It collects notices and metadata, rather than certifying licensing or bundling
corresponding source. Follow [RELEASING.md](../RELEASING.md) for delivery checks.