@koordinates/xstate-tree 2.0.5 → 2.0.7

package/README.md

@@ -1,13 +1,112 @@
 # xstate-tree
 
-xstate-tree is a React state management framework built using XState. It allows you to create a tree of XState machines and map them to a tree of React views representing them as a UI.
+xstate-tree was born as an answer to the question "What would a UI framework that uses [Actors](https://en.wikipedia.org/wiki/Actor_model) as the building block look like?". Inspired by Thomas Weber's [Master Thesis](https://links-lang.org/papers/mscs/Master_Thesis_Thomas_Weber_1450761.pdf) on the topic. [XState](https://xstate.js.org/) was chosen to power the actors with [React](https://reactjs.org) powering the UI derived from the actors.
+
+xstate-tree was designed to enable modeling large applications as a single tree of xstate machines, with each machine being responsible for smaller and smaller sub sections of the UI. This allows modeling the entire UI structure in state machines, but without having to worry about the complexity of managing the state of the entire application in a single large machine.
+
+Each machine has an associated, but loosely coupled, React view associated with it. The loose coupling allows the view to have no knowledge of the state machine for ease of testing and re-use in tools like [Storybook](https://storybook.js.org). Actors views are composed together via "slots", which can be rendered in the view to provide child actors a place to render their views in the parent's view.
+
+While xstate-tree manages your application state, it does not have a mechanism for providing global application state accessible by multiple actors, this must be provided with another library like [Redux](https://redux.js.org/) or [GraphQL](https://graphql.org/). It does provide a routing solution, outlined [here](https://github.com/koordinates/xstate-tree/blob/master/src/routing/README.md).
+
+At Koordinates we use xstate-tree for all new UI development. Our desktop application, built on top of [Kart](https://kartproject.org/) our Geospatial version control system, is built entirely with xstate-tree using GraphQL for global state.
+
+A minimal example of a single machine tree
+
+```tsx
+import React from "react";
+import { createRoot } from "react-dom/client";
+import { createMachine } from "xstate";
+import { assign } from "@xstate/immer";
+import { buildSelectors, buildActions, buildView, buildXstateTreeMachine, buildRootComponent } from "@koordinates/xstate-tree";
+
+type Events = { type: "SWITCH_CLICKED" } | { type: "INCREMENT", amount: number };
+type Context = { incremented: number };
+
+// If this tree had more than a single machine the slots to render child machines into would be defined here
+const slots = [];
+
+// A standard xstate machine, nothing extra is needed for xstate-tree
+const machine = createMachine<Context, Events>({
+  id: "root",
+  initial: "inactive",
+  context: {
+    incremented: 0,
+  },
+  states: {
+    inactive: {
+      on: {
+        SWITCH_CLICKED: "active",
+      },
+    },
+    active: {
+      on: {
+        SWITCH_CLICKED: "idle",
+        INCREMENT: { actions: "increment" },
+      },
+    },
+  },
+}, {
+  actions: {
+    increment: assign((context, event) => {
+      context.incremented += event.amount;
+    }),
+  },
+});
+
+// Selectors to transform the machines state into a representation useful for the view
+const selectors = buildSelectors(machine, (ctx, canHandleEvent) => ({
+  canIncrement: canHandleEvent({type: "INCREMENT", count: 1 }),
+  showSecret: ctx.incremented > 10,
+  count: ctx.incremented,
+}));
+
+// Actions to abstract away the details of sending events to the machine
+const actions = buildActions(machine, actions, (send, selectors) => ({
+  increment(amount: number) {
+     send({ type: "INCREMENT", amount: selectors.count > 4 ? amount * 2 : amount });
+  },
+  switch() {
+    send({ type: "SWITCH_CLICKED" });
+  },
+}));
+
+// A view to bring it all together
+// the return value is a plain React view that can be rendered anywhere by passing in the needed props
+// the view has no knowledge of the machine it's bound to
+const view = buildView(machine, actions, selectors, slots, ({ actions, selectors, inState }) => {
+  return (
+    <div>
+      <button onClick={() => actions.switch()}>{inState("active") ? "Deactivate" : "Activate"}</button>
+      <p>Count: {selectors.count}</p>
+      <button onClick={() => actions.increment(1)} disabled={!selectors.canIncrement}>Increment</button>
+      {selectors.showSecret && <p>The secret password is hunter2</p>}
+    </div>
+  );
+});
+
+// Stapling the machine, selectors, actions, view, and slots together
+const RootMachine = buildXstateTreeMachine(machine, {
+  selectors,
+  actions,
+  view,
+  slots
+});
+
+// Build the React host for the tree
+const XstateTreeRoot = buildRootComponent(RootMachine);
+
+
+// Rendering it with React
+const ReactRoot = createRoot(document.getElementById("root"));
+ReactRoot.render(<XstateTreeRoot />);
+```
 
 ## Overview
 
 Each machine that forms the tree representing your UI has an associated set of selector, action, view functions, and "slots"
   - Selector functions are provided with the current context of the machine, a function to determine if it can handle a given event and a function to determine if it is in a given state, and expose the returned result to the view.
   - Action functions are provided with the `send` method bound to the machines interpreter and the result of calling the selector function
-  - Slots are how children of the machine are exposed to the view. They can be either single slot, a single machine, or multi slot for when you have a list of actors. 
+  - Slots are how children of the machine are exposed to the view. They can be either single slot for a single actor, or multi slot for when you have a list of actors. 
   - View functions are React views provided with the output of the selector and action functions, a function to determine if the machine is in a given state, and the currently active slots
 
 ## API
@@ -19,6 +118,8 @@ To assist in making xstate-tree easy to use with TypeScript there are "builder"
 * `buildView`, first argument is the machine we are creating a view for, second argument is the selector factory, third argument is the actions factory, fourth argument is the array of slots and the fifth argument is the view function itself which gets supplied the selectors, actions, slots and `inState` method as props. It wraps the view in a React.memo  
 * `buildXStateTreeMachine` takes the results of `buildSelectors`, `buildActions`, `buildView` and the list of slots and returns an xstate-tree compatible machine
 
+Full API docs coming soon, see [#20](https://github.com/koordinates/xstate-tree/issues/20)
+
 ### Slots
 
 Slots are how invoked/spawned children of the machine are supplied to the Machines view. The child machines get wrapped into a React component responsible for rendering the machine itself. Since the view is provided with these components it is responsible for determining where in the view output they show up. This leaves the view in complete control of where the child views are placed.
@@ -58,10 +159,9 @@ These events can be added anywhere, either next to a component for component spe
 2. If they are tied to a component they need to be in the index.ts file that imports the view/selectors/actions etc and calls `buildXstateTreeMachine`. If they are in the file containing those functions the index.d.ts file will not end up importing them.
 
 
-### Storybook
+### [Storybook](https://storybook.js.org)
 
-It's relatively uncomplicated to display xstate-tree views directly in Storybook. Since the views are plain React components
-that accept selectors/actions/slots/inState as props you can just import the view and render it in a Story
+It is relatively simple to display xstate-tree views directly in Storybook. Since the views are plain React components that accept selectors/actions/slots/inState as props you can just import the view and render it in a Story
 
 There are a few utilities in xstate-tree to make this easier
 
@@ -87,4 +187,4 @@ are planning on rendering the view using the xstate-tree machine itself, or test
 via the view.
 
 It's a simple function that takes a name argument and returns a basic xstate-tree machine that you
-can replace slot services with. It just renders a div containing the name supplied
+can replace slot services with. It just renders a div containing the name supplied

package/lib/builders.js

@@ -1,6 +1,19 @@
 import React from "react";
 /**
  * @public
+ *
+ * Factory function for selectors. The selectors function is passed three arguments:
+ * - `ctx` - the current context of the machines state
+ * - `canHandleEvent` - a function that can be used to determine if the machine can handle a
+ * given event, by simulating sending the event and seeing if a stat change would happen.
+ * Handles guards
+ * - `inState` - equivalent to xstates `state.matches`, allows checking if the machine is in a given state
+ *
+ * The resulting selector function has memoization. It will return the same value until the
+ * machine's state changes or the machine's context changes
+ * @param machine - The machine to create the selectors for
+ * @param selectors - The selector function
+ * @returns The selectors - ready to be passed to {@link buildActions}
  */
 export function buildSelectors(__machine, selectors) {
     let lastState = undefined;
@@ -27,7 +40,19 @@ export function buildSelectors(__machine, selectors) {
 }
 /**
  * @public
- */
+ *
+ * Factory function for actions. The actions function is passed two arguments:
+ * - `send` - the interpreters send function, which can be used to send events to the machine
+ * - `selectors` - the output of the selectors function from {@link buildSelectors}
+ *
+ * The resulting action function has memoization. It will return the same value until the
+ * selectors reference changes or the send reference changes
+ *
+ * @param machine - The machine to create the actions for
+ * @param selectors - The selectors function
+ * @param actions - The action function
+ * @returns The actions function - ready to be passed to {@link buildView}
+ * */
 export function buildActions(__machine, __selectors, actions) {
     let lastSelectorResult = undefined;
     let lastCachedResult = undefined;
@@ -46,12 +71,33 @@ export function buildActions(__machine, __selectors, actions) {
 }
 /**
  * @public
+ *
+ * Factory function for views. The view is passed four props:
+ * - `slots` - the slots object, which can be used to render the children of the view invoked by the machine
+ * - `actions` - the output of the actions function from {@link buildActions}
+ * - `selectors` - the output of the selectors function from {@link buildSelectors}
+ * - `inState` - equivalent to xstates `state.matches`, allows checking if the machine is in a given state
+ *
+ * The resulting view is wrapped in React.memo, it will re-render when the actions or selectors reference changes
+ *
+ * @param machine - The machine to create the view for
+ * @param selectors - The selectors function from {@link buildSelectors}
+ * @param actions - The actions function from {@link buildActions}
+ * @param slots - The array of slots that can be rendered by the view
+ * @param view - The view function
+ * @returns The React view
  */
 export function buildView(__machine, __selectors, __actions, __slots, view) {
     return React.memo(view);
 }
 /**
  * @public
+ *
+ * staples xstate machine and xstate-tree metadata together into an xstate-tree machine
+ *
+ * @param machine - The machine to staple the selectors/actions/slots/view to
+ * @param metadata - The xstate-tree metadata to staple to the machine
+ * @returns The xstate-tree machine, ready to be invoked by other xstate-machines or used with `buildRootComponent`
  */
 export function buildXStateTreeMachine(machine, meta) {
     const copiedMeta = { ...meta };

package/lib/lazy.js

@@ -4,6 +4,7 @@ import { buildActions, buildSelectors, buildView, buildXStateTreeMachine, } from
 import { singleSlot } from "./slots";
 /**
  * @public
+ *
  * Wraps an xstate-tree returning Promise (generated by `import()` in an xstate-tree machine responsible for
  * booting up the machine upon resolution
  *

package/lib/routing/Link.js

@@ -2,6 +2,7 @@ import React from "react";
 import { useHref } from "./useHref";
 /**
  * @public
+ *
  * Renders an anchor tag pointing at the provided Route
  *
  * The query/params/meta props are conditionally required based on the

package/lib/routing/createRoute/createRoute.js

@@ -4,6 +4,11 @@ import { isNil } from "../../utils";
 import { joinRoutes } from "../joinRoutes";
 /**
  * @public
+ *
+ * Creates a route factory
+ *
+ * @param history - the history object to use for this route factory, this needs to be the same one used in the trees root component
+ * @param basePath - the base path for this route factory
  */
 export function buildCreateRoute(history, basePath) {
     function navigate({ history, url, meta, }) {

package/lib/testingUtilities.js

@@ -8,6 +8,11 @@ import { difference } from "./utils";
 import { emitter, recursivelySend, XstateTreeView } from "./xstateTree";
 /**
  * @public
+ *
+ * Creates a dummy machine that just renders the supplied string - useful for rendering xstate-tree views in isolation
+ *
+ * @param name - the string to render in the machines view
+ * @returns a dummy machine that renders a div containing the supplied string
  */
 export function slotTestingDummyFactory(name) {
     return buildXStateTreeMachine(createMachine({
@@ -26,6 +31,8 @@ export function slotTestingDummyFactory(name) {
 }
 /**
  * @public
+ *
+ * Can be used as the slots prop for an xstate-tree view, will render a div containing a <p>slotName-slot<p> for each slot
  */
 export const genericSlotsTestingDummy = new Proxy({}, {
     get(_target, prop) {
@@ -38,6 +45,12 @@ export const genericSlotsTestingDummy = new Proxy({}, {
 });
 /**
  * @public
+ *
+ * Aids in type inference for creating props objects for xstate-tree views.
+ *
+ * @param view - The view to create props for
+ * @param props - The actions/selectors props to pass to the view
+ * @returns An object with the view's selectors, actions, and inState function props
  */
 export function buildViewProps(_view, props) {
     return {

package/lib/xstate-tree.d.ts

@@ -57,16 +57,37 @@ export declare type ArgumentsForRoute<T> = T extends Route<infer TParams, infer
 
 /**
  * @public
+ *
+ * Broadcasts a global event to all xstate-tree machines
+ *
+ * @param event - the event to broadcast
  */
 export declare function broadcast(event: GlobalEvents): void;
 
 /**
  * @public
- */
+ *
+ * Factory function for actions. The actions function is passed two arguments:
+ * - `send` - the interpreters send function, which can be used to send events to the machine
+ * - `selectors` - the output of the selectors function from {@link buildSelectors}
+ *
+ * The resulting action function has memoization. It will return the same value until the
+ * selectors reference changes or the send reference changes
+ *
+ * @param machine - The machine to create the actions for
+ * @param selectors - The selectors function
+ * @param actions - The action function
+ * @returns The actions function - ready to be passed to {@link buildView}
+ * */
 export declare function buildActions<TMachine extends AnyStateMachine, TActions, TSelectors, TSend = InterpreterFrom<TMachine>["send"]>(__machine: TMachine, __selectors: TSelectors, actions: (send: TSend, selectors: OutputFromSelector<TSelectors>) => TActions): (send: TSend, selectors: OutputFromSelector<TSelectors>) => TActions;
 
 /**
  * @public
+ *
+ * Creates a route factory
+ *
+ * @param history - the history object to use for this route factory, this needs to be the same one used in the trees root component
+ * @param basePath - the base path for this route factory
  */
 export declare function buildCreateRoute(history: XstateTreeHistory, basePath: string): {
     /**
@@ -146,6 +167,11 @@ export declare function buildCreateRoute(history: XstateTreeHistory, basePath: s
 
 /**
  * @public
+ *
+ * Builds a React host component for the root machine of an xstate-tree
+ *
+ * @param machine - The root machine of the tree
+ * @param routing - The routing configuration for the tree
  */
 export declare function buildRootComponent(machine: AnyXstateTreeMachine, routing?: {
     routes: AnyRoute[];
@@ -160,6 +186,19 @@ export declare function buildRootComponent(machine: AnyXstateTreeMachine, routin
 
 /**
  * @public
+ *
+ * Factory function for selectors. The selectors function is passed three arguments:
+ * - `ctx` - the current context of the machines state
+ * - `canHandleEvent` - a function that can be used to determine if the machine can handle a
+ * given event, by simulating sending the event and seeing if a stat change would happen.
+ * Handles guards
+ * - `inState` - equivalent to xstates `state.matches`, allows checking if the machine is in a given state
+ *
+ * The resulting selector function has memoization. It will return the same value until the
+ * machine's state changes or the machine's context changes
+ * @param machine - The machine to create the selectors for
+ * @param selectors - The selector function
+ * @returns The selectors - ready to be passed to {@link buildActions}
  */
 export declare function buildSelectors<TMachine extends AnyStateMachine, TSelectors, TContext = ContextFrom<TMachine>>(__machine: TMachine, selectors: (ctx: TContext, canHandleEvent: CanHandleEvent<TMachine>, inState: MatchesFrom<TMachine>, __currentState: never) => TSelectors): Selectors<TContext, EventFrom<TMachine>, TSelectors, MatchesFrom<TMachine>>;
 
@@ -186,16 +225,43 @@ export declare function buildTestRootComponent<TMachine extends AnyStateMachine,
 
 /**
  * @public
+ *
+ * Factory function for views. The view is passed four props:
+ * - `slots` - the slots object, which can be used to render the children of the view invoked by the machine
+ * - `actions` - the output of the actions function from {@link buildActions}
+ * - `selectors` - the output of the selectors function from {@link buildSelectors}
+ * - `inState` - equivalent to xstates `state.matches`, allows checking if the machine is in a given state
+ *
+ * The resulting view is wrapped in React.memo, it will re-render when the actions or selectors reference changes
+ *
+ * @param machine - The machine to create the view for
+ * @param selectors - The selectors function from {@link buildSelectors}
+ * @param actions - The actions function from {@link buildActions}
+ * @param slots - The array of slots that can be rendered by the view
+ * @param view - The view function
+ * @returns The React view
  */
 export declare function buildView<TMachine extends AnyStateMachine, TEvent extends EventObject, TActions, TSelectors extends AnySelector, TSlots extends readonly Slot[] = [], TMatches extends AnyFunction = MatchesFrom<TMachine>, TViewProps = ViewProps<OutputFromSelector<TSelectors>, TActions, TSlots, TMatches>, TSend = (send: TEvent) => void>(__machine: TMachine, __selectors: TSelectors, __actions: (send: TSend, selectors: OutputFromSelector<TSelectors>) => TActions, __slots: TSlots, view: React_2.ComponentType<TViewProps>): React_2.ComponentType<TViewProps>;
 
 /**
  * @public
+ *
+ * Aids in type inference for creating props objects for xstate-tree views.
+ *
+ * @param view - The view to create props for
+ * @param props - The actions/selectors props to pass to the view
+ * @returns An object with the view's selectors, actions, and inState function props
  */
 export declare function buildViewProps<C extends keyof JSX.IntrinsicElements | JSXElementConstructor<any>>(_view: C, props: Pick<InferViewProps<PropsOf<C>>, "actions" | "selectors">): InferViewProps<PropsOf<C>>;
 
 /**
  * @public
+ *
+ * staples xstate machine and xstate-tree metadata together into an xstate-tree machine
+ *
+ * @param machine - The machine to staple the selectors/actions/slots/view to
+ * @param metadata - The xstate-tree metadata to staple to the machine
+ * @returns The xstate-tree machine, ready to be invoked by other xstate-machines or used with `buildRootComponent`
  */
 export declare function buildXStateTreeMachine<TMachine extends AnyStateMachine, TSelectors extends AnySelector, TActions extends AnyActions>(machine: TMachine, meta: XStateTreeMachineMeta<TMachine, TSelectors, TActions>): StateMachine<ContextFrom<TMachine>, XstateTreeMachineStateSchema<TMachine, TSelectors, TActions>, EventFrom<TMachine>, any, any, any, any>;
 
@@ -213,6 +279,8 @@ declare type Events = any;
 
 /**
  * @public
+ *
+ * Can be used as the slots prop for an xstate-tree view, will render a div containing a <p>slotName-slot<p> for each slot
  */
 export declare const genericSlotsTestingDummy: any;
 
@@ -249,6 +317,7 @@ keyof (ExcludeOptional extends true ? OmitOptional<Obj> : Obj)
 
 /**
  * @public
+ *
  * Wraps an xstate-tree returning Promise (generated by `import()` in an xstate-tree machine responsible for
  * booting up the machine upon resolution
  *
@@ -260,6 +329,7 @@ export declare function lazy<TMachine extends AnyStateMachine>(factory: () => Pr
 
 /**
  * @public
+ *
  * Renders an anchor tag pointing at the provided Route
  *
  * The query/params/meta props are conditionally required based on the
@@ -304,6 +374,8 @@ export declare function matchRoute<TRoutes extends Route<any, any, any, any>[]>(
 
 /**
  * @public
+ *
+ * Extract meta type from route object
  */
 export declare type Meta<T> = T extends {
     meta: infer TMeta;
@@ -329,6 +401,10 @@ declare type OmitOptional<T> = {
 
 /**
  * @public
+ *
+ * Allows hooking in to the global events sent between machines
+ *
+ * @param handler - the handler to call when an event is broadcast
  */
 export declare function onBroadcast(handler: (event: GlobalEvents) => void): () => void;
 
@@ -360,6 +436,8 @@ export declare type OutputFromSelector<T> = T extends Selectors<any, any, infer
 
 /**
  * @public
+ *
+ * Extract params type from route object object
  */
 export declare type Params<T> = T extends {
     params: infer TParams;
@@ -380,6 +458,8 @@ declare type PropsOf<C extends keyof JSX.IntrinsicElements | JSXElementConstruct
 
 /**
  * @public
+ *
+ * Extract query type from route object
  */
 export declare type Query<T> = T extends {
     query: infer TQuery;
@@ -397,6 +477,8 @@ declare type Return<TRoutes extends Route<any, any, any, any>[]> = {
 
 /**
  * @public
+ *
+ * xstate-tree routing event
  */
 export declare type Route<TParams, TQuery, TEvent, TMeta> = {
     /**
@@ -438,6 +520,9 @@ export declare type Route<TParams, TQuery, TEvent, TMeta> = {
     getEvent: RouteArgumentFunctions<{
         type: TEvent;
     } & RouteArguments<TParams, TQuery, TMeta>, TParams, TQuery, TMeta>;
+    /**
+     * Event type for this route
+     */
     event: TEvent;
     url?: string;
     history: XstateTreeHistory;
@@ -478,11 +563,15 @@ export declare type RouteArguments<TParams, TQuery, TMeta> = TParams extends und
 
 /**
  * @public
+ *
+ * Extract meta type from route
  */
 export declare type RouteMeta<T> = T extends Route<any, any, any, infer TMeta> ? TMeta : undefined;
 
 /**
  * @public
+ *
+ * Extract params type from route
  */
 export declare type RouteParams<T> = T extends Route<infer TParams, any, any, any> ? TParams : undefined;
 
@@ -496,6 +585,7 @@ export declare type Routing404Event = {
 
 /**
  * @public
+ *
  * Converts a Route type into the Event that will be broadcast for that route
  *
  * All routes a machine should handle should be added to the machines event union using this type
@@ -519,6 +609,9 @@ export declare type Selectors<TContext, TEvent, TSelectors, TMatches> = (ctx: TC
 export declare type SharedMeta = {
     /**
      * Suppresses this routing change event from being picked up by react-router
+     *
+     * This is for a Koordinates specific modification to react-router
+     * TODO: Remove once there are user providable shared meta
      */
     doNotNotifyReactRouter?: boolean;
     /**
@@ -556,6 +649,11 @@ export declare type Slot = SingleSlot<any> | MultiSlot<any>;
 
 /**
  * @public
+ *
+ * Creates a dummy machine that just renders the supplied string - useful for rendering xstate-tree views in isolation
+ *
+ * @param name - the string to render in the machines view
+ * @returns a dummy machine that renders a div containing the supplied string
  */
 export declare function slotTestingDummyFactory(name: string): StateMachine<unknown, XstateTreeMachineStateSchema<StateMachine<unknown, any, AnyEventObject, {
     value: any;

package/lib/xstateTree.js

@@ -10,6 +10,10 @@ import { isLikelyPageLoad } from "./utils";
 export const emitter = new TinyEmitter();
 /**
  * @public
+ *
+ * Broadcasts a global event to all xstate-tree machines
+ *
+ * @param event - the event to broadcast
  */
 export function broadcast(event) {
     console.debug("[xstate-tree] broadcasting event ", event.type);
@@ -17,6 +21,10 @@ export function broadcast(event) {
 }
 /**
  * @public
+ *
+ * Allows hooking in to the global events sent between machines
+ *
+ * @param handler - the handler to call when an event is broadcast
  */
 export function onBroadcast(handler) {
     emitter.on("event", handler);
@@ -138,6 +146,11 @@ export function recursivelySend(service, event) {
 }
 /**
  * @public
+ *
+ * Builds a React host component for the root machine of an xstate-tree
+ *
+ * @param machine - The root machine of the tree
+ * @param routing - The routing configuration for the tree
  */
 export function buildRootComponent(machine, routing) {
     if (!machine.meta) {

package/package.json

@@ -2,7 +2,7 @@
   "name": "@koordinates/xstate-tree",
   "main": "lib/index.js",
   "types": "lib/xstate-tree.d.ts",
-  "version": "2.0.5",
+  "version": "2.0.7",
   "license": "MIT",
   "description": "Build UIs with Actors using xstate and React",
   "keywords": [
@@ -73,7 +73,8 @@
     "build": "rimraf dist && tsc -p tsconfig.build.json",
     "build:watch": "tsc -p tsconfig.build.json -w",
     "api-extractor": "api-extractor run",
-    "release": "semantic-release"
+    "release": "semantic-release",
+    "commitlint": "commitlint --edit"
   },
   "files": [
     "lib/**/*.js",