zed-gpui 0.1.1 â 0.2.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +130 -85
- package/dist/{index.d.mts â index.d.ts} +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
#
|
|
1
|
+
# zed-gpui
|
|
2
2
|
|
|
3
3
|
[](https://www.npmjs.org/package/zed-gpui)
|
|
4
4
|
[](https://www.npmjs.org/package/zed-gpui)
|
|
@@ -8,121 +8,166 @@
|
|
|
8
8
|
<img src="../../assets/icon.png" width="240px" alt="zed-gpui logo" />
|
|
9
9
|
</p>
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
A small TypeScript / Web UI framework with a **gpui-inspired** style.
|
|
12
12
|
|
|
13
|
-
|
|
13
|
+
Its core characteristics are simple and explicit:
|
|
14
14
|
|
|
15
|
-
|
|
15
|
+
- **Chainable API**: methods return `this` so calls can be composed fluently
|
|
16
|
+
- **All instance methods end with `_`**: such as `flex_()`, `w_()`, `onClick_()`
|
|
17
|
+
- **Directly uses native DOM**: the returned value is an actual `HTMLElement`
|
|
18
|
+
- **Creates elements by tag**: `div()`, `btn()`, `input()`, `h('section')`
|
|
19
|
+
- **Adds capabilities through prototype enhancement**: styling, attributes, events, and form helpers live on native elements
|
|
16
20
|
|
|
17
|
-
|
|
18
|
-
- ⥠**Event handling** - Comprehensive event listeners (mouse, keyboard, touch, drag & drop, etc.)
|
|
19
|
-
- ð§ **Type-safe** - Full TypeScript support with type inference
|
|
20
|
-
- ðŠķ **Lightweight** - Zero dependencies, tree-shakeable
|
|
21
|
-
|
|
22
|
-
## Installation
|
|
21
|
+
## Install
|
|
23
22
|
|
|
24
23
|
```bash
|
|
25
24
|
pnpm add zed-gpui
|
|
26
25
|
```
|
|
27
26
|
|
|
28
|
-
##
|
|
29
|
-
|
|
30
|
-
```typescript
|
|
31
|
-
import { div, p, btn } from 'zed-gpui';
|
|
27
|
+
## Design conventions
|
|
32
28
|
|
|
33
|
-
|
|
34
|
-
const container = div().flex().gap('1rem').p('2rem').bg('#f0f0f0');
|
|
29
|
+
### 1. Chain-first API
|
|
35
30
|
|
|
36
|
-
|
|
31
|
+
Almost every method returns the current element, so the normal style is fluent chaining:
|
|
37
32
|
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
.
|
|
41
|
-
.
|
|
42
|
-
.
|
|
43
|
-
.
|
|
44
|
-
.
|
|
45
|
-
.
|
|
46
|
-
.text('Click Me');
|
|
47
|
-
|
|
48
|
-
// Build and append to DOM
|
|
49
|
-
document.body.append(container.build(), title.build(), button.build());
|
|
33
|
+
```ts
|
|
34
|
+
const app = div()
|
|
35
|
+
.flex_()
|
|
36
|
+
.items_('center')
|
|
37
|
+
.justify_('center')
|
|
38
|
+
.w_('100%')
|
|
39
|
+
.h_('100vh')
|
|
40
|
+
.bg_('#f5f5f5');
|
|
50
41
|
```
|
|
51
42
|
|
|
52
|
-
|
|
43
|
+
### 2. Every method ends with an underscore
|
|
53
44
|
|
|
54
|
-
|
|
45
|
+
This is one of the most recognizable parts of the library.
|
|
55
46
|
|
|
56
|
-
```
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
47
|
+
```ts
|
|
48
|
+
id_()
|
|
49
|
+
class_()
|
|
50
|
+
child_()
|
|
51
|
+
text_()
|
|
52
|
+
onClick_()
|
|
53
|
+
placeholder_()
|
|
62
54
|
```
|
|
63
55
|
|
|
64
|
-
|
|
56
|
+
The goal is straightforward:
|
|
65
57
|
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
.grid() // display: grid
|
|
70
|
-
.gridTemplateColumns('1fr 1fr')
|
|
71
|
-
.block() // display: block
|
|
72
|
-
.hidden() // display: none
|
|
73
|
-
```
|
|
58
|
+
- distinguish framework methods from native properties
|
|
59
|
+
- distinguish chainable element methods from ordinary utility functions
|
|
60
|
+
- make zed-gpui calls visually obvious at a glance
|
|
74
61
|
|
|
75
|
-
###
|
|
62
|
+
### 3. The result is real DOM, not a virtual node
|
|
76
63
|
|
|
77
|
-
```
|
|
78
|
-
.
|
|
79
|
-
.
|
|
80
|
-
.py('1rem') // padding-top & bottom
|
|
81
|
-
.m('1rem') // margin
|
|
82
|
-
.mx('auto') // margin-left & right
|
|
83
|
-
.gap('1rem') // gap (for flex/grid)
|
|
64
|
+
```ts
|
|
65
|
+
const node = div().text_('hello');
|
|
66
|
+
document.body.appendChild(node);
|
|
84
67
|
```
|
|
85
68
|
|
|
86
|
-
|
|
69
|
+
`node` is a real `HTMLDivElement`, not a virtual DOM node and not an intermediate description object.
|
|
70
|
+
|
|
71
|
+
## Quick example
|
|
72
|
+
|
|
73
|
+
```ts
|
|
74
|
+
import { div, btn, input } from 'zed-gpui';
|
|
75
|
+
|
|
76
|
+
const app = div()
|
|
77
|
+
.flex_()
|
|
78
|
+
.flexDirection_('column')
|
|
79
|
+
.gap_('12px')
|
|
80
|
+
.items_('center')
|
|
81
|
+
.justify_('center')
|
|
82
|
+
.w_('100%')
|
|
83
|
+
.h_('100vh');
|
|
84
|
+
|
|
85
|
+
const field = input()
|
|
86
|
+
.placeholder_('Enter text...')
|
|
87
|
+
.px_('12px')
|
|
88
|
+
.py_('8px')
|
|
89
|
+
.border_()
|
|
90
|
+
.rounded_('8px')
|
|
91
|
+
.w_('280px')
|
|
92
|
+
.onInput_((event) => {
|
|
93
|
+
console.log(event.currentTarget.value);
|
|
94
|
+
});
|
|
87
95
|
|
|
88
|
-
|
|
89
|
-
.
|
|
90
|
-
.
|
|
91
|
-
.
|
|
92
|
-
.
|
|
93
|
-
.
|
|
96
|
+
const button = btn()
|
|
97
|
+
.text_('Click me')
|
|
98
|
+
.px_('16px')
|
|
99
|
+
.py_('10px')
|
|
100
|
+
.bg_('blue')
|
|
101
|
+
.textColor_('white')
|
|
102
|
+
.rounded_('8px')
|
|
103
|
+
.cursorPointer_()
|
|
104
|
+
.onClick_(() => {
|
|
105
|
+
console.log('clicked');
|
|
106
|
+
});
|
|
107
|
+
|
|
108
|
+
app.child_(field, button);
|
|
109
|
+
document.body.appendChild(app);
|
|
94
110
|
```
|
|
95
111
|
|
|
96
|
-
|
|
112
|
+
## API style
|
|
97
113
|
|
|
98
|
-
|
|
99
|
-
.bg('#fff') // background-color
|
|
100
|
-
.bgImage('url(...)') // background-image
|
|
101
|
-
.text('#333') // color
|
|
102
|
-
.borderColor('#ccc') // border-color
|
|
103
|
-
```
|
|
114
|
+
### Create elements
|
|
104
115
|
|
|
105
|
-
|
|
116
|
+
```ts
|
|
117
|
+
div();
|
|
118
|
+
span();
|
|
119
|
+
section();
|
|
120
|
+
p();
|
|
121
|
+
btn();
|
|
122
|
+
input();
|
|
123
|
+
textarea();
|
|
124
|
+
select([{ value: 1, label: 'One' }]);
|
|
125
|
+
h('dialog');
|
|
126
|
+
```
|
|
106
127
|
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
.
|
|
112
|
-
.
|
|
128
|
+
### Common capabilities
|
|
129
|
+
|
|
130
|
+
```ts
|
|
131
|
+
div()
|
|
132
|
+
.id_('app')
|
|
133
|
+
.class_('container')
|
|
134
|
+
.child_(span().text_('hello'))
|
|
135
|
+
.w_('320px')
|
|
136
|
+
.h_('80px')
|
|
137
|
+
.p_('16px')
|
|
138
|
+
.rounded_('12px')
|
|
139
|
+
.shadowMd_()
|
|
140
|
+
.onClick_(() => {});
|
|
113
141
|
```
|
|
114
142
|
|
|
115
|
-
|
|
143
|
+
The API surface broadly includes:
|
|
116
144
|
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
145
|
+
- element attributes: `id_`, `attr_`, `name_`
|
|
146
|
+
- children and text: `child_`, `text_`
|
|
147
|
+
- layout: `flex_`, `grid_`, `justify_`, `items_`
|
|
148
|
+
- sizing and spacing: `w_`, `h_`, `p_`, `m_`, `gap_`
|
|
149
|
+
- border and radius: `border_`, `borderColor_`, `rounded_`
|
|
150
|
+
- color and typography: `bg_`, `textColor_`, `textSize_`
|
|
151
|
+
- positioning and overflow: `absolute_`, `top_`, `overflow_`
|
|
152
|
+
- events: `onClick_`, `onInput_`, `onChange_`, `on_`
|
|
153
|
+
- form helpers: `value_`, `placeholder_`, `checked_`, `options_`
|
|
154
|
+
|
|
155
|
+
## Good fit for
|
|
156
|
+
|
|
157
|
+
This library is a good match if you want to:
|
|
158
|
+
|
|
159
|
+
- build UI directly with **native DOM**
|
|
160
|
+
- use a **chainable API** for styling and events
|
|
161
|
+
- keep a consistent naming style with **underscore-suffixed methods**
|
|
162
|
+
- write lightweight pages, tools, panels, or experimental UI
|
|
163
|
+
|
|
164
|
+
## Repository structure
|
|
165
|
+
|
|
166
|
+
This repository is a monorepo and mainly contains:
|
|
167
|
+
|
|
168
|
+
- `zed-gpui`: the main runtime package
|
|
169
|
+
- `unplugin-zed-gpui-treeshake`: the companion tree-shaking plugin
|
|
170
|
+
- `@zed-gpui/example`: the example project
|
|
126
171
|
|
|
127
172
|
## License
|
|
128
173
|
|