dioxus-theme-core 0.1.0-alpha.2

Serializable custom theme configuration for no-reload Dioxus theme switching.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94

# 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.

## Install

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

## 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.1", features = ["viewtx"] }
```

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

## 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>