API
Props
<Kotick /> from kotick takes these props. All props are optional.
| Prop | Type | Default | Details |
|---|---|---|---|
position | Position | 'bottom-right' | |
| |||
defaultOpen | boolean | false | |
| |||
shortcut | string | false | 'alt+s' | |
fixtures | FixturesInput | None | |
portalTarget | Element | ShadowRoot | document.body | |
| |||
The panel keeps its open state, its corner and the machine whose page it shows in localStorage, so position and defaultOpen apply only until the user changes them. The user changes the corner in Settings. After a reload, the panel shows the page of the same machine when that machine registers.
The overlay renders in a shadow root, so the styles of the page do not change it, and its styles do not change the page. It is dark on every page.
In production builds, <Kotick /> renders nothing and does not call the fixtures loader.
Shortcut
Write the parts of a shortcut with + between them, for example ctrl+shift+d. The last part is the key, and the other parts are modifiers. Uppercase letters and spaces have no effect.
| Modifier | Other names |
|---|---|
alt | option, opt |
ctrl | control |
shift | |
meta | cmd, command |
mod | ⌘ on macOS, Ctrl on other systems |
The key is a value of KeyboardEvent.key, for example s, f2 or escape. These names are also accepted: esc, space, up, down, left, right, return, del, and plus for the + key.
- The modifiers must agree exactly.
alt+sdoes not open the panel when the user also holds Shift. - For letters and digits, the physical key also agrees. Thus,
alt+sworks on macOS, where Alt+S typesß, and on keyboard layouts that move the letters. - The shortcut does nothing while the focus is in a text field.
- kotick ignores a shortcut that it cannot read, and logs a warning:
[kotick] Ignoring the shortcut "…": expected something like "alt+s".
Reducer exports
kotick/reducer has these exports:
| Export | What it is |
|---|---|
defineReducerMachine<State, Event, Input>()(definition) | Declares a machine over your union of states and your union of events. Returns the machine. |
useMachineReducer(machine, initial, options?) | Runs a machine in a component. Returns [state, dispatch], as useReducer does. |
defineFixtures(machine, fixtures) | Makes a fixture set for <Kotick fixtures>. Each fixture is a state object of the state of its key. Refer to Fixtures. |
Refer to Define a machine for the rules of a machine, and to useReducer for a guide.
defineReducerMachine()
The first call takes three type arguments: the union of states, the union of events, and the type of the input that the effects read, if they read one. The second call takes the definition, and TypeScript infers the discriminant from it. TypeScript cannot take some type arguments of one call from you and infer the others, so there are two calls.
| Prop | Type | Default | Details |
|---|---|---|---|
id | string | None | |
| |||
discriminant | keyof State | None | |
| |||
states | object | None | |
| |||
The machine is the definition, frozen, with one more property: reducer(state, event), the transitions as a plain reducer. It returns the same object for an event that the state ignores.
useMachineReducer()
initial is the state at mount, or a function that returns it, as for useReducer. dispatch is the same function for the life of the component, as the dispatch of useReducer is. During a preview, it logs each event in the panel, and the event does not get to the machine. Call the hook only in client components.
The third argument takes these options:
| Prop | Type | Default | Details |
|---|---|---|---|
input | Input | None | |
| |||
debug | object | None | |
| |||
XState exports
kotick/xstate has these exports:
| Export | What it is |
|---|---|
useMachine(machine, options?) | Same as @xstate/react. Returns [snapshot, send, actorRef]. |
useActor(logic, options?) | Same as @xstate/react. Returns [snapshot, send, actorRef]. |
useActorRef(logic, options?, observer?) | Same as @xstate/react. Returns the actor. |
createActorContext(logic, options?) | Same as @xstate/react. Its Provider creates the actor. |
useSelector(actor, selector, compare?) | Same as @xstate/react. It works with each actor from this package. |
shallowEqual | A re-export of @xstate/react. |
connect(actor, debug?) | Registers an actor that you created outside React. Returns the actor to use in the app. |
defineFixtures(machine, states) | Makes a fixture set for <Kotick fixtures>. |
The actors that the hooks return are proxies of the real actors. They have the same interface. actorRef.send() goes to the real actor when nothing is previewed. Refer to XState for a guide.
The debug option
The hooks and createActorContext accept one more option, debug. connect() takes the same object as its second argument.
In development, kotick removes debug before the options get to XState. In production builds, the hooks are the hooks of @xstate/react, so XState also gets debug. XState keeps it in actor.options and does nothing with it.
Give each machine an id. A machine without one has the XState default id (machine). kotick then makes an id from the states and context keys of the machine, and logs a warning once. That id changes when you add or remove states or context keys, so the previews and recordings of the machine do not carry over after such a change.
connect()
connect() registers the actor immediately, and unregisters it when the actor is done, fails or stops. Use the actor that connect() returns everywhere in the app. Refer to Actors outside React.
connect() returns the actor unchanged, and does not register it, when:
- The actor is not a machine actor, for example a promise actor.
- The actor is done, failed or stopped.
debug.disabledistrue.- The build is a production build.
An actor that kotick registered before does not register again. This includes an actor from connect(), an actor from a hook, and the real actor of either. connect() returns the proxy that the actor already has, with its first id and label. If the actor is from a hook and you give id or label, kotick logs a warning.
Types
kotick exports these types:
| Type | What it is |
|---|---|
KotickProps | The props of <Kotick />. |
Position | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' |
FixtureSet | The return value of defineFixtures(): { machineId: string; states: Record<string, { context: unknown }> }. |
FixturesResult | readonly FixtureSet[], or a module whose default export is readonly FixtureSet[], as import() gives it. |
FixturesInput | readonly FixtureSet[], or a function that returns a FixturesResult or a promise of one. |
kotick/reducer exports these types:
| Type | What it is |
|---|---|
ReducerMachine<State, Event, Key, Input> | The return value of defineReducerMachine(): id, discriminant, states and reducer. Input is undefined when the effects read no input. |
MachineEvent | { readonly type: string }. Each member of the event union extends it. |
MachineReducerOptions<Input> | The options of useMachineReducer(): { input?: Input; debug?: { label?: string; disabled?: boolean } }. |
ReducerFixtures<State, Key> | The second argument of defineFixtures(): an optional state object for each state name. Each one is a state of its own name. |
CompleteFixtures<Machine> | The ReducerFixtures of a machine, with a state object for every state. Check a set with satisfies CompleteFixtures<typeof machine>. |
kotick/xstate exports these types:
| Type | What it is |
|---|---|
DebugOptions | The debug option of the hooks and the second argument of connect(). |
FixtureStates<TMachine> | The second argument of defineFixtures(): an optional { context } for each leaf id. context has the context type of the machine. |
LeafIdFrom<TMachine> | The leaf ids of a machine as a union, for example 'cart' | 'payment.error'. It is string when TypeScript cannot know the states. |