Ursa.Avalonia

# Ursa.Avalonia

Ursa.Avalonia is an enterprise-level UI library for building cross-platform applications with Avalonia UI. This is a .NET 8.0 library that provides advanced UI controls and themes for Avalonia applications.

**Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.**

## Working Effectively

### Prerequisites and Setup
- Requires .NET 8.0 SDK (minimum 8.0.0). Check version with `dotnet --version`
- Install required workloads for full functionality:
  - `dotnet workload restore` -- installs wasi-experimental workload automatically
  - `dotnet workload install wasm-tools` -- required for browser demos. Takes 30-60 seconds.
  - Mobile workloads (Android/iOS) may not be available in all environments

### Building the Library
- Use the provided build scripts for core libraries:
  - Linux/macOS: `./build.sh` -- builds core Ursa libraries. NEVER CANCEL. Takes ~26 seconds. Set timeout to 120+ seconds.
  - Windows: `./build.ps1` -- builds core Ursa libraries
- Build specific projects:
  - Core library: `dotnet build src/Ursa/Ursa.csproj`
  - Themes: `dotnet build src/Ursa.Themes.Semi/Ursa.Themes.Semi.csproj`
  - Prism extension: `dotnet build src/Ursa.PrismExtension/Ursa.PrismExtension.csproj`
- Build entire solution (excluding mobile): `dotnet build` -- may fail on mobile projects without workloads

### Running Demo Applications
- Desktop demo: `dotnet run --project demo/Ursa.Demo.Desktop/Ursa.Demo.Desktop.csproj` -- NEVER CANCEL. Build takes ~22 seconds. Set timeout to 120+ seconds.
  - Cannot run in headless environments (will fail with XOpenDisplay error)
- Browser demo: 
  - Build: `dotnet build demo/Ursa.Demo.Browser/Ursa.Demo.Browser.csproj` -- NEVER CANCEL. Takes ~14 seconds. Set timeout to 120+ seconds.
  - Serve locally: `python3 -m http.server 8000 --directory demo/Ursa.Demo.Browser/bin/Debug/net8.0-browser/`
  - Access at: `http://127.0.0.1:8000`
- Sandbox project: `dotnet run --project demo/Sandbox/Sandbox.csproj` -- minimal test environment

### Testing
- Unit tests: `dotnet test tests/Test.Ursa` -- NEVER CANCEL. Takes ~13 seconds, runs 66 tests. Set timeout to 60+ seconds.
- Headless tests: `dotnet test tests/HeadlessTest.Ursa` -- NEVER CANCEL. Takes ~29 seconds, runs 584 tests. Set timeout to 120+ seconds.
- Both test suites should pass completely in a properly configured environment

### Validation Steps
- Always run these commands after making changes:
  - `./build.sh` to validate core library builds
  - `dotnet test tests/Test.Ursa && dotnet test tests/HeadlessTest.Ursa` to validate functionality
- Test browser demo functionality by building and serving locally
- Verify mobile demo builds work if mobile workloads are available

## Repository Structure

### Key Directories
- `/src/` -- Core library source code
  - `Ursa/` -- Main UI library (netstandard2.0 and net8.0)
  - `Ursa.Themes.Semi/` -- Semi Design theme package
  - `Ursa.PrismExtension/` -- Prism.Avalonia integration
  - `Ursa.ReactiveUIExtension/` -- ReactiveUI integration
- `/demo/` -- Example applications
  - `Ursa.Demo/` -- Shared demo code
  - `Ursa.Demo.Desktop/` -- Desktop application (Windows/Linux/macOS)
  - `Ursa.Demo.Browser/` -- WebAssembly browser application
  - `Ursa.Demo.Android/` -- Android application (requires workloads)
  - `Ursa.Demo.iOS/` -- iOS application (requires workloads)
  - `Sandbox/` -- Simple test application
- `/tests/` -- Test projects
  - `Test.Ursa/` -- Unit tests (66 tests)
  - `HeadlessTest.Ursa/` -- Headless UI tests (584 tests)

### Important Files
- `global.json` -- Specifies .NET 8.0.0 SDK requirement
- `Ursa.sln` -- Main solution file with all projects
- `src/Package.props` -- Shared package properties (Avalonia 11.1.1)
- `demo/Directory.Build.props` -- Demo-specific properties (Avalonia 11.2.5)
- `build.sh`/`build.ps1` -- Core library build scripts

## Common Development Tasks

### Making Changes to Controls
- Ursa controls are located in `src/Ursa/Controls/`
- Themes and styles are in `src/Ursa.Themes.Semi/`
- Always test changes with both unit tests and headless tests
- Verify demo applications still function correctly

### Adding New Features
- Follow existing patterns in `src/Ursa/Controls/`
- Add corresponding tests in `tests/HeadlessTest.Ursa/Controls/`
- Update demo applications to showcase new functionality
- Ensure compatibility with both netstandard2.0 and net8.0 targets

### Working with Themes
- Semi theme implementation is in `src/Ursa.Themes.Semi/`
- Reference theme in applications: `xmlns:semi="https://irihi.tech/semi"`
- Theme must be included after Semi base theme in App.axaml

### CI/CD Integration
- GitHub Actions are configured in `.github/workflows/`
- `test.yml` runs on both Windows and Ubuntu
- Tests include code coverage reporting
- Mobile builds may be excluded from CI in environments without workloads

## Known Issues and Workarounds

### Build Warnings
- Nullable reference type warnings are common and generally non-blocking
- Async method warnings in demo code are cosmetic

### Platform Limitations
- Desktop applications require display server (fail in headless environments)
- Mobile applications require specific workloads that may not be available
- Browser applications require WASM workloads

### Environment Dependencies
- .NET 8.0 SDK is required (specified in global.json)
- Avalonia versions differ between library (11.1.1) and demos (11.2.5)
- Some workloads may have long installation times

## Troubleshooting

### Build Failures
- Ensure correct .NET SDK version: `dotnet --version` should show 8.0.x
- Install missing workloads: `dotnet workload restore`
- Clean build artifacts: `dotnet clean` then rebuild

### Test Failures
- Verify all dependencies are installed
- Check that Avalonia themes are properly configured
- Ensure headless environment is properly set up for UI tests

### Demo Issues
- Desktop demos require display server
- Browser demos need proper WASM workload installation
- Mobile demos need platform-specific workloads

Always validate that your changes work by running the full test suite and building all target projects before committing changes.

More agent context in irihitech/Ursa.Avalonia

One other file this repository gives its agents.