docs: Improve documentation (#964)

.storybook/main.js

@@ -30,6 +30,9 @@ module.exports = {
         {
           loader: path.resolve(__dirname, 'webpack-loader-redirect-mdx-to-github'),
         },
+        {
+          loader: path.resolve(__dirname, 'mdx-code-block-rewrite'),
+        },
       ],
     });
 
@@ -46,6 +49,18 @@ module.exports = {
       enforce: 'pre',
     });
 
+    // Load the whole example code of story files to display in docs.
+    config.module.rules.push({
+      test: /examples\/.*\.tsx?$/,
+      include: [modulesPath],
+      loaders: [
+        {
+          loader: path.resolve(__dirname, 'whole-source-loader'),
+        },
+      ],
+      enforce: 'pre',
+    });
+
     // Load our scss files with postscss.
     // Note: This is the same as @storybook/preset-scss, but with postcss added.
     config.module.rules.push({

.storybook/mdx-code-block-rewrite.js

@@ -0,0 +1,27 @@
+const path = require('path');
+
+// This loader replaces example code blocks with Storybook specific tags
+// before:
+// <ExampleCodeBlock code={MyComponent} />
+// after:
+// <Canvas><Story name="MyComponent" story={MyComponent} parameters={{storySource: { source: MyComponent.__RAW__ }}}
+// __RAW__ comes from the `whole-source-loader
+module.exports = function rewriteExampleCodeBlock(source) {
+  const hasMeta = /import {.*Meta[,\s}]/.test(source);
+  const hasCanvas = /import {.*Canvas[,\s}]/.test(source);
+  const hasStory = /import {.*Story[,\s}]/.test(source);
+  const hasArgsTable = /import {.*ArgsTable[,\s}]/.test(source);
+  const imports = [];
+  if (!hasMeta) imports.push('Meta');
+  if (!hasCanvas) imports.push('Canvas');
+  if (!hasStory) imports.push('Story');
+  if (!hasArgsTable) imports.push('ArgsTable');
+  return (
+    (imports.length ? `import {${imports.join(',')}} from '@storybook/addon-docs/blocks';\n` : '') +
+    source
+      .replace(/\<ExampleCodeBlock code={([A-Za-z0-9]+)} \/\>/g, function replacer(match, p1, p2) {
+        return `<Canvas><Story name="${p1}" parameters={{storySource: {source: ${p1}.__RAW__}}}><${p1} /></Story></Canvas>`;
+      })
+      .replace(/\<PropsTable of=/g, '<ArgsTable of=')
+  );
+};

.storybook/whole-source-loader.js

@@ -0,0 +1,47 @@
+module.exports = function sourceAndPropTypeLoader(/** @type string */ source) {
+  const raw = JSON.stringify(source)
+    .replace(/\u2028/g, '\\u2028')
+    .replace(/\u2029/g, '\\u2029');
+
+  /* This will match the following patterns:
+    export default class Banner
+    export default class Banner<T> {
+    export default Banner = (
+    export default Banner;
+    export default Banner: React.FC<any> =
+    export const Banner = (
+    export const Banner: React.FC =
+    export const Banner;
+    export default function Banner (
+    export default function Banner<T> (
+    export function Banner(
+    export function Banner<T>(
+    export default (
+    It will extract out the export name only if it starts with a capital. In the examples here, that would be
+    "Banner" in all cases except for the last one which would be "Example"
+  */
+  const exportPattern = /export (?:default|const|function)(?: class)?(?: function)? ([^:\s<();]*)/;
+  const exportSet = new Set();
+  source
+    .match(new RegExp(exportPattern, 'g'))
+    .map(match => match.match(exportPattern)[1] || 'Example') // default export name to "Example"
+    .filter(name => name.charAt(0).toUpperCase() === name.charAt(0))
+    .forEach(m => exportSet.add(m));
+  const exports = [...exportSet]; // Make sure export names are unique
+
+  // rewrite out example files so that we can attach the __RAW__ property
+  // This will rewrite this:
+  //  export default () => <div />;
+  // to this:
+  //  const Example = () => <div />;
+  //  export default Example;
+  //  Example.__RAW__ = 'export default () => <div />;';
+  // We do this so that the whole source code can be used in Storybook examples
+  const rewriteExampleSource = source.includes('export default (')
+    ? source.replace('export default (', 'const Example = (') + '\nexport default Example;'
+    : source;
+
+  return `${rewriteExampleSource}
+${exports.map(name => `${name}.__RAW__ = ${raw};`).join('\n')}
+`;
+};

modules/card/react/lib/Card.tsx

@@ -30,7 +30,7 @@ export interface CardProps extends React.HTMLAttributes<HTMLDivElement> {
 
   /**
    * The depth of the Card. Imported from `@workday/canvas-kit-react-core`.
-   * @default depthValues[2]
+   * @default depth[2]
    */
   depth?: CanvasDepthValue;
 

modules/card/react/stories/card.stories.mdx

@@ -1,29 +1,45 @@
-import {Meta, Story, Canvas, ArgsTable} from '@storybook/addon-docs/blocks';
+import {Meta} from '@storybook/addon-docs/blocks';
 
-import {spacing} from '../../../core/react';
-import README from '../README.md';
-import Card from '../index';
+import {Card} from '@workday/canvas-kit-react-card';
+import {Default} from './examples/Default';
+import {WithNoPadding} from './examples/WithNoPadding';
+import {Depth} from './examples/Depth';
 
 <Meta title="Components/Containers/Card/React" component={Card} />
 
-# Card
+# Canvas Kit Card
 
-<Canvas>
-  <Story name="Default">
-    <div className="story">
-      <Card heading="Title">Card contents</Card>
-    </div>
-  </Story>
-</Canvas>
+Generic Canvas Card component
 
-<ArgsTable of={Card} />
+[> Workday Design Reference](https://design.workday.com/components/containers/cards)
+
+## Installation
+
+```sh
+yarn add @workday/canvas-kit-react
+```
+
+or
+
+```sh
+yarn add @workday/canvas-kit-react-card
+```
+
+## Examples
+
+Default Card Example:
 
-## No Padding
+<ExampleCodeBlock code={Default} />
 
-<Canvas>
-  <Story name="With No Padding">
-    <Card heading="Title" padding={spacing.zero}>
-      No Padding
-    </Card>
-  </Story>
-</Canvas>
+If you would like to change the padding:
+
+<ExampleCodeBlock code={WithNoPadding} />
+
+Card also takes `depth` levels, which changes the perceived "height above the canvas" of the card.
+This changes the box shadow surrounding the card. Values are `inset`, or 0-4. Here's an inset cardL:
+
+<ExampleCodeBlock code={Depth} />
+
+## Properties
+
+<ArgsTable of={Card} />

modules/card/react/stories/examples/Default.tsx

@@ -0,0 +1,6 @@
+import React from 'react';
+import {Card} from '@workday/canvas-kit-react-card';
+
+export const Default = () => {
+  return <Card heading="Title">Card contents</Card>;
+};

modules/card/react/stories/examples/Depth.tsx

@@ -0,0 +1,11 @@
+import React from 'react';
+import {Card} from '@workday/canvas-kit-react-card';
+import {depth} from '@workday/canvas-kit-react-core';
+
+export const Depth = () => {
+  return (
+    <Card heading="Title" depth={depth.inset}>
+      No Padding
+    </Card>
+  );
+};

modules/card/react/stories/examples/WithNoPadding.tsx

@@ -0,0 +1,11 @@
+import React from 'react';
+import {Card} from '@workday/canvas-kit-react-card';
+import {spacing} from '@workday/canvas-kit-react-core';
+
+export const WithNoPadding = () => {
+  return (
+    <Card heading="Title" padding={spacing.zero}>
+      No Padding
+    </Card>
+  );
+};