statelyai / docs Goto Github PK

Assuming statelyai/xstate#3997 is merged for v5, need to add docs for how they work.

I wrote the changeset for the PR with docs in mind so hopefully it works for that or can at least serve as inspiration: https://github.com/with-heart/xstate/blob/action-groups-next/.changeset/wild-roses-sort.md

I wasn't aware that there are contribution guidelines in the wiki. I just stumbled upon them reading the introductory blog post about the new docs.

Oftentimes, a CONRTIBUTION.md file can be found at the root of a repo (e.g. for linking to the wiki) or you can mention the Wiki in the readme. Adding either of these options or both would make sense imo.

You can also hide the Projects and Actions tab of the repo. Maybe that makes the wiki also somewhat more discoverable:
https://github.com/statelyai/docs/settings
https://github.com/statelyai/docs/settings/actions

Currently missing an image. Description might be better if it had something brand-related and exciting to draw people in, at least for the index page?

Description

The xState v4 docs implied you could call .useActor() from the Actor Context in React.

That is not the current behavior, and the docs for XState v5 reflect that.

But the docs have a typo implying .useActor() is still available in the API, and it's not part of the XState v5 API.

Bug in the docs

In the current code in the docs, .useActor() is used where .useActorRef() should have been used.

Docs: https://stately.ai/docs/xstate-v5/xstate-react#createactorcontextmachine

Suggested improvement to docs

This looks to be the correct usage that should be shared in the docs:

//      const actorRef = SomeContext.useActorRef();
//      const state = SomeContext.useSelector((state) => state);

Source: createActorContext.test.tsx, lines 397-400 of
packages/xstate-react/test/createActorContext.test.tsx

Expected result

Bug in the docs

The bug:

  const someactorRef = SomeMachineContext.useActor();

The full current code example in the docs:

import { SomeMachineContext } from '../path/to/SomeMachineContext';

function SomeComponent() {
  const count = SomeMachineContext.useSelector((state) => state.context.count);
  const someactorRef = SomeMachineContext.useActor();

  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={() => someactorRef.send({ type: 'inc' })}>
        Increment
      </button>
    </div>
  );
}

Actual result

Bug in the docs

I'll highlight the error again for clarity. The current docs would need .useActor() replaced with .useActorRef().

  const someactorRef = SomeMachineContext.useActorRef();

Suggested improvement to docs

This looks to be the correct usage that should be shared in the docs:

//      const actorRef = SomeContext.useActorRef();
//      const state = SomeContext.useSelector((state) => state);

Source: createActorContext.test.tsx, lines 397-400 of
packages/xstate-react/test/createActorContext.test.tsx

To put the whole code example back together, here's what I would suggest:

import { SomeMachineContext } from '../path/to/SomeMachineContext';

/** Optimize machine selectors by defining them externally. */

/** The type of the machine's state. Used for `useSelector` selectors. */
type State = ReturnType<typeof machine.getInitialState>

/** @returns the `state` of the state machine. */
const selectState = (state: State) => state

/** @returns the `count` from the state machine's context. */
const selectCount = (state: State) => state.context.count

function SomeComponent() {
  /** We can use state.matches() to check the machine's state. */
  const state = SomeMachineContext.useSelector(selectState);
  /** Using selectors is more efficient than reading the context. */
  const count = SomeMachineContext.useSelector(selectCount);
  /** We send events to the state machine with `actorRef.send()`. */
  const actorRef = SomeMachineContext.useActor();

  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={() => actorRef.send({ type: 'inc' })}>
        Increment
      </button>
    </div>
  );
}

Reproduction

https://codesandbox.io/s/funny-jackson-rhsdld?file=/src/index.tsx

Additional context

I tried to create a reproduction, but I couldn't install the XState v5 beta packages installed into the React + TypeScript template at Codesandbox.

Here are the packages I am running locally:

 xstate@npm:5.0.0-beta.21 (via npm:beta)
 @xstate/react@npm:4.0.0-beta.8 [9dce3] (via npm:beta [9dce3])

For what it's worth, the following code did not give me the correct type value for state:

  const state = SomeMachineContext.useSelector((state) => state);

...

This code does give me the correct type for state, when selectState is defined outside the component.

  const state = SomeMachineContext.useSelector(selectState);

That is why I recommend the selectState usage for the docs.

I've check this documentation but it seems like not too clear for as wanted a to go example in setting it up
The documentation only shows how to setup states but Im wondering why not include on how to include services, guards and so when creating state

https://xstate.js.org/docs/recipes/vue.html

Though upon checking the createMachine docs it provides options
But not seeing clear information in making through on non-composition-api.

In composition-api version is easy and clear.
createMachine then userMachine which dev can inject services, actions, and guards in to.

Can you provide other example which we can see on how do we inject those options?
Or are there already existing example but hidden or not accessible on the site?

Description

It's difficult to find how to type a statemachine because theres only a small line about it in the react recipe

For Typescript, you can create the context as createContext({ authService: {} as InterpreterFrom }); to ensure strong typings.

Expected result

Add it in the using typescript section

Actual result

Searched for 1 or 2 hours before finding it

Additional context

See this thread on discord.

In addition to documenting the features of XState, we should provide a curated list of external resources related to state machines. The old XState docs have their own "Resources" section, but this list is pretty outdated.

GOALS

• Similar to the "Blog" section, each resource should have its own page so that they can be easily indexed and organized.
• Resource posts should include metadata tags so that users can easily search by medium / topic (e.g. book or statechart).
  ** Docusaurus should support multiple blogs but I am still researching alternative ideas.
• Whenever possible, resources should be embedded in the page so that users don't have to leave the docs site.

