Merge branch 'main' into davidkpiano/persisting-restoring-state

Author: laurakalbag

.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+  "editor.wordWrap": "on"
+}

blog/2023-09-15-teams-feature-overview/index.mdx

@@ -0,0 +1,106 @@
+---
+title: Make the dream work! An overview of Stately Studio’s teams feature
+description: Getting the most out of Stately Studio’s teams feature
+tags: [stately studio, xstate, teams, machine versions, machine locking]
+authors: [gavin]
+slug: using-teams-in-stately-studio
+image: /blog/2023-09-15-stately-teams-overview.png
+date: 2023-09-19
+---
+
+Our team knew early on that users needed the ability to share machines in the Studio and build on each other’s work.
+We also needed the Studio to be an effective tool for teams to work together and share context.
+But how do we do that safely, making sure the right eyes were on the right machines?
+And how do we protect against accidental mishaps that have plagued devs since the dawn of the computer?
+Being a distributed dev team ourselves, we’ve shared these same pain points and decided to build a solution directly in the Studio.
+Enter [Stately teams](https://stately.ai/docs/teams), our way to provide privacy and safety while allowing effortless collaboration.
+
+<!--truncate-->
+
+## Why would I need a team?
+
+Great question, and we’re glad you asked!
+While we have the [Discover](https://stately.ai/registry/discover) page, which showcases over 20 thousand(!) community-created machines, we know that statecharts can contain critical details about core algorithms or processes that give businesses a competitive edge.
+Many users expressed interest in keeping these types of machines private, and we listened.
+
+### Sharing machine visualizations with teammates
+
+Developing software is collaborative by nature. To get any product launched, bug fixed, or feature shipped, teams need to work together under the same shared context.
+As projects grow in scope and complexity, it gets easier for team members to lose track of the bigger picture.
+Team members may get lost in the weeds of their own work while the rest of the project changes around them, or they may not have the full context of the project and make decisions that don’t align with the team’s goals.
+This is where the Studio’s teams feature comes in.
+Visualizing app logic as statecharts allows teams to see the entire project at a glance, and the ability to share these visualizations empowers each member to make well-informed decisions, regardless of discipline.
+Every teammate may not be a dev, but we’re confident that every teammate can benefit from a well-thought-out flowchart!
+
+## Teams 101
+
+Teams is an exclusive feature for [**Pro** and **Enterprise** users](https://stately.ai/pricing) that allows them to collaborate on different projects without needing to make them publicly visible. Team owners can assign roles that map closely with their team members’ intended set of responsibilities.
+
+![The Stately Studio Next team members tab. Under Owners/Admin, Kevin is labeled as Owner. David is an admin. Laura, Farzad and Gavin are listed under Editors. Anders, cirephe, and Mateusz are listed under Viewers.](./teamVNext.png)
+
+### Access control
+There are many times when a dev team needs to share their work context with others without granting them full rights to the projects. 
+For example, Lenny in accounting probably shouldn't have access to the company repo, but he could benefit from visually understanding the steps involved in processes and workflows.
+Having different teams with different roles lets us keep parties informed without added risk. 
+Don't trust your PM's trigger finger? Make them a [viewer](https://stately.ai/docs/teams#viewer-role); we promise not to tell. 
+Taking a vacation before new members can be onboarded? 
+Make another teammate an [admin](https://stately.ai/docs/teams#admin-role). 
+[Check out all our roles and permissions in our docs](https://stately.ai/docs/teams#team-roles). 
+
+### Sharing conveniently and safely
+
+There are ways to share machine visualizations in the Studio without teams, but they’re not ideal for many users.
+Users can make their projects and machines public, but that is a no-go for most businesses.
+Alternatively, Pro users could keep their projects private and only share with people they trust by exporting and re-importing. However, that invites potentially different sources of truth, adds potential confusion, and lacks a truly shared context.
+Inviting users to collaborate on the same private team allows them to share without the exporting and copy/paste gymnastics. 
+
+### A source of what, now?
+
+Simply put, a “source of truth” is a single place where all the information about a project is stored.
+In our case, we wanted to make sure that teams have a single place to view and collaborate on machine visualizations, and that place is a team project in the Studio.
+This prevents confusion and allows for a shared context between all team members. With a proper source of truth configured, we can avoid situations like this:
+
+![Four files with the filenames: onboardMachine.json, onboardMachine-final.json, onboardMachine-final-final.json, onboardMachine-actual-final-for-real-this-time.json.](/blog/2023-09-15-file-confusion.png)
+
+### But what about source control? Shouldn’t that be the source of truth?
+
+Ideally, yes, the team’s repository is the single source of truth for all application logic, but not every team member is a developer, nor should they all have access to source code.
+That said, we know teams need to ensure their machines in the Studio are always in lockstep with the rest of their source, so we added the ability to [import machines directly from GitHub](https://stately.ai/docs/import-from-github).
+We’re also working on a fully-fledged GitHub Sync feature, allowing users to save machines as commits back to their source repos! [Check out Anders’ demo previewing GitHub Sync in our recent office hours live stream](https://www.youtube.com/watch?v=WelBycMg2eA&t=1293s).
+### Superpower Pro features
+
+Having teams allows other features to shine. For example, we all know the value of collaboration, but more users naturally add more potential for mistakes to happen, even with proper roles assigned. To protect against mistakes, we’ve added the ability to [lock machines](https://stately.ai/docs/lock-machines), preventing teammates from accidentally overwriting or deleting machines.
+
+![A machine with locked status in Stately. Hovering over the status shows the information that the machine was Locked by cirephe on September 8, 2023 at 07:48PM.](./lockedScreenshot.png)
+
+Team members often need to manage and track variants of the same machine, so we added the ability to create [machine versions](https://stately.ai/docs/versions). Members can edit and save specific checkpoints of their machines and can even see the last person to and save a specific version. Team roles come into play here again by allowing only owners and admins to actually delete versions.
+
+![Machine versions panel in Stately. The current version is named Gavin’s ultimate joke machine. The previous version is a generated flow for a “A flow showing someone how to be funny.”](./versionScreenshot.png)
+
+## FAQs
+
+### Who can join my team?
+
+Anyone with an email address can be invited to a team!
+If they are not already members, they will have to [sign up for a Stately account](https://stately.ai/registry/login?).
+
+### How many users can be on a team?
+
+A team can have as many members as there are seats in your Pro or Enterprise plan, except for viewers.
+Viewers are free to add.
+
+### Does inviting a user take up a seat on the team?
+
+The seat is only taken once a user accepts the invite and claims the seat.
+If the invite was not accepted, the seat remains free.
+
+### Can I swap member roles and reclaim seats?
+Yes, but only owners and admins have the ability to reassign roles. 
+Any role except the owner may choose to leave the team, however. 
+The owner can instead delete the team. 
+
+Yes, but only owners and admins can reassign roles.
+Any role except the owner may choose to leave the team, however.
+The owner can instead delete the team.
+
+For more detailed information, visit our [Stately teams page in the docs](https://stately.ai/docs/teams#teams-members-and-pro-plan-seats)!

blog/2023-09-15-teams-feature-overview/lockedScreenshot.png

@@ -93,15 +93,15 @@ Use the <kbd>Backspace</kbd> key to delete the action.
 
 ## Add a built-in action
 
-You can add built-in XState actions which will be formatted in your [exported code](export-as-code.mdx). The options are:
+You can add built-in XState actions which will be formatted in your [exported code](/docs/export-as-code.mdx). The options are:
 
-- [assign](#assign-action): assigns data to the state context.
-- [raise](#raise-action): _raises_ an event that is received by the same machine.
-- [log](#log-action): an easy way to log messages to the console.
-- [sendTo](#send-to-action): sends an event to a specific actor.
-- [stop](#stop-action): stops a child actor.
+- [assign](/docs/xstate/actions/context#assign-action): assigns data to the state context.
+- [raise](/docs/xstate/actions/built-in-actions#raise-action): _raises_ an event that is received by the same machine.
+- [log](/docs/xstate/actions/built-in-actions#log-action): an easy way to log messages to the console.
+- [sendTo](/docs/xstate/actions/built-in-actions#sending-events-to-actors): sends an event to a specific actor.
+- [stop](/docs/xstate/actors/spawn#stopping-spawned-actors): stops a child actor.
 
-To add a built-in action, first add a [transition action](#add-a-transition-action), [entry action](#add-an-entry-action-to-a-state), or [exit action](#add-an-exit-action-to-a-state).
+To add a built-in action, first add a [transition action](#add-a-transition-action), [entry action](#add-an-entry-action-or-exit-action-to-a-state), or [exit action](#add-an-entry-action-or-exit-action-to-a-state).
 
 ### On the canvas
 
@@ -114,15 +114,15 @@ To add a built-in action, first add a [transition action](#add-a-transition-acti
 
 1. Open the state, or event <Info size={18} /> **Details** panel from the right tool menu.
 1. Hover, focus, or select the action block to reveal the <Edit size={18} /> edit icon button.
-2. Use the <Edit size={18} /> edit icon button to open the **Action** panel.
-3. Choose your desired action from the dropdown menu at the top of the **Action** panel.
-4. Fill out the required corresponding action input fields.
+1. Use the <Edit size={18} /> edit icon button to open the **Action** panel.
+1. Choose your desired action from the dropdown menu at the top of the **Action** panel.
+1. Fill out the required corresponding action input fields.
 
 ## Add a custom action
 
-You can also add custom actions with a custom action type and parameters which will be formatted as [XState action objects](#action-objects) in your [exported code](export-as-code.mdx).
+You can also add custom actions with a custom action type and parameters which will be formatted as [XState action objects](/docs/xstate/actions) in your [exported code](/docs/export-as-code).
 
-First, add a [transition action](#add-a-transition-action), [entry action](#add-an-entry-action-to-a-state), or [exit action](#add-an-exit-action-to-a-state).
+First, add a [transition action](#add-a-transition-action), [entry action](#add-an-entry-action-or-exit-action-to-a-state), or [exit action](#add-an-entry-action-or-exit-action-to-a-state).
 
 ### On the canvas
 
@@ -131,16 +131,16 @@ First, add a [transition action](#add-a-transition-action), [entry action](#add-
 3. Custom action is selected by default. Add your custom action type in the **Action type** text input.
 4. Add your custom **Action parameters** using the **Parameter key** and **Parameter value** text input pairs.
 
-[Read about action objects below for more on action types and and parameters](#action-objects).
+[Read about action objects below for more on action types and and parameters](/docs/xstate/actions).
 
 ### Using the details panel
 
 1. Open the state, or event <Info size={18} /> **Details** panel from the right tool menu.
 1. Hover, focus, or select the action block to reveal the <Edit size={18} /> edit icon button.
-2. Use the <Edit size={18} /> edit icon button to open the **Action** panel.
-3. Custom action is selected by default. Add your custom action type in the **Action type** text input.
-4. Add your custom **Action parameters** using the **Parameter key** and **Parameter value** text input pairs.
-:::xstate
+1. Use the <Edit size={18} /> edit icon button to open the **Action** panel.
+1. Custom action is selected by default. Add your custom action type in the **Action type** text input.
+1. Add your custom **Action parameters** using the **Parameter key** and **Parameter value** text input pairs.
+   :::xstate
 
 ## Looking for how to use entry and exit actions in XState?
 

blog/2023-09-15-teams-feature-overview/teamVNext.png

@@ -9,25 +9,25 @@ Here you can find all the documentation for the Stately Studio and [XState](/xst
 
 <ul className="content-boxes">
   <li>
-    <a className="link-box" href="states/intro">
+    <a className="link-box" href="docs/states/intro">
       🏁 <strong>Get started</strong> Jump straight into learning how to use the
       editor, starting with states.
     </a>
   </li>
   <li>
-    <a className="link-box" href="#stately-studio-editor">
+    <a className="link-box" href="#stately-studios-editor">
       ⬇️ <strong>Editor overview</strong> Keep reading to find out more about
       Stately Studio’s editor.
     </a>
   </li>
   <li>
-    <a className="link-box" href="state-machines-and-statecharts">
+    <a className="link-box" href="docs/state-machines-and-statecharts">
       🧠 <strong>Learn state machines and statecharts</strong> With our no-code
       introduction.
     </a>
   </li>
   <li>
-    <a className="link-box" href="/docs/xstate">
+    <a className="link-box" href="docs/xstate">
       💻 <strong>Learn XState</strong> Get started with our JavaScript and
       TypeScript library for state machines and statecharts.
     </a>
@@ -69,6 +69,7 @@ Stately Studio’s editor supports everything you need to visually build state m
 You can access quick start tutorials from the blue <HelpCircle size={12} /> Help button in the editor.
 
 When you first visit the Editor, you’ll be shown two short videos (7m36s) as a quick start guide. You can access these videos again anytime from:
+
 - Editor menu > Help > <GraduationCap size={12} /> **Learn Stately**.
 - The <HelpCircle size={12} /> Help button > <GraduationCap size={12} /> **Learn Stately**.
 

blog/2023-09-15-teams-feature-overview/versionScreenshot.png

@@ -17,7 +17,7 @@ Are you looking for the _Stately Studio_ visual _Editor_? Check out the [Stately
 
 :::tip
 
-Stately still supports the Stately Visualizer, but you will find many more advanced features, including the visual [Studio Editor](studio.mdx/#studio-editor), teams, and shared projects.
+Stately still supports the Stately Visualizer, but you will find many more advanced features, including the visual [Studio Editor](/studio.mdx#stately-studios-editor), teams, and shared projects.
 
 :::
 

docs/actions-and-actors/entry-and-exit-actions.mdx

@@ -35,7 +35,7 @@ You can also [download the VS Code extension from the VS Code marketplace](https
 
 ## TypeScript typegen
 
-You can automatically generate intelligent typings for XState with our VS Code extension and [command line interface](/tools/developer-tools.mdx#xstate-cli-command-line-interface). [Read more about how to use typegen, and our recommended best practices, on the Typegen page](../xstate/typescript/typegen).
+You can automatically generate intelligent typings for XState with our VS Code extension and [command line interface](/tools/developer-tools.mdx#xstate-cli-command-line-interface). [Read more about how to use typegen, and our recommended best practices, on the Typegen page](/docs/xstate/typescript/typegen).
 
 ## `xsm` snippet
 

docs/studio.mdx

@@ -12,7 +12,7 @@ const config = {
   baseUrl: '/',
   baseUrlIssueBanner: false,
   onBrokenLinks: 'throw',
-  onBrokenMarkdownLinks: 'warn',
+  onBrokenMarkdownLinks: 'throw',
   favicon: 'icon.svg',
   staticDirectories: ['static'],
 
@@ -90,7 +90,7 @@ const config = {
           blogSidebarCount: 0,
           postsPerPage: 10,
           editUrl: ({ locale, blogDirPath, blogPath, permalink }) =>
-            `https://github.com/statelyai/docs/edit/main/${blogDirPath}/${blogPath}`
+            `https://github.com/statelyai/docs/edit/main/${blogDirPath}/${blogPath}`,
         },
         theme: {
           customCss: require.resolve('./src/css/custom.css'),