docs: add CSS Theme Variables and Shadow DOM pages

.changeset/tonic-ui-943a.md

@@ -0,0 +1,5 @@
+---
+"@tonic-ui/react": patch
+---
+
+feat(react): add exports for `DefaultPropsProvider` and `useDefaultProps`

.changeset/tonic-ui-943b.md

@@ -0,0 +1,5 @@
+---
+"@tonic-ui/react": patch
+---
+
+feat(react/Popper): use the `useDefaultProps` hook for managing default props

packages/react-docs/components/MDXComponents.js

@@ -1,4 +1,3 @@
-import styled from '@emotion/styled';
 import {
   Box,
   Code,
@@ -16,7 +15,6 @@ import { codeBlockLight, codeBlockDark } from '../prism-themes/tonic-ui';
 
 const ParagraphComponent = props => (
   <Box
-    as="p"
     mt={0}
     mb="4x"
     fontSize="md"
@@ -142,7 +140,7 @@ const H6Component = props => {
   );
 };
 
-const BlockquoteComponent = styled(props => {
+const BlockquoteComponent = props => {
   const [colorMode] = useColorMode();
   const [colorStyle] = useColorStyle({ colorMode });
   const backgroundColor = {
@@ -168,14 +166,16 @@ const BlockquoteComponent = styled(props => {
       mb="4x"
       px="4x"
       py="3x"
+      sx={{
+        // The "ParagraphComponent" was changed to "div" instead of "p"
+        '> div': {
+          marginBottom: 0,
+        },
+      }}
       {...props}
     />
   );
-})`
-  > p {
-    margin-bottom: 0;
-  }
-`;
+};
 
 const UnorderedListComponent = props => (
   <Box

packages/react-docs/config/sidebar-routes.js

@@ -10,6 +10,7 @@ import {
   MigrateSuccessIcon,
   RocketIcon,
   SVGIcon,
+  ToolsConfigurationIcon,
   UserTeamIcon,
   WidgetsIcon,
   WorkspaceIcon,
@@ -33,10 +34,8 @@ export const routes = [
       { title: 'Usage', path: 'getting-started/usage' },
       { title: 'Color Mode', path: 'getting-started/color-mode' },
       { title: 'Color Style', path: 'getting-started/color-style' },
-      { title: 'CSS Variables', path: 'getting-started/css-variables' },
       { title: 'Icons', path: 'getting-started/icons' },
       { title: 'The sx prop', path: 'getting-started/the-sx-prop' },
-      { title: 'Security', path: 'getting-started/security' },
       { title: 'Tonic UI Versions', path: 'getting-started/versions' },
     ],
   },
@@ -61,6 +60,17 @@ export const routes = [
       { title: 'React Icons', path: 'contributing/react-icons' },
     ],
   },
+  {
+    title: 'Customization',
+    icon: (props) => (
+      <ToolsConfigurationIcon size="4x" {...props} />
+    ),
+    routes: [
+      { title: 'Content Security Policy', path: 'customization/content-security-policy' },
+      { title: 'CSS Theme Variables', path: 'customization/css-theme-variables' },
+      { title: 'Shadow DOM', path: 'customization/shadow-dom' },
+    ],
+  },
   {
     title: 'Migrations',
     icon: (props) => (

packages/react-docs/pages/_app.page.js

@@ -38,7 +38,7 @@ const EmotionCacheProvider = ({
   nonce,
 }) => {
   const cache = createCache({
-    key: 'tonic-ui',
+    key: 'tonic-css',
     nonce,
   });
 
@@ -51,7 +51,10 @@ const EmotionCacheProvider = ({
 
 const App = (props) => {
   const customTheme = useConst(() => createTheme({
-    cssVariables: true, // Enable CSS variables replacement
+    cssVariables: {
+      rootSelector: ':root',
+      prefix: 'tonic',
+    },
     components: {
       // Set default props for specific components
       //
@@ -91,6 +94,12 @@ const App = (props) => {
     <InstantSearch
       indexName={process.env.ALGOLIA_INDEX_NAME}
       searchClient={searchClient}
+      future={{
+        // https://www.algolia.com/doc/api-reference/widgets/instantsearch/react/#widget-param-preservesharedstateonunmount
+        // Starting from the next major version, InstantSearch will change how widgets state is preserved when they are removed.
+        // InstantSearch will keep the state of unmounted widgets to be usable by other widgets with the same attribute.
+        preserveSharedStateOnUnmount: true,
+      }}
     >
       <Configure
         // https://www.algolia.com/doc/api-reference/search-api-parameters/

packages/react-docs/pages/customization/content-security-policy.page.mdx

@@ -0,0 +1,42 @@
+# Content Security Policy
+
+Content Security Policy plays a critical role in protecting against various attacks, most notably Cross-Site Scripting (XSS) and data injections. Its core function involves the inclusion of either a `Content-Security-Policy` header in the HTTP response or `<meta>` tags within the HTML of a page.
+
+## Getting Started
+
+Tonic UI relies on [Emotion](https://emotion.sh/) for its styling system. To seamless integrate [Emotion](https://emotion.sh/) with Content Security Policy, it is essential to provide a `nonce` value to the `CacheProvider` component. Detailed instruction can be found in the [Emotion documentation](https://emotion.sh/docs/@emotion/cache).
+
+### 1. Implement a `EmotionCacheProvider` component
+
+```jsx
+const EmotionCacheProvider = ({
+  children,
+  nonce,
+}) => {
+  const cache = createCache({
+    key: 'tonic-ui',
+    nonce,
+  });
+
+  return (
+    <CacheProvider value={cache}>
+      {children}
+    </CacheProvider>
+  );
+};
+```
+
+### 2. Integrate the `EmotionCacheProvider` component with `TonicProvider`
+
+Wrap the `TonicProvider` component with the `EmotionCacheProvider` and provide the relevant `nonce` value. This value will be utilized by [Emotion](https://emotion.sh/) to generate a style tag with the necessary `nonce` attribute.
+
+```jsx
+<EmotionCacheProvider nonce={nonce}>
+  <TonicProvider
+    colorMode={colorMode}
+    useCSSBaseline
+  >
+    <App />
+  </TonicProvider>
+</EmotionCacheProvider>
+```

packages/react-docs/pages/getting-started/css-variables/default-css-variables.js → packages/react-docs/pages/customization/css-theme-variables.js

@@ -17,23 +17,23 @@ const App = () => {
 
   return (
     <Box fontFamily="mono">
-      {Object.entries(theme?.cssVariables).map(([name, value]) => {
-        if (!name.startsWith('--')) {
-          return null;
-        }
-
-        return (
-          <Flex key={name} columnGap="2x">
-            <Text color={tokenColor}>{name}:</Text>
-            <Flex alignItems="center" columnGap="1x">
-              {isColorCode(value) && (
-                <Box backgroundColor={value} border={1} borderColor={borderColor} width="3x" height="3x" />
-              )}
-              <Text>{value};</Text>
+      {':root {'}
+      <Box ml="4x">
+        {Object.entries(theme?.cssVariables).map(([name, value]) => {
+          return (
+            <Flex key={name} columnGap="2x">
+              <Text color={tokenColor}>{name}:</Text>
+              <Flex alignItems="center" columnGap="1x">
+                {isColorCode(value) && (
+                  <Box backgroundColor={value} border={1} borderColor={borderColor} width="3x" height="3x" />
+                )}
+                <Text>{value};</Text>
+              </Flex>
             </Flex>
-          </Flex>
-        );
-      })}
+          );
+        })}
+      </Box>
+      {'}'}
     </Box>
   );
 };

packages/react-docs/pages/customization/css-theme-variables.page.mdx

@@ -0,0 +1,111 @@
+# CSS Theme Variables
+
+Learn how to adopt CSS theme variables.
+
+## Getting Started
+
+To use CSS theme variables, create a theme with `cssVariables: true` and wrap your app with `TonicProvider`:
+
+```jsx
+import {
+  TonicProvider,
+  createTheme,
+} from '@tonic-ui/react';
+
+const theme = createTheme({ cssVariables: true });
+
+function App() {
+  return (
+    <TonicProvider theme={theme}>
+      {/* Your app content */}
+    </TonicProvider>
+  );
+}
+```
+
+The `createTheme` function was introduced in v2.5.0. Use the following approach if you're using a version prior to v2.5.0:
+
+```jsx
+import {
+  TonicProvider,
+  theme,
+} from '@tonic-ui/react';
+
+const customTheme = {
+  ...theme,
+  config: {
+    ...theme?.config,
+    useCSSVariables: true,
+  },
+};
+
+function App() {
+  return (
+    <TonicProvider theme={customTheme}>
+      {/* Your app content */}
+    </TonicProvider>
+  );
+}
+```
+
+After rendering, you will see all CSS theme variables in the `:root` stylesheet of the HTML document. By default, these variables are prefixed with `--tonic`. You can open the **Developer Tools** and go to the **Elements** tab to see all the CSS theme variables being used on the webpage.
+
+{render('./css-theme-variables')}
+
+## Customizing Variable Prefix
+
+You can customize the variable prefix by providing a string to the `prefix` property in the theme configuration.
+
+```js
+createTheme({
+  cssVariables: {
+    prefix: 'custom',
+  },
+});
+```
+
+```css
+:root {
+  --custom-borders-1: .0625rem solid;
+  --custom-borders-2: .125rem solid;
+  /* More variables */
+}
+```
+
+If you prefer not to use any prefix, set `prefix` to an empty string:
+
+```js
+createTheme({
+  cssVariables: {
+    prefix: '',
+  },
+});
+```
+
+```css
+:root {
+  --borders-1: .0625rem solid;
+  --borders-2: .125rem solid;
+  /* More variables */
+}
+```
+
+## Variables Inside Shadow DOM
+
+To apply CSS theme variables inside shadow DOM, specify a different root selector using the `rootSelector` option:
+
+```js
+createTheme({
+  cssVariables: {
+    rootSelector: ':host',
+  },
+});
+```
+
+```css
+:host {
+  --tonic-borders-1: .0625rem solid;
+  --tonic-borders-2: .125rem solid;
+  /* More variables */
+}
+```