feat: add per story description, supports markdown

ccontrols · Apr 30, 2020 · 578d820 · 578d820
1 parent b9817bd
commit 578d820
Show file tree

Hide file tree

Showing 14 changed files with 94 additions and 80 deletions.
diff --git a/core/config/README.md b/core/config/README.md
@@ -51,7 +51,7 @@ _defined in [@component-controls/config/src/index.ts](https://github.com/ccontro
 find the story files out of a configuration file
 using glob for the regex file search
 
-_defined in [@component-controls/config/src/index.ts](https://github.com/ccontrols/component-controls/tree/master/core/config/src/index.ts#L56)_
+_defined in [@component-controls/config/src/index.ts](https://github.com/ccontrols/component-controls/tree/master/core/config/src/index.ts#L53)_
 
 **function** extractStories(`__namedParameters`\*: **config**: [Configuration](#configuration)**configPath**: string): string\[] | undefined;
 

diff --git a/core/specification/README.md b/core/specification/README.md
@@ -108,7 +108,7 @@ _defined in [@component-controls/specification/src/stories.ts](https://github.co
 
 map of stories. The id is compatible with CSF story ids
 
-_defined in [@component-controls/specification/src/stories.ts](https://github.com/ccontrols/component-controls/tree/master/core/specification/src/stories.ts#L137)_
+_defined in [@component-controls/specification/src/stories.ts](https://github.com/ccontrols/component-controls/tree/master/core/specification/src/stories.ts#L142)_
 
 `id`\*: string: [Story](#story)
 
@@ -118,7 +118,7 @@ a group of stories. Usually multiple stories are in one  csf file
 and the 'group' is the default export
 in the case of MDX stories, the kind is crated using a &lt;Meta /> tag
 
-_defined in [@component-controls/specification/src/stories.ts](https://github.com/ccontrols/component-controls/tree/master/core/specification/src/stories.ts#L146)_
+_defined in [@component-controls/specification/src/stories.ts](https://github.com/ccontrols/component-controls/tree/master/core/specification/src/stories.ts#L151)_
 
 `name`\*: string: any
 
@@ -145,7 +145,7 @@ _defined in [@component-controls/specification/src/stories.ts](https://github.co
 
 store of stories information in memory after the loader is applied
 
-_defined in [@component-controls/specification/src/stories.ts](https://github.com/ccontrols/component-controls/tree/master/core/specification/src/stories.ts#L255)_
+_defined in [@component-controls/specification/src/stories.ts](https://github.com/ccontrols/component-controls/tree/master/core/specification/src/stories.ts#L260)_
 
 
 
@@ -173,6 +173,7 @@ _defined in [@component-controls/specification/src/stories.ts](https://github.co
 | `component`     | string \| object                        | id for component associated with the story                                                  |
 | `controls`      | [ComponentControls](#componentcontrols) | object of key/value pairs specifying the controls for the story                             |
 | `decorators`    | [StoryRenderFn](#storyrenderfn)\[]      | story decorators (or wrappers)                                                              |
+| `description`   | string                                  | story extended description. can use markdown.                                               |
 | `id`            | string                                  | csf id of the story                                                                         |
 | `kind`          | string                                  | title of the file/group of stories                                                          |
 | `loc`           | [CodeLocation](#codelocation)           | location in the source file of the story definition                                         |
@@ -204,15 +205,15 @@ _defined in [@component-controls/specification/src/stories.ts](https://github.co
 
 list of components used in stories
 
-_defined in [@component-controls/specification/src/stories.ts](https://github.com/ccontrols/component-controls/tree/master/core/specification/src/stories.ts#L234)_
+_defined in [@component-controls/specification/src/stories.ts](https://github.com/ccontrols/component-controls/tree/master/core/specification/src/stories.ts#L239)_
 
 `fileName`\*: string: [StoryComponent](#storycomponent)
 
 ## StoryKinds
 
 list of story files, or groups
 
-_defined in [@component-controls/specification/src/stories.ts](https://github.com/ccontrols/component-controls/tree/master/core/specification/src/stories.ts#L241)_
+_defined in [@component-controls/specification/src/stories.ts](https://github.com/ccontrols/component-controls/tree/master/core/specification/src/stories.ts#L246)_
 
 `title`\*: string: [StoriesKind](#storieskind)
 
@@ -229,7 +230,7 @@ _defined in [@component-controls/specification/src/stories.ts](https://github.co
 
 list of stories
 
-_defined in [@component-controls/specification/src/stories.ts](https://github.com/ccontrols/component-controls/tree/master/core/specification/src/stories.ts#L248)_
+_defined in [@component-controls/specification/src/stories.ts](https://github.com/ccontrols/component-controls/tree/master/core/specification/src/stories.ts#L253)_
 
 `id`\*: string: [Story](#story)
 

diff --git a/core/specification/src/stories.ts b/core/specification/src/stories.ts
@@ -84,11 +84,16 @@ export interface Story {
    * render function for the story
    */
   renderFn?: StoryRenderFn;
+
+  /**
+   * story extended description. can use markdown.
+   */
+  description?: string;
+
   /**
    * arguments pass to a CSF story
    * eg `export const story = props => <Story {...props} />;`
    */
-
   arguments?: StoryArguments;
   /**
    * configuration parameters passed to the story - either CSF or MDX

diff --git a/examples/stories/src/stories/controls-editors-starter.stories.tsx b/examples/stories/src/stories/controls-editors-starter.stories.tsx
@@ -21,6 +21,9 @@ export const overview = ({ name, age }: DocsControlsTable) => {
 };
 
 overview.story = {
+  description:
+    'Story with two dynamic control values: `name` and `age`. You can use the controls to edit the story properties at run-time.',
+
   controls: {
     name: { type: ControlTypes.TEXT, label: 'Name', value: 'Mark' },
     age: {

diff --git a/examples/stories/src/stories/controls-editors.stories.js b/examples/stories/src/stories/controls-editors.stories.js
@@ -8,6 +8,7 @@ export default {
 
 export const textDefaultProp = ({ text }) => text;
 textDefaultProp.story = {
+  description: 'A simple story that just returns the text parameter',
   controls: {
     text: { type: ControlTypes.TEXT, value: 'Hello' },
   },
@@ -26,6 +27,8 @@ selectProp.defaultProps = {
 };
 
 selectProp.story = {
+  description:
+    'Story that shocases the `ControlTypes.OPTIONS` setting, using a `<Select />` component',
   controls: {
     value: {
       type: ControlTypes.OPTIONS,
@@ -122,6 +125,7 @@ const GROUP_IDS = {
 };
 
 tweaksStaticValues.story = {
+  description: 'Complex story with a variety of control types.',
   controls: {
     userName: {
       type: ControlTypes.TEXT,
@@ -253,6 +257,7 @@ dynamicProps.propTypes = {
 };
 
 dynamicProps.story = {
+  description: 'Dynamic control values checked in the story.',
   controls: {
     showOptional: {
       type: ControlTypes.OPTIONS,
@@ -275,6 +280,8 @@ export const complexSelect = ({ m }) => {
 };
 
 complexSelect.story = {
+  description:
+    '`ControlTypes.OPTIONS` control type where the options can have different data-types.',
   controls: {
     m: {
       type: ControlTypes.OPTIONS,
@@ -336,6 +343,8 @@ optionsProperties.propTypes = {
 };
 
 optionsProperties.story = {
+  description:
+    'Showcase `ControlTypes.OPTIONS` controls of types `radio`, `inline-radio`, `select`, `multi-select`, `check` and `inline-check`.',
   controls: {
     optionRadio: {
       type: ControlTypes.OPTIONS,
@@ -405,69 +414,10 @@ optionsProperties.story = {
   },
 };
 
-let injectedItems = [];
-let injectedIsLoading = false;
-
-const ItemLoader = ({ isLoading, items }) => {
-  if (isLoading) {
-    return <p>Loading data</p>;
-  }
-  if (!items.length) {
-    return <p>No items loaded</p>;
-  }
-  return (
-    <ul>
-      {items.map(i => (
-        <li key={i}>{i}</li>
-      ))}
-    </ul>
-  );
-};
-
-ItemLoader.propTypes = {
-  isLoading: PropTypes.bool.isRequired,
-  items: PropTypes.arrayOf(PropTypes.string).isRequired,
-};
-
-export const triggersActionsViaButton = () => {
-  // Needed to enforce @babel/transform-react-constant-elements deoptimization
-  // See https://github.com/babel/babel/issues/10522
-  const loaderProps = {
-    isLoading: injectedIsLoading,
-    items: injectedItems,
-  };
-  return (
-    <>
-      <p>
-        Hit the knob button and it will toggle the items list into multiple
-        states.
-      </p>
-      <ItemLoader {...loaderProps} />
-    </>
-  );
-};
-
-triggersActionsViaButton.story = {
-  controls: {
-    button: {
-      type: ControlTypes.BUTTON,
-      onClick: () => {
-        if (!injectedIsLoading && injectedItems.length === 0) {
-          injectedIsLoading = true;
-        } else if (injectedIsLoading && injectedItems.length === 0) {
-          injectedIsLoading = false;
-          injectedItems = ['pencil', 'pen', 'eraser'];
-        } else if (injectedItems.length > 0) {
-          injectedItems = [];
-        }
-      },
-    },
-  },
-};
-
 export const radioEnum = ({ radio }) => radio;
 
 radioEnum.story = {
+  description: '`ControlTypes.OPTIONS` display: `radio`.',
   controls: {
     radio: {
       type: ControlTypes.OPTIONS,
@@ -483,14 +433,6 @@ radioEnum.story = {
   },
 };
 
-export const reservedKeyword = ({ name }) => name;
-
-reservedKeyword.story = {
-  controls: {
-    name: { type: ControlTypes.TEXT, label: 'Text', value: 'Hello' },
-  },
-};
-
 export const XssSafety = ({ content }) => (
   <div
     // eslint-disable-next-line react/no-danger
@@ -519,6 +461,8 @@ XssSafety.story = {
 export const generateRandomData = ({ street }) => street;
 
 generateRandomData.story = {
+  description:
+    'Story using the `data` field of `controls` to generate **streetAddress** random data.',
   controls: {
     street: {
       type: ControlTypes.TEXT,
@@ -533,6 +477,8 @@ generateRandomData.story = {
 export const randomNumber = ({ number }) => number;
 
 randomNumber.story = {
+  description:
+    'Story using the `data` field of `controls` to generate random **number** with **min/max** parameters.',
   controls: {
     number: {
       type: ControlTypes.NUMBER,
@@ -557,6 +503,7 @@ const personalGroupId = 'personal info';
 const generalGroupId = 'general info';
 
 groupedControls.story = {
+  description: 'Controls grouped in multiple tabs.',
   controls: {
     name: {
       type: ControlTypes.TEXT,