refactor(docs): use React component instead of markdown in MDX - WIP

packages/storybook/.storybook/manager.tsx

@@ -13,7 +13,7 @@ addons.setConfig({
   sidebar: {
     filters: {
       patterns: (item) => {
-        return !item.tags.includes('isHidden');
+        return !item.tags?.includes('isHidden');
       }
     }
   },

packages/storybook/.storybook/preview.ts → packages/storybook/.storybook/preview.tsx

@@ -1,4 +1,7 @@
-import type { Preview } from '@storybook/web-components';
+import { DocsContainer } from '@storybook/addon-docs';
+import { Unstyled } from '@storybook/blocks';
+import { type Preview } from '@storybook/web-components';
+import React from 'react';
 import '@ovhcloud/ods-themes/default';
 import { defineCustomElement as defineAccordion } from '@ovhcloud/ods-components/dist/components/ods-accordion';
 import { defineCustomElement as defineBadge } from '@ovhcloud/ods-components/dist/components/ods-badge';
@@ -93,6 +96,15 @@ const preview: Preview = {
   ],
   parameters: {
     docs: {
+      container: ({ children, context }: any) => {
+        return (
+          <DocsContainer context={ context }>
+            <Unstyled>
+              { children }
+            </Unstyled>
+          </DocsContainer>
+        );
+      },
       toc: {
         contentsSelector: '.sbdocs-content',
         headingSelector: 'h2, h3',

packages/storybook/assets/css/preview.css

@@ -1,64 +1,27 @@
-#storybook-docs > .sbdocs-wrapper {
-  padding: 1.5rem 3rem 3rem 3rem;
-}
-
-/***************************************
- * TYPOGRAPHY
- ***************************************/
-
-html body *:not(pre):not(code),
-html body .sbdocs-content *:not(pre):not(code) {
+/* Global typography */
+body {
   font-family: var(--ods-font-family-default);
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+  -webkit-tap-highlight-color: rgba(0, 0, 0, 0);
+  -webkit-overflow-scrolling: touch;
+  line-height: 24px;
+  color: #2e3438;
 }
 
-pre,
-code {
-  font-family: var(--ods-font-family-code) !important;
+/* Code preview typography */
+pre * {
+  font-family: var(--ods-font-family-code);
+  font-size: 13px;
+  line-height: 19px;
+  color: #fff;
 }
 
-.sbdocs-content > h1,
-.sbdocs-content > div:not(.sb-unstyled) > h1,
-.sbdocs-content > h2,
-.sbdocs-content > div:not(.sb-unstyled) > h2,
-.sbdocs-content > h3,
-.sbdocs-content > div:not(.sb-unstyled) > h3,
-.sbdocs-content > h4,
-.sbdocs-content > div:not(.sb-unstyled) > h4,
-.sbdocs-content > h5,
-.sbdocs-content > div:not(.sb-unstyled) > h5,
-.sbdocs-content > h6,
-.sbdocs-content > div:not(.sb-unstyled) > h6 {
-  color: var(--ods-color-primary-800);
+img {
+  max-width: 100%;
 }
 
-.sbdocs-content :where(span:not(.sb-anchor, .sb-unstyled, .sb-unstyled span)) {
-  font-size: 1rem !important;
-}
-
-.sbdocs-content :where(p:not(.sb-anchor, .sb-unstyled, .sb-unstyled p)) {
-  font-size: 1rem !important;
-}
-
-.documentation-overview {
-  display: grid;
-  grid-template-columns: 1.5fr 1fr;
-  column-gap: 2rem;
-}
-
-.documentation-overview__table {
-  align-self: flex-start;
-  text-align: left;
-}
-
-.documentation-do-table,
-.documentation-dont-table {
-  width: 100%;
-}
-
-.documentation-do-table tr {
-  background-color: var(--ods-color-success-050) !important;
-}
-
-.documentation-dont-table tr {
-  background-color: var(--ods-color-critical-050) !important;
+/* Doc pages content */
+#storybook-docs > .sbdocs-wrapper {
+  padding: 1.5rem 3rem 3rem 3rem;
 }

packages/storybook/assets/css/storybook.css

@@ -1,3 +1,6 @@
+/* Hide toolbar for non demo stories */
+/* :nth-child(4) is the  "Addons" pane at the bottom of individual Stories view */
+/* see https://github.com/storybookjs/storybook/discussions/20620 */
 [id='root'] > div:not(:has(> :nth-child(4))) [data-test-id='sb-preview-toolbar'] {
   display: none;
 }
@@ -6,15 +9,18 @@ body {
   letter-spacing: 0.03rem;
 }
 
-a[title*="Design System"] {
+a[title="OVHcloud Design System"] {
+  display: flex;
+  justify-content: center;
   margin: auto;
-  max-width: 75%;
 }
 
+/* Hide the cog button with Storybook options */
 button[title="Shortcuts"] {
   display: none;
 }
 
+/* Double class to increase the weight to overwrite storybook internal css */
 .sidebar-subheading.sidebar-subheading {
   font-size: 1em;
   font-weight: bold;
@@ -28,7 +34,7 @@ button[title="Shortcuts"] {
   grid-template-columns: 1fr max-content;
 }
 
-/* select the brand image */
+/* Enforce the brand image to take the whole space */
 .sidebar-header > div:first-of-type {
   grid-column: span 2;
 }

packages/storybook/package.json

@@ -19,6 +19,7 @@
     "@storybook/addon-essentials": "8.0.4",
     "@storybook/addon-links": "8.0.4",
     "@storybook/blocks": "8.0.4",
+    "@storybook/components": "8.0.4",
     "@storybook/test": "8.0.4",
     "@storybook/web-components": "8.0.4",
     "@storybook/web-components-vite": "8.0.4",

packages/storybook/src/components/banner/Banner.tsx

@@ -0,0 +1,34 @@
+import { useOf } from '@storybook/blocks';
+import { type ModuleExports } from '@storybook/types';
+import React from 'react';
+import styles from './banner.module.css';
+
+const Banner = ({ of, label, section }: { of: ModuleExports, label?: string, section?: string }) => {
+  let title = label;
+  let subtitle = section;
+
+  if (of) {
+    const resolvedOf = useOf(of || 'story', ['meta']);
+    const metaTitle = resolvedOf.preparedMeta.title;
+    const metaTitles = metaTitle.split('/');
+
+    title = label || metaTitles[metaTitles.length - 1];
+    subtitle = section || metaTitles.slice(0, -1).join(' / ');
+  }
+
+  return (
+    <div className={ styles.banner }>
+      <span>
+        { subtitle }
+      </span>
+
+      <h1>
+        { title }
+      </h1>
+    </div>
+  );
+}
+
+export {
+  Banner,
+};

packages/storybook/src/components/banner/banner.module.css

@@ -0,0 +1,9 @@
+.banner {
+  position: relative;
+  margin-top: -1.5rem;
+  border-radius: 0 0 1rem 1rem;
+  background-color: var(--ods-color-primary-500);
+  padding: 1.25rem;
+  min-height: 5rem;
+  color: var(--ods-color-primary-000);
+}

packages/storybook/src/components/bestPractices/BestPractices.tsx

@@ -0,0 +1,62 @@
+import { Table } from '@storybook/components';
+import React, { type ReactNode } from 'react';
+import styles from './bestPractices.module.css';
+
+type Props = {
+  donts: ReactNode[],
+  dos: ReactNode[],
+}
+
+const BestPractices = ({ donts, dos }: Props) => {
+  return (
+    <div>
+      <Table className={ styles['best-practices__do-table'] }>
+        <thead>
+          <tr>
+            <th className={ styles['best-practices__do-table__cell'] }>
+              ✅ Do
+            </th>
+          </tr>
+        </thead>
+
+        <tbody>
+          {
+            dos.map((item, idx) => (
+              <tr key={ idx }>
+                <td className={ styles['best-practices__do-table__cell'] }>
+                  { item }
+                </td>
+              </tr>
+            ))
+          }
+        </tbody>
+      </Table>
+
+      <Table className={ styles['best-practices__dont-table'] }>
+        <thead>
+          <tr>
+            <th className={ styles['best-practices__dont-table__cell'] }>
+              ❌ Don't
+            </th>
+          </tr>
+        </thead>
+
+        <tbody>
+          {
+            donts.map((item, idx) => (
+              <tr key={ idx }>
+                <td className={ styles['best-practices__dont-table__cell'] }>
+                  { item }
+                </td>
+              </tr>
+            ))
+          }
+        </tbody>
+      </Table>
+    </div>
+  );
+};
+
+export {
+  BestPractices,
+};

packages/storybook/src/components/bestPractices/bestPractices.module.css

@@ -0,0 +1,12 @@
+.best-practices__do-table,
+.best-practices__dont-table {
+  width: 100%;
+}
+
+.best-practices__do-table__cell {
+  background-color: var(--ods-color-success-050);
+}
+
+.best-practices__dont-table__cell {
+  background-color: var(--ods-color-critical-050);
+}

packages/storybook/src/components/heading/Heading.tsx

@@ -0,0 +1,34 @@
+import { ODS_DIVIDER_SPACING } from '@ovhcloud/ods-components';
+import { OdsDivider } from '@ovhcloud/ods-components/react';
+import { HeaderMdx } from '@storybook/blocks';
+import React from 'react';
+import styles from './heading.module.css';
+
+type Props = {
+  label: string,
+  level: number,
+}
+
+const Heading = ({ label, level }: Props) => {
+  const tagID = label.toLowerCase().replace(/[^a-z0-9]/gi, '-');
+
+  return (
+    <>
+      {/* @ts-ignore to fix when extra time */}
+      <HeaderMdx className={ styles[`heading-${level}`] }
+                 as={ `h${level}` }
+                 id={ tagID }>
+        { label }
+      </HeaderMdx>
+
+      {
+        level < 3 &&
+        <OdsDivider spacing={ level === 1 ? ODS_DIVIDER_SPACING._32 : ODS_DIVIDER_SPACING._16 } />
+      }
+    </>
+  );
+};
+
+export {
+  Heading,
+};

packages/storybook/src/components/heading/heading.module.css

@@ -0,0 +1,9 @@
+.heading-1,
+.heading-2,
+.heading-3,
+.heading-4,
+.heading-5,
+.heading-6 {
+  margin-bottom: 0;
+  color: var(--ods-color-primary-800);
+}

packages/storybook/src/components/homepage/Homepage.tsx

@@ -0,0 +1,42 @@
+import { ODS_ICON_NAME, ODS_TEXT_PRESET } from '@ovhcloud/ods-components';
+import { OdsLink, OdsText } from '@ovhcloud/ods-components/react';
+import React from 'react';
+import { StorybookLink } from '../storybookLink/StorybookLink';
+import styles from './homepage.module.css';
+
+const Homepage = () => {
+  return (
+    <div className={ styles.homepage }>
+      <div className={ styles['homepage__content'] }>
+        <img alt="OVHcloud logo"
+             height="64"
+             src="ods_logo.svg"
+             width="640" />
+
+        <OdsText preset={ ODS_TEXT_PRESET.heading3 }>
+          A collection of assets, guidelines and UI components for building consistent user experiences across OVHcloud products.
+        </OdsText>
+
+        <div className={ styles['homepage__content__links'] }>
+          <StorybookLink icon={ ODS_ICON_NAME.arrowRight }
+                         label="Get Started"
+                         title="OVHcloud Design System/Get Started" />
+
+          <OdsLink href="https://zeroheight.com/6fc8a63f7/p/533db0-ovhcloud-design-system"
+                   icon={ ODS_ICON_NAME.externalLink }
+                   label="Design Guidelines"
+                   target="_blank" />
+
+          <OdsLink href="https://github.com/ovh/design-system"
+                   icon={ ODS_ICON_NAME.externalLink }
+                   label="GitHub repository"
+                   target="_blank" />
+        </div>
+      </div>
+    </div>
+  );
+};
+
+export {
+  Homepage,
+};

packages/storybook/src/components/homepage/homepage.module.css

@@ -0,0 +1,24 @@
+.homepage {
+  position: absolute;
+  inset: 0;
+  background: url('ods_bg.png') no-repeat center center fixed;
+  background-size: cover;
+}
+
+.homepage__content {
+  display: flex;
+  flex-flow: column;
+  row-gap: 2rem;
+  box-shadow: 0 0 10px #fff, 0 0 20px #fff, 0 0 30px #fff, 0 0 40px #fff, 0 0 50px #fff, 0 0 60px #fff, 0 0 70px #fff, 0 0 80px #fff, 0 0 90px #fff, 0 0 100px #fff;
+  border-radius: 0 0 20em 0;
+  padding: 4rem;
+  max-width: 45rem;
+  background-color: #fff;
+}
+
+.homepage__content__links {
+  display: flex;
+  flex-flow: column;
+  row-gap: 2rem;
+  font-size: 1.4rem;
+}