Merge pull request #259 from mongodb/code-example

Author: TheSonOfThomp

components/pages/example/Knob/Knob.styles.ts renamed to components/pages/example/KnobsTable/Knob/Knob.styles.ts

@@ -1,6 +1,6 @@
 import { HTMLElementProps } from '@leafygreen-ui/lib';
 
-import { KnobOptionType, TypeString } from '../types';
+import { KnobOptionType, TypeString } from '../../types';
 
 export interface KnobProps extends HTMLElementProps<'input'> {
   propName: string;

components/pages/example/Knob/Knob.tsx renamed to components/pages/example/KnobsTable/Knob/Knob.tsx

@@ -1,16 +1,18 @@
 import { kebabCase } from 'lodash';
+import { isRequired } from 'utils/tsdoc.utils';
 
 import { css } from '@leafygreen-ui/emotion';
 import { useDarkMode } from '@leafygreen-ui/leafygreen-provider';
 import { HTMLElementProps } from '@leafygreen-ui/lib';
 import { palette } from '@leafygreen-ui/palette';
 import { spacing } from '@leafygreen-ui/tokens';
 import Tooltip from '@leafygreen-ui/tooltip';
-import { Body } from '@leafygreen-ui/typography';
+import { Body, Disclaimer } from '@leafygreen-ui/typography';
 
-import { Knob } from '../Knob/Knob';
 import { KnobType } from '../types';
 
+import { Knob } from './Knob/Knob';
+
 const knobRowWrapperStyle = (darkMode: boolean) => css`
   display: flex;
   width: 100%;
@@ -31,6 +33,13 @@ const knobControlStyle = css`
   justify-content: end;
 `;
 
+const requiredFlagStyle = css`
+  display: inline;
+  padding-left: 1ch;
+  color: ${palette.red.base};
+  text-transform: uppercase;
+`;
+
 interface KnobRowProps extends HTMLElementProps<'div'> {
   knob: KnobType;
   knobValue?: any;
@@ -66,6 +75,9 @@ export const KnobRow = ({ knob, knobValue, setKnobValue }: KnobRowProps) => {
           id={`${kebabCase()}-knob-${name}`}
         >
           <strong>{name}</strong>
+          {isRequired(knob) && (
+            <Disclaimer className={requiredFlagStyle}>(required)</Disclaimer>
+          )}
         </Body>
       </div>
       {args?.disabled && args?.description ? (

components/pages/example/Knob/RawKnob.tsx renamed to components/pages/example/KnobsTable/Knob/RawKnob.tsx

@@ -0,0 +1,10 @@
+import { css } from '@leafygreen-ui/emotion';
+
+export const exampleCodeButtonRowStyle = css`
+  text-align: right;
+  padding: 16px 24px;
+`;
+
+export const exampleCodeButtonStyle = css`
+  white-space: nowrap;
+`;

components/pages/example/Knob/types.ts renamed to components/pages/example/KnobsTable/Knob/types.ts

@@ -0,0 +1,61 @@
+import { MouseEventHandler } from 'react';
+
+import Button from '@leafygreen-ui/button';
+import Icon from '@leafygreen-ui/icon';
+
+import {
+  LiveExampleContext,
+  LiveExampleStateReturnValue,
+} from '../useLiveExampleState';
+
+import { KnobRow } from './KnobRow';
+import {
+  exampleCodeButtonRowStyle,
+  exampleCodeButtonStyle,
+} from './KnobsTable.styles';
+
+interface KnobsTableProps {
+  showCode: boolean;
+  codeExampleEnabled: boolean;
+  handleShowCodeClick: MouseEventHandler;
+  knobsArray: Required<LiveExampleContext>['knobsArray'];
+  knobValues: Required<LiveExampleContext>['knobValues'];
+  updateKnobValue: LiveExampleStateReturnValue['updateKnobValue'];
+}
+
+export const KnobsTable = ({
+  showCode,
+  codeExampleEnabled,
+  handleShowCodeClick,
+  knobsArray,
+  knobValues,
+  updateKnobValue,
+}: KnobsTableProps) => {
+  return (
+    <div id="knobs">
+      {codeExampleEnabled && (
+        <div className={exampleCodeButtonRowStyle}>
+          <Button
+            className={exampleCodeButtonStyle}
+            variant="default"
+            size="xsmall"
+            onClick={handleShowCodeClick}
+            leftGlyph={
+              <Icon glyph={showCode ? 'VisibilityOff' : 'Visibility'} />
+            }
+          >
+            {showCode ? 'Hide' : 'Show'} Code
+          </Button>
+        </div>
+      )}
+      {knobsArray.map(knob => (
+        <KnobRow
+          key={knob.name}
+          knob={knob}
+          knobValue={knobValues?.[knob.name]}
+          setKnobValue={updateKnobValue}
+        />
+      ))}
+    </div>
+  );
+};

components/pages/example/KnobRow/KnobRow.tsx renamed to components/pages/example/KnobsTable/KnobRow.tsx

@@ -85,12 +85,3 @@ export const codeStyle = css`
   height: 100%;
   overflow: auto;
 `;
-
-export const exampleCodeButtonRowStyle = css`
-  text-align: right;
-  padding: 16px 24px;
-`;
-
-export const exampleCodeButtonStyle = css`
-  white-space: nowrap;
-`;

components/pages/example/KnobsTable/KnobsTable.styles.ts

@@ -1,24 +1,18 @@
 import { useEffect, useRef, useState } from 'react';
 import { CustomComponentDoc } from 'utils/tsdoc.utils';
 
-import Button from '@leafygreen-ui/button';
 import Card from '@leafygreen-ui/card';
 import { css, cx } from '@leafygreen-ui/emotion';
 import { usePrevious } from '@leafygreen-ui/hooks';
 import LeafyGreenProvider, {
   useDarkMode,
 } from '@leafygreen-ui/leafygreen-provider';
 
-import { KnobRow } from './KnobRow/KnobRow';
-import {
-  assertCompleteContext,
-  isStateReady,
-} from './useLiveExampleState/utils';
+import { KnobsTable } from './KnobsTable/KnobsTable';
+import { isStateReady } from './useLiveExampleState/utils';
 import { CodeExample } from './CodeExample';
 import {
   blockContainerStyle,
-  exampleCodeButtonRowStyle,
-  exampleCodeButtonStyle,
   liveExampleWrapperStyle,
   storyContainerStyle,
 } from './LiveExample.styles';
@@ -28,8 +22,8 @@ import {
   LiveExampleLoading,
   LiveExampleNotFound,
 } from './LiveExampleStateComponents';
-import { LiveExampleContext, useLiveExampleState } from './useLiveExampleState';
-import { getStoryCode } from './utils';
+import { useLiveExampleState } from './useLiveExampleState';
+import { useStoryCode } from './useStoryCode';
 
 // Use standard block flow for these packages
 const useBlockWrapperFor = [
@@ -50,7 +44,6 @@ export const LiveExample = ({
 }) => {
   const prevComponentName = usePrevious(componentName);
   const [showCode, setShowCode] = useState(false);
-  const [storyCode, setCode] = useState('No code found');
   const storyContainerRef = useRef<HTMLDivElement>(null);
   const storyWrapperRef = useRef<HTMLDivElement>(null);
 
@@ -72,23 +65,11 @@ export const LiveExample = ({
     }
   }, [componentName, prevComponentName, tsDoc, resetContext, setErrorState]);
 
-  /** Re-generates story example code from context */
-  const regenerateStoryCode = (context: Partial<LiveExampleContext>) => {
-    const code = assertCompleteContext(context)
-      ? getStoryCode(context) ?? 'No code found'
-      : 'No code found';
-    setCode(code);
-  };
-
-  /** re-generate example code when the context changes */
-  useEffect(() => {
-    regenerateStoryCode(context);
-  }, [context]);
+  const storyCode = useStoryCode(context, showCode);
 
   /** Triggered on button click */
-  const handleShowCodeClick = () => {
+  const toggleShowCode = () => {
     setShowCode(sc => !sc);
-    regenerateStoryCode(context);
   };
 
   const storyWrapperStyle = context.meta?.parameters?.wrapperStyle;
@@ -104,6 +85,8 @@ export const LiveExample = ({
   // should match the total height of the story container
   const exampleCodeHeight = storyContainerHeight + 48;
 
+  const codeExampleEnabled = !disableCodeExampleFor.includes(componentName);
+
   return (
     <LeafyGreenProvider darkMode={darkMode}>
       <Card
@@ -141,37 +124,24 @@ export const LiveExample = ({
               <LiveExampleError message={context.errorMessage} />
             )}
           </div>
-          {!disableCodeExampleFor.includes(componentName) && (
+          {codeExampleEnabled && (
             <CodeExample
               showCode={showCode}
               code={storyCode}
               height={exampleCodeHeight}
             />
           )}
         </div>
-        <div id="knobs">
-          {!disableCodeExampleFor.includes(componentName) && (
-            <div className={exampleCodeButtonRowStyle}>
-              <Button
-                className={exampleCodeButtonStyle}
-                variant="default"
-                size="xsmall"
-                onClick={handleShowCodeClick}
-              >
-                {showCode ? 'Hide' : 'Show'} Code
-              </Button>
-            </div>
-          )}
-          {isStateReady(context) &&
-            context.knobsArray.map(knob => (
-              <KnobRow
-                key={knob.name}
-                knob={knob}
-                knobValue={context.knobValues?.[knob.name]}
-                setKnobValue={updateKnobValue}
-              />
-            ))}
-        </div>
+        {isStateReady(context) && (
+          <KnobsTable
+            showCode={showCode}
+            codeExampleEnabled={codeExampleEnabled}
+            handleShowCodeClick={toggleShowCode}
+            knobsArray={context.knobsArray}
+            knobValues={context.knobValues}
+            updateKnobValue={updateKnobValue}
+          />
+        )}
       </Card>
     </LeafyGreenProvider>
   );

components/pages/example/KnobsTable/KnobsTable.tsx

@@ -19,7 +19,7 @@ export interface LiveExampleContext {
   componentName?: string;
   tsDoc?: Array<CustomComponentDoc> | null;
   meta?: Meta<any>;
-  StoryFn?: ComponentStoryFn<any>;
+  StoryFn?: ComponentStoryFn<any> & React.FunctionComponent<any>;
   knobValues?: { [arg: string]: any };
   knobsArray?: Array<KnobType>;
   errorMessage?: string;
@@ -51,3 +51,11 @@ export type LiveExampleAction =
       type: LiveExampleActionType.NOT_FOUND;
       componentName: string;
     };
+
+export interface LiveExampleStateReturnValue {
+  context: LiveExampleContext;
+  updateKnobValue: (prop: string, val: any) => void;
+  resetContext: (name: string, tsDoc: Array<CustomComponentDoc>) => void;
+  setErrorState: (msg: string) => void;
+  isState: (state: LiveExampleState) => boolean;
+}

components/pages/example/LiveExample.styles.ts

@@ -1,2 +1,5 @@
-export type { LiveExampleContext } from './LiveExampleState.types';
+export type {
+  LiveExampleContext,
+  LiveExampleStateReturnValue,
+} from './LiveExampleState.types';
 export { useLiveExampleState } from './useLiveExampleState';

components/pages/example/LiveExample.tsx

@@ -1,5 +1,6 @@
 import { useReducer } from 'react';
 import { kebabCase, merge } from 'lodash';
+import pascalcase from 'pascalcase';
 import { getComponentStories, ModuleType } from 'utils/getComponentStories';
 import { CustomComponentDoc } from 'utils/tsdoc.utils';
 
@@ -14,14 +15,15 @@ import {
 import {
   LiveExampleActionType,
   LiveExampleState,
+  LiveExampleStateReturnValue,
 } from './LiveExampleState.types';
 import { liveExampleStateReducer } from './LiveExampleStateReducer';
 import { assertContext, defaultLiveExampleContext } from './utils';
 
 export function useLiveExampleState(
   componentName: string,
   tsDoc?: Array<CustomComponentDoc> | null,
-) {
+): LiveExampleStateReturnValue {
   const initialState = merge(
     { componentName, tsDoc },
     defaultLiveExampleContext,
@@ -51,6 +53,7 @@ export function useLiveExampleState(
     });
   }
 
+  /** Log an error */
   function setErrorState(message: string) {
     dispatch({
       type: LiveExampleActionType.ERROR,
@@ -70,6 +73,7 @@ export function useLiveExampleState(
   function parse(module: ModuleType) {
     const { default: meta, ...stories } = module;
     const StoryFn = getDefaultStoryFn(meta, stories);
+    StoryFn.displayName = pascalcase(componentName) + 'Story';
 
     if (assertContext(context, ['state', 'componentName', 'tsDoc'])) {
       const knobsArray = getKnobsArray({

components/pages/example/useLiveExampleState/LiveExampleState.types.ts

@@ -0,0 +1,23 @@
+import { useEffect, useState } from 'react';
+
+import { isStateReady } from './useLiveExampleState/utils';
+import { getStoryCode } from './utils/getStoryCode';
+import { LiveExampleContext } from './useLiveExampleState';
+
+const emptyStateCode = 'No code found';
+
+export const useStoryCode = (
+  context: LiveExampleContext,
+  showCode: boolean,
+) => {
+  const [storyCode, setCode] = useState(emptyStateCode);
+
+  useEffect(() => {
+    if (showCode && isStateReady(context)) {
+      const code = getStoryCode(context) ?? emptyStateCode;
+      setCode(code);
+    }
+  }, [context, showCode]);
+
+  return storyCode;
+};