NOTES:

• ✅ I am willing to contribute to this

I am on the page templates (https://stately.ai/docs/xstate/templates).

Middle mouse click or "right click > open in new tab" opens the current page in a new tab instead of the page that was clicked on.
You can see in the screenshot below that # is linked, so the current page. So instead a basics overview page or the first child item should be linked: xstate/basics/what-is-a-statechart

I have never worked with docusaurus but tried a fix.

In sidebars.js I replaced

        {
          type: 'category',
          label: 'Basics',
          items: [
            'xstate/basics/what-is-a-statechart',
            'xstate/basics/options',
            'xstate/basics/inline-vs-named-options',
          ],

...with this

        {
          type: 'category',
          label: 'Basics',
          link: {
            type: 'doc',
            id: 'xstate/basics/what-is-a-statechart',
          },
          items: [
            'xstate/basics/what-is-a-statechart',
            'xstate/basics/options',
            'xstate/basics/inline-vs-named-options',
          ],
        },

This seems to be working in principle but somehow creates another caret.

I guess the custom.css needs to be adjusted in that case: https://github.com/statelyai/docs/blob/main/src/css/custom.css

Description

Looking at the docs of MachineOptions and it mentions only actions.

But from the Configuring services part of the guides

const userMachine = createMachine(
  {
      // ...
  },
  {
  services: {
    getUser: (context, event) => fetchUser(context.user.id)
  }
);

and Serialising guards

const searchMachine = createMachine(
  {
    // ...
  },
  {
    guards: {
      searchValid: (context, event) => {
        return context.canSearch && event.query && event.query.length > 0;
      }
    }
  }
);

it seems to me that the MachineOptions object can also have services and guards keys? So it should be mentioned in the guides.

Expected result

### Machine options

- `actions?` (object) - a lookup object for your string actions.
- `guards?` (object) - a lookup object for your string guards.
- `services?` (object) - a lookup object for your string services.

Actual result

Confusion? :)

Reproduction

N/A

Additional context

No response

At page https://stately.ai/docs/xstate/actions/#actions

the configuration is:

    entry: ['youSayGoodbye', 'iSayHello']

and the explanation is

In the example above, Me: Hello will be logged to the console, followed by You: Goodbye.

I would say that is incorrect...

You: Goodbye 
Me: Hello 

The source:
https://github.com/statelyai/docs/blame/main/docs/xstate/actions/actions.mdx#L132

Description
https://xstate.js.org/docs/guides/history.html#history-state-configuration

1. First of all, it would be nice if there could be some kind of comparative example between shallow and deep types.

2. Also, some kind of fan type introduction to the reader. There are a lot of fan types.

This one is obviusly not

But is this one? (infinite conmutator)

Or this one? (fixed positions, remembers the position even when plug-unplug from electric cable)

has it an aditional independent power button, like this one?

feel the difference between the latest two as well. Physical state vs in-memory state.

3. Which kind on event is HIGH_POWER in real life and why does it ask for history? HIGHEST POWER is third, I don't understand why whould you ask for history.

4. Why on a POWER event it would target to 'fanOff'? As a reader I would expect to go 'fanOn'

    fanOn: {
      ....
      on: {
        POWER: { target: 'fanOff' }
      }
    }

5. If you try to paste the full example on Visualizer, you will get an error

Type '{ type: "history"; target: string; }' is not assignable to type 'StateNodeConfig<unknown, any, AnyEventObject, ActionObject<unknown, AnyEventObject>>'.
  Object literal may only specify known properties, and 'target' does not exist in type 'StateNodeConfig<unknown, any, AnyEventObject, ActionObject<unknown, AnyEventObject>>'.(2322)

Thanks

I'm sorry if my English sounds very strict or even not understandable. I don't speak english but I try my best. Thanks for your comprehension.

I tried running the docs in local development mode but got an error because the three environment variables were not set for the Algolia search.

ValidationError: "algolia.appId" is required. If you haven't migrated to the new DocSearch infra, please refer to the blog post for instructions: https://docusaurus.io/blog/2021/11/21/algolia-docsearch-migration

I got around this issue by commenting out the whole algolia config in the file docusaurus.config.js

algolia: {
  appId: process.env.ALGOLIA_APP_ID,
  apiKey: process.env.ALGOLIA_API_KEY,
  indexName: process.env.ALGOLIA_INDEX,
  contextualSearch: false,
  replaceSearchResultPathname:
    // Remove /docs from the search result pathname when we're in a preview deployment
    process.env.VERCEL_ENV === 'preview'
      ? {
          from: '/docs/',
          to: '/',
        }
      : undefined,
},

Then building works fine. The docs just don't have a search as expected.

So, it would be nice to add this information to the readme and maybe give additional instructions on how to set up a free Algolia account and creation of .env and the three variables.

https://github.com/statelyai/docs/blob/3b06dd70689b6ab63744bcfe50ca810476adc4c9/docs/state-machines-and-statecharts.mdx#L211C2-L211C52

This link target is identical to the previous and does not contain the content described in the prior paragraph

Description
Syntax highlighting is broken Svelte on this docs page.

Expected Result
See syntax highlighting.

Actual Result
Text is white all highlighted the same color.

Reproduction
https://xstate.js.org/docs/packages/xstate-svelte

Additional context
It looks fine on the GitHub page, however.

Instructions on how to generate docsets specifically for Dash.

This needs some research to establish and plan the best approach for VuePress.

Description

Expected result

That things stay in the navbar at all breakpoints.

Actual result

Things broke out of the navbar between 990sth and 1060sth px.

Reproduction

https://stately.ai/docs/category/get-started

Additional context

No response