Skip to content

Commit 217ccb6

Browse files
StevenTCramerStevenTCramer
authored
Merge pull request #514 from TimeWarpEngineering/Cramer/2024-12-05/Samples
Release docs and migration notes
2 parents ce4cc63 + 6f7da56 commit 217ccb6

File tree

10 files changed

+608
-28
lines changed

10 files changed

+608
-28
lines changed

‎Documentation/Migrations/Migration10-11.md

+154-4
Original file line numberDiff line numberDiff line change
@@ -3,10 +3,160 @@ uid: BlazorState:Migration10-11.md
33
title: Migrate From 10.X to 11.X
44
---
55

6-
# Migration
6+
# Migration From 10.x to 11.x
77

8-
## From 10.x to 11.x
8+
This guide will help you migrate your application from Blazor-State 10.x to TimeWarp.State 11.x.
99

10-
Update your project to use .NET 8.0 or later.
10+
## Required Changes
1111

12-
Change AddBlazorState to AddTimeWarpState<YourState>.
12+
### 1. Update .NET Version
13+
- Update your project to use .NET 8.0 or later
14+
- Update your project file's `TargetFramework` to `net8.0`
15+
16+
### 2. Package References
17+
- Remove the `Blazor-State` NuGet package
18+
- Add the `TimeWarp.State` NuGet package
19+
- Optionally add new packages based on your needs:
20+
- `TimeWarp.State.Plus` for additional features
21+
- `TimeWarp.State.Policies` for architecture enforcement
22+
23+
### 3. Namespace Updates
24+
Replace all occurrences of `BlazorState` with `TimeWarp.State`:
25+
- Update using statements
26+
- Update base class references
27+
- Update interface implementations
28+
29+
Common replacements:
30+
```csharp
31+
// Old
32+
using BlazorState;
33+
using static BlazorState.Features.Routing.RouteState;
34+
class MyComponent : BlazorStateComponent
35+
36+
// New
37+
using TimeWarp.State;
38+
using static TimeWarp.State.Features.Routing.RouteState;
39+
class MyComponent : TimeWarpStateComponent
40+
```
41+
42+
### 4. Component Changes
43+
- Replace `BlazorStateComponent` with `TimeWarpStateComponent`
44+
- Replace `BlazorStateDevToolsComponent` with `TimeWarpStateDevComponent`
45+
- Replace `BlazorStateInputComponent` with `TimeWarpStateInputComponent`
46+
47+
### 5. Configuration Updates
48+
In your `Program.cs`:
49+
```csharp
50+
// Old
51+
services.AddBlazorState();
52+
53+
// New
54+
services.AddTimeWarpState();
55+
```
56+
57+
### 6. Redux DevTools Configuration
58+
If you're using Redux DevTools:
59+
```csharp
60+
// Old
61+
services.AddBlazorState(options =>
62+
options.UseReduxDevTools()
63+
);
64+
65+
// New
66+
services.AddTimeWarpState(options =>
67+
options.UseReduxDevTools()
68+
);
69+
```
70+
71+
## Breaking Changes
72+
73+
### State Implementation
74+
- All state classes must now properly implement the State pattern
75+
- Public properties in state classes must be read-only
76+
- Actions must be properly nested within their state classes
77+
78+
### Component Lifecycle
79+
- Changes to render subscription management with new `RenderSubscriptionContext`
80+
- Updated component lifecycle hooks in `TimeWarpStateComponent`
81+
82+
### Time Travel Debugging
83+
- Time travel debugging feature has been removed
84+
- Use Redux DevTools for debugging state changes
85+
86+
## Optional Feature Migrations
87+
88+
### 1. Action Tracking
89+
If you want to track action processing:
90+
```csharp
91+
services.AddTimeWarpState(options =>
92+
options.UseActionTracking()
93+
);
94+
```
95+
96+
### 2. Persistent State
97+
To use the new persistent state feature:
98+
```csharp
99+
[PersistentState]
100+
public class MyState : State<MyState>
101+
{
102+
// Your state properties
103+
}
104+
```
105+
106+
### 3. Enhanced Routing
107+
To use the new routing components:
108+
```razor
109+
<TwBreadcrumb />
110+
<TwPageTitle />
111+
```
112+
113+
### 4. Timer System
114+
To use the new timer system from TimeWarp.State.Plus:
115+
```csharp
116+
services.AddTimeWarpState(options =>
117+
options.UseTimers(timerOptions => {
118+
timerOptions.AddTimer("MyTimer", TimeSpan.FromMinutes(5));
119+
})
120+
);
121+
```
122+
123+
### 5. Feature Flags
124+
To use the new feature flag system:
125+
```csharp
126+
services.AddTimeWarpState(options =>
127+
options.UseFeatureFlags()
128+
);
129+
```
130+
131+
## Architecture Enforcement
132+
133+
Consider adding the TimeWarp.State.Policies package to enforce architectural rules:
134+
```xml
135+
<PackageReference Include="TimeWarp.State.Policies" Version="11.0.0" />
136+
```
137+
138+
This will help ensure:
139+
- Proper state implementation
140+
- Correct action nesting
141+
- Appropriate constructor injection
142+
- JSON serialization support
143+
144+
## Analyzer Updates
145+
146+
The TimeWarp.State.Analyzer has been enhanced with new rules. Address any analyzer warnings to ensure your code follows best practices:
147+
- State implementation rules
148+
- Action nesting rules
149+
- Property accessibility rules
150+
151+
## Testing Updates
152+
153+
If you're using the testing infrastructure:
154+
- Update test base classes to use new TimeWarp.State namespaces
155+
- Consider adding Playwright end-to-end tests using the new testing infrastructure
156+
- Use the new architecture testing capabilities from TimeWarp.State.Policies
157+
158+
## Additional Resources
159+
160+
- Review the [Release Notes](xref:TimeWarpState:Release.11.0.0.md) for a complete list of changes
161+
- Check out the new samples in the repository for implementation examples
162+
- Consult the updated documentation for detailed feature guides

