axon-ui

axon-ui

Immediate-mode GUI framework for Axon.

axon-ui is a declarative, immediate-mode GUI framework written in pure Axon. It provides OS window creation, GPU-accelerated rendering, a flexbox layout engine, input handling, and a standard widget library — all targeting the M11/M12/M19 milestones.

Status

Phase	Status	Notes
Scaffolding (M11.0)	✅ This PR	Directory structure, module stubs, docs
UI Framework (M11)	📋 Planned	Window, GPU backend, flexbox, input
Widgets (M12)	📋 Planned	Button, Label, TextInput, containers
Theming	🚧 WIP	Python reference impl in axon_ui/theme.py
WASM (M19)	📋 Planned	Browser deployment

Directory Structure

axon-ui/
├── src/                         # Axon source files (the framework itself)
│   ├── context.axs              # UI state management (M11)
│   ├── layout.axs               # Flexbox layout engine (M11)
│   ├── input.axs                # Event handling & hit-testing (M11)
│   └── widgets.axs              # Standard widget library (M12)
│
├── tests/                       # Tests
│   ├── test_layout.axs          # Layout engine tests (Axon)
│   ├── test_input.axs           # Event handling tests (Axon)
│   ├── test_golden_runner.py    # Golden file test harness (Python)
│   ├── test_theme.py            # Theme API tests (Python reference)
│   ├── test_theme_api.py        # Theme inheritance tests
│   ├── test_theme_properties.py # Property-based theme tests
│   ├── test_widgets.py          # Widget tests (Python reference)
│   ├── test_widget_contracts.py # Widget contract tests
│   ├── test_widgets_properties.py # Property-based widget tests
│   ├── test_layout_properties.py  # Property-based layout tests
│   ├── test_metrics.py          # Metrics collection tests
│   ├── golden/                  # Golden files for snapshot tests
│   └── conftest.py              # Pytest fixtures
│
├── axon_ui/                     # Python reference implementation
│   ├── __init__.py
│   ├── theme.py                 # Theme + ThemeResolver (M12 theming)
│   └── widgets.py               # Widget base + standard widgets
│
├── docs/
│   ├── architecture.md          # Framework architecture overview
│   ├── theming.md               # Theme API reference
│   ├── widgets.md               # Widget reference
│   ├── api/                     # Planned API docs (Axon formatter strips comments)
│   │   ├── README.md
│   │   ├── context.md
│   │   ├── layout.md
│   │   ├── input.md
│   │   └── widgets.md
│   ├── TESTING.md               # Test workflow
│   ├── CONTRIBUTING.md          # Contributor guide
│   ├── ci-pipeline.md           # CI pipeline reference
│   └── metrics.md               # Metrics collection
│
├── metrics/                     # Collected metrics output
├── tools/                       # Build/CI helper scripts
├── requirements-dev.txt         # Python dev dependencies
├── .gitlab-ci.yml               # CI configuration
└── README.md                    # This file

Module Overview

src/context.axs — UI State Management (M11)

Application-level state management: stores, signals, and reactive updates.

Planned API:

• (store initial-state) — create a new state store
• (get store) — read current state
• (set store value) — replace state
• (update store fn) — transform state via fn
• (signal initial-value) — create a reactive signal
• (bind signal view-fn) — bind a view to a signal

src/layout.axs — Flexbox Layout Engine (M11)

CSS flexbox subset for laying out widget trees. Takes widgets with layout properties and produces absolute positions/sizes.

Planned API:

• (layout root-widget max-width max-height) — compute layout
• (flex-direction "row" | "column")
• (justify-content "start" | "center" | "end" | "space-between")
• (align-items "start" | "center" | "end" | "stretch")
• (gap px)

src/input.axs — Event Handling (M11)

Event dispatch for user input: mouse clicks, keyboard, focus, form submit. Events bubble up the widget tree with preventDefault/stopPropagation.

Planned API:

• (event-loop) — start the event loop
• (dispatch event widget-tree) — dispatch a single event
• (on-click widget handler) — register click handler
• (on-change widget handler) — register change handler
• (on-submit widget handler) — register submit handler
• (on-key widget handler) — register key handler

Event types: click, dblclick, change, submit, keydown, keyup, focus, blur.

src/widgets.axs — Standard Widget Library (M12)

Standard UI widgets, all inheriting from a common base and supporting theming.

Planned widgets:

• (button "text" (on-click handler)) — clickable button
• (label "text") — static text display
• (text-input placeholder value handler) — single-line text field
• (checkbox checked handler) — boolean toggle
• (select options selected handler) — dropdown selector
• (vstack children) — vertical stack container
• (hstack children) — horizontal stack container
• (container child) — generic container with padding

Python Reference Implementation

