@koordinates/xstate-tree 2.0.5 → 2.0.6

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.6",
   "license": "MIT",
   "description": "Build UIs with Actors using xstate and React",
   "keywords": [