docs: storybook upgrade & renovation

.storybook/main.js

@@ -30,6 +30,18 @@ module.exports = {
     // https://storybook.js.org/docs/react/configure/overview#configure-story-loading
     stories: isTesting
         ? ['../packages/*/src/**/*.stories.e2e.@(js|jsx)']
-        : ['../packages/*/src/**/*.stories.@(js|jsx)'],
-    addons: ['@storybook/preset-create-react-app', 'storybook-addon-jsx'],
+        : [
+              '../docs/**/*.stories.mdx',
+              '../packages/*/src/**/*.stories.@(js|jsx)',
+          ],
+    addons: [
+        '@storybook/preset-create-react-app',
+        '@storybook/addon-essentials',
+        {
+            name: '@storybook/addon-storysource',
+            options: { loaderOptions: { injectDecorator: false } },
+        },
+        'storybook-addon-jsx',
+        '@storybook/addon-a11y',
+    ],
 }

.storybook/manager-head.html

@@ -0,0 +1,13 @@
+<!-- these assets are loaded by adding the `-s .storybook/static` flag 
+    to the run script -->
+<link rel="shortcut icon" href="favicon.ico" type="image/x-icon" />
+<link
+    rel="icon"
+    type="image/png"
+    href="dhis2-icon-rgb-positive.png"
+    sizes="192x192"
+/>
+
+<!-- Stylesheet to theme storybook UI (stylesheet for docs is linked in preview-head.html) -->
+<!-- https://storybook.js.org/docs/react/configure/theming#css-escape-hatches -->
+<link rel="stylesheet" href="manager.css" />

.storybook/manager.js

@@ -0,0 +1,6 @@
+import { addons } from '@storybook/addons'
+import theme from './theme'
+
+addons.setConfig({
+    theme: theme
+})

.storybook/preview-head.html

@@ -0,0 +1,3 @@
+<!-- This stylesheet applies to pages in the docs tab -->
+<!-- https://storybook.js.org/docs/react/configure/theming#css-escape-hatches -->
+<link rel="stylesheet" href="preview.css" />

.storybook/preview.js

@@ -2,6 +2,16 @@ import '@fontsource/roboto/latin.css'
 import React, { Fragment } from 'react'
 import { jsxDecorator } from 'storybook-addon-jsx'
 import { addDecorator, addParameters } from '@storybook/react'
+import '@storybook/addon-console'
+import {
+    Title,
+    Subtitle,
+    Description,
+    Primary,
+    ArgsTable,
+    Stories,
+    PRIMARY_STORY,
+} from '@storybook/addon-docs/blocks'
 import { CssReset } from '@dhis2/ui-core'
 
 // Enable storybook jsx visualization
@@ -32,16 +42,51 @@ addDecorator(Component => (
     </Fragment>
 ))
 
-/**
- * Sort all our stories alphabetically
- *
- * See: https://storybook.js.org/docs/configurations/options-parameter/#sorting-stories
- */
 addParameters({
     options: {
-        storySort: (a, b) =>
-            a[1].kind === b[1].kind
-            ? 0
-            : a[1].id.localeCompare(b[1].id, undefined, { numeric: true }),
+        storySort: {
+            // Manually sort top content
+            order: [
+                'About This Documentation',
+                ['For readers', 'For maintainers'],
+                'Using UI',
+                [
+                    'Getting Started',
+                    'Troubleshooting',
+                    'Advanced Usage',
+                    'Recipes',
+                ],
+            ],
+            // Then sort the rest alphabetically
+            method: 'alphabetical',
+        },
+    },
+    docs: {
+        // Customize docs page layout (in order to rename 'Stories' section)
+        page: () => (
+            <>
+                <Title />
+                <Subtitle />
+                <Description />
+                <Primary />
+                <ArgsTable story={PRIMARY_STORY} />
+                <Stories title="Examples" />
+            </>
+        ),
+    },
+    jsx: {
+        filterProps: val => val !== undefined,
+        showDefaultProps: false,
+        functionValue: fn => fn.name,
+        tabStop: 4,
+        maxInlineAttributesLineLength: 80,
+    },
+    // A11y addon config
+    a11y: {
+        // the target DOM element
+        element: '#root',
+        // execution mode for the addon
+        manual: false,
     },
+    controls: { hideNoControlsWarning: true, expanded: true },
 })

.storybook/static/manager.css