The axon_ui/ directory contains a Python reference implementation of the theming and widget subsystems. This serves as:

1. A specification for the Axon implementation (what the API should look like)
2. A testable target — the Python tests verify the API contract
3. A fallback — apps that need UI now can use the Python version while the Axon version is under construction

The Python and Axon implementations should stay in sync API-wise.

Internationalization (axon_ui/i18n/)

A standards-based i18n/l10n layer — ICU MessageFormat catalogs, CLDR plural rules, locale-aware number/currency/percent formatting, RTL layout mirroring, and a reactive LocaleProvider for runtime locale switching. Pure-Python with zero required dependencies (optional Babel backend for full CLDR). See docs/i18n.md and the runnable Arabic/Hebrew demo examples/i18n_demo.py.

Animation engine (axon_ui/animation.py)

A declarative animation layer (Issue #24) — the full Robert-Penner easing set plus a CSS-style cubic_bezier solver, a shape-agnostic Tween (scalars, vectors/colours, dicts), damped-harmonic Spring physics with mid-flight interruption, Sequence/Parallel timelines, and a fixed-timestep Driver for reproducible sampling. Pure-Python, deterministic, no GPU/windowing dependency. GPU-accelerated compositing of the animated properties is a follow-up (needs the renderer backend #9). See docs/animation.md.

Drag-and-drop (axon_ui/drag_drop.py)

A semantic drag-and-drop model (Issue #16) — DragData payloads (text, files, text/uri-list, arbitrary MIME), DropTarget regions with half-open hit-testing and payload-type acceptance, and a DragDropManager that turns pointer motion into edge-triggered on_drag_enter/over/leave/on_drop callbacks with topmost-wins z-order and source↔target effect negotiation. Pure-Python, deterministic. The native OS drag FFI is a follow-up (needs the window/event loop #8); this ships the model + the DND_PLATFORM_MAP protocol spec the binding layer targets. See docs/drag-drop.md.

Native system dialogs (axon_ui/dialogs.py)

A semantic model for OS file/message dialogs (Issue #15) — FileDialog (open / open-files / save / pick-directory) with FileDialogFilter glob matching and save-mode extension enforcement, MessageDialog (info / warning / error / question) with stock DialogButton sets and default / cancel button routing, a DialogResponse carrying paths-or-button plus the accepted/cancelled/path conveniences, and a DialogManager that owns the in-flight dialog and validates native-layer responses before accepting. Pure-Python, deterministic, zero third-party deps. The native OS FFI (NSOpenPanel/NSSavePanel, IFileDialog, GtkFileChooserDialog / xdg-desktop-portal) is a follow-up (needs the window/event loop #8); this ships the model + the DIALOG_PLATFORM_MAP backend spec the binding layer targets. See docs/dialogs.md.

CI Infrastructure

Job	Template	Status	Purpose
pipeline:status	—	✅ Active	Verifies CI connectivity, counts .axs files
test:axon-e2e	axon-library.yml	✅ Active	Runs golden file tests on .axs files
test:axon-check	axon-library.yml	✅ Active	Axon type checking on .axs files
test:axon-format	axon-library.yml	✅ Active	Code formatting check on .axs files
test:python	—	✅ Active	Runs the Python test suite (theme, widgets, etc.)
metrics:library	metrics-collector.yml	✅ Active	Collects lines-of-code and module count metrics
performance:regression-check	perf-thresholds.yml	⚠️ allow_failure	Binary size and compile time gates

The test:axon-* jobs are now active because .axs source files exist (in stub form). They will run the golden file tests and type/format checks as the stubs grow into real implementations.

Milestone Roadmap

Milestone	Focus	Key Tickets
M11	UI Framework core	context/state, flexbox, input/hit-test, window, GPU backend
M12	Widgets & tooling	widget set, font/text, theming, bundler
M19	WASM canvas backend	WASM backend for browser deployment

See the GitLab issues for detailed acceptance criteria on each ticket.

Running Tests

# Python tests (theme, widgets, properties)
pip install -r requirements-dev.txt
python -m pytest tests/ -v

# Axon tests (when .axs files have real implementations)
# CI runs these automatically via test:axon-e2e, test:axon-check, test:axon-format

See docs/TESTING.md for the full test workflow.

Contributing

See docs/CONTRIBUTING.md for contributor onboarding, and docs/architecture.md for the planned architecture.

Part of the Axon Ecosystem

Package	Description	Status
axon-lang	Compiler & runtime	✅ Active
axon-std	Standard library	✅ Active
axon-pkg	Package manager	🚧 WIP
axon-ui	GUI framework	📋 Scaffolding
axon-web	HTTP framework (M14)	📋 Scaffolding

License

See project license file.