Merge pull request #250 from codesandbox/draft/eager-smoke

Add org & storybook docs

Author: necoline

packages/projects-docs/pages/learn/access/_meta.json

@@ -1,4 +1,5 @@
 {
+  "organizations": "Organizations",
   "workspace": "Workspaces",
   "permissions": "User permissions"
 }

packages/projects-docs/pages/learn/access/organizations.mdx

@@ -0,0 +1,64 @@
+---
+title: Organizations
+authors: ['CompuIves']
+description:
+  An organzation is a collection of workspaces under one shared domain.
+---
+
+import { Callout } from 'nextra-theme-docs'
+
+# Organizations & domains
+
+![Organization](../images/org-create.png)
+
+Organizations provide a way to group and manage multiple workspaces under a single entity. This is particularly useful for companies, institutions or agencies that need to organize work into distinct teams.
+
+Additionally, organizations make it possible to connect all the employees at a company using CodeSandbox in a single space based on the company's shared email domain.
+
+## Creating an organization
+
+You can create an organization from any active workspace that is not already part of an organzation. 
+In the _Workspace settings_, open the [Organization tab](https://codesandbox.io/t/org) and enter a name for the organization. 
+
+
+![create org](../images/org-create.png)
+
+To prevent confusion, we recommend that you name your organization so it directly relates to your business’ name.
+
+
+![name org](../images/org-name.png) 
+
+Once you have created an organization, it will automatically be linked to the workspace you created it from. However, you can choose to add additional existing workspaces to that organization.
+You can also manage the organization admins. 
+
+
+![edit org](../images/org-edit.png) 
+
+The [Organization settings](https://codesandbox.io/t/org) will always be discoverable through the _Workspace settings_.
+
+## Setting an email domain
+
+In the _Organizations settings_, open the `Domain` tab and add your email domain. 
+The domain must be verified before being approved. This is an automated process that requires no action from you. 
+
+
+![add domain](../images/org-domain-add.png)
+
+Once the domain is approved, users who have CodeSandbox accounts connected to emails with a matching domain will be given the option to join the workspace.
+Users may encounter the suggestion to join an eligible workspace when they are attempting to access projects in the workspace or when they log into CodeSandbox for the first time after the email domain has been approved. 
+
+Below is an example of the message a user with a matching email domain will see when opening a private Sandbox from a workspace they are not yet part of.
+
+
+![join ws](../images/org-domain-join-ws.png)
+
+
+## Accounts and domains
+CodeSandbox accounts are tied to individual users. They grant access to shared workspaces and organizations, enabling collaboration with other CodeSandbox users.
+
+With a single CodeSandbox account, users can create or join multiple workspaces and organizations to collaborate with various groups of CodeSandbox users; these workspaces and organizations are separate entities, each with a unique set of members and projects.
+
+Since each workspace and organization are their own separate entities, members cannot see the other workspaces or organizations a user belongs to.
+
+
+![graph](../images/org-account-graph.png)

packages/projects-docs/pages/learn/access/workspace.mdx

@@ -10,11 +10,7 @@ import { Callout } from 'nextra-theme-docs'
 
 # Workspaces
 
-![Workspaces](../images/workspace-selector.png)
-
-CodeSandbox uses **Workspaces** to provide boundaries for collaboration on CodeSandbox. [Free workspaces](#free-workspace) are available to all users for public development work. [Pro workspaces](#pro-workspace), on the other hand, are reserved for any type of work requiring privacy or collaboration with others.
-
-Every sandbox belongs to a workspace, and every branch of a repository has a separate development environment in each workspace. If you are working on something in one workspace and decide to collaborate with users who are in a different workspace, it may be necessary to transfer (in the case of a sandbox) or re-import (in the case of a repository) into a workspace that your workspace members have access to.
+A workspace provides a collaborative space where members can work on various projects. Members of a workspace that is part of an organization will also be members of the organization. Each workspace may have a unique list of members who may have different roles and permissions.
 
 ## Getting started with workspaces
 

packages/projects-docs/pages/learn/images/org-account-graph.png

@@ -1,4 +1,5 @@
 {
   "github-app": "GitHub App",
+  "storybook": "Storybook",
   "tailscale": "Tailscale"
 }

packages/projects-docs/pages/learn/images/org-create.png

@@ -0,0 +1,172 @@
+---
+title: Storybook
+description: Use the Storybook Addon to seamlessly open a story as a sandbox.
+---
+
+import { Callout } from 'nextra-theme-docs'
+import Video from '../../../../../shared-components/Video'
+
+# Storybook Addon
+
+The [@codesandbox/storybook-addon](https://github.com/codesandbox/storybook-addon) allows you to open the code from a story in a Sandbox with the click of a button.
+
+This integration allows you to transform design system documentation into interactive example. We have found this incredibly useful for interactive learning and for sharing bug reproductions.
+
+<Video src="https://assets.codesandbox.io/videos/storybook-add-on.mp4" />
+
+## Connecting Storybook to your workspace
+
+All Sandboxes created from the Storybook addon will be created within the workspace that is listed in the [configuration](#configuration).
+
+Anyone opening a Sandbox from the addon will need to be a part of the workspace in order to access the Sandbox.
+Luckily organization domains make it very easy for new users to join automatically.
+
+If a workspace has an organzation domain, when a new user opens a Sandbox from a Storybook addon, they will be asked to join the workspace if they have an account with an email that matches the domain of the organization.
+
+You can find a step-by-step guide for setting a domain on the [Organization](/learn/access/organizations#creating-an-organization) documentation.
+
+## Configuration
+
+```js
+// .storybook/main.js
+
+module.exports = {
+  // ...
+  addons: ['@codesandbox/storybook-addon'],
+};
+
+```
+
+<details>
+  <summary>Storybook configuration (required)</summary>
+
+<br />
+
+To run the addon, you'll need to configure it in your Storybook's `.storybook/preview.js` file.
+
+```js
+// .storybook/preview.js
+
+const preview: Preview = {
+  parameters: {
+    codesandbox: {
+      /**
+       * @required
+       * Workspace API key from codesandbox.io/t/permissions.
+       * This sandbox is created inside the given workspace
+       * and can be shared with team members.
+       */
+      apiToken: <api-token>,
+
+      /**
+       * @required
+       * Dependencies list to be installed in the sandbox.
+       *
+       * @note You cannot use local modules or packages since
+       * this story runs in an isolated environment (sandbox)
+       * inside CodeSandbox. As such, the sandbox doesn't have
+       * access to your file system.
+       *
+       * Example:
+       */
+      dependencies: {
+        "@radix-ui/themes": "latest",
+        "@myscope/mypackage": "1.0.0",
+      },
+
+      /**
+       * @required
+       * CodeSandbox will try to import all components by default from
+       * the given package, in case `mapComponent` property is not provided.
+       *
+       * This property is useful when your components imports are predictable
+       * and come from a single package and entry point.
+       */
+      fallbackImport: "@radix-ui/themes",
+
+      /**
+       * @optional
+       * All required providers to run the sandbox properly,
+       * such as themes, i18n, store, and so on.
+       *
+       * @note Remember to use only the dependencies listed above.
+       *
+       * Example:
+       */
+      provider: `import { Theme } from "@radix-ui/themes";
+        import '@radix-ui/themes/styles.css';
+
+        export default ThemeProvider = ({ children }) => {
+          return (
+            <Theme>
+              {children}
+            </Theme>
+          )
+        }`,
+    },
+  },
+};
+
+export default preview;
+```
+
+</details>
+
+<details>
+  <summary>Story configuration (recommended)</summary>
+
+````ts
+import type { Meta, StoryObj } from "@storybook/react";
+
+const meta: Meta<typeof Button> = {
+  title: "Example/Button",
+  component: Button,
+  parameters: {
+    codesandbox: {
+     /**
+       * To import all components used within each story in
+       * CodeSandbox, provide all necessary packages and modules.
+       *
+       * Given the following story:
+       * ```js
+       * import Provider from "@myscope/mypackage";
+       * import { Button } from "@radix-ui/themes";
+       * import "@radix-ui/themes/styles.css";
+       * ```
+       *
+       * You need to map all imports to the following:
+       */
+      mapComponent: {
+        // Example of default imports
+        "@myscope/mypackage": "Provider",
+
+        // Example of named functions
+        "@radix-ui/themes": ["Button"],
+
+        // Example of static imports
+        "@radix-ui/themes/styles.css": true,
+      },
+
+      /**
+       * @note You cannot use local modules or packages since
+       * this story runs in an isolated environment (sandbox)
+       * inside CodeSandbox. As such, the sandbox doesn't have
+       * access to your file system.
+       */
+    },
+  },
+};
+````
+
+</details>
+
+<br />
+
+Make sure to provide the necessary values for [`apiToken`](https://codesandbox.io/t/permissions) and any additional dependencies or providers required for your specific setup.
+
+For now, this addon only supports the [Component Story Format (CSF)](https://storybook.js.org/docs/api/csf) stories format.
+
+### Additional Notes
+
+- Ensure that you have proper permissions and access rights to the CodeSandbox workspace specified in the configuration.
+- Verify the correctness of the dependencies and providers listed in the configuration to ensure the sandbox runs smoothly.