Merge pull request #682 from oceanbase/dengfuping-dev

feat(docs): Add spec and blog

.dumi/rehypePlugin.ts

@@ -0,0 +1,109 @@
+import assert from 'assert';
+import type { HastRoot, UnifiedTransformer } from 'dumi';
+import { unistUtilVisit } from 'dumi';
+
+/**
+ * plugin for modify hast tree when docs compiling
+ */
+function rehypeAntd(): UnifiedTransformer<HastRoot> {
+  return (tree, vFile) => {
+    const { filename } = vFile.data.frontmatter as any;
+
+    unistUtilVisit.visit(tree, 'element', (node, i, parent) => {
+      if (node.tagName === 'DumiDemoGrid') {
+        // replace DumiDemoGrid to DemoWrapper, to implement demo toolbar
+        node.tagName = 'DemoWrapper';
+      } else if (node.tagName === 'ResourceCards') {
+        const propNames = ['title', 'cover', 'description', 'src', 'official'];
+        const contentNode = node.children[0];
+
+        assert(
+          contentNode.type === 'text',
+          `ResourceCards content must be plain text!\nat ${filename}`
+        );
+
+        // clear children
+        node.children = [];
+
+        // generate JSX props
+        (node as any).JSXAttributes = [
+          {
+            type: 'JSXAttribute',
+            name: 'resources',
+            value: JSON.stringify(
+              contentNode.value
+                .trim()
+                .split('\n')
+                .reduce<any>((acc, cur) => {
+                  // match text from `  - 桌面组件 Sketch 模板包`
+                  const [, isProp, val] = cur.match(/(\s+)?-\s(.+)/)!;
+
+                  if (!isProp) {
+                    // create items when match title
+                    acc.push({ [propNames[0]]: val });
+                  } else {
+                    // add props when match others
+                    const prev = acc[acc.length - 1];
+
+                    prev[propNames[Object.keys(prev).length]] = val;
+                  }
+
+                  return acc;
+                }, [])
+            ),
+          },
+        ];
+      } else if (
+        node.type === 'element' &&
+        node.tagName === 'Table' &&
+        (/^packages\/design/.test(filename) ||
+          /^packages\/ui/.test(filename) ||
+          /^packages\/charts/.test(filename))
+      ) {
+        if (!node.properties) return;
+        node.properties.className ??= [];
+        (node.properties.className as string[]).push('component-api-table');
+      }
+      // else if (node.type === 'element' && (node.tagName === 'Link' || node.tagName === 'a')) {
+      //   const { tagName } = node;
+      //   node.properties!.sourceType = tagName;
+      //   node.tagName = 'LocaleLink';
+      // }
+      // else if (node.type === 'element' && node.tagName === 'video') {
+      //   node.tagName = 'VideoPlayer';
+      // }
+      else if (node.tagName === 'SourceCode') {
+        const { lang } = node.properties!;
+
+        if (typeof lang === 'string' && lang.startsWith('sandpack')) {
+          const code = (node.children[0] as any).value as string;
+          const configRegx = /^const sandpackConfig = ([\S\s]*?});/;
+          const [configString] = code.match(configRegx) || [];
+          /* biome-ignore lint/security/noGlobalEval: used in documentation */ /* eslint-disable-next-line no-eval */
+          const config = configString && eval(`(${configString.replace(configRegx, '$1')})`);
+          Object.keys(config || {}).forEach(key => {
+            if (typeof config[key] === 'object') {
+              config[key] = JSON.stringify(config[key]);
+            }
+          });
+
+          parent!.children.splice(i!, 1, {
+            type: 'element',
+            tagName: 'Sandpack',
+            properties: {
+              ...config,
+            },
+            children: [
+              {
+                type: 'text',
+                value: code.replace(configRegx, '').trim(),
+              },
+            ],
+          });
+        }
+      }
+    });
+  };
+}
+
+export default rehypeAntd;

.dumi/remarkPlugin.ts

@@ -0,0 +1,15 @@
+import { unistUtilVisit } from 'dumi';
+import type { UnifiedTransformer } from 'dumi';
+
+function remarkMeta(): UnifiedTransformer<any> {
+  return (tree, vFile) => {
+    // read frontmatter
+    unistUtilVisit.visit(tree, 'yaml', (node) => {
+      if (!/(^|[\n\r])description:/.test(node.value)) {
+        (vFile.data.frontmatter as any).__autoDescription = true;
+      }
+    });
+  };
+}
+
+export default remarkMeta;

