chakra-ui@zag-js/core
This package contains a minimal implementation of XState FSM for finite state machines with addition of extra features we need for our components.
Features
- Finite states (non-nested)
- Initial state
- Transitions (object or strings)
- Context
- Entry actions
- Exit actions
- Delayed timeout actions (basically
setTimeout) - Delayed interval actions (basically
setInterval) - Transition actions
- Boolean guard helpers (
and,or,not) - Basic spawn helpers
- Activities (for state nodes)
To better understand the state machines, we strongly recommend going though the xstate docs and videos. It'll give you the foundations you need.
Quick start
Installation
npm i @zag-js/core
# or
yarn add @zag-js/coreUsage (machine):
import { createMachine } from "@zag-js/core"
const toggleMachine = createMachine({
id: "toggle",
initialState() {
return "inactive"
},
states: {
inactive: { on: { TOGGLE: "active" } },
active: { on: { TOGGLE: "inactive" } },
},
})
toggleMachine.start()
console.log(toggleMachine.state.value) // => "inactive"
toggleMachine.send("TOGGLE")
console.log(toggleMachine.state.value) // => "active"
toggleMachine.send("TOGGLE")
console.log(toggleMachine.state.value) // => "inactive"Usage (service):
import { createMachine } from "@zag-js/core"
const toggleMachine = createMachine({...})
toggleMachine.start()
toggleService.subscribe((state) => {
console.log(state.value)
})
toggleService.send("TOGGLE")
toggleService.send("TOGGLE")
toggleService.stop()API
createMachine(config, options)
Creates a new finite state machine from the config.
| Argument | Type | Description |
|---|---|---|
config |
object (see below) | The config object for creating the machine. |
options |
object (see below) | The optional options object. |
Returns:
A Machine, which provides:
machine.initialState: the machine's resolved initial statemachine.start(): the function to start the machine in the specified initial state.machine.stop(): the function to stop the machine completely. It also cleans up all scheduled actions and timeouts.machine.transition(state, event): a transition function that returns the next state given the currentstateandevent. It also performs any delayed, entry or exit side-effects.machine.send(event): a transition function instructs the machine to execute a transition based on the event.machine.onTransition(fn): a function that gets called when the machine transition function instructs the machine to execute a transition based on the event.machine.onChange(fn): a function that gets called when the machine's context value changes.machine.state: the state object that describes the machine at a specific point in time. It contains the following properties:value: the current state valuepreviousValue: the previous state valueevent: the event that triggered the transition to the current statenextEvents: the list of events the machine can respond to at its current statetags: the tags associated with this statedone: whether the machine that reached its final statecontext: the current context valuematches(...): a function used to test whether the current state matches one or more state values
The machine config has this schema:
Machine config
id(string) - an identifier for the type of machine this is. Useful for debugging.context(object) - the extended state data that represents quantitative data (string, number, objects, etc) that can be modified in the machine.initial(string) - the key of the initial state.states(object) - an object mapping state names (keys) to stateson(object) - an global mapping of event types to transitions. If specified, this event will called if the state node doesn't handle the emitted event.
State config
on(object) - an object mapping event types (keys) to transitions
Transition config
String syntax:
- (string) - the state name to transition to.
- Same as
{ target: stateName }
- Same as
Object syntax:
target(string) - the state name to transition to.actions(Action | Action[]) - the action(s) to execute when this transition is taken.guard(Guard) - the condition (predicate function) to test. If it returnstrue, the transition will be taken.
Machine options
actions?(object) - a lookup object for your string actions.guards?(object) - a lookup object for your string guards specified asguardin the machine.activities?(object) - a lookup object for your string activities.delays?(object) - a lookup object for your string delays used inafterandeveryconfig.
Action config
The action function to execute while transitioning from one state to another. It takes the following arguments:
context(any) - the machine's currentcontext.event(object) - the event that caused the action to be executed.