docs(theme): add theme for light & dark theme usage

Author: gcornut

packages/site-demo/content/menu.yml

@@ -5,6 +5,7 @@
         - Typography
         - Size
         - Spacing
+        - Light & Dark Theme
     - Components: '*'
     - Patterns:
         - Drag and drop

packages/site-demo/content/product/foundations/light-dark-theme/index.mdx

@@ -0,0 +1,54 @@
+import { ThemeProvider, Button, Chip, Flag, useTheme } from '@lumx/react';
+
+# Light & Dark Theme
+
+By default, all component use a `light` theme that works on light-colored backgrounds.
+**Some components** provide an alternative `dark` theme that can be used to adapt to dark backgrounds.
+
+This theme is not synced to the user's preferred color scheme, it **must be activated manually**.
+
+## Activate via prop
+
+On the supported components, use the `theme` prop to activate the desired theme.
+
+<DemoBlock orientation="horizontal"  withThemeSwitcher theme="dark" alwaysShowCode>
+    {function App({ theme }) {
+        return (
+            <>
+                <Button theme={theme}>Button</Button>
+                <Chip theme={theme}>Chip</Chip>
+            </>
+        )
+    }}
+</DemoBlock>
+
+## Activate via context
+
+Use the `ThemeProvider` component to apply the desired theme to all descendants that supports it.
+
+<DemoBlock orientation="horizontal"  withThemeSwitcher theme="dark" alwaysShowCode>
+    {function App({ theme }) {
+        return (
+            <ThemeProvider value={theme}>
+                <Button>Button</Button>
+                <Chip>Chip</Chip>
+            </ThemeProvider>
+        )
+    }}
+</DemoBlock>
+
+Please note **some exceptions** to the theme context propagation:
+- The `Popover` ignores the theme context for now because most children that we put inside do not support the `dark` theme (List & ListItem)
+- The components `Popover`, `Lightbox` and `Dialog` all stop the propagation of the theme context and reset the theme because their children won't appear on the same background from where they are called
+
+Use the `useTheme()` hook to get the theme from the current theme context when you need to adapt within your custom component.
+
+<DemoBlock orientation="horizontal" withThemeSwitcher theme="dark" alwaysShowCode>
+    {function App({ theme }) {
+        function MyComponent() {
+            const theme = useTheme();
+            return <Flag theme={theme} label={`Current theme: ${theme}`} />;
+        }
+        return <ThemeProvider value={theme}><MyComponent /></ThemeProvider>;
+    }}
+</DemoBlock>

packages/site-demo/plugins/lumx-mdx-preprocessor/mdx-demo-block.js

@@ -24,12 +24,17 @@ const removeIndent = (code) => {
     return code.trim().replace(new RegExp(`\n${indentMatch[1]}`, 'g'), '\n')
 }
 
+// Use a regular expression to remove curly braces at the start and end
+function removeCurlyBracesFromJSX(code) {
+    return code.replace(/^\{|\}$/g, '');
+}
+
 /** Update <DemoBlock/> props to import source code. */
 async function updateDemoBlock(resourceFolder, addImport, props) {
     if (props.children) {
         // <DemoBlock> with children already have a demo inside them.
         // We copy the demo as string into the `codeString` prop.
-        props.codeString = JSON.stringify(removeIndent(props.children));
+        props.codeString = JSON.stringify(removeCurlyBracesFromJSX(removeIndent(props.children)));
         return props;
     }
 

packages/site-demo/src/components/content/DemoBlock/DemoBlock.scss

@@ -35,6 +35,7 @@
 
     &__theme-toggle {
         flex-shrink: 0;
+        margin-left: auto;
     }
 
     &__code {

packages/site-demo/src/components/content/DemoBlock/DemoBlock.tsx

@@ -23,9 +23,11 @@ import './DemoBlock.scss';
 interface DemoBlockProps extends FlexBoxProps {
     demo?: string;
     codeString?: string;
+    theme?: Theme;
     withThemeSwitcher?: boolean;
     hasPlayButton?: boolean;
     backgroundColor?: { color: ColorPalette; variant: ColorVariant };
+    alwaysShowCode?: boolean;
 }
 
 const DEFAULT_PROPS: Partial<DemoBlockProps> = {
@@ -37,17 +39,19 @@ export const DemoBlock: React.FC<DemoBlockProps> = ({
     children,
     demo,
     codeString,
+    theme: defaultTheme = Theme.light,
     withThemeSwitcher = false,
     hasPlayButton = false,
     backgroundColor: propBackgroundColor,
+    alwaysShowCode,
     ...flexBoxProps
 }) => {
-    const [theme, setTheme] = useState<Theme>(Theme.light);
+    const [theme, setTheme] = useState<Theme>(defaultTheme);
     const toggleTheme = (isChecked: boolean) => {
         setTheme(isChecked ? Theme.dark : Theme.light);
     };
 
-    const [showCode, setShowCode] = useState(false);
+    const [showCode, setShowCode] = useState(!!alwaysShowCode);
     const toggleShowCode = () => setShowCode(!showCode);
 
     if (flexBoxProps.orientation === Orientation.horizontal) {
@@ -74,31 +78,35 @@ export const DemoBlock: React.FC<DemoBlockProps> = ({
                 )}
                 {isFunction(children) ? children({ theme }) : children}
             </FlexBox>
-            <div className="demo-block__toolbar">
-                <div className="demo-block__code-toggle">
-                    <Button
-                        disabled={!codeString}
-                        emphasis={Emphasis.low}
-                        leftIcon={mdiCodeTags}
-                        onClick={toggleShowCode}
-                    >
-                        {showCode ? 'Hide code' : 'Show code'}
-                    </Button>
-                </div>
+            {(!alwaysShowCode || withThemeSwitcher) && (
+                <div className="demo-block__toolbar">
+                    {!alwaysShowCode && (
+                        <div className="demo-block__code-toggle">
+                            <Button
+                                disabled={!codeString}
+                                emphasis={Emphasis.low}
+                                leftIcon={mdiCodeTags}
+                                onClick={toggleShowCode}
+                            >
+                                {showCode ? 'Hide code' : 'Show code'}
+                            </Button>
+                        </div>
+                    )}
 
-                {withThemeSwitcher && (
-                    <div className="demo-block__theme-toggle">
-                        <Switch
-                            disabled={!children}
-                            position={Alignment.right}
-                            isChecked={theme === Theme.dark}
-                            onChange={toggleTheme}
-                        >
-                            Dark theme
-                        </Switch>
-                    </div>
-                )}
-            </div>
+                    {withThemeSwitcher && (
+                        <div className="demo-block__theme-toggle">
+                            <Switch
+                                disabled={!children}
+                                position={Alignment.right}
+                                isChecked={theme === Theme.dark}
+                                onChange={toggleTheme}
+                            >
+                                Dark theme
+                            </Switch>
+                        </div>
+                    )}
+                </div>
+            )}
 
             <CodeBlock
                 className={classNames('demo-block__code', showCode && codeString && 'demo-block__code--shown')}