@modern-js/module-tools-docs 2.0.0-beta.4

package/docs/en/api/design-system.md

@@ -0,0 +1,524 @@
+# DesignSystem
+This chapter describes the configuration related to designSystem
+
+:::tips
+The Tailwind CSS feature needs to be enabled first via `pnpm run new`.
+:::
+
+
+* Type: `Object`
+* Default value: see configuration details below.
+
+<details>
+  <summary>designSystem configuration details</summary>
+
+
+:::tips
+More about [TailwindCSS configuration](https://tailwindcss.com/docs/configuration#theme)
+:::
+</details>
+
+
+`designSystem` is used to define the project's color palette, typographic scales (Typographic Scales or Type Scale), font lists, breakpoints, border rounding values, and more. Since Modern.js borrows the design approach from Tailwind Theme and integrates Tailwind CSS internally, `designSystem` is used in the same way as Tailwind CSS Theme
+
+The `designSystem` object contains the `screens`, `colors` and `spacing` properties, as well as each customizable core plugin.
+
+## Screens
+
+The responsive breakpoints in your project can be customized using `screens`: the
+
+```js
+const designSystem = {
+  screens: {
+    sm: '640px',
+    md: '768px',
+    lg: '1024px',
+    xl: '1280px',
+  },
+};
+```
+
+where the property name in the `screens` object is the screen name (used as a prefix for the adaptive utility variants generated by `Tailwind CSS`, e.g. `md:text-center`) and the value is the `min-width` at which the breakpoint should start.
+
+Default breakpoints are inspired by common device resolutions: the
+
+```js
+const designSystem = {
+  screens: {
+    sm: '640px',
+    // => @media (min-width: 640px) { ... }
+
+    md: '768px',
+    // => @media (min-width: 768px) { ... }
+
+    lg: '1024px',
+    // => @media (min-width: 1024px) { ... }
+
+    xl: '1280px',
+    // => @media (min-width: 1280px) { ... }
+  },
+};
+```
+
+You can use any name you like as a breakpoint property in your project: the
+
+```js
+const designSystem = {
+  screens: {
+    tablet: '640px',
+    // => @media (min-width: 640px) { ... }
+
+    laptop: '1024px',
+    // => @media (min-width: 1024px) { ... }
+
+    desktop: '1280px',
+    // => @media (min-width: 1280px) { ... }
+  },
+};
+```
+
+These screen names are reflected in `utilities`, so `text-center` now looks like this
+
+```css
+.text-center { text-align: center }
+
+@media (min-width: 640px) {
+    .tablet\:text-center { text-align: center }
+}
+
+@media (min-width: 1024px) {
+    .laptop\:text-center { text-align: center }
+}
+
+@media (min-width: 1280px) {
+    .desktop\:text-center { text-align: center }
+}
+```
+
+### Max-width breakpoints
+
+To use the `max-width` breakpoint instead of `min-width`, you can specify the screen as an object with the `max` attribute.
+
+```js
+const designSystem = {
+  screens: {
+    xl: { max: '1279px' }
+    // => @media (max-width: 1279px) { ... }
+
+    lg: { max: '1023px' },
+    // => @media (max-width: 1023px) { ... }
+
+    md: { max: '767px' },
+    // => @media (max-width: 767px) { ... }
+
+    sm: { max: '639px' },
+    // => @media (max-width: 639px) { ... }
+  },
+};
+```
+
+If necessary, to create breakpoints with `min-width` and `max-width` definitions, e.g.
+
+```js
+const designSystem = {
+  screens: {
+    sm: { min: '640px', max: '767px' }
+    md: { min: '768px', max: '1023px' }
+    lg: { min: '1024px', max: '1279px' }, lg: { min: '1024px', max: '1279px' },
+    xl: { min: '1280px' }
+  },
+};
+```
+
+### Multiple range breakpoints
+
+Sometimes it can be useful to apply a single breakpoint definition to multiple scopes.
+
+For example, suppose you have a `sidebar` and want the breakpoint to be based on the width of the content area rather than the entire viewport. You can simulate this situation by using a smaller breakpoint style when the `sidebar` is visible and the content area is narrowed: the
+
+```js
+const designSystem = {
+  screens: {
+    sm: '500px',
+    md: [
+      // Sidebar appears at 768px, so revert to `sm:` styles between 768px
+      // and 868px, after which the main content area is wide enough again to
+      // apply the `md:` styles.
+      { min: '668px', max: '767px' }
+      { min: '868px' }, { min: '868px' },
+    ],
+    lg: '1100px',
+    xl: '1400px',
+  },
+};
+```
+
+### Custom media queries
+
+If a fully customizable media query is required for a breakpoint, an object with the `raw` attribute can be used.
+
+```js
+const designSystem = {
+  extend: {
+    screens: {
+      portrait: { raw: '(orientation: portrait)' },
+      // => @media (orientation: portrait) { ... }
+    },
+  },
+};
+```
+
+### Print 样式
+
+如果需要为打印应用不同的样式，则 `raw` 选项可能特别有用。
+
+需要做的就是在 `designSystem.extend.screens` 下添加一个 `print`：
+
+```js
+const designSystem = {
+  extend: {
+    screens: {
+      print: { raw: 'print' },
+      // => @media print { ... }
+    },
+  },
+};
+```
+
+然后，可以使用诸如 `print:text-black` 之类的类来指定仅当某人尝试打印页面时才应用的样式：
+
+```html
+<div class="text-gray-700 print:text-black">
+  <! -- ... -->
+</div>
+```
+
+### Dark Mode
+
+`raw` 选项可以用于实现 “暗模式” 屏幕：
+
+```js
+const designSystem = {
+  extend: {
+    screens: {
+      dark: { raw: '(prefers-color-scheme: dark)' },
+      // => @media (prefers-color-scheme: dark) { ... }
+    },
+  },
+};
+```
+
+然后，您可以使用 `dark:` 前缀在暗模式下为元素设置不同的样式：
+
+```html
+<div class="text-gray-700 dark:text-gray-200">
+  <! -- ... -->
+</div>
+```
+
+请注意，由于这些 `screen variants` 是在 `Tailwind CSS` 中实现的，因此**无法使用这种方法将断点与暗模式结合使用** ，例如 `md:dark:text-gray-300` 将不起作用。
+
+## Colors
+
+`colors` 属性可让您自定义项目的全局调色板。
+
+```js
+const designSystem = {
+  colors: {
+    transparent: 'transparent',
+    black: '#000',
+    white: '#fff',
+    gray: {
+      100: '#f7fafc',
+      // ...
+      900: '#1a202c',
+    },
+
+    // ...
+  },
+};
+```
+
+默认情况下，这些颜色由 `backgroundColor`，`textColor` 和 `borderColor` 核心插件继承。
+
+想了解更多，可以查看：[Customizing Colors](https://tailwindcss.com/docs/customizing-colors)。
+
+## Spacing
+
+The global spacing and scaling of items can be customized using the `space` property.
+
+```js
+const designSystem = {
+  spacing: {
+    px: '1px',
+    0: '0',
+    1: '0.25rem',
+    2: '0.5rem',
+    3: '0.75rem',
+    4: '1rem',
+    5: '1.25rem',
+    6: '1.5rem',
+    8: '2rem',
+    10: '2.5rem',
+    12: '3rem',
+    16: '4rem',
+    20: '5rem',
+    24: '6rem',
+    32: '8rem',
+    40: '10rem',
+    48: '12rem',
+    56: '14rem',
+    64: '16rem',
+  },
+};
+```
+
+By default, these values are inherited by the `padding`, `margin`, `negativeMargin`, `width` and `height` core plugins.
+
+To learn more, see [Customizing Spacing](https://tailwindcss.com/docs/customizing-spacing).
+
+## Core Plugins
+
+The rest of the theme section is used to configure the values available for each core plugin.
+
+For example, the ``borderRadius`` property allows you to customize the ``utilities` that will generate the rounded corners.
+
+``js
+const designSystem = {
+  borderRadius: {
+    none: '0',
+    sm: '.125rem',
+    default: '.25rem',
+    lg: '.5rem',
+    full: '9999px',
+  },
+};
+```
+
+** The property name determines the suffix of the generated class, and the value determines the value of the actual CSS declaration. **
+The example ``borderRadius`` configuration above will generate the following CSS classes.
+
+```css
+.rounded-none { border-radius: 0 }
+.rounded-sm { border-radius: .125rem }
+.rounded { border-radius: .25rem }
+.rounded-lg { border-radius: .5rem }
+.rounded-full { border-radius: 9999px }
+```
+
+You will notice that the `rounded` class is created without the suffix in the theme configuration using the `default` attribute. This is a common convention in Tailwind CSS that is supported by many (though not all) core plugins.
+
+To learn more about customizing a specific core plugin, please visit the documentation for that plugin.
+
+## Customizing the default configuration
+
+Out of the box, your project will automatically inherit values from the default theme configuration. If you want to customize the default theme, there are several different options depending on the goal.
+
+### Override the default configuration
+
+To override the options in the default configuration, add the attributes to be overridden in ``designSystem`'' at
+
+```js title="modern.config.js"
+const designSystem = {
+  // Replaces all of the default `opacity` values
+  opacity: {
+    0: '0',
+    20: '0.2',
+    40: '0.4',
+    60: '0.6',
+    80: '0.8',
+    100: '1',
+  },
+};
+
+export default defineConfig({
+  source: {
+    designSystem,
+  },
+});
+```
+
+This will completely replace the default property configuration, so in the above example, the default `opacity utilities` will not be generated.
+
+Any properties you don't provide will be inherited from the default theme, so in the above example, the default theme configuration for color, spacing, border rounding, background position, etc. will be retained.
+
+### Extending the default configuration
+
+If you want to keep the default values of the theme options but add new values, add the extensions under the `designSystem.extend` property.
+
+For example, if you want to add an additional breakpoint but keep the existing one, you can extend the `screens` property with.
+
+```js title="modern.config.js"
+const designSystem = {
+  extend: {
+    // Adds a new breakpoint in addition to the default breakpoints
+    screens: {
+      '2xl': '1440px',
+    },
+  },
+};
+
+export default defineConfig({
+  source: {
+    designSystem,
+  },
+});
+```
+
+You can of course override some parts of the default theme and extend other parts of the default theme in the same configuration: the
+
+```js title="modern.config.js"
+const designSystem = {
+  opacity: {
+    0: '0',
+    20: '0.2',
+    40: '0.4',
+    60: '0.6',
+    80: '0.8',
+    100: '1',
+  },
+  extend: {
+    screens: {
+      '2xl': '1440px',
+    },
+  },
+};
+
+export default defineConfig({
+  source: {
+    designSystem,
+  },
+});
+```
+
+### Referencing other values
+
+If you need to reference another value in the configuration, you can do so by providing a closure function instead of a static value. The function will receive the `theme()` function as an argument, and you can use this function to find other values in the configuration using the dot representation.
+
+For example, you can generate `fill` utilities for each color in the palette by referring to `theme('colors')` on the `fill` configuration.
+
+```js title="modern.config.js"
+const designSystem = {
+  colors: {
+    // ...
+  },
+  fill: theme => theme('colors'),
+};
+
+export default defineConfig({
+  source: {
+    designSystem,
+  },
+});
+```
+
+The `theme()` function attempts to find the value you are looking for from an already fully merged configuration object, so it can reference your own custom settings as well as the default theme value. It also works recursively, so as long as there is a static value at the end of the chain, it can resolve the value you are looking for.
+
+**Reference to the default configuration**
+
+If for any reason you want to reference a value in the default configuration, you can import it from `tailwindcss/defaultTheme`. A useful example would be to add one of the fonts provided by the default configuration to.
+
+```js title="modern.config.js"
+const defaultTheme = require('tailwindcss/defaultTheme');
+
+const designSystem = {
+  extend: {
+    fontFamily: {
+      sans: ['Lato', . .defaultTheme.fontFamily.sans],
+    },
+  },
+};
+
+export default defineConfig({
+  source: {
+    designSystem,
+  },
+});
+```
+
+### Disabling the entire core plugin
+
+If you don't want to generate any classes for a core plugin, it is better to set the plugin to ``false`` in the ``corePlugins` configuration, rather than providing an empty object for the property in the configuration: ``
+
+```js
+// Don't assign an empty object in your theme configuration
+
+const designSystem = {
+  opacity: {},
+};
+
+// Do disable the plugin in your corePlugins configuration
+const designSyttem = {
+  corePlugins: {
+    opacity: { false,
+  },
+};
+```
+
+The end result is the same, but since many core plugins don't expose any configuration, it's best to keep it consistent by only disabling them with corePlugins anyway.
+
+### Add your own key
+
+In many cases it may be useful to add your own properties to the configuration object.
+
+One example is to add new properties for multiplexing between multiple core plugins. For example, you can extract a ``positions`` object that both the ``backgroundPosition`` and ``objectPosition`` plugins can refer to.
+
+```js
+const designSystem = {
+  positions: {
+    bottom: 'bottom',
+    center: 'center',
+    left: 'left',
+    'left-bottom': 'left bottom',
+    'left-top': 'left top',
+    right: 'right',
+    'right-bottom': 'right bottom',
+    'right-top': 'right top',
+    top: 'top',
+  },
+  backgroundPosition: theme => theme('positions'),
+  objectPosition: theme => theme('positions'),
+};
+```
+
+Another example is to add a new property to a custom plugin for referencing. For example, if you write a gradient plugin for your project, you can add a gradient property to the theme object referenced by that plugin.
+
+```js title="modern.config.js"
+const designSystem = {
+  gradients: theme => ({
+    'blue-green': [theme('colors.blue.500'), theme('colors.green.500')],
+    'purple-blue': [theme('colors.purple.500'), theme('colors.blue.500')],
+    // ...
+  }),
+};
+
+export default defineConfig({
+  source: {
+    designSystem,
+  },
+  tools: {
+    tailwind: {
+      plugins: [require('. /plugins/gradients')],
+    },
+  },
+});
+```
+
+## Configuration references
+
+All properties in the configuration object, except `screens`, `colors` and `spacing`, map to the core plugins of `Tailwind CSS`. Since many plugins are responsible for CSS properties that accept only static sets of values (e.g., e.g., `float`), please note that not every plugin has a corresponding property in the theme object.
+
+All of these properties can also be used under the `designSystem.extend` property to extend the default theme.
+
+For more information about what all the properties do, check this [link](https://tailwindcss.com/docs/theme#configuration-reference).
+
+## Additional Configuration
+
+In addition to the same configuration as Tailwind CSS Theme, there are additional configurations provided by Modern.js.
+
+### supportStyledComponents
+
+- type: `boolean`
+- default: `false`
+
+With the value `true`, the `styled-components` `ThemeProvider` component is provided in the outer layer of the application at runtime and the `Theme Token` object generated by the `designSystem` is injected.

package/docs/en/api/dev.md

@@ -0,0 +1,32 @@
+# Dev
+
+## storybook
+
+For Storybook configuration see: [Storybook Configuration](https://storybook.js.org/docs/react/configure/overview)
+
+:::info
+To use Storybook for debugging, you need to enable the "Visual Testing (Storybook)" mode feature by executing the new command under the project in advance.
+:::
+
+```js
+export default {
+  dev: {
+    storybook: {
+      addons: ['@storybook/addon-essentials'],
+      babel: async (options) => ({
+        // Update your babel configuration here
+        ...options,
+      }),
+      framework: '@storybook/react',
+      stories: ['../src/**/*.stories.@(js|mdx)'],
+      webpackFinal: async (config, { configType }) => {
+        // Make whatever fine-grained changes you need
+        // Return the altered config
+        return config;
+      },
+    }
+  }
+}
+
+```
+

package/docs/en/api/index.md

@@ -0,0 +1,3 @@
+---
+pageType: 'api'
+---

package/docs/en/api/plugin.md

@@ -0,0 +1,34 @@
+# Plugins
+This section describes the configuration related to the plugin
+
+- type: `CliPlugin<ModuleToolsHooks>[]`
+- default: `[]`
+
+```js
+export default (): CliPlugin<ModuleToolsHooks> => {
+  return {
+    name: 'dev-plugin-example',
+    setup: () => {
+      return {
+        registerDev() {
+          return {
+            name: 'plugin-example',
+            menuItem: {
+              name: 'dev-example',
+              value: 'dev-example',
+            },
+            action() {
+              console.info('running dev-example');
+            },
+          };
+        },
+        beforeDevMenu(originQuestion) {
+          return originQuestion;
+        },
+      };
+    },
+  };
+};
+```
+
+Check out[插件](https://modernjs.dev/docs/apis/app/runtime/plugin/plugin-api)for more information

package/docs/en/api/test.md

@@ -0,0 +1,48 @@
+# Testing
+
+:::tips
+You need to enable the unit testing feature with `pnpm run new` first.
+:::
+
+
+## jest
+* Type: `Object | Function`
+* Default value: `{}`
+
+The configuration corresponding to [Jest](https://jestjs.io/docs/configuration), when of type ``Object``, can be configured with all the underlying configurations supported by Jest .
+
+```js title=modern.config.js
+export default defineConfig({
+  testing: {
+    jest: {
+      testTimeout: 10000
+    }
+  }
+});
+```
+
+When the value is of type ``Function``, the default configuration is passed in as the first parameter and a new Jest configuration object needs to be returned.
+
+```js title=modern.config.js
+export default defineConfig({
+  testing: {
+    jest: options => {
+      return {
+        ... . options,
+        testTimeout: 10000
+      }
+    }
+  }
+});
+```
+
+## transformer
+
+- Type: `'babel-jest' | 'ts-jest'`
+- Default value: `babel-jest`
+
+Configure the compilation tool for the source code when executing tests: [babel-jest](https://www.npmjs.com/package/babel-jest) or [ts-jest](https://github.com/kulshekhar/ts-jest). The default is `babel-jest`.
+
+:::info
+`babel-jest` can also compile TS files without type errors, so use `ts-jest` if you need to check the TS type when running tests.
+:::