Skip to content

Commit ee94c8f

Browse files
wibus-weewibus-wee
committed
docs: document
1 parent 7966cc0 commit ee94c8f

File tree

7 files changed

+354
-8
lines changed

7 files changed

+354
-8
lines changed

‎docs/.vitepress/config.ts

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ export default defineConfig({
1515
},
1616

1717
nav: [
18-
{ text: 'Guide', link: '/guide/' },
18+
{ text: 'Guide', link: '/guide/quick-start', activeMatch: '^/guide/' },
1919
],
2020

2121
sidebar: {
@@ -32,19 +32,19 @@ export default defineConfig({
3232
{
3333
text: 'Components', items: [{
3434
text: 'Defining',
35-
link: '/guide/defining',
35+
link: '/components/defining',
3636
}, {
3737
text: 'Rendering',
38-
link: '/guide/rendering',
38+
link: '/components/rendering',
3939
}, {
40-
text: 'Reactivity',
41-
link: '/guide/reactivity',
40+
text: 'Reactive properties',
41+
link: '/components/reactive-properties',
4242
}, {
4343
text: 'Styles',
44-
link: '/guide/styles',
44+
link: '/components/styles',
4545
}, {
4646
text: 'Lifecycle',
47-
link: '/guide/lifecycle',
47+
link: '/components/lifecycle',
4848
},],
4949
},
5050
]

‎docs/components/defining.md

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# Defining a Component
2+
3+
Define a Jwc component by creating a class that extends `JwcComponent` or a function that returns a `JSX Element`.
4+
5+
::: code-group
6+
7+
```tsx [Class Based]
8+
@JwcComponent({ name: "app-element" })
9+
export class App extends JwcComponent {
10+
/* ... */
11+
}
12+
```
13+
14+
```js [Function Based <Badge text="Not yet implemented" type="danger"/>]
15+
// no yet implemented
16+
```
17+
18+
:::
19+
20+
## Class Based
21+
22+
The `@JwcComponent` decorator is used to define a Jwc component. It takes an object with the following properties:
23+
24+
- `name` - The name of the component. This is used to identify the component in the DOM. It must be unique.
25+
- [`css`](./styles.md) - The CSS to be applied to the component. The CSS is applied to the shadow DOM of the component.
26+
- `options` - The options to be passed to the component. Follows the ElementDefinitionOptions interface from the [Custom Elements API](https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/define#Parameters).
27+
28+
I recommend you do not use JavaScript to define your component. Instead, use TypeScript. This will allow you to use the `@JwcComponent` decorator to define your component.
29+
30+
But if you do use JavaScript or you want to define without using the decorator:
31+
32+
```js
33+
const options = { // [!code ++]
34+
name: "app-element", // [!code ++]
35+
/* ... */
36+
}; // [!code ++]
37+
38+
@JwcComponent({ name: "app-element" /* ... */ }) // [!code --]
39+
export class App extends JwcComponent {
40+
constructor() {
41+
super();
42+
// inject options into the component
43+
this.$options.options = options; // [!code ++]
44+
/* ... */
45+
}
46+
/* ... */
47+
}
48+
customElements.define("app-element", App, options.options); // [!code ++]
49+
```
50+
51+
Make sure to inject the options into the component. This is required for the component to work properly.
52+
53+
```js
54+
/* ... */
55+
export class App extends JwcComponent {
56+
constructor() {
57+
super();
58+
// MAKE SURE: inject options into the component// [!code focus]
59+
this.$options.options = options; // [!code focus]
60+
/* ... */
61+
}
62+
/* ... */
63+
}
64+
/* ... */
65+
```
66+
67+
68+
## Function Based <Badge text="Not yet implemented" type="danger"/>
69+
70+
Not yet implemented.

‎docs/components/lifecycle.md

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
---
2+
outline: deep
3+
---
4+
5+
# Lifecycle
6+
7+
Web components have a lifecycle. This lifecycle is similar to the lifecycle of a Vue component. The lifecycle of a web component is as follows:
8+
9+
- `constructor` - The constructor is called when the component is created. This is where you can initialize the component.
10+
- `connectedCallback` - The connected callback is called when the component is added to the DOM.
11+
- `disconnectedCallback` - The disconnected callback is called when the component is removed from the DOM.
12+
- `attributeChangedCallback` - The attribute changed callback is called when an attribute of the component is changed.
13+
- `adoptedCallback` - The adopted callback is called when the component is moved to a new document.
14+
15+
In class-based components, you can override these methods. In function-based components, you maybe use another way to do this.
16+
17+
## Class Based
18+
19+
### Constructor
20+
21+
The constructor is called when the component is created. This is where you can initialize the component.
22+
23+
```ts
24+
@JwcComponent({ name: "app-element" })
25+
export class App extends JwcComponent {
26+
constructor() {
27+
super();
28+
// Initialize the component
29+
}
30+
}
31+
```
32+
33+
Jwc will get the `options` property from the `@JwcComponent` decorator and pass it to the constructor. Then initialize the reactive properties of the component.
34+
35+
### Connected callback
36+
37+
The connected callback is called when the component is added to the DOM.
38+
39+
```ts
40+
@JwcComponent({ name: "app-element" })
41+
export class App extends JwcComponent {
42+
override connectedCallback() {
43+
super.connectedCallback();
44+
// The component is added to the DOM
45+
}
46+
}
47+
```
48+
49+
Jwc will call the `connectedCallback` method of the parent class. Then call the `connectedCallback` method of the child class.
50+
51+
Jwc will init shadowRoot in the `connectedCallback` method. Then setAttributes and setProperties in the `connectedCallback` method.
52+
53+
At last, Jwc will render the component in the `connectedCallback` method and append the rendered result to the shadowRoot.
54+
55+
### Disconnected callback
56+
57+
The disconnected callback is called when the component is removed from the DOM.
58+
59+
```ts
60+
@JwcComponent({ name: "app-element" })
61+
export class App extends JwcComponent {
62+
override disconnectedCallback() {
63+
super.disconnectedCallback();
64+
// The component is removed from the DOM
65+
}
66+
}
67+
```
68+
69+
Jwc will call the `disconnectedCallback` method of the child class. Then call the `disconnectedCallback` method of the parent class.
70+
71+
Jwc will remove the rendered result from the shadowRoot in the `disconnectedCallback` method.
72+
73+
### Attribute changed callback
74+
75+
The attribute changed callback is called when an attribute of the component is changed.
76+
77+
```ts
78+
@JwcComponent({ name: "app-element" })
79+
export class App extends JwcComponent {
80+
override attributeChangedCallback(
81+
name: string,
82+
oldValue: string | null,
83+
newValue: string | null
84+
) {
85+
super.attributeChangedCallback(name, oldValue, newValue);
86+
// An attribute of the component is changed
87+
}
88+
}
89+
```
90+
91+
Jwc will call the `attributeChangedCallback` method of the parent class. Then call the `attributeChangedCallback` method of the child class.
92+
93+
Jwc will update dom in the `attributeChangedCallback` method.
94+
95+
### Adopted callback
96+
97+
The adopted callback is called when the component is moved to a new document.
98+
99+
```ts
100+
@JwcComponent({ name: "app-element" })
101+
export class App extends JwcComponent {
102+
override adoptedCallback() {
103+
super.adoptedCallback();
104+
// The component is moved to a new document
105+
}
106+
}
107+
```
108+
109+
Jwc do nothing in the `adoptedCallback` method by default.
110+
111+
## Function Based <Badge text="Not yet implemented" type="danger"/>
112+
113+
Not yet implemented

‎docs/components/reactive-properties.md

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Reactive properties
2+
3+
::: warning
4+
Jwc only has reactive properties. It means that you can't define a reactive state in a component.
5+
:::
6+
7+
Jwc components have reactive properties. These properties are automatically updated when the component is updated.
8+
9+
10+
::: code-group
11+
12+
```tsx [Class Based]
13+
@JwcComponent({ name: "app-element" })
14+
export class App extends JwcComponent {
15+
@Prop() name: string = "World";
16+
override render() {
17+
return <div>{this.name}</div>;
18+
}
19+
}
20+
```
21+
22+
```ts [Function Based <Badge text="Not yet implemented" type="danger"/>]
23+
// no yet implemented
24+
```
25+
26+
```html [index.html]
27+
<app-element name="John"></app-element>
28+
```
29+
:::
30+
31+
## Class Based
32+
33+
In a class based component, you can define reactive properties by adding a `@Prop` decorator to a property.
34+
35+
```ts
36+
@Prop({ type: String, default: "World" }) name: string;
37+
```
38+
39+
The `@Prop` decorator takes an object with the following properties:
40+
41+
- `type` - The type of the property. This is used to convert the property to the correct type. The default type is `string`.
42+
- `default` - The default value of the property. This is used when the property is not set. The default value is `undefined`.
43+
44+
To define the value of the property (like `name`) in html, you can use the `name` attribute.
45+
46+
```html
47+
<app-element name="John"></app-element>
48+
```
49+
50+
## Function Based <Badge text="Not yet implemented" type="danger"/>
51+
52+
Not yet implemented

‎docs/components/rendering.md

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Rendering a Component
2+
3+
You have 2 choices for rendering a component:
4+
5+
::: code-group
6+
7+
```tsx [Class Based]
8+
@JwcComponent({ name: "app-element" })
9+
export class App extends JwcComponent {
10+
/* ... */
11+
override render() {
12+
return <div>Hello World</div>;
13+
}
14+
}
15+
```
16+
17+
```ts [Function Based <Badge text="Not yet implemented" type="danger"/>]
18+
// no yet implemented
19+
```
20+
:::
21+
22+
## Class Based
23+
24+
Add a template to your component by adding a `render` method. The `render` method returns a `JSX Element`.
25+
26+
::: warning
27+
Different from React, we use `class` to define component className. Like this:
28+
29+
```tsx
30+
<div class="my-class"></div>
31+
// not <div className="my-class"></div>
32+
```
33+
:::
34+
35+
`render` method will return a VNode, which is a virtual node. It is a lightweight representation of a DOM node. It is used to create the DOM node.
36+
37+
we will call `render` method when the component is connected to the DOM.
38+
39+
## Function Based <Badge text="Not yet implemented" type="danger"/>
40+
41+
Not yet implemented

‎docs/components/styles.md

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# Styles
2+
3+
Styles are one of the most important parts of a component. You can define the styles of a component in two ways.
4+
5+
::: code-group
6+
```tsx [Class Based]
7+
import styles from "./app.css";
8+
@JwcComponent({ name: "app-element", css: styles })
9+
export class App extends JwcComponent {
10+
/* ... */
11+
}
12+
```
13+
14+
```js [Function Based <Badge text="Not yet implemented" type="danger"/>]
15+
// no yet implemented
16+
```
17+
:::
18+
19+
## Class Based
20+
21+
The `css` property of the `@JwcComponent` decorator is used to define the CSS of the component. The CSS is applied to the shadow DOM of the component.
22+
23+
```ts
24+
@JwcComponent({ name: "app-element", css: styles })
25+
```
26+
27+
The `styles` variable is a string that contains the CSS. You can use any CSS preprocessor you want. The CSS is automatically compiled to CSS.
28+
29+
```ts
30+
import styles from "./app.css";
31+
```
32+
33+
::: warning
34+
In `Vite`, the CSS import method is became different. You should add `?inline` to the end of the import statement.
35+
36+
```ts
37+
// In Vite
38+
import styles from "./app.css?inline";
39+
```
40+
:::
41+
42+
## Function Based <Badge text="Not yet implemented" type="danger"/>
43+
44+
Not yet implemented

0 commit comments

Comments
 (0)