Developer Guide for Extending the zzson Web Tool

This guide is for developers who want to contribute to or extend the zzson web tool. It covers the project structure, build process, and key development considerations.

Project Structure

The zzson project uses a multi-crate Cargo workspace structure with Jekyll integration for web tools.

Workspace Structure

  • Root: Multi-crate workspace with Cargo.toml defining members
  • crates/core: Core parsing functionality and AST types
  • crates/cli: Command-line interface binary
  • crates/wasm: WebAssembly bindings for browser use
  • crates/serde: Serde integration for serialization support
  • crates/test-utils: Shared testing utilities

Web Tools Structure

  • docs/: The root directory for the GitHub Pages site.
    • _config.yml: Jekyll configuration file.
    • tool.html: ZZSON interactive tool (WebAssembly-powered)
    • jsonic.html: Jsonic interactive tool (CDN-powered)
    • zzson-tool.md: Jekyll wrapper for ZZSON tool
    • jsonic-tool.md: Jekyll wrapper for Jsonic tool
    • tool.md: Tools overview page
    • assets/: Static assets for the web tools.
      • css/: CSS files, including tool.css and enhanced-features.css.
      • js/: JavaScript files for both tools
    • pkg/: Contains the compiled WebAssembly module (zzson_bg.wasm, zzson.js, zzson.d.ts).

Development Environment Setup

To set up your development environment, you’ll need:

  1. Rust and Cargo: Follow the official Rust installation guide.
  2. wasm-pack: Install with cargo install wasm-pack.
  3. Node.js and npm: For managing JavaScript dependencies and running Jekyll.
  4. Ruby and Bundler: For Jekyll. Follow the Jekyll installation guide.

Build Process

  1. Build All Crates: Navigate to the project root and run: 
    ./build.sh

    This script handles formatting, linting, building, and testing all workspace crates.

  2. Build WebAssembly: For WASM specifically: 
    cd crates/wasm
wasm-pack build --target web --out-dir ../../docs/pkg
  3. Build Jekyll Site: Navigate to the docs/ directory and run: 
    bundle install # First time setup
bundle exec jekyll build

    Or to serve locally for development:

    bundle exec jekyll serve

    The web tool will be accessible at http://localhost:4000/tool.html (or similar, depending on your Jekyll configuration).

Key Development Areas

Rust WebAssembly Bindings (src/wasm.rs)

This file exposes Rust functions to JavaScript using #[wasm_bindgen]. When adding new functionality from the Rust core to the web tool, you’ll modify this file.

  • #[wasm_bindgen]: This macro handles the FFI (Foreign Function Interface) between Rust and JavaScript.
  • Error Handling: Rust Result types are automatically converted to JavaScript exceptions. Ensure your Rust code handles errors gracefully.
  • Data Conversion: wasm_bindgen handles conversion of basic types (strings, numbers, booleans, arrays, objects) between Rust and JavaScript. For complex types, you might need custom serialization/deserialization logic (e.g., using serde with wasm-bindgen-serde).

JavaScript Logic (docs/assets/js/tool.js)

This is the main JavaScript file for the web tool. It handles UI interactions, calls the WASM functions, and updates the display.

  • WASM Module Import: The pkg/zzson.js module (generated by wasm-pack) is imported here.
  • Asynchronous Operations: WASM module loading and initialization are asynchronous. Ensure you await the init() function.
  • UI Updates: Use standard DOM manipulation to update the input/output areas, error messages, and other UI elements.
  • Event Listeners: Attach event listeners to buttons, toggles, and text areas to respond to user actions.

Examples (docs/assets/js/examples.js)

This file contains the data for the pre-loaded examples. To add new examples:

  1. Define a new object in the EXAMPLES array with category, name, input, and options (if custom parser options are needed).
  2. Ensure the category is consistent with existing categories or add a new one if appropriate.

Styling (docs/assets/css/tool.css, enhanced-features.css)

These CSS files define the visual appearance of the web tool. tool.css contains core styles, while enhanced-features.css handles specific styling for features like error highlighting.

Jekyll Integration

The web tool is part of a Jekyll static site. Key considerations:

  • Front Matter: Each Markdown or HTML page uses YAML front matter to define layout, title, and navigation order.
  • Includes: Jekyll allows reusing content snippets via _includes/.
  • Static Files: Ensure all assets (JS, CSS, WASM files) are correctly placed and referenced so Jekyll copies them to the _site directory.

Testing

After making changes, always:

  1. Rebuild WASM: Run ./build-wasm.sh.
  2. Rebuild/Serve Jekyll: Run bundle exec jekyll build or bundle exec jekyll serve.
  3. Test in Browser: Open the tool.html page in your browser and thoroughly test all functionalities, especially those you’ve modified.

Contributing

We welcome contributions! Please refer to the main Contributing Guide for general contribution guidelines, including how to submit pull requests and code style conventions.