‎Documentation/ReleaseNotes/Release11.0.0.md

+48-24
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,3 @@
1-
---
21
uid: TimeWarpState:Release.11.0.0.md
32
title: Release 11.0.0
43
---
@@ -23,41 +22,66 @@ See [Migrations](xref:BlazorState:Migration10-11.md) for instructions on how to
2322
### New Features
2423

2524
- Enabled chained inherits from State<> - so users can make/use their own BaseState<>
26-
- Introduced `TimeWarp.State.Plus` NuGet package with additional features.
27-
- Added `TimeWarp.State.Policies` NuGet package for architecture policies.
28-
- Implemented ActionSet source generator for simplified action creation.
29-
- Added support for persistent state with `[PersistentState]` attribute.
30-
- Introduced `RenderSubscriptionContext` for improved render subscription management.
31-
- Added `ActionTrackingState` for better action tracking capabilities.
25+
- Introduced `TimeWarp.State.Plus` NuGet package with additional features:
26+
- New Timer system with MultiTimer support and activity-based reset capabilities
27+
- Feature Flag system for managing feature toggles
28+
- Enhanced routing with TwBreadcrumb and TwPageTitle components
29+
- Improved caching with TimeWarpCacheableState
30+
- Added `TimeWarp.State.Policies` NuGet package for architecture policies:
31+
- BeNestedInStateCustomRule for enforcing proper nesting
32+
- HaveInjectableConstructor rule
33+
- HaveJsonConstructor rule
34+
- Action, ActionHandler, ActionSet, and State policies
35+
- Implemented ActionSet source generator for simplified action creation
36+
- Added support for persistent state with `[PersistentState]` attribute
37+
- Introduced `RenderSubscriptionContext` for improved render subscription management
38+
- Added `ActionTrackingState` for better action tracking capabilities
39+
- Enhanced component rendering with new RenderMode and RenderReasons tracking
3240

3341
### Improvements
3442

35-
- Optimized CI/CD pipelines for better performance and reliability.
36-
- Enhanced caching mechanisms for NuGet packages in GitHub Actions.
37-
- Improved logging capabilities with new Logger implementation.
38-
- Updated to use the latest MediatR version.
39-
- Refactored and improved the test suite, including new E2E tests.
43+
- Optimized CI/CD pipelines for better performance and reliability
44+
- Enhanced caching mechanisms for NuGet packages in GitHub Actions
45+
- Improved logging capabilities with new Logger implementation
46+
- Updated to use the latest MediatR version
47+
- Refactored and improved the test suite:
48+
- Added comprehensive Playwright end-to-end tests
49+
- New architecture tests for enforcing conventions
50+
- Enhanced integration tests
51+
- Optimized TwPageTitle component with improved rendering performance
52+
- Added state initialization pre-processor
53+
- Enhanced JavaScript interop capabilities
4054