.dumi/theme/builtins/Caution.tsx

@@ -0,0 +1,25 @@
+import React from 'react';
+import { css } from '@emotion/react';
+import useSiteToken from '../../hooks/useSiteToken';
+
+export interface CautionProps {
+  title: React.ReactNode;
+  filename?: string;
+}
+
+const useStyle = () => {
+  const { token } = useSiteToken();
+
+  return {
+    do: css`
+      font-size: 20px;
+      color: ${token.colorWarningText};
+    `,
+  };
+};
+
+export default function Caution({}: CautionProps) {
+  const styles = useStyle();
+
+  return <span css={styles.do}>Caution</span>;
+}

.dumi/theme/builtins/DemoWrapper/index.tsx

@@ -29,6 +29,7 @@ const DemoWrapper: typeof DumiDemoGrid = ({ items }) => {
         (acc, item) => {
           const { previewerProps } = item;
           const { debug } = previewerProps;
+          console.log(debug);
 
           if (debug && !showDebug) return acc;
 
@@ -37,8 +38,6 @@ const DemoWrapper: typeof DumiDemoGrid = ({ items }) => {
             previewerProps: {
               ...previewerProps,
               expand: expandAll,
-              // always override debug property, because dumi will hide debug demo in production
-              debug: false,
               /**
                * extra marker for the original debug
                */

.dumi/theme/builtins/Do.tsx

@@ -0,0 +1,25 @@
+import React from 'react';
+import { css } from '@emotion/react';
+import useSiteToken from '../../hooks/useSiteToken';
+
+export interface DoProps {
+  title: React.ReactNode;
+  filename?: string;
+}
+
+const useStyle = () => {
+  const { token } = useSiteToken();
+
+  return {
+    do: css`
+      font-size: 20px;
+      color: ${token.colorSuccessText};
+    `,
+  };
+};
+
+export default function Do({}: DoProps) {
+  const styles = useStyle();
+
+  return <span css={styles.do}>Do</span>;
+}

.dumi/theme/builtins/Donot.tsx

@@ -0,0 +1,25 @@
+import React from 'react';
+import { css } from '@emotion/react';
+import useSiteToken from '../../hooks/useSiteToken';
+
+export interface DonotProps {
+  title: React.ReactNode;
+  filename?: string;
+}
+
+const useStyle = () => {
+  const { token } = useSiteToken();
+
+  return {
+    do: css`
+      font-size: 20px;
+      color: ${token.colorErrorText};
+    `,
+  };
+};
+
+export default function Do({}: DonotProps) {
+  const styles = useStyle();
+
+  return <span css={styles.do}>Don't</span>;
+}

.dumi/theme/common/styles/Markdown.tsx

@@ -23,38 +23,56 @@ const GlobalStyle: React.FC = () => {
           line-height: 1.5;
         }
 
+        // 非段落图片最大宽度: 100% - 32px
         .markdown img {
           max-width: calc(100% - 32px);
           max-height: 100%;
         }
 
+        // 段落图片最大宽度: 100%
         .markdown p > img {
-          margin: 34px 0;
-          box-shadow: 0 8px 20px rgba(143, 168, 191, 0.35);
+          max-width: 100%;
         }
 
-        .markdown p > img.markdown-inline-image {
-          margin: 0;
-          box-shadow: none;
+        // 暂时去掉段落图片的阴影
+        // .markdown p > img {
+        //   margin: 24px 0;
+        //   box-shadow: 0 8px 20px rgba(143, 168, 191, 0.35);
+        // }
+
+        // .markdown p > img.markdown-inline-image {
+        //   margin: 0;
+        //   box-shadow: none;
+        // }
+
+        .markdown .image-description {
+          color: ${token.colorTextDescription};
+          margin-right: 16px;
+        }
+
+        .markdown .image-description-center {
+          color: ${token.colorTextDescription};
+          margin-right: 16px;
+          text-align: center;
         }
 
         .markdown h1 {
           margin-top: 8px;
           margin-bottom: 20px;
           color: ${token.colorTextHeading};
           font-weight: 500;
-          font-size: 30px;
+          font-size: 24px;
           font-family: Avenir, ${token.fontFamily}, sans-serif;
-          line-height: 38px;
+          line-height: 32px;
 
           .subtitle {
             margin-left: 12px;
           }
         }
 
         .markdown h2 {
-          font-size: 24px;
-          line-height: 32px;
+          font-size: 20px;
+          line-height: 28px;
         }
 
         .markdown h2,
@@ -305,12 +323,18 @@ const GlobalStyle: React.FC = () => {
             border: 1px solid ${token.colorSplit};
             border-collapse: collapse;
             border-spacing: 0;
+            width: 100%;
 
             th,
             td {
               padding: 12px 24px;
               text-align: left;
               border: 1px solid ${token.colorSplit};
+              vertical-align: top;
+
+              img {
+                max-width: 100%;
+              }
 
               &:first-child {
                 border-left: 1px solid ${token.colorSplit};
@@ -319,20 +343,10 @@ const GlobalStyle: React.FC = () => {
               &:last-child {
                 border-right: 1px solid ${token.colorSplit};
               }
-
-              img {
-                max-width: unset;
-              }
-            }
-
-            td {
-              &:nth-child(3) {
-                color: ${token.magenta7};
-              }
             }
 
             th {
-              color: #5c6b77;
+              color: ${token.colorTextSecondary};
               font-weight: 500;
               white-space: nowrap;
               background: rgba(0, 0, 0, 0.02);

.dumi/theme/locales/en-US.json

@@ -13,6 +13,12 @@
   "app.content.edit-page": "Edit this page on GitHub!",
   "app.content.contributors": "contributors",
   "app.component.examples": "Examples",
+  "app.component.examples.expand": "Expand all code",
+  "app.component.examples.collapse": "Collapse all code",
+  "app.component.examples.visible": "Expand debug examples",
+  "app.component.examples.hide": "Collapse debug examples",
+  "app.component.examples.openDemoNotReact18": "Open Demo with React < 18",
+  "app.component.examples.openDemoWithReact18": "Open Demo with React 18",
   "app.docs.components.icon.search.placeholder": "Search icons here, click icon to copy code",
   "app.docs.components.icon.outlined": "Outlined",
   "app.docs.components.icon.filled": "Filled",

.dumi/theme/locales/zh-CN.json

@@ -13,6 +13,12 @@
   "app.content.edit-page": "在 GitHub 上编辑此页！",
   "app.content.contributors": "文档贡献者",
   "app.component.examples": "代码演示",
+  "app.component.examples.expand": "展开全部代码",
+  "app.component.examples.collapse": "收起全部代码",
+  "app.component.examples.visible": "显示调试专用演示",
+  "app.component.examples.hide": "隐藏调试专用演示",
+  "app.component.examples.openDemoNotReact18": "使用 React 18 以下版本打开 Demo",
+  "app.component.examples.openDemoWithReact18": "使用 React 18 打开 Demo",
   "app.docs.components.icon.search.placeholder": "在此搜索图标，点击图标可复制代码",
   "app.docs.components.icon.outlined": "线框风格",
   "app.docs.components.icon.filled": "实底风格",

.dumi/theme/slots/Content/index.tsx

@@ -52,7 +52,7 @@ const useStyle = () => {
       top: 8px;
       inset-inline-end: 0;
       right: 0;
-      width: 160px;
+      width: 180px;
       margin: 12px 0;
       padding: 8px 0;
       padding-inline: 4px 8px;
@@ -82,8 +82,10 @@ const useStyle = () => {
       }
     `,
     articleWrapper: css`
-      padding: 0 170px 32px 64px;
+      padding: 0 200px 32px 48px;
+      max-width: 1280px;
       min-height: calc(100vh - 242px);
+      margin: 0 auto;
 
       &.rtl {
         padding: 0 64px 144px 170px;
@@ -230,7 +232,7 @@ const Content: React.FC<{ children: ReactNode }> = ({ children }) => {
         </Affix>
         <article css={styles.articleWrapper} className={classNames({ rtl: isRTL })}>
           {meta.frontmatter?.title ? (
-            <Typography.Title style={{ fontSize: 30 }}>
+            <Typography.Title style={{ fontSize: 24 }}>
               {meta.frontmatter?.title}
               {meta.frontmatter.subtitle && (
                 <span style={{ marginLeft: 12 }}>{meta.frontmatter.subtitle}</span>