u2-component/README.md

U2Component is a cross-framework component library inspired by the Material Design 3 design system, based on web component.

<div align="center">
  <img src="https://github.com/ShawnDGitHub/imgPack/blob/main/img/icon_vertical_v1.0.png" alt="The logo of U2Component"/>
</div>
<div align="center">
  <img src="https://img.shields.io/badge/License-Apache--2.0_license-green" alt="License"/>
  <img src="https://img.shields.io/badge/stars-2-orange" alt="stars"/>
</div>

> U2Component is a cross-framework component library inspired by the Material Design 3 design system, based on web component. The project is being refactored.

[中文](https://github.com/ShawnDGitHub/U2Component/blob/main/README-zh.md)

## menu

- [Introduction](#Introduction)
- [Notice](#Notice)
- [Instructions](#Instructions)
  - [theme](#theme)
  - [Import](#Import)
- [Components](#components)
- [Doc](#Doc)
  - [text field](#text-field)
  - [textarea](#textarea)
  - [select](#select)
  - [button](#button)
  - [segmented button](#segmented-button)
  - [form](#form)
  - [form-item](#form-item)

## Introduction
U2Component is a component library based on **web component**. You can change the color of all components at once by replacing the CSS file "token.css", all component colors and fonts use design tokens.
## Notice
1. Please make sure that you use this component library for development on **mainstream browsers**.
2. Make sure you set ```font-size: 1rem``` on  html. Some styles use rem and em units.
## Instructions
### theme

**Color tokens**

The css files in ""/style" folder are generated by  or **Figma plugin** [Material Theme Builder](https://www.figma.com/community/plugin/1034969338659738588/material-theme-builder). Choose "Export" - "Web(CSS)", just replace the token.css.

> **[Material-Theme-Builder web](https://material-foundation.github.io/material-theme-builder/)**:  as they have updated this tool, it will not generated token.css now.

I am trying to design a repository that can generate the token required for U2Component theme, stay tuned.

**Icon (TODO)**

The previous icon library used material-symbols, which has now been removed and will be supported in the future.

### Import
#### Package Manager / Framework
**setp 1**
```js
npm install u2-component
```

**setp 2**

For *Vite (vue)*

```js
// vite.config.js
export default defineConfig({
  plugins: [
    vue({
      template: {
        compilerOptions: {
          isCustomElement: (tag) => tag.startsWith('u2-'),
        },
      },
    }),
  ],
});
```

For *Vue CLI / Webpack (vue)*

```js
// vue.config.js
module.exports = {
  chainWebpack: config => {
    config.module
      .rule('vue')
      .use('vue-loader')
      .tap(options => {
        options.compilerOptions = {
          isCustomElement: (tag) => tag.startsWith('u2-')
        };
        return options;
      });
  }
};
```

**final setp**
For *vue*

```typescript
// main.ts
import U2Component from 'u2-component'
import 'u2-component/style' // import style

import { createApp } from 'vue'
const app = createApp(App)
app.use(U2Component) // install
app.mount('#app')
```

For *react* (in progress)

#### Without framework
You can download the github repository file and import it directly.

**1. Import style**
The style file contains various tokens, such as **light and dark themes**.
```html
<link rel="stylesheet" type="text/css" href="../style/theme.css">
```
**2. Import component**
Just import it into the HTML file (there are many parameters that can be adjusted):

```html
<script src="../components/TextField.js" type="module"></script>
```

## Components
| name          | state                  | the name when using      |
| :---------------: | :------------------------- | :------------- |
| text field         | stable                      | u2-field    |
| textarea         | stable                      | u2-textarea    |
| select         | may change                 | u2-Select    |
| filled button  | stable                       | u2-button variant="filled"  |
| outlined button    | stable                       | u2-button variant="outlined"      |
| text button       | stable                       | u2-button       |
| segmented button   | may change                  | segmented-button  |
| form   | may change                  | u2-form  |
| form item   | may change                  | u2-form-item  |

## Doc
### text-field

<div align="center">
  <img src="https://github.com/ShawnDGitHub/imgPack/blob/main/img/u2_example-text-field.png" alt="examples of text field"/>
</div>

Basic use. it will auto add a placeholder attribute to itself.
```html
  <u2-field variant="filled"></u2-field>
  <u2-field variant="outlined"></u2-field>
```
There are two types of text field: filled and outlined. **variant attribute is required**.
```html
  <u2-field
      variant="filled"
      label="username"
      autocomplete="name"
      width="240">
  </u2-field>
  <u2-field
      variant="outlined"
      placeholder="verify code"
      type="password">
  </u2-field>
```
parameter:
(\*) means required

1. **variant**(\*) : 
The style type of the text input box. In Material 3, this component has two style variants: filled and outlined.
2. **value** : 
Set default input.
3. **placeholder** : 
The placeholder text to be displayed in the initial state when the user has not input anything.
4. **label** :
A label may float to top when user focus on text field. **You can't set both of label and placeholder**.
5. **width** : 
*The default unit is px, and percentage units are not supported*. You can specify the width of the component, and the width of the component will no longer fill the width of the parent element. (*TextField has a maximum width of 112 px in M3 Doc*, but I designed a property to help you remove this limitation.)
6. **fullWidth** : 
Here it comes. The component will fill the container width.
7. **type** : 
Set ```type="password"``` to let input be invisible.
8. **disabled** : 
Set ```disabled``` to make it uninputable.

### textarea

<div align="center">
  <img src="https://github.com/ShawnDGitHub/imgPack/blob/main/img/u2_example-textarea.png" alt="examples of textarea"/>
</div>

```html
  <u2-textarea
      variant="filled"
      label="note"
      height="200">
  </u2-textarea>
```
parameter:
(\*) means required

1. **variant**(\*) : 
This component has two style variants: filled and outlined.
2. **value** :
3. **placeholder** 
4. **label** 
5. **width**
6. **height**

### select

<div align="center">
  <img src="https://github.com/ShawnDGitHub/imgPack/blob/main/img/u2_example-select.png" alt="examples of select"/>
</div>

Same as the native web select, put option element in it.
```html
  <u2-select
      variant="filled"
      label="type selector">
      <option value="1">inner option 1</option>
      <option value="2">inner option 2</option>
  </u2-select>
```
parameter:
(\*) means required
1. **variant**(\*) : 
This component has two style variants: filled and outlined.
2. **label**(\*)
3. **disabled**

### button

<div align="center">
  <img src="https://github.com/ShawnDGitHub/imgPack/blob/main/img/u2_example-buttons.png" alt="examples of buttons"/>
</div>

```html
  <u2-button>text button</u2-button>
  <u2-button variant="filled">filled button</u2-button>
  <u2-button variant="outlined">outlined button</u2-button>
  <u2-button disabled>disabled state</u2-button>
```
parameter:
(\*) means required
1. **variant** : 
This component has three style variants: text, filled and outlined. *If you don't set this attribute, it will fallback to default text type*.
2. **disabled**

### segmented-button

<div align="center">
  <img src="https://github.com/ShawnDGitHub/imgPack/blob/main/img/u2_example-segmented-button.png" alt="example of segmented button"/>
</div>

```html
  <segmented-button>
      <u2-button>option 1</u2-button>
      <u2-button>option 2</u2-button>
      <u2-button>option 3</u2-button>
  </segmented-button>
```
no parameter is needed.

### form
For validation usage.

<div align="center">
  <img src="https://github.com/ShawnDGitHub/imgPack/blob/main/img/u2_example-validation.png" alt="example of form validation"/>
</div>

```html
  <u2-form>
      <u2-form-item prop="age">
          <u2-field
              variant="filled"
              label="age"
              fullWidth>
          </u2-field>
      </u2-form-item>
  </u2-form>
```
When setting rules for form, the inner element form item must have a prop attribute.
```javascript
const FORM = document.getElementsByTagName("U2-FORM")[0];
const rules = {
    age: [
        {
            required: true,
            trigger: "change",
        },
    ]
}
FORM.rules = rules; // (*)
```
When using it in vue or react, you also need to get form first and set the rules configuration of form. (Pass it like (\*) line)

**The configuration requirements of the rules are the same as Element Plus**.

### form-item
See upper case. **Put form item into u2-form component**.