Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 3 commits into from
Nov 24, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions .i18nrc.js
Original file line number Diff line number Diff line change
@@ -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',
};
121 changes: 121 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -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
112 changes: 112 additions & 0 deletions docs/api/create-instance.en-US.md
Original file line number Diff line number Diff line change
@@ -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. |
3 changes: 3 additions & 0 deletions docs/api/create-instance.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,9 @@ sourceUrl: '{github}/blob/master/src/functions/createInstance.ts'
group:
title: 高级设置
order: 10
nav:
title: API
order: 10
---

## 简介
Expand Down
Loading