4155
### Documentation
4256

43-
- Completely revamped documentation structure and content.
44-
- Added new tutorials and updated existing ones for TimeWarp.State.
45-
- Implemented automated documentation publishing workflow.
57+
- Completely revamped documentation structure and content
58+
- Added new tutorials and updated existing ones for TimeWarp.State
59+
- Implemented automated documentation publishing workflow
60+
- Added comprehensive samples demonstrating various features:
61+
- Sample 00: Basic State and Action Handler usage
62+
- Sample 01: Redux DevTools integration
63+
- Sample 02: Action Tracking capabilities
64+
- Sample 03: Advanced routing features
4665

4766
### Developer Experience
4867

49-
- Added support for central package management.
50-
- Improved developer tooling, including updated EditorConfig and coding standards.
51-
- Enhanced source generators for better development productivity.
52-
- Added TimeWarp.State.Analyzer for code analysis.
53-
- ActionAnalyzer.
68+
- Added support for central package management
69+
- Improved developer tooling, including updated EditorConfig and coding standards
70+
- Enhanced source generators for better development productivity
71+
- Added TimeWarp.State.Analyzer for code analysis:
72+
- ActionAnalyzer
73+
- StateImplementationAnalyzer
74+
- StateInheritanceAnalyzer
75+
- StateReadOnlyPublicPropertiesAnalyzer
5476

5577
### Other Changes
5678

57-
- Removed time travel debugging feature to optimize performance and reduce complexity.
58-
- Updated all dependencies to their latest stable versions.
59-
- Improved error handling and exception reporting throughout the library.
60-
- Added .ai folder to the repository for prompting AI-generated content.
79+
- Removed time travel debugging feature to optimize performance and reduce complexity
80+
- Updated all dependencies to their latest stable versions
81+
- Improved error handling and exception reporting throughout the library
82+
- Added .ai folder to the repository for prompting AI-generated content
83+
- Reorganized project structure for better maintainability
84+
- Enhanced build and test scripts
6185

6286
### Migration Guide
6387

‎Kanban/ToDo/016-Create-Sample03Wasm-Tutorial.md

+74
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# Task 016: Create Sample03Wasm Tutorial
2+
3+
## Description
4+
5+
Create a comprehensive tutorial that guides users through building Sample03Wasm, demonstrating TimeWarp.State.Plus's routing capabilities. The tutorial will build upon the ReduxDevTools sample, showing how to implement stack-based navigation management with features like breadcrumb navigation, direct route changes, and back navigation.
6+
7+
## Requirements
8+
9+
- Tutorial must follow the progression from ReduxDevTools sample to routing implementation
10+
- Cover all key routing features:
11+
* Stack-based navigation
12+
* Breadcrumb navigation
13+
* Direct route changes
14+
* Back navigation
15+
* Thread-safe route updates
16+
* Page title synchronization
17+
- Include implementation of core routing actions:
18+
* ChangeRoute
19+
* GoBack
20+
* PushRouteInfo
21+
- Demonstrate integration with:
22+
* Blazor's NavigationManager
23+
* ReduxDevTools for route debugging
24+
* Built-in logging support
25+
26+
## Checklist
27+
28+
### Design
29+
- [ ] Review Sample01Wasm (ReduxDevTools) implementation
30+
- [ ] Review Sample03Wasm routing implementation
31+
- [ ] Map progression path from ReduxDevTools to routing features
32+
- [ ] Identify key learning points and concepts
33+
34+
### Implementation
35+
- [ ] Create step-by-step tutorial structure
36+
- [ ] Document initial setup from ReduxDevTools base
37+
- [ ] Detail routing feature implementation steps
38+
- [ ] Include code samples for each routing action
39+
- [ ] Add configuration and integration steps
40+
- [ ] Include thread safety implementation details
41+
- [ ] Document ReduxDevTools integration for route debugging
42+
43+
### Documentation
44+
- [ ] Add tutorial to Documentation/Tutorial folder
45+
- [ ] Include screenshots of:
46+
* Route state in ReduxDevTools
47+
* Breadcrumb navigation
48+
* Navigation stack visualization
49+
- [ ] Add diagrams explaining:
50+
* Stack-based navigation flow
51+
* Route state management
52+
- [ ] Include troubleshooting section
53+
- [ ] Add best practices section
54+
- [ ] Cross-reference with existing tutorials
55+
56+
### Review
57+
- [ ] Verify tutorial progression logic
58+
- [ ] Test all code samples
59+
- [ ] Validate ReduxDevTools integration steps
60+
- [ ] Review thread safety explanations
61+
- [ ] Check clarity of routing concepts
62+
- [ ] Ensure consistency with existing documentation
63+
64+
## Notes
65+
66+
- Base tutorial structure on existing Sample01Wasm (ReduxDevTools) tutorial format
67+
- Focus on explaining the transition from basic state management to advanced routing features
68+
- Include practical examples demonstrating real-world routing scenarios
69+
- Emphasize debugging capabilities through ReduxDevTools integration
70+
- Include examples of common routing patterns and their implementation
71+
72+
## Implementation Notes
73+
74+
- To be added during implementation

