statelyai / docs Goto Github PK

Instructions on how to generate docsets specifically for Dash.

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

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?

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

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

Hi,

I was going through the docs on npm for the @xstate/react library and I ran into some errors trying out the sample code. So, the sample code is this shown below:

import { useMachine } from '@xstate/react';
import { createMachine } from 'xstate';

const toggleMachine = createMachine({
  id: 'toggle',
  initial: 'inactive',
  states: {
    inactive: {
      on: { TOGGLE: 'active' }
    },
    active: {
      on: { TOGGLE: 'inactive' }
    }
  }
});

export const Toggler = () => {
  const [state, send] = useMachine(toggleMachine);

  return (
    <button onClick={() => send('TOGGLE')}>
      {state.value === 'inactive'
        ? 'Click to activate'
        : 'Active! Click to deactivate'}
    </button>
  );
};

This leads to the following errors in both my code and the console:

In VSCode:

The error in the browser console 👇 . The state doesn't get updated, and nothing happens in the UI:

The issue happens to be that send requires an object rather than a string. The fix was to write the following code:

Recommendation
The sample code to should updated to reflect the proper way of updating state with @xstate/react.

import { useMachine } from '@xstate/react';
import { createMachine } from 'xstate';

const toggleMachine = createMachine({
  id: 'toggle',
  initial: 'inactive',
  states: {
    inactive: {
      on: { TOGGLE: 'active' }
    },
    active: {
      on: { TOGGLE: 'inactive' }
    }
  }
});

export const Toggler = () => {
  const [state, send] = useMachine(toggleMachine);

  return (
    <button onClick={() => send({ type: "TOGGLE" })}>
      {state.value === 'inactive'
        ? 'Click to activate'
        : 'Active! Click to deactivate'}
    </button>
  );
};

Package versions

@xstate/react: "^4.1.0"
@xstate: "^5.9.1"

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.

{
  target: 'step2',
  guard: and([
    {
      type: 'checkStep',
      params: { step: 2 }
    },
    {
      type: 'combinationFist',
      params: { objName: 'xxxxx' }
    },
    'nowStepEqualParams'
  ])
},
{
  target: 'step5',
  guard: and([
    {
      type: 'checkStep',
      params: { step: 5 }
    },
    {
      type: 'combinationFist',
      params: { objName: 'xxxx' }
    },
    'nowStepEqualParams'
  ])
},

When I use Guard, an error message appears in the editor stating 'Found 2 guards named' inline: [id] '. Watt # start [-1] # guard ", simulation cannot run normally. No matter which path I choose, it will jump to step 2。

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
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.

XState version

XState version 5

Description

The very first paragraph of this section, https://stately.ai/docs/state-machine-actors#state-machine-actor-input belongs to a different section.

I searched the repo & branches to make a PR, although I wasn't able to find a branch to submit the PR to.

May be worth having an issue template for docs-related issues too.

Expected result

Correct docs

Actual result

Incorrect docs

Reproduction

https://codesandbox.io/p/devbox/github/statelyai/xstate/tree/main/templates/vanilla-ts

Additional context

Please make the above links for reproduction templates open in new tabs, I almost lost all changes by clicking on one.

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

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

XState version

XState version 5

Description

basic "dynamic delay" example at https://stately.ai/docs/delayed-transitions#dynamic-delays seems to have typescript errors

Expected result

no TS errors

Actual result

TS errors

Reproduction

lll

Additional context

No response

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

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.

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.

Thank you for the great docs so far - but a crucial part is missing: testing!
Please provide best practices and a minimal example so we can use xState to the fullest: https://github.com/statelyai/docs/blob/main/docs/testing.mdx

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?

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

https://discord.com/channels/795785288994652170/1186344618116263976/1251885762836697139

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.

XState version

XState version 5

Description

API docs are broken for me. Attempting to visit api docs linked to via stately.ai and the result is a cloudflare-hosted 524 (timed out, yesterday) or 502 (bad gateway, today) error page.

Expected result

I expect API documentation to be available on the link provided via the official website stately.ai.

Actual result

I am receiving 502 / 524 via cloudflare-hosted error page.

Reproduction

GET https://tsdocs.dev/docs/xstate

Additional context

• retried via proxy & the site still times out

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