Added a bunch of comments and some READMEs

lib/preview-web/README.md

@@ -1,3 +1,19 @@
-# Web Preview
+# Preview (Web)
 
-TODO
+This is the main API for the (web) version of the Storybook Preview.
+
+The preview's job is:
+
+1. Read and update the URL (via the URL Store)
+
+2. Listen to instructions on the channel and emit events as things occur.
+
+3. Render the current selection to the web view in either story or docs mode.
+
+## V7 Store vs Legacy (V6)
+
+The story store is designed to load stories 'on demand', and will operate in this fashion if the `storyStoreV7` feature is enabled.
+
+However, for back-compat reasons, in v6 mode, we need to load all stories, synchronously on bootup, emitting the `SET_STORIES` event.
+
+In V7 mode we do not emit that event, instead preferring the `STORY_PREPARED` event.

lib/preview-web/src/PreviewWeb.tsx

@@ -95,6 +95,8 @@ export class PreviewWeb<TFramework extends AnyFramework> {
     await this.setupListenersAndRenderSelection();
   }
 
+  // We have a second "sync" code path through `initialize` for back-compat reasons.
+  // Specifically Storyshots requires the story store to be syncronously loaded completely on bootup
   initializeSync({ cacheAllCSFFiles = false }: { cacheAllCSFFiles?: boolean } = {}) {
     this.storyStore.initializeSync({ cacheAllCSFFiles });
     // NOTE: we don't await this, but return the promise so the caller can await it if they want
@@ -129,7 +131,7 @@ export class PreviewWeb<TFramework extends AnyFramework> {
     this.channel.on(Events.RESET_STORY_ARGS, this.onResetArgs.bind(this));
   }
 
-  // Use the selection specifier to choose a story
+  // Use the selection specifier to choose a story, then render it
   async selectSpecifiedStory() {
     if (!this.urlStore.selectionSpecifier) {
       this.renderMissingStory();
@@ -346,8 +348,8 @@ export class PreviewWeb<TFramework extends AnyFramework> {
     return this.renderStoryToElement({ story, renderContext, element });
   }
 
-  // We want this function to be called directly by `renderSelection` above,
-  // but also by the `<ModernStory>` docs component
+  // Render a story into a given element and watch for the events that would trigger us
+  // to re-render it (plus deal sensibly with things like changing story mid-way through).
   renderStoryToElement({
     story,
     renderContext: renderContextWithoutStoryContext,

lib/store/README.md

@@ -1,3 +1,122 @@
 # Storybook Store
 
-TODO
+The store is reponsible for loading a story from a CSF file and preparing into a `Story` type, which is our internal format.
+
+## Story vs StoryContext
+
+Story functions and decorators recieve a `StoryContext<Framework>` object (parameterized by their framework).
+
+The `Story` type that we pass around in our code includes all of those fields apart from the `args`, `globals`, `hooks` and `viewMode`, which are mutable and stored separately in the store.
+
+## Identification
+
+The first set of fields on a `Story` are the identifying fields for a story:
+
+- `componentId` - the URL "id" of the component
+- `title` - the title of the component, which generates the sidebar entry
+- `id` - the story "id" (in the URL)
+- `name` - the name of the story
+
+## Annotations
+
+The main fields on a `Story` are the various annotations. Annotations can be set:
+
+- At the project level in `preview.js` (or via addons)
+- At the component level via `export default = { ... }` in a CSF file
+- At the story level via `export Story = {...}` in a CSF file.
+
+Not all annotations can be set at every level but most can.
+
+## Parameters
+
+The story parameters is a static, serializable object of data that provides details about the story. Those details can be used by addons or Storybook itself to render UI or provide defaults about the story rendering.
+
+Parameters _cannot change_ and are synchronized to the manager once when the story is loaded (note over the lifetime of a development Storybook a story can be loaded several times due to hot module reload, so the parameters technically can change for that reason).
+
+Usually addons will read from a single key of `parameters` namespaced by the name of that addon. For instance the configuration of the `backgrounds` addon is driven by the `parameters.backgrounds` namespace.
+
+Parameters are inheritable -- you can set project parameters via `export parameters = {}`, at the component level by the `parameters` key of the component (default) export in CSF, and on a single story via the `parameters` key on the story data.
+
+Some notable parameters:
+
+- `parameters.fileName` - the file that the story was defined in, when available
+
+## Args
+
+Args are "inputs" to stories.
+
+You can think of them equivalently to React props, Angular inputs and outputs, etc.
+
+Changing the args cause the story to be re-rendered with the new set of args.
+
+### Using args in a story
+
+By default (starting in 6.0) the args will be passed to the story as first argument and the context as second:
+
+```js
+const YourStory = ({ x, y } /*, context*/) => /* render your story using `x` and `y` */
+```
+
+If you set the `parameters.options.passArgsFirst` option on a story to false, args are passed to a story in the context, preserving the pre-6.0 story API; like parameters, they are available as `context.args`.
+
+```js
+const YourStory = ({ args: { x, y }}) => /* render your story using `x` and `y` */
+```
+
+### Arg types and values
+
+Arg types are used by the docs addon to populate the props table and are documented there. They are controlled by `argTypes` and can (sometimes) be automatically inferred from type information about the story or the component rendered by the story.
+
+A story can set initial values of its args with the `args` annotation. If you set an initial value for an arg that doesn't have a type a simple type will be inferred from the value.
+
+If an arg doesn't have an initial value, it will start unset, although it can still be set later via user interaction.
+
+Args can be set at the project, component and story level.
+
+### Using args in an addon
+
+Args values are automatically synchronized (via the `changeStoryArgs` and `storyArgsChanged` events) between the preview and manager; APIs exist in `lib/api` to read and set args in the manager.
+
+Args need to be serializable -- so currently cannot include callbacks (this may change in a future version).
+
+Note that arg values are passed directly to a story -- you should only store the actual value that the story needs to render in the arg. If you need more complex information supporting that, use parameters or addon state.
+
+Both `@storybook/client-api` (preview) and `@storybook/api` (manager) export a `useArgs()` hook that you can use to access args in decorators or addon panels. The API is as follows:
+
+```js
+import { useArgs } from '@storybook/client-api'; // or '@storybook/api'
+
+// `args` is the args of the currently rendered story
+// `updateArgs` will update its args. You can pass a subset of the args; other args will not be changed.
+const [args, updateArgs] = useArgs();
+```
+
+## ArgTypes
+
+Arg types add type information and metadata about args that are used to control the docs and controls addons.
+
+### ArgTypes enhancement
+
+To add a argTypes enhancer, `export addArgTypesEnhancers = []` from `preview.js` or and addon
+
+There is a default enhancer that ensures that each `arg` in a story has a baseline `argType`. This value can be improved by subsequent enhancers, e.g. those provided by `@storybook/addon-docs`.
+
+## Globals
+
+Globals are rendering information that is global across stories. They are used for things like themes and internationalization (i18n) in stories, where you want Storybook to "remember" your setting as you browse between stories.
+
+They can be access in stories and decorators in the `context.globals` key.
+
+### Initial values of globals
+
+To set initial values of globals, `export globals = {...}` from `preview.js`
+
+### Using globals in an addon
+
+Similar to args, globals are synchronized to the manager and can be accessed via the `useGlobals` hook.
+
+```js
+import { useGlobals } from '@storybook/addons'; // or '@storybook/api'
+
+const [globals, updateGlobals] = useGlobals();
+```

lib/store/src/StoryStore.ts

@@ -94,6 +94,9 @@ export class StoryStore<TFramework extends AnyFramework> {
     this.args = new ArgsStore();
     this.hooks = {};
 
+    // We use a cache for these two functions for two reasons:
+    //  1. For performance
+    //  2. To ensure that when the same story is prepared with the same inputs you get the same output
     this.processCSFFileWithCache = memoize(CSF_CACHE_SIZE)(processCSFFile) as typeof processCSFFile;
     this.prepareStoryWithCache = memoize(STORY_CACHE_SIZE)(prepareStory) as typeof prepareStory;
   }
@@ -106,6 +109,7 @@ export class StoryStore<TFramework extends AnyFramework> {
     }
   }
 
+  // See note in PreviewWeb about the 'sync' init path.
   initializeSync({ cacheAllCSFFiles = false }: { cacheAllCSFFiles?: boolean } = {}) {
     this.storyIndex.initializeSync();
 
@@ -120,6 +124,7 @@ export class StoryStore<TFramework extends AnyFramework> {
     this.globals.resetOnProjectAnnotationsChange({ globals, globalTypes });
   }
 
+  // This means that one of the CSF functions has changed.
   async onImportFnChanged({ importFn }: { importFn: ModuleImportFn }) {
     this.importFn = importFn;
 
@@ -131,9 +136,11 @@ export class StoryStore<TFramework extends AnyFramework> {
     }
   }
 
+  // To load a single CSF file to service a story we need to look up the importPath in the index
   async loadCSFFileByStoryId(storyId: StoryId): Promise<CSFFile<TFramework>> {
     const { importPath, title } = this.storyIndex.storyIdToEntry(storyId);
     const moduleExports = await this.importFn(importPath);
+    // We pass the title in here as it may have been generated by autoTitle on the server.
     return this.processCSFFileWithCache(moduleExports, title);
   }
 
@@ -148,6 +155,7 @@ export class StoryStore<TFramework extends AnyFramework> {
     return this.processCSFFileWithCache(moduleExports as ModuleExports, title);
   }
 
+  // Load all CSF files into the cache so we can call synchronous functions like `extract()`.
   async loadAllCSFFiles(): Promise<Record<Path, CSFFile<TFramework>>> {
     const importPaths: Record<Path, StoryId> = {};
     Object.entries(this.storyIndex.stories).forEach(([storyId, { importPath }]) => {
@@ -194,11 +202,14 @@ export class StoryStore<TFramework extends AnyFramework> {
     this.cachedCSFFiles = this.loadAllCSFFilesSync();
   }
 
+  // Load the CSF file for a story and prepare the story from it and the project annotations.
   async loadStory({ storyId }: { storyId: StoryId }): Promise<Story<TFramework>> {
     const csfFile = await this.loadCSFFileByStoryId(storyId);
     return this.storyFromCSFFile({ storyId, csfFile });
   }
 
+  // This function is synchronous for convenience -- often times if you have a CSF file already
+  // it is easier not to have to await `loadStory`.
   storyFromCSFFile({
     storyId,
     csfFile,
@@ -222,12 +233,15 @@ export class StoryStore<TFramework extends AnyFramework> {
     return story;
   }
 
+  // If we have a CSF file we can get all the stories from it synchronously
   componentStoriesFromCSFFile({ csfFile }: { csfFile: CSFFile<TFramework> }): Story<TFramework>[] {
     return Object.keys(csfFile.stories).map((storyId: StoryId) =>
       this.storyFromCSFFile({ storyId, csfFile })
     );
   }
 
+  // A prepared story does not include args, globals or hooks. These are stored in the story store
+  // and updated separtely to the (immutable) story.
   getStoryContext(story: Story<TFramework>): Omit<StoryContextForLoaders<TFramework>, 'viewMode'> {
     return {
       ...story,