dioxus-theme-core 0.1.0-alpha.4

# dioxus-theme-core

Serializable custom theme configuration for no-reload Dioxus theme switching.

This crate is part of the Dioxus SSR package workspace. The APIs are pre-1.0 and may change between releases while the package family stabilizes.

## Release Status

- Current crate version: `0.1.0-alpha.4`.
- Release wave: June 8, 2026 workspace integration update.
- Publish status: Prepared as a crates.io update for this package.
- Scope: Serializable custom theme configuration for no-reload Dioxus theme switching.
- The README install examples and local workspace dependency requirements are aligned with this publish wave.

## Install

```toml
[dependencies]
dioxus-theme-core = "0.1.0-alpha.4"
```

## What It Provides

- Theme registries with overrideable defaults.
- Serializable theme tokens for SSR and lazy runtimes.
- Animation, storage, target, and reduced-motion policy configuration.
- Built-in animation presets: `fade`, `cross-fade`, `slide`, `radial-wipe`, and `masked-wave`.
- Validation for route-safe selectors, storage keys, registered defaults, and CSS token values.
- Token-name constants such as `THEME_TOKEN_BG`, `THEME_TOKEN_FG`, and `THEME_TOKEN_ACCENT`.
- Visual-token manifest metadata for Shader, HoverFX, TextFX, and other packages listening to `dioxus-theme:change`.

## Example

```rust
use dioxus_theme_core::{
    ThemeAnimationPreset, ThemeConfig, ThemeDefinition, ThemeRegistry, THEME_TOKEN_ACCENT,
};

let brand = ThemeDefinition::new("brand", "Brand")
    .with_token(THEME_TOKEN_ACCENT, "#0f766e");

let config = ThemeConfig::default()
    .with_registry(ThemeRegistry::default().with_theme(brand))
    .with_default_theme("brand")
    .with_animation_preset(ThemeAnimationPreset::MaskedWave)
    .with_animation_speed(125)
    .with_animation_storage_key("app-theme-animation")
    .with_animation_speed_storage_key("app-theme-animation-speed");

let report = config.validate();
assert!(report.is_valid());
```

## Animation Timing

`ThemeAnimationMode` controls capability and fallback behavior:

- `ViewTransition`: use the View Transition API when available.
- `CssOnly`: use CSS variable transitions only.
- `None`: apply changes immediately.

`ThemeAnimationPreset` controls the visual preset independently, and `animation_speed` is a percentage from `25` to `300`. The default easing is `ease-in-out`; call `with_easing("linear")` or another easing string to override it.

Theme View Transitions isolate route-level `view-transition-name` elements by default so package theme switches animate the root snapshot without reordering named route content. Call `with_view_transition_name_isolation(false)` only when child named View Transition elements should participate in theme switches.

## Visual Tokens

Theme semantic tokens are also exported as a shared visual contract:

```rust
use dioxus_theme_core::{
    theme_visual_token_manifest, THEME_CHANGE_EVENT, THEME_TOKEN_ACCENT, THEME_TOKEN_SURFACE,
    THEME_TOKEN_TEXT,
};

let manifest = theme_visual_token_manifest();
assert_eq!(THEME_CHANGE_EVENT, "dioxus-theme:change");
assert!(manifest.tokens.iter().any(|token| token.css_var == THEME_TOKEN_ACCENT));
```

The runtime dispatches `dioxus-theme:change` with raw `tokens`, semantic `visualTokens`, `visualTokenCssVars`, and `visualTokenManifestVersion`. Shader palettes, HoverFX sand/texture effects, and TextFX gradients can update from `accent`, `muted`, `surface`, and `text` without reloading or re-reading broad DOM state.

## ViewTX Interop

Enable the optional `viewtx` feature to copy timing and reduced-motion policy from `dioxus-viewtx-core`:

```toml
dioxus-theme-core = { version = "0.1.0-alpha.4", features = ["viewtx"] }
```

```rust
let theme_config = ThemeConfig::default().with_viewtx_timing(&viewtx_config);
```

## Integration Recipes

Theme integrations can emit route metadata and reuse it for SSR, Strata,
asset-budget reports, WorkerTown offload planning, and optimizer caches:

```rust
use dioxus_theme_core::prelude::*;

let config = theme().with_default_theme("dark");
let policy = theme_route_policy()
    .route("/settings")
    .diagnostics(ThemeDiagnosticVerbosity::Summary)
    .fallback(ThemeFallbackStrategy::StoredOrSystem);

let manifest = theme_manifest_fragment(&config, &policy);
let batch = theme_serialize_batch([(&config, policy.clone())], ThemeBatchOptions::default())?;
let budget = theme_asset_budget_bridge(&config.output_report(&policy));
let migration = theme_strata_migration_plan(&config, &policy);

assert_eq!(manifest.package, "dioxus-theme");
assert!(batch.total_bytes > 0);
assert!(budget.categories.iter().any(|category| category.name == "style"));
assert!(migration.steps.iter().any(|step| step.contains("Strata")));
# Ok::<(), serde_json::Error>(())
```

`ThemeRuntimeIds::duplicate_ids` and `deduped` protect generated script/style
ids, `theme_precomputed_css_fragments` exposes reusable custom-property CSS,
and `theme_optimizer_artifacts` returns minifier/cache-friendly artifact hashes.

## License

Licensed under either of:

- MIT license ([LICENSE-MIT](https://github.com/Collin-Budrick/dioxus_template/blob/main/LICENSE-MIT))
- Apache License, Version 2.0 ([LICENSE-APACHE](https://github.com/Collin-Budrick/dioxus_template/blob/main/LICENSE-APACHE))

Repository: <https://github.com/Collin-Budrick/dioxus_template>