docxcraft 0.1.0

# docxcraft


Generate editable Word `.docx` documents in Rust: paragraphs, tables, images,
SVG drawings and native charts, packaged directly as Office Open XML.
Microsoft Office and external services are not required to generate files.

Use this library for reports assembled from your application's data. It is
independent of the Reporsa CLI and report JSON protocol.

## Project status


Source repository: [AlgForce/docxcraft](https://github.com/AlgForce/docxcraft).
The `0.1` API is evolving. See [CHANGELOG.md](CHANGELOG.md) for version details.

The manifest declares Rust 1.89 or later, edition 2021. Recent local checks used
Rust 1.93 on Windows x64. CI is configured for Linux and Windows; this is not a
claim that every Office viewer or toolchain has been verified.

## Start from source


From this repository's root directory:

```bash
cargo run --example basic
cargo run --example chart
```

The examples create `target/examples/basic.docx` and
`target/examples/chart.docx`. This directory is ignored by Git.

Charts use `xlsxcraft` from crates.io. For cross-repository development,
keep a sibling `xlsxcraft` checkout and copy `.cargo/config.example.toml`
to ignored `.cargo/config.toml`. Adjust the local path if needed.
This override is optional; no parent workspace is required.
See [development and publication](RELEASING.md) for registry dependency rules.

## Install in an application


Add the following to your application's `Cargo.toml`:

```toml
[dependencies]
docxcraft = "0.1.0"
```

For local development, use a path dependency such as
`docxcraft = { path = "../docxcraft" }`.
To test a sibling XLSX checkout, configure the following in the
**application's** `.cargo/config.toml` too:

```toml
[patch.crates-io]
xlsxcraft = { path = "../xlsxcraft" }
```

Cargo uses configuration from the directory where it
is invoked, rather than automatically loading a dependency's local config.

## Quick start


This complete program is also [examples/basic.rs](examples/basic.rs):

```no_run
use docxcraft::{
    document::Document,
    paragraph::Paragraph,
    table::{Table, TableCell, TableRow},
};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let locale = String::from("en");
    let mut document = Document::new(&locale);
    document.add_paragraph(Paragraph::new("Quarterly sales".into()).with_bold(true));

    let mut table = Table::new();
    let mut header = TableRow::new();
    header.add_cell(TableCell::header("Quarter"));
    header.add_cell(TableCell::header("Revenue"));
    table.add_row(header);
    let mut row = TableRow::new();
    row.add_cell(TableCell::new("Q1"));
    row.add_cell(TableCell::new("120"));
    table.add_row(row);
    document.add_table(table);

    std::fs::create_dir_all("target/examples")?;
    document.save("target/examples/basic.docx")?;
    Ok(())
}
```

`Document` appends owned content in document order and uses Word's flow layout.
Fonts and pagination are resolved by the application opening the document.
`save` returns an error on I/O or export failure; it creates or truncates the
destination file. Create parent directories and choose an appropriate output path.

## Add an editable chart


[examples/chart.rs](examples/chart.rs) creates a native chart with an embedded
XLSX data workbook. It passes an ECharts-style **JSON string**, with no JavaScript
runtime or ECharts installation:

```no_run
use docxcraft::{chart::Chart, document::Document, paragraph::Paragraph};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let locale = String::from("en");
    let mut document = Document::new(&locale);
    document.add_paragraph(Paragraph::new("Quarterly sales".into()));
    let option = r#"{
        "xAxis": { "type": "category", "data": ["Q1", "Q2"] },
        "yAxis": { "type": "value" },
        "series": [{ "name": "Revenue", "type": "bar", "data": [120, 180] }]
    }"#;
    document.add_chart(Chart::from_echart_option("Revenue", option, None)?);

    std::fs::create_dir_all("target/examples")?;
    document.save("target/examples/chart.docx")?;
    Ok(())
}
```

This adapter implements a subset of ECharts options. It does not render arbitrary
ECharts configurations. Match category labels to numeric series values and
validate your data before conversion; some missing or invalid values fall back
to zero. See [the agent/API guide](docs/agent-guide.md#chart-input).

## API map


| Task | Entry point |
| --- | --- |
| Build and save a document | `document::Document` |
| Plain text and paragraph formatting | `paragraph::Paragraph` |
| Tables | `table::{Table, TableRow, TableCell}` |
| Markdown / HTML content | `markdown::Markdown` / `html_paragraph` |
| Images | `image::Image` |
| Editable SVG subset | `editable_svg::EditableSvgGroup` |
| Native charts | `chart::{Chart, ChartType}` |

Imports are module-qualified; `Document` is not re-exported at the crate root.
Generate local API documentation with `cargo doc --no-deps --open`.
[src/lib.rs](src/lib.rs) defines the public modules.

## Scope and limitations


| Available | Boundary |
| --- | --- |
| New DOCX files with text, tables and images | No API for reading or editing an existing DOCX template |
| Native column, bar, line, pie, radar, scatter, bubble and waterfall chart models | Viewer support varies; the chart adapter is a subset |
| HTML, Markdown and SVG conversion | Subsets, without browser CSS layout or script execution |
| Editable Office content | No PDF export, Word automation or page rendering engine |
| Locale-based font selection | Fonts must be present in the viewer; they are not bundled |

Check complex drawings, charts and pagination in the target Word/WPS/LibreOffice
version. ZIP/XML regression tests check package contents and data; they do not
prove visual equivalence across viewers.

## Develop and contribute


```bash
cargo fmt --all -- --check
cargo test
cargo check --examples
cargo doc --no-deps
```

Add `--offline` to Cargo build/test commands when dependencies are cached.
Issue reports and feature requests are welcome. External code PRs are not
currently accepted while contribution terms are being established.
See [CONTRIBUTING.md](CONTRIBUTING.md) for changes and bug reports,
[CHANGELOG.md](CHANGELOG.md) for release notes, and
[RELEASING.md](RELEASING.md) for maintainer publication steps.

For coding agents, start with [AGENTS.md](AGENTS.md), then read
[docs/agent-guide.md](docs/agent-guide.md). Those files describe repository
boundaries, actual method signatures, ownership and chart-input conventions.

## License and origin


`AGPL-3.0-only`; see [LICENSE](./LICENSE).
Copyright (C) 2026 ALGFORCE INC. Separate commercial licensing inquiries:
[founders@exceldashboard.ai](mailto:founders@exceldashboard.ai). See [LICENSING.md](LICENSING.md) for scope,
[THIRD_PARTY.md](THIRD_PARTY.md) for dependencies, and
[PROVENANCE.md](PROVENANCE.md) for source history.