✨: add new hook: useStateMachine

[AKAAE86]

This commit introduces a new Composable hook, useStateMachine, for managing state machines.

Key features:

• Defines state transitions using either a traditional Map or a more readable DSL approach.
• Provides functions to:
  • Check if a transition is possible.
  • Execute a transition.
  • Reset to the initial state.
  • Go back to the previous state.
  • Get available events for the current state.
• Tracks state history with a configurable maximum size.

A new example, UseStateMachineExample, demonstrates the usage of this hook with a loading state machine, showcasing the DSL approach for defining transitions.

[AKAAE86]

Kindly request you to review with that.Thank you. @junerver

[junerver]

Thank you for your contribution again, the feature looks cool!

I have the following questions to confirm with you:

1. The time year in the file header in the commit is incorrect, you wrote Date: 2024/6/22-9:30

2. The type of currentState in StateMachineHolder should be State<S> instead of the value of the state, and the type of history should be State<PersistentList<S>>, be sure to use Defer Reads

3. stateGraphBuilder may be renamed to buildStateMachineGraph to be more in line with Kotlin's naming rules?

4. You defined the type alias of Transition in the file, but did not use it in useStateMachine

5. Should reset clear the history? Now the reset function is actually setState(initialState), but the state machine history does not have reset, which is inconsistent with the semantic expectations

6. Ideas: For recording operation history and rollback, maybe useUndo can be used instead of manual recording through useList?

7. DSL function scope is best named XxxScope, for example: Description => DescriptionScope, StateGraph => StateGraphScope

8. In Description, should the eventBlock parameter of the on function be a pure function? Can side effects be performed? If so, should it also be allowed to run and execute suspended functions?

9. If the Description scope is only used to build a mapping from Event to State, you may refer to the style of the infix function in /hooks/useredux/createStore.kt, for example: LoadingEvent.START transitionTo LoadingState.LOADING. This can reduce some misunderstandings and prevent users from writing business code in the Description scope.

[AKAAE86]

• Integrate useUndo for history management.
• Change DSL builder function name from stateGraphBuilder to buildStateMachineGraph.
• Change DSL scope class names from StateGraph to StateMachineGraphScope and Description to StateDescriptionScope.
• Adapt StateDescriptionScope to use infix function transitionTo for more natural syntax (e.g., Event.START transitionTo State.LOADING).
• Update StateMachineHolder properties:
  • currentState is now a State<S>.
  • history is now a State<PersistentList<S>>.
  • canGoBack is now a State<Boolean>.
• Update example to reflect DSL and API changes.
• Modify reset to also reset history.

[AKAAE86]

@junerver All issues were addressed.Please review it again when you have time ! Thank you!

[junerver]

COOL JOB !

[junerver]

Hi, I have an idea. Maybe we can refer to the xstate approach to refactor this hook. I have implemented a rough version and would like to discuss it with you. If you are interested, maybe we can try to improve it. I have created a new discussion board where we can discuss. This is the branch I implemented: useStateMachine