📝 docs: add English documents with lobe-i18n (#124)

* 📝 docs: add english document with lobe-i18n * 📝 docs: add english document with lobe-i18n * 📝 docs: fix docs
ant-design · Nov 24, 2023 · 6f83860 · 6f83860
1 parent 2c3f113
commit 6f83860
Show file tree

Hide file tree

Showing 46 changed files with 3,202 additions and 5 deletions.
diff --git a/.i18nrc.js b/.i18nrc.js
@@ -0,0 +1,12 @@
+/**
+ * @type {import("@lobehub/i18n-cli").Config}
+ */
+module.exports = {
+  markdown: {
+    entry: ['docs/**/**.md', './README.zh-CN.md'],
+    entryLocale: 'zh-CN',
+    entryExtension: '.zh-CN.md',
+    outputLocales: ['en-US'],
+  },
+  modelName: 'gpt-3.5-turbo-1106',
+};
diff --git a/README.md b/README.md
@@ -0,0 +1,121 @@
+# antd-style
+
+[![NPM version][npm-image]][npm-url] [![NPM downloads][download-image]][download-url] [![install size][npm-size]][npm-size-url]
+
+[![Test CI status][test-ci]][test-ci-url] [![Rlease CI][release-ci]][release-ci-url] [![Coverage][coverage]][codecov-url]
+
+[![ docs by dumi][dumi-url]](https://d.umijs.org/) [![Build With father][father-url]](https://github.com/umijs/father/)
+
+<!-- gitpod url -->
+
+<!-- umi url -->
+
+<!-- npm url -->
+
+<!-- coverage -->
+
+<!-- Github CI -->
+
+## Introduction
+
+A business-level `css-in-js` solution built on the Ant Design V5 Token System. It is based on [emotion](https://emotion.sh/) at the bottom.
+
+- **🧩 Token System**: Default integration of Ant Design V5 Token System, making style customization easy, and token consumption flexible and easy to use;
+- **🌓 One-click Dark Mode Switching**: Based on antd v5 cssinjs dynamic theme configuration and dark theme algorithm encapsulation, it provides an easy-to-use light and dark theme switching capability for application-level scenarios, making it easier to use;
+- **🎨 Flexible Custom Theme Extension**: Ant Design Style provides the functionality of custom tokens and custom styles. When the default tokens of antd cannot meet the style requirements, you can flexibly extend your own theme system and freely consume it in CSS in JS;
+- **🏂 Smooth Migration from less**: Need to migrate an old project? Using antd-style can smoothly migrate less in the project to CSS in JS at a lower cost, and provide a better user experience and development experience;
+- **☯️ Good Compatibility with Micro-Apps**: Ant Design Style is compatible with qiankun micro-apps by default (but may sacrifice some performance). At the same time, it provides performance optimization options for scenarios that do not require micro-apps;
+- **📱 Easy Adaptation for Responsive Design**: Ant Design Style will provide convenient utility functions for responsive applications, helping developers quickly complete responsive theme development;
+- **🪴 Stylish**: Ant Design Style provides the ability to compose complex interactive styles through the combination of multiple atomic tokens, achieving a high degree of reusability;
+- **🌰 Documentation and Application Examples**: Show various examples of components and applications using Ant Design Style, helping developers get started quickly. (This document is also built using Ant Design Style for styling)
+
+## Quick Start
+
+### Installation
+
+It is recommended to install using `pnpm`
+
+```bash
+pnpm i antd-style -S
+```
+
+### Typical Use Cases
+
+#### Create Styles
+
+```tsx
+import { createStyles } from 'antd-style';
+
+const useStyles = createStyles(({ token, css }) => ({
+  // Supports the writing style of css object
+  container: {
+    backgroundColor: token.colorBgLayout,
+    borderRadius: token.borderRadiusLG,
+    maxWidth: 400,
+    width: '100%',
+    height: 180,
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    flexDirection: 'column',
+    marginLeft: 'auto',
+    marginRight: 'auto',
+  },
+  // Also supports obtaining the same writing experience as normal css through css string templates
+  card: css`
+    box-shadow: ${token.boxShadow};
+    padding: ${token.padding}px;
+    border-radius: ${token.borderRadius}px;
+    color: ${token.colorTextTertiary};
+    background: ${token.colorBgContainer};
+    transition: all 100ms ${token.motionEaseInBack};
+
+    margin-bottom: 8px;
+    cursor: pointer;
+
+    &:hover {
+      color: ${token.colorTextSecondary};
+      box-shadow: ${token.boxShadowSecondary};
+    }
+  `,
+}));
+
+export default () => {
+  // The styles object in the useStyles method is cached by default, so there is no need to worry about re-rendering issues
+  const { styles, cx, theme } = useStyles();
+
+  return (
+    // Use cx to organize className
+    <div className={cx('a-simple-create-style-demo-classname', styles.container)}>
+      <div className={styles.card}>createStyles Demo</div>
+      {/* The theme object contains all token and theme information */}
+      <div>Current theme mode: {theme.appearance}</div>
+    </div>
+  );
+};
+```
+
+## CHANGELOG
+
+Details: [CHANGELOG](./CHANGELOG.md)
+
+## License
+
+[MIT](./LICENSE)
+
+[gitpod-badge]: https://img.shields.io/badge/Gitpod-ready--to--code-blue?logo=gitpod
+[gitpod-url]: https://gitpod.io/#https://github.com/ant-design/antd-style
+[dumi-url]: https://img.shields.io/badge/docs%20by-dumi-blue
+[father-url]: https://img.shields.io/badge/build%20with-father-028fe4.svg
+[npm-image]: http://img.shields.io/npm/v/antd-style.svg?style=flat-square&color=deepgreen&label=latest
+[npm-url]: http://npmjs.org/package/antd-style
+[npm-size]: https://img.shields.io/bundlephobia/minzip/antd-style?color=deepgreen&label=gizpped%20size&style=flat-square
+[npm-size-url]: https://packagephobia.com/result?p=antd-style
+[coverage]: https://codecov.io/gh/ant-design/antd-style/branch/master/graph/badge.svg
+[codecov-url]: https://codecov.io/gh/ant-design/antd-style/branch/master
+[test-ci]: https://github.com/ant-design/antd-style/actions/workflows/test.yml/badge.svg
+[release-ci]: https://github.com/ant-design/antd-style/actions/workflows/release.yml/badge.svg
+[test-ci-url]: https://github.com/ant-design/antd-style/actions/workflows/test.yml
+[release-ci-url]: https://github.com/ant-design/antd-style/actions/workflows/release.yml
+[download-image]: https://img.shields.io/npm/dm/antd-style.svg?style=flat-square
+[download-url]: https://npmjs.org/package/antd-style
diff --git a/docs/api/create-instance.en-US.md b/docs/api/create-instance.en-US.md
@@ -0,0 +1,112 @@
+---
+title: createInstance
+description: Method for creating style instances
+sourceUrl: '{github}/blob/master/src/functions/createInstance.ts'
+group:
+  title: Advanced Settings
+  order: 10
+nav:
+  title: API Reference
+  order: 10
+---
+
+## Introduction
+
+The `createInstance` method can be used to create another set of style instance methods. This method is basically unnecessary for applying style schemes, but it is essential for component development scenarios.
+
+## Creating Style Instances
+
+Create your own style instance for the component, so that when using the component library, you can automatically obtain a set of style methods with default values configured.
+
+```ts | pure
+import { createInstance } from 'antd-style';
+
+interface DefaultToken {
+  accessColor: string;
+}
+
+const styleInstance = createInstance<DefaultToken>({
+  // **** Style Generation Related **** //
+
+  key: 'abc', // Set the prefix for generating hash class names, the result will be .abc-xxxx
+  speedy: false, // Currently, the default cssom insertion method in the cssinjs solution is not very compatible with qiankun micro-apps, so it is recommended to disable it
+  hashPriority: 'low', // Set the style selector that generates hash to :where selector to reduce weight. This allows user-defined styles to override component styles
+
+  // ***** Theme Related ***** //
+  // Configure the props passed to the ThemeProvider by default, and this Provider can also be overridden by external props
+  // The configured value will also become the default value consumed by related methods, so there is no need to wrap ThemeProvider to consume the default value
+
+  prefixCls: 'tna', // Set the class name prefix for antd components, for example, the type of Button will be .tna-btn
+  customToken: {
+    accessColor: '#12388f',
+  },
+});
+
+export const {
+  // **** Core Style Methods **** //
+  createStyles,
+  createStylish,
+  createGlobalStyle,
+
+  // **** Basic Style Methods **** //
+  cx,
+  css,
+  keyframes,
+  injectGlobal,
+
+  //**** Style Sheet Management  **** //
+  styleManager,
+
+  // **** Data Container   **** //
+  useTheme,
+  StyleProvider,
+  ThemeProvider,
+} = styleInstance;
+```
+
+## Specify Container
+
+Specifying a container during creation can ensure that styles are inserted at that container, which is useful in scenarios such as iframes.
+
+```ts
+const { css, StyleProvider, createStyles } = createInstance({
+  key: 'test',
+  container: document.body,
+});
+```
+
+<code src="../demos/api/createInstance/withContainer.tsx"></code>
+
+If you define styles with `createStyles` exposed by `createInstance` in a component library, and then want to specify different insertion positions in different business scenarios.
+
+Then, when using in the business application, wrap a layer of `StyleProvider` externally and set `container` to achieve custom insertion positions.
+
+<code src="../demos/api/createInstance/withStyleProviderContainer.tsx"></code>
+
+## Compatible with styled Themes
+
+If you use `styled-component` and need to respond to theme changes, you need to wrap a `ThemeProvider` outside the component. At this time, if your component also needs to respond to theme changes, you need to wrap another `ThemeProvider` inside the component. By passing the `styled` configuration to createInstance, you can make the component styled with `styled` respond to custom Tokens.
+
+```ts | pure
+// styled-components version
+import { createInstance } from 'antd-style';
+import { ThemeContext } from 'styled-components';
+
+const componentStyleIntanceWithSC = createInstance({
+  // ...
+  styled: { ThemeContext },
+});
+```
+
+## API
+
+| Property Name | Type                                      | Description                                        |
+| ------------- | ----------------------------------------- | -------------------------------------------------- |
+| key           | `string`                                  | The generated CSS keyword, default is `ant-css`.   |
+| prefixCls     | `string`                                  | Default component prefix.                          |
+| speedy        | `boolean`                                 | Whether to enable speedy mode, default is `false`. |
+| container     | `Node`                                    | Rendering container node.                          |
+| customToken   | `T`                                       | Default custom Token.                              |
+| hashPriority  | `HashPriority`                            | Control the priority of CSS class name generation. |
+| ThemeProvider | `Omit<ThemeProviderProps<T>, 'children'>` | Theme provider.                                    |
+| styled        | `StyledConfig`                            | `styled-components` configuration.                 |
diff --git a/docs/api/create-instance.zh-CN.md b/docs/api/create-instance.zh-CN.md
@@ -5,6 +5,9 @@ sourceUrl: '{github}/blob/master/src/functions/createInstance.ts'
 group:
   title: 高级设置
   order: 10
+nav:
+  title: API
+  order: 10
 ---
 
 ## 简介