@@ -0,0 +1,5 @@
+/* Styles to customize storybook manager UI (search, sidebar, etc) go here */
+
+.sidebar-subheading {
+    color: #4a5768 !important;
+}

.storybook/static/preview.css

@@ -0,0 +1,9 @@
+/* Styles for storybook docs or anything else in the 'preview' frame go here */
+
+.sbdocs.sbdocs-a:hover {
+    text-decoration: underline;
+}
+
+.sbdocs-expandable {
+    color: #004D40 !important; /* teal800 */
+}

.storybook/theme.js

@@ -0,0 +1,91 @@
+import { create } from '@storybook/theming/create'
+import { colors } from '@dhis2/ui-constants'
+
+/**
+ * See here for an example of these values:
+ * https://github.com/storybookjs/storybook/blob/master/lib/theming/src/themes/light.ts
+ */
+export default create({
+    /** Main theme ('light' or 'dark') */
+    base: 'light',
+
+    /**
+     * Color palette
+     */
+    /** Not sure where this is applied */
+    // colorPrimary: '#FF4785', // Storybook coral
+
+    /**
+     * '4-square' icon in sidebar, sidebar highlight color, link color,
+     * toolbar icon color (when hovered), focused input highlight
+     */
+    colorSecondary: colors.teal600,
+
+    /**
+     * UI
+     */
+    /** Background of side bar & rest of page: */
+    appBg: colors.grey050,
+
+    /** Background of preview & docs ('app') frame: */
+    // appContentBg: 'white',
+
+    /** Color for 'glowing' placeholders for loading stories AND lines in app frame: */
+    // appBorderColor: 'red',
+
+    /** Border radius of app frame */
+    // appBorderRadius: 4,
+
+    /**
+     * Typography ---
+     */
+    /** Affects text in sidebar */
+    // fontBase: '"Georgia", serif',
+    // fontCode: 'monospace',
+
+    /**
+     * Text colors
+     */
+    /** Color for text in sidebar and addons */
+    // textColor: 'blue',
+
+    /** Not sure where this applies */
+    // textInverseColor: 'green', // 'rgba(255,255,255,0.9)',
+
+    /** Text in search bar */
+    // textMutedColor: 'purple',
+
+    /**
+     * Toolbar default and active colors ---
+     */
+    /** Color of text & icons in toolbars (addons and top bar) when unselected */
+    // barTextColor: 'purple',
+
+    /** Text color and underline of selected tab in toolbars (e.g. Canvas, Controls) */
+    barSelectedColor: colors.teal600,
+
+    /** Background color of toolbars (addons and top bar) */
+    // barBg: 'yellow',
+
+    /**
+     * Form colors
+     */
+    /** Mostly self-explanatory */
+    // inputBg: "red",
+
+    /** Border while not focused - when focused, uses 'colorSecondary' */
+    // inputBorder: 'purple',
+
+    // inputTextColor: 'green',
+    // inputBorderRadius: 0,
+
+    /**
+     * Brand
+     */
+    brandTitle: 'DHIS2 UI',
+    // TODO: Better place to send this?
+    brandUrl: 'https://www.dhis2.org',
+    // TODO: Serve this statically?
+    brandImage:
+        'https://raw.githubusercontent.com/dhis2/dhis2-identity/master/web/Logo/Default/dhis2-logo-rgb-positive.svg',
+})

docs/advanced-usage.stories.mdx

@@ -0,0 +1,6 @@
+import { Meta, Description } from '@storybook/addon-docs/blocks'
+import AdvancedUsage from './advanced-usage.md'
+
+<Meta title="Using UI/Advanced Usage" />
+
+<Description>{AdvancedUsage}</Description>

docs/getting-started.stories.mdx

@@ -0,0 +1,6 @@
+import { Meta, Description } from '@storybook/addon-docs/blocks'
+import GettingStarted from './getting-started.md'
+
+<Meta title="Using UI/Getting Started" />
+
+<Description>{GettingStarted}</Description>

docs/recipes/transfer-infinite-loading-all-options-selected.stories.mdx

@@ -0,0 +1,6 @@
+import { Meta, Description } from '@storybook/addon-docs/blocks'
+import markdown from './transfer-infinite-loading-all-options-selected.md'
+
+<Meta title="Using UI/Recipes/Transfer: Infinite Loading, All Options Selected" />
+
+<Description>{markdown}</Description>