Development

Source mapCopy Anchor Link

Verify the libraryCopy Anchor Link

cargo fmt --all -- --check
cargo check --workspace --all-targets --locked
cargo test --workspace --lib --tests --examples --locked
cargo test --workspace --doc --locked

The checks include settings example model/layout tests. Do not use cargo test --all-targets for ordinary correctness checks: the custom benchmark harness requires cargo bench. Rust CI checks Linux, Windows, macOS, and Rust 1.90; it skips adapter-dependent GPU tests.

To check the minimum toolchain and optional codec boundary:

cargo +1.90.0 check --workspace --all-targets --locked
cargo check --lib --no-default-features --locked

GPU pipeline and native runner checks require a desktop and functioning GPU:

cargo run --example demo -- --smoke-test
cargo run --example settings -- --smoke-test
cargo run --example integration -- --smoke-test

For profiling rather than correctness checks, use Performance.

Custom componentsCopy Anchor Link

Outside the crate, implement Widget by composing the public controls. For example, this passive status row returns the text label's response:

use zaxis::{Color, Response, Text, Ui, Widget};

struct StatusRow {
    text: String,
    color: Color,
}

impl Widget for StatusRow {
    fn ui(self, ui: &mut Ui<'_>) -> Response {
        ui.horizontal(|ui| {
            ui.add(Text::new("●").color(self.color));
            ui.label(self.text)
        })
    }
}

Use ui.add(StatusRow { ... }). Ui::add applies follow-up repaint when the returned response clicks or changes. A composed component's response describes the control it returns, not automatically the entire row.

Public Ui::allocate_space and paint support passive geometry. A widget with its own input asks Ui::interact(rect, id_source, Sense) for its Response; hit registration, paint descriptions and Response construction stay private, so there is one hit path for built-in and external widgets. See Custom widgets.

Inside the library, add a component in this order:

1. Create src/components/<name>.rs with builders, its Widget implementation, and optional impl Ui<'_> helper.
2. Declare pub mod <name>; and re-export the type in src/components/mod.rs.
3. Add a crate-root re-export in src/lib.rs if it belongs in the root API.
4. Use stable scoped IDs, clipped hit regions, and cached paint descriptions.
5. Define whether activation/value change sets the response flags; route helpers through Ui::add.
6. Add the component page and update the API index.

Existing zaxis::widgets compatibility exports then pick up the component automatically.

Work on the documentationCopy Anchor Link

The site uses Fumadocs, MDX, Next.js static export, and Tailwind CSS. Node.js 22 or newer is required; CI uses Node.js 24.

cd docs
npm ci
npm run dev

Open http://localhost:3000. Page content is in content/docs/*.mdx; folder meta.json files control navigation order. Frontmatter contains title, description, and a Lucide icon name registered in lib/source.ts.

Use relative .mdx links for documentation pages. createRelativeLink resolves them to site routes and Next.js applies the deployment base path. Keep text task oriented: commands, signatures, defaults, limits, and a direct link for the next task.

npm run typecheck
npm run build

The result is docs/out, containing static HTML, assets, .nojekyll, and the search index. Search runs in the browser; it requires no API server or external search account.

GitHub PagesCopy Anchor Link

Set repository Settings → Pages → Build and deployment → Source to GitHub Actions. The Documentation workflow builds pull requests and deploys pushes to the default branch (main or master). It can also be started with workflow_dispatch.

The workflow uses /<repository> for project sites and an empty base path for a repository named *.github.io. For this repository the target is nihmadev.github.io/zaxis.

To reproduce that project path locally in PowerShell:

$env:NEXT_PUBLIC_BASE_PATH = '/zaxis'
npm run build

To build for a nihmadev.github.io repository, leave NEXT_PUBLIC_BASE_PATH empty. Upload the contents of out, not the Next.js source or .next directory. Deep routes export as page/index.html, so direct links work on Pages without a server rewrite.

LicensesCopy Anchor Link

Source is MIT licensed. The bundled Inter fonts (UI and SVG text) use the SIL Open Font License. The bundled Noto Color Emoji font also uses the SIL Open Font License. Medium, SemiBold and Bold are static instances of the Inter 4.1 variable font (fonttools varLib.instancer InterVariable.ttf wght=500|600|700 opsz=14), the same recipe as the bundled Regular. Include both licenses when redistributing these fonts.

Contributions and releasesCopy Anchor Link

See CONTRIBUTING.md for contribution guidelines. The current development release is 0.0.3 Genetic, tagged v0.0.3. Report problems in GitHub Issues or contact @nihmadev on Telegram.