‎Samples/00-StateActionHandler/Auto/Readme.md

+8
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,14 @@ description: Learn TimeWarp.State basics using Blazor with Interactive Auto rend
77

88
# TimeWarp.State Blazor Interactive Auto Tutorial
99

10+
> [!TIP]
11+
> View the complete reference implementation for this tutorial:
12+
> - [Sample00Auto Project](./Sample00Auto/)
13+
> - [Client Project with TimeWarp.State](./Sample00Auto/Sample00Auto.Client/)
14+
> - [CounterState Implementation](./Sample00Auto/Sample00Auto.Client/Features/Counter/CounterState.cs)
15+
> - [Counter Page Component](./Sample00Auto/Sample00Auto.Client/Pages/Counter.razor)
16+
> - [Program.cs with Service Configuration](./Sample00Auto/Sample00Auto/Program.cs)
17+
1018
## State, Actions, and Handlers
1119

1220
This tutorial will walk you through the steps to create a Blazor application with TimeWarp.State using Interactive Auto render mode.

‎Samples/00-StateActionHandler/Server/README.md

+7
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,13 @@ description: Learn TimeWarp.State basics using Blazor with Interactive Server re
77

88
# TimeWarp.State Blazor Interactive Server Tutorial
99

10+
> [!TIP]
11+
> View the complete reference implementation for this tutorial:
12+
> - [Sample00Server Project](./Sample00Server/)
13+
> - [CounterState Implementation](./Sample00Server/Features/Counter/CounterState.cs)
14+
> - [Counter Page Component](./Sample00Server/Components/Pages/Counter.razor)
15+
> - [Program.cs with Service Configuration](./Sample00Server/Program.cs)
16+
1017
## State, Actions, and Handlers
1118

1219
This tutorial will walk you through the steps to create a Blazor application with TimeWarp.State using Interactive Server render mode.

‎Samples/00-StateActionHandler/Wasm/README.md

+6
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,12 @@ description: Learn TimeWarp.State basics using Blazor WebAssembly
77

88
# TimeWarp.State Blazor WebAssembly Tutorial
99

10+
> [!TIP]
11+
> View the complete reference implementation for this tutorial:
12+
> - [Sample00Wasm Project](./Sample00Wasm/)
13+
> - [CounterState Implementation](./Sample00Wasm/Features/Counter/CounterState.cs)
14+
> - [Counter Page Component](./Sample00Wasm/Pages/Counter.razor)
15+
1016
## State, Actions, and Handlers
1117

1218
This tutorial will walk you through the steps to create a Blazor WebAssembly application with TimeWarp.State.

‎Samples/01-ReduxDevTools/Wasm/Readme.md

+6
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,12 @@ description: Learn how to integrate Redux DevTools with TimeWarp.State for enhan
77

88
# Adding Redux DevTools to TimeWarp.State
99

10+
> [!TIP]
11+
> View the complete reference implementation for this tutorial:
12+
> - [Sample01Wasm Project](./Sample01Wasm/)
13+
> - [Program.cs with Redux Configuration](./Sample01Wasm/Program.cs)
14+
> - [App.razor with Redux Components](./Sample01Wasm/App.razor)
15+
1016
This tutorial demonstrates how to add Redux DevTools support to your TimeWarp.State Blazor WebAssembly application. Redux DevTools provides powerful debugging capabilities, allowing you to monitor state changes, inspect actions, and understand your application's behavior.
1117

1218
## Prerequisites

0 commit comments

Comments
 (0)