@chocbite/ts-lib-ui 1.1.4 → 1.2.0
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/AGENTS.md +547 -9
- package/README.md +3 -0
- package/SOURCE.md +10313 -7355
- package/base/index.d.mts +2 -2
- package/base/index.mjs +68 -5
- package/base/index.mjs.map +1 -1
- package/canvas/index.d.mts +1 -1
- package/canvas/index.mjs +1 -1
- package/composition/index.d.mts +283 -0
- package/composition/index.mjs +2 -0
- package/composition-BlntkKR0.mjs +869 -0
- package/composition-BlntkKR0.mjs.map +1 -0
- package/context-menu/index.d.mts +1 -1
- package/context-menu/index.mjs +1 -1
- package/{context-menu-JAujBGVW.mjs → context-menu-C0KTV5zC.mjs} +2 -2
- package/{context-menu-JAujBGVW.mjs.map → context-menu-C0KTV5zC.mjs.map} +1 -1
- package/depot_ui/index.d.mts +60 -0
- package/depot_ui/index.mjs +280 -0
- package/depot_ui/index.mjs.map +1 -0
- package/form/index.d.mts +2 -758
- package/form/index.mjs +1 -2953
- package/form-CJA3s46n.mjs +2961 -0
- package/form-CJA3s46n.mjs.map +1 -0
- package/icons/index.d.mts +1 -1
- package/{index-76zZKjTH.d.mts → index-CApVOEcI.d.mts} +2 -2
- package/{index-ClIBfrHy.d.mts → index-Czy8O3me.d.mts} +5 -1
- package/index-DD09-bGe.d.mts +761 -0
- package/{index-D6L_jK1x.d.mts → index-U3pqQjLg.d.mts} +4 -4
- package/{index-ClfL2SQR.d.mts → index-_y7vmunA.d.mts} +72 -8
- package/keyboard/index.d.mts +1 -1
- package/keyboard/index.mjs +1 -1
- package/list/index.d.mts +1 -1
- package/list/index.mjs +1 -1
- package/{list-eV59DvUB.mjs → list-CVrn4y2k.mjs} +3 -3
- package/{list-eV59DvUB.mjs.map → list-CVrn4y2k.mjs.map} +1 -1
- package/package.json +2 -2
- package/prompts/index.d.mts +48 -0
- package/prompts/index.mjs +107 -0
- package/prompts/index.mjs.map +1 -0
- package/spinner/index.d.mts +1 -1
- package/spinner/index.mjs +1 -1
- package/style.css +2049 -1640
- package/svg/index.d.mts +1 -1
- package/svg-Yz7elqnU.mjs.map +1 -1
- package/theme/index.d.mts +1 -1
- package/theme/index.mjs +1 -1
- package/{theme-CpaCSGOf.mjs → theme-D0pRMLyT.mjs} +2 -2
- package/{theme-CpaCSGOf.mjs.map → theme-D0pRMLyT.mjs.map} +1 -1
- package/form/index.mjs.map +0 -1
- package/test/index.d.mts +0 -98
- package/test/index.mjs +0 -193
- package/test/index.mjs.map +0 -1
package/AGENTS.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# @chocbite/ts-lib-ui, notes for agents
|
|
2
2
|
|
|
3
|
-
@chocbite/ts-lib-ui 1.
|
|
3
|
+
@chocbite/ts-lib-ui 1.2.0, built from ssh://git@forgejo.nsns.dk:2222/chocbite/ts-lib.git at commit e86d86d, with uncommitted changes.
|
|
4
4
|
|
|
5
5
|
Read the sections for the modules you use before using them. The full source of this version is in `SOURCE.md` next to this file, every file under a `## <repo path>` heading, e.g. search it for `## package-ui/<module>/` to find a module.
|
|
6
6
|
|
|
@@ -66,6 +66,7 @@ SCSS mixins are available for use in your own styles:
|
|
|
66
66
|
|
|
67
67
|
- `@chocbite/ts-lib-ui/base`
|
|
68
68
|
- `@chocbite/ts-lib-ui/canvas`
|
|
69
|
+
- `@chocbite/ts-lib-ui/composition`
|
|
69
70
|
- `@chocbite/ts-lib-ui/context-menu`
|
|
70
71
|
- `@chocbite/ts-lib-ui/document`
|
|
71
72
|
- `@chocbite/ts-lib-ui/dom`
|
|
@@ -73,12 +74,463 @@ SCSS mixins are available for use in your own styles:
|
|
|
73
74
|
- `@chocbite/ts-lib-ui/icons`
|
|
74
75
|
- `@chocbite/ts-lib-ui/keyboard`
|
|
75
76
|
- `@chocbite/ts-lib-ui/list`
|
|
77
|
+
- `@chocbite/ts-lib-ui/prompts`
|
|
76
78
|
- `@chocbite/ts-lib-ui/selection`
|
|
77
79
|
- `@chocbite/ts-lib-ui/settings`
|
|
78
80
|
- `@chocbite/ts-lib-ui/spinner`
|
|
81
|
+
- `@chocbite/ts-lib-ui/state_ui`
|
|
79
82
|
- `@chocbite/ts-lib-ui/svg`
|
|
80
83
|
- `@chocbite/ts-lib-ui/theme`
|
|
81
84
|
|
|
85
|
+
## Writing your own elements
|
|
86
|
+
|
|
87
|
+
Elements of this package, and elements you write on its `Base`, follow the pattern below. Read it before writing an element. It names files by their repo path, find them in `SOURCE.md` under `## <path>`. The complete example it refers to is `package-ui/pattern_example/` in `SOURCE.md`, it is not exported from the package, copy from it instead of importing it. Paths under `dev/` are dev pages of the library repo and not part of the package.
|
|
88
|
+
|
|
89
|
+
### Element pattern
|
|
90
|
+
|
|
91
|
+
This is how elements of `@chocbite/ts-lib-ui` take their inputs, and the pattern to use from now on. Every new element follows it, and an existing element is converted to it when it is reworked.
|
|
92
|
+
|
|
93
|
+
Most existing elements still use an older style: constructor options, setters and getters, or `opts`. Don't copy those into new code.
|
|
94
|
+
|
|
95
|
+
The mechanics live in `Base` (`package-ui/base/base.ts`) and the key helpers in `package-ui/base/input.ts`. **`package-ui/pattern_example` is a complete example of every case below**, with tests. Copy from it when writing an element. It is not exported, and in the repo the dev page `dev/pages/ui/pattern_example.ts` shows it.
|
|
96
|
+
|
|
97
|
+
#### Scope
|
|
98
|
+
|
|
99
|
+
The pattern is the interface an element gives to users of the library: the inputs they can change while the element lives. Its point is a consistent interface for users, so it does not cover:
|
|
100
|
+
|
|
101
|
+
- **Configuration that never changes** after creation. It is a plain value, given in the factory options or as a plain input key, never a state.
|
|
102
|
+
- **References up the tree**, like the container, parent or document an element lives in. They are found from the DOM or given directly, never as states.
|
|
103
|
+
- **Internal logic** of a feature: private fields, children wired to each other, communication between the elements of one module. Use what is simplest and fastest.
|
|
104
|
+
|
|
105
|
+
#### The rules
|
|
106
|
+
|
|
107
|
+
1. **Inputs that change are states.** An input is a `StateOrVal<T>`, either a fixed value or a state (see `StateOrVal` in the state README). A fixed value is a constant and never changes. Elements have no setters or getters for their inputs, so an element never deals with properties and states for the same thing.
|
|
108
|
+
2. **A factory creates the element.** It takes optional options and creates the element with `create`, which applies them. It may take required arguments for things outside the pattern, like the container an element lives in. The class is exported only as a type, unless it is meant to be subclassed, so nobody outside the module calls `new`.
|
|
109
|
+
3. **The constructor takes no arguments.** It builds the children and sets visible defaults, so an element that never gets inputs still shows something sensible. Inputs are never applied in it.
|
|
110
|
+
4. **Inputs are declared as keys.** Each element has a module-level object of keys made with `input_key`, and its options type is `InputOptions` of that object.
|
|
111
|
+
5. **`set(options)` can be called again.** Each input is applied with `set_input`. Options left out stay as they are.
|
|
112
|
+
6. **Handed out inputs are given once.** An input that other elements follow is a creation input, applied by `[CREATE]` and left out of the options of `set`, so it can not be replaced while others follow it.
|
|
113
|
+
7. **States are handed down from parent to child.** A parent passes its inputs on to its children unchanged. It does not wrap them or copy their values.
|
|
114
|
+
8. **Every input is its own state.** Use one state per value, like `x`, `y` and `width`, never one state holding an object of them, so each value can be connected to other elements on its own.
|
|
115
|
+
9. **Writable inputs make a fixed value read only.** An element that writes an input, like a slider or a moveable panel, can not change a fixed value, so it shows it as read only. Give a writable state to make it changeable.
|
|
116
|
+
|
|
117
|
+
```ts
|
|
118
|
+
const box = my_box({ width: 100, label: label_state });
|
|
119
|
+
box.set({ label: other_state }); // width stays 100
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
#### Writing an element
|
|
123
|
+
|
|
124
|
+
```ts
|
|
125
|
+
import { Base, define_element, input_key, type InputOptions } from "#base";
|
|
126
|
+
import type { StateOrVal } from "@chocbite/ts-lib/state";
|
|
127
|
+
|
|
128
|
+
/**Inputs of the box*/
|
|
129
|
+
const BOX = {
|
|
130
|
+
/**Width in px, keeps the last good value on errors*/
|
|
131
|
+
width: input_key<StateOrVal<number>>(),
|
|
132
|
+
/**Text in the box, shows the error on errors*/
|
|
133
|
+
label: input_key<StateOrVal<string>>(),
|
|
134
|
+
};
|
|
135
|
+
export type MyBoxOptions = InputOptions<typeof BOX>;
|
|
136
|
+
|
|
137
|
+
class MyBox extends Base {
|
|
138
|
+
static element_name() {
|
|
139
|
+
return "box";
|
|
140
|
+
}
|
|
141
|
+
static element_name_space() {
|
|
142
|
+
return "my";
|
|
143
|
+
}
|
|
144
|
+
|
|
145
|
+
//Children and defaults, nothing that depends on inputs
|
|
146
|
+
#text = this.appendChild(document.createElement("span"));
|
|
147
|
+
|
|
148
|
+
set(options: MyBoxOptions): this {
|
|
149
|
+
this.set_input(BOX.width, options.width, (width) => {
|
|
150
|
+
if (width.ok) this.style.width = width.value + "px";
|
|
151
|
+
});
|
|
152
|
+
this.set_input(BOX.label, options.label, (label) => {
|
|
153
|
+
this.#text.textContent = label.ok ? label.value : "⚠ " + label.error;
|
|
154
|
+
});
|
|
155
|
+
return this;
|
|
156
|
+
}
|
|
157
|
+
}
|
|
158
|
+
define_element(MyBox);
|
|
159
|
+
|
|
160
|
+
export type { MyBox };
|
|
161
|
+
export function my_box(options: MyBoxOptions = {}): MyBox {
|
|
162
|
+
return MyBox.create(options);
|
|
163
|
+
}
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
#### `create(options)`
|
|
167
|
+
|
|
168
|
+
`Base.create` is static, every element has it. It creates the element it is called on, then applies the options in two steps, both after every constructor has finished:
|
|
169
|
+
|
|
170
|
+
1. `[CREATE](options)` applies the creation inputs, see [Inputs given at creation](#inputs-given-at-creation). It runs once, and does nothing for an element without creation inputs.
|
|
171
|
+
2. `set(options)` applies the rest.
|
|
172
|
+
|
|
173
|
+
Its options type is the options of `[CREATE]` and `set` together, taken from the class it is called on, so `MyBox.create({ nope: 1 })` is a compile error. Called on a subclass it creates the subclass with the subclass's options. An abstract class can not be created.
|
|
174
|
+
|
|
175
|
+
Every factory calls `create`, also for elements without creation inputs, so all factories look the same. The constructor must take no arguments (rule 3), because `create` calls it without any.
|
|
176
|
+
|
|
177
|
+
#### Keys
|
|
178
|
+
|
|
179
|
+
A key is a symbol that carries the type of its input. The keys object of an element is the only place where its inputs are declared.
|
|
180
|
+
|
|
181
|
+
- **`input_key<S>()`** makes a key. `S` is a `StateOrVal` variant, or a plain value type for configuration that never needs a state. A plain `Symbol()` is not accepted as a key.
|
|
182
|
+
- **`InputOptions<typeof KEYS>`** gives the options type, with every option optional. The doc comments written on the keys show up on the options when you hover them, so document inputs on the keys.
|
|
183
|
+
- **`InputOf<typeof KEYS.name>`** gives the input type of one key. It's for options interfaces built by hand, like a parent that passes an option on to a child, and for keys that aren't options, like an inner input.
|
|
184
|
+
|
|
185
|
+
Keys are module constants, so they can't be generic. An element that is generic in its value type, like a selector of `T`, writes its options interface by hand and uses loosely typed keys.
|
|
186
|
+
|
|
187
|
+
#### `set_input(key, input, apply)`
|
|
188
|
+
|
|
189
|
+
- `undefined` leaves the input unchanged.
|
|
190
|
+
- A fixed value detaches the state the key had and calls `apply` right away with an ok result.
|
|
191
|
+
- A state replaces the state the key had. `apply` is subscribed while the element is in the document, like every element state, so an element that is never shown costs nothing for its states.
|
|
192
|
+
- Giving a key a new value always drops the old state, also while the element is not in the document.
|
|
193
|
+
- The key decides the type: an input that doesn't match the key is a compile error.
|
|
194
|
+
|
|
195
|
+
##### Errors
|
|
196
|
+
|
|
197
|
+
The key's type decides whether the element must handle errors:
|
|
198
|
+
|
|
199
|
+
- **Can't be an error:** `StateOrValROS`, `StateOrValROSW`, `StateOrValROA` and plain values give `apply` a `ResultOk`, so it reads `.value`.
|
|
200
|
+
- **Can be an error:** `StateOrVal`, `StateOrValRES` and `StateOrValREA` give a `StateResult`, and TypeScript makes `apply` handle the error.
|
|
201
|
+
|
|
202
|
+
Every element decides what an error looks like for each input. `ExampleBox` keeps its last width, shows the error text in its label, and greys out its color. Pick what makes sense for the user, and never throw.
|
|
203
|
+
|
|
204
|
+
##### Writable inputs and `input_state(key)`
|
|
205
|
+
|
|
206
|
+
An element that writes, like a slider, uses a writable key such as `input_key<StateOrValROSW<number>>()`.
|
|
207
|
+
|
|
208
|
+
`input_state(key)` returns the state the input has right now, typed by the key, so a writable key gives a state with `write`. It returns `undefined` for a fixed value or an input that was never set. The element keeps no reference of its own, because `Base` already stores the state under the key:
|
|
209
|
+
|
|
210
|
+
```ts
|
|
211
|
+
constructor() {
|
|
212
|
+
super();
|
|
213
|
+
//Writes to whatever state the value input has now
|
|
214
|
+
this.#input.oninput = () =>
|
|
215
|
+
void this.input_state(SLIDER.value)?.write(Number(this.#input.value));
|
|
216
|
+
}
|
|
217
|
+
|
|
218
|
+
set(options: SliderOptions): this {
|
|
219
|
+
this.set_input(SLIDER.value, options.value, (v) => (this.#input.value = String(v.value)));
|
|
220
|
+
//A fixed value can not be written
|
|
221
|
+
this.#input.disabled = !this.input_state(SLIDER.value);
|
|
222
|
+
return this;
|
|
223
|
+
}
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
A fixed value is shown read only (rule 9), so there is no separate option to turn writing off. An element that is only sometimes changeable, like a panel that can be moved, is changeable exactly when its inputs are writable states.
|
|
227
|
+
|
|
228
|
+
##### Plain values
|
|
229
|
+
|
|
230
|
+
Configuration that never needs a state, like the step of a slider, gets a key with a plain type, `input_key<number>()`, and goes through `set_input` like every other input. Use a plain type only when a state would make no sense. When in doubt, use `StateOrVal`.
|
|
231
|
+
|
|
232
|
+
#### Inputs given at creation
|
|
233
|
+
|
|
234
|
+
An input that the element hands out to other elements, like the items of a group that a watcher follows, is given once when the element is created (rule 6). If `set` could replace it, everything following the old state would keep following it without knowing. A state given at creation can still change its value, only the state itself can not be swapped.
|
|
235
|
+
|
|
236
|
+
These inputs get their own keys object, and the element overrides `[CREATE]` (the `CREATE` symbol from `#base`) to apply them, the same way it overrides `set`. `create` calls it once, before `set`. The options of `set` leave the creation inputs out, so TypeScript refuses them there, while the factory takes both.
|
|
237
|
+
|
|
238
|
+
```ts
|
|
239
|
+
import {
|
|
240
|
+
Base,
|
|
241
|
+
CREATE,
|
|
242
|
+
define_element,
|
|
243
|
+
input_key,
|
|
244
|
+
type InputOptions,
|
|
245
|
+
} from "#base";
|
|
246
|
+
|
|
247
|
+
/**Inputs of the group that can be set again*/
|
|
248
|
+
const GROUP = {
|
|
249
|
+
/**Space between the boxes in px*/
|
|
250
|
+
gap: input_key<StateOrVal<number>>(),
|
|
251
|
+
};
|
|
252
|
+
export type GroupOptions = InputOptions<typeof GROUP>;
|
|
253
|
+
/**Inputs of the group given at creation, handed out to other elements*/
|
|
254
|
+
const GROUP_CREATE = {
|
|
255
|
+
/**Boxes shown in the group, handed out as items*/
|
|
256
|
+
items: input_key<StateOrVal<Box[]>>(),
|
|
257
|
+
};
|
|
258
|
+
export type GroupCreateOptions = GroupOptions &
|
|
259
|
+
InputOptions<typeof GROUP_CREATE>;
|
|
260
|
+
|
|
261
|
+
class Group extends Base {
|
|
262
|
+
#items: StateOrVal<Box[]> = [];
|
|
263
|
+
/**Given at creation and never replaced*/
|
|
264
|
+
get items(): StateOrVal<Box[]> {
|
|
265
|
+
return this.#items;
|
|
266
|
+
}
|
|
267
|
+
|
|
268
|
+
[CREATE](options: GroupCreateOptions) {
|
|
269
|
+
super[CREATE](options);
|
|
270
|
+
if (options.items === undefined) return;
|
|
271
|
+
this.#items = options.items;
|
|
272
|
+
this.set_input(GROUP_CREATE.items, options.items, (items) => {
|
|
273
|
+
if (items.ok) this.replaceChildren(...items.value);
|
|
274
|
+
});
|
|
275
|
+
}
|
|
276
|
+
|
|
277
|
+
set(options: GroupOptions): this {
|
|
278
|
+
this.set_input(GROUP.gap, options.gap, (gap) => {
|
|
279
|
+
if (gap.ok) this.style.gap = gap.value + "px";
|
|
280
|
+
});
|
|
281
|
+
return this;
|
|
282
|
+
}
|
|
283
|
+
}
|
|
284
|
+
|
|
285
|
+
export function group(options: GroupCreateOptions = {}): Group {
|
|
286
|
+
return Group.create(options);
|
|
287
|
+
}
|
|
288
|
+
|
|
289
|
+
group({ items: items_state, gap: 4 }).set({ gap: 8 }); // set({ items }) is a compile error
|
|
290
|
+
```
|
|
291
|
+
|
|
292
|
+
`[CREATE]` is public in TypeScript, as `create` must call it on the class it is created for, but it is keyed by a symbol, so only code that imports `CREATE` can reach it. That is code writing elements, users of an element never see it.
|
|
293
|
+
|
|
294
|
+
Only use creation inputs for values others follow. Everything else goes through `set`, so the element can still be reused.
|
|
295
|
+
|
|
296
|
+
#### Subclasses
|
|
297
|
+
|
|
298
|
+
A subclass has its own keys object for the inputs it adds, and its options type combines them with the parent's options. It overrides `set` and calls `super.set(options)` once, before or after its own inputs as it needs.
|
|
299
|
+
|
|
300
|
+
```ts
|
|
301
|
+
const LABEL_BOX = {
|
|
302
|
+
/**Bold text in front of the label*/
|
|
303
|
+
badge: input_key<StateOrVal<string>>(),
|
|
304
|
+
};
|
|
305
|
+
export type MyLabelBoxOptions = MyBoxOptions & InputOptions<typeof LABEL_BOX>;
|
|
306
|
+
|
|
307
|
+
class MyLabelBox extends MyBox {
|
|
308
|
+
#badge = this.appendChild(document.createElement("b"));
|
|
309
|
+
|
|
310
|
+
set(options: MyLabelBoxOptions): this {
|
|
311
|
+
super.set(options);
|
|
312
|
+
this.set_input(LABEL_BOX.badge, options.badge, (badge) => {
|
|
313
|
+
this.#badge.textContent = badge.ok ? badge.value : "";
|
|
314
|
+
});
|
|
315
|
+
return this;
|
|
316
|
+
}
|
|
317
|
+
}
|
|
318
|
+
```
|
|
319
|
+
|
|
320
|
+
A subclass that adds creation inputs does the same with `[CREATE]`: its own keys object, an options type combining its creation options with the parent's, and an override calling `super[CREATE](options)` once. `create` takes the options of the subclass automatically.
|
|
321
|
+
|
|
322
|
+
Inputs are never applied in the constructor. When a base constructor applies a fixed value, a subclass override called from it runs before the subclass's own fields exist. That throws for `#private` fields and silently gives `undefined` for plain fields. `[CREATE]` and `set` run after every constructor has finished, so overrides called from them can use all fields.
|
|
323
|
+
|
|
324
|
+
Elements meant to be subclassed by library users are exported as classes. The user creates the subclass with `MySubclass.create(options)`, never with `new`, which would skip the creation inputs.
|
|
325
|
+
|
|
326
|
+
#### Parents and children
|
|
327
|
+
|
|
328
|
+
- **Children are built in the constructor**, as field initializers or in the constructor body. They get their defaults there too, for example `child({ min: 0, max: 3 })`.
|
|
329
|
+
- **A parent passes inputs on unchanged**, like `this.#view.set({ scale: options.scale })`. Only convert with `state.as_state` when the parent needs a state itself, for example to derive a value with a proxy, or to hand it out.
|
|
330
|
+
- **A parent's options for inputs it only passes on** are written by hand with `InputOf`, so they always match the child: `scale?: InputOf<typeof SLIDER.value>`.
|
|
331
|
+
- **A value an element hands out**, like a state other elements follow, is a creation input, kept in a private field with a getter, see [Inputs given at creation](#inputs-given-at-creation).
|
|
332
|
+
- **Inputs inside inputs**, like a group state whose value holds an items state, use their own key for the inner input, typed with `InputOf` of the inner key. Setting the outer input again replaces the inner subscription automatically. Fixed inner values need their own branch, since nothing is subscribed for them.
|
|
333
|
+
- **References up the tree** are outside the pattern. A child that needs its parent or container finds it from the DOM, or the parent gives it directly.
|
|
334
|
+
|
|
335
|
+
#### Reused elements
|
|
336
|
+
|
|
337
|
+
Because `set` can be called again, an element can be reused for other data, like a list row showing another entry. Each call replaces the states of the inputs it is given, and only states of elements in the document are subscribed. Scrolling through thousands of entries with a few reused elements therefore keeps only the visible states subscribed.
|
|
338
|
+
|
|
339
|
+
#### When not to use it
|
|
340
|
+
|
|
341
|
+
Elements created in large numbers, like list rows, list fields and canvas widgets, can keep a lighter way of taking their data when the pattern costs too much. Measure it on a dev page with thousands of elements. In the example, 5000 boxes took about 17ms with fixed values against about 16ms for the old setters, see the Cost section of the dev page.
|
|
342
|
+
|
|
343
|
+
#### `set` and `bind`
|
|
344
|
+
|
|
345
|
+
`set` gives inputs. A few elements also have a `bind` method that two-way binds a writable state the element owns the meaning of: form elements bind their `value`, and list containers their `selection`. These are older than this pattern, and they are their own methods, not part of `Base`.
|
|
346
|
+
|
|
347
|
+
#### Status
|
|
348
|
+
|
|
349
|
+
- **Done and tested** in `package-ui/base/base.test.ts`: `Base.create` with `[CREATE]`, `Base.set`, `Base.set_input`, `Base.input_state`, and the key helpers `input_key`, `InputOptions` and `InputOf`.
|
|
350
|
+
- **Being converted:** `composition` is the first production module written to the pattern. Other elements are converted one at a time, canvas `Page` and `Viewport` after the depot work.
|
|
351
|
+
- **Example:** `package-ui/pattern_example` is kept as the reference and must stay in line with this file. It is never built or exported, its source reaches consumers through the `SOURCE.md` of the package.
|
|
352
|
+
|
|
353
|
+
#### Checklist for a new or converted element
|
|
354
|
+
|
|
355
|
+
- [ ] The class is exported only as a type, unless meant to be subclassed, and a factory taking optional options creates it with `create`.
|
|
356
|
+
- [ ] The constructor takes no arguments, builds the children and sets visible defaults.
|
|
357
|
+
- [ ] A module-level keys object made with `input_key` declares every input, with a doc comment on each key.
|
|
358
|
+
- [ ] The options type is `InputOptions<typeof KEYS>`, or `InputOf` for options built by hand.
|
|
359
|
+
- [ ] Every input is applied with `set_input`, in `set`, or in `[CREATE]` for creation inputs.
|
|
360
|
+
- [ ] Inputs handed out to other elements are creation inputs, applied by overriding `[CREATE]`, and left out of the options of `set`.
|
|
361
|
+
- [ ] Each input handles its errors in a way that makes sense to the user.
|
|
362
|
+
- [ ] Writable inputs use `input_state` to write, and fixed values are shown as read only.
|
|
363
|
+
- [ ] Subclasses have their own keys objects and call `super.set(options)` and `super[CREATE](options)` once.
|
|
364
|
+
- [ ] Configuration that never changes, references up the tree and internal logic are kept out of the inputs.
|
|
365
|
+
- [ ] Tests cover fixed values, states, setting again with both, and errors.
|
|
366
|
+
- [ ] A dev page shows fixed values and states side by side.
|
|
367
|
+
- [ ] When the pattern itself changes, this file and `package-ui/pattern_example` change with it.
|
|
368
|
+
|
|
369
|
+
### pattern_example
|
|
370
|
+
|
|
371
|
+
The complete example of the element pattern in `package-ui/PATTERN.md`. Every case the pattern describes is shown by an element here, and tested in `index.test.ts`. Every factory takes optional options and creates its element with `create`, which applies them with `[CREATE]` and `set`.
|
|
372
|
+
|
|
373
|
+
This module is never built or exported, see `NOT_BUILT` in `config/tsdown.config.ts`. Its source is shipped in the `SOURCE.md` of the published package, for agents writing elements to copy from. In the repo, the dev page `dev/pages/ui/pattern_example.ts` shows the elements.
|
|
374
|
+
|
|
375
|
+
| Element | Shows |
|
|
376
|
+
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
|
|
377
|
+
| `ExampleBox` | A keys object, `InputOptions`, and inputs handling their errors in different ways |
|
|
378
|
+
| `ExampleLabelBox` | A subclass adding its own keys |
|
|
379
|
+
| `ExampleOverrideBox` | A subclass override reading a private field from an input, which works because inputs are applied in `set` |
|
|
380
|
+
| `ExampleGroup` | Handing an input out to other elements, as a creation input applied by overriding `[CREATE]` |
|
|
381
|
+
| `ExampleWatcher` | An input inside an input, with an inner key typed by `InputOf` |
|
|
382
|
+
| `ExampleSlider` | A writable input written through `input_state`, and a plain value key |
|
|
383
|
+
| `ExampleView`, `ExampleEditor` | A parent passing inputs on to its children, with options built by hand with `InputOf`, a creation input and set options |
|
|
384
|
+
|
|
385
|
+
## Module @chocbite/ts-lib-ui/composition
|
|
386
|
+
|
|
387
|
+
### @chocbite/ts-lib-ui/composition
|
|
388
|
+
|
|
389
|
+
Builds up the page of an app: a top bar, panels floating over the page, and content shown in them.
|
|
390
|
+
|
|
391
|
+
```ts
|
|
392
|
+
import { comp } from "@chocbite/ts-lib-ui/composition";
|
|
393
|
+
```
|
|
394
|
+
|
|
395
|
+
The elements follow the element pattern of ts-lib-ui: factories take options, every option is a fixed value or a state, and `set` changes options later. Give a state for anything that changes.
|
|
396
|
+
|
|
397
|
+
#### Top bar
|
|
398
|
+
|
|
399
|
+
A bar along the top of the page, with items at the left, in the middle and at the right.
|
|
400
|
+
|
|
401
|
+
```ts
|
|
402
|
+
const title = state.ok_w("Overview");
|
|
403
|
+
const bar = comp.topbar({
|
|
404
|
+
left: [
|
|
405
|
+
comp.topbar_button({ icon: material_menu_rounded, on_click: open_menu }),
|
|
406
|
+
],
|
|
407
|
+
mid: [comp.topbar_label({ text: title })],
|
|
408
|
+
right: [
|
|
409
|
+
comp.topbar_button({
|
|
410
|
+
icon: material_settings_rounded,
|
|
411
|
+
text: "Settings",
|
|
412
|
+
on_click: open_settings,
|
|
413
|
+
}),
|
|
414
|
+
],
|
|
415
|
+
});
|
|
416
|
+
```
|
|
417
|
+
|
|
418
|
+
- **`comp.topbar({ left, mid, right })`**: each side is an array of elements, or a state of one. A side in error is empty. The middle stays centered, and when space runs out the middle gives way first, its labels end in "…".
|
|
419
|
+
- **`comp.topbar_button({ text, icon, on_click })`**: a button with an icon, a text or both. A text in error shows the error, an icon in error is left out. `on_click` is a plain function, `set({ on_click })` replaces it.
|
|
420
|
+
- **`comp.topbar_label({ text })`**: a text, showing the error when the state is in error.
|
|
421
|
+
|
|
422
|
+
Colors come from the theme variables of the composition group: title bar background, hover and text.
|
|
423
|
+
|
|
424
|
+
#### Content
|
|
425
|
+
|
|
426
|
+
Content is what a container, like a panel, shows. The container follows the title, icon, closable and minimum size of the content, so they are given when the content is created and can not be replaced later. Give states for values that change.
|
|
427
|
+
|
|
428
|
+
```ts
|
|
429
|
+
const title = state.ok_w("Report");
|
|
430
|
+
const report = comp.content({
|
|
431
|
+
title,
|
|
432
|
+
icon: material_description_rounded,
|
|
433
|
+
closable: true,
|
|
434
|
+
min_width: 20,
|
|
435
|
+
context_menu: () => [ctm.line("Refresh", refresh)],
|
|
436
|
+
});
|
|
437
|
+
report.append(report_table);
|
|
438
|
+
```
|
|
439
|
+
|
|
440
|
+
| Option | Given | Description |
|
|
441
|
+
| -------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
|
|
442
|
+
| `title` | at creation | Title the container shows. An error is shown as the title. |
|
|
443
|
+
| `icon` | at creation | Icon in front of the title, `undefined` for none. An error shows no icon. |
|
|
444
|
+
| `closable` | at creation | Whether the container shows a close button. |
|
|
445
|
+
| `min_width` | at creation | Smallest width in rem the container gives the content. |
|
|
446
|
+
| `min_height` | at creation | Smallest height in rem the container gives the content. |
|
|
447
|
+
| `context_menu` | `set` as well | Lines, a menu, or a function giving them, called every time the menu opens. Shown on the content and on the title bar of its panel. |
|
|
448
|
+
|
|
449
|
+
- **`content_close()`** closes the content and the container showing it.
|
|
450
|
+
- **`content_on_close()`** gives a promise resolved when the content is closed, by itself or by its container.
|
|
451
|
+
|
|
452
|
+
##### Own content
|
|
453
|
+
|
|
454
|
+
Extend `ContentBase` and create it with `create`, which takes the content options together with your own. Inputs your content hands out to others go in `[CREATE]`, everything else in `set`, see `PATTERN.md` of ts-lib-ui. To follow its own size, content attaches to the resize observer of `Base` and overrides `on_resize`.
|
|
455
|
+
|
|
456
|
+
```ts
|
|
457
|
+
class Note extends ContentBase {
|
|
458
|
+
static element_name() {
|
|
459
|
+
return "note";
|
|
460
|
+
}
|
|
461
|
+
static element_name_space() {
|
|
462
|
+
return "myapp";
|
|
463
|
+
}
|
|
464
|
+
#text = this.appendChild(document.createElement("p"));
|
|
465
|
+
set(options: NoteOptions): this {
|
|
466
|
+
super.set(options);
|
|
467
|
+
this.set_input(NOTE.text, options.text, (text) => {
|
|
468
|
+
this.#text.textContent = text.ok ? text.value : "⚠ " + text.error;
|
|
469
|
+
});
|
|
470
|
+
return this;
|
|
471
|
+
}
|
|
472
|
+
}
|
|
473
|
+
define_element(Note);
|
|
474
|
+
|
|
475
|
+
const note = Note.create({ title: "Note", closable: true, text: note_text });
|
|
476
|
+
```
|
|
477
|
+
|
|
478
|
+
#### Panels
|
|
479
|
+
|
|
480
|
+
A panel floats over the page and shows one content, with a title bar showing the title, icon and close button of the content. Panels live in the panel container of their document, which is made the first time it is needed.
|
|
481
|
+
|
|
482
|
+
```ts
|
|
483
|
+
const x = state.ok_w(10);
|
|
484
|
+
const y = state.ok_w(4);
|
|
485
|
+
const panel = comp.panel(report, { x, y, width: 30 });
|
|
486
|
+
```
|
|
487
|
+
|
|
488
|
+
`comp.panel(content, options)` opens the panel in the main document, `comp.panel_container(element).panel(content, options)` in the document of the element, like a second window registered with `DOCUMENT_HANDLER`.
|
|
489
|
+
|
|
490
|
+
| Option | Description |
|
|
491
|
+
| ------------ | --------------------------------------------------------------------------------------------------------------------------------- |
|
|
492
|
+
| `x`, `y` | Position in rem from the top left of the page, of the anchor point of the panel. |
|
|
493
|
+
| `anchor` | Point of the panel x and y place, `CompAnchor`: the corners or `center`. `top_left` by default. |
|
|
494
|
+
| `width` | Width in rem, not given the panel fits its content. Never smaller than the `min_width` of the content. |
|
|
495
|
+
| `height` | Height in rem, like width. |
|
|
496
|
+
| `sizeable` | Whether the user can size the panel, true by default. |
|
|
497
|
+
| `hidden` | Whether the panel is hidden. |
|
|
498
|
+
| `auto_hide` | Hides the panel when the user presses outside it. |
|
|
499
|
+
| `auto_close` | Closes the panel when the user presses outside it. |
|
|
500
|
+
| `modal` | Darkens the page behind the panel and keeps the focus in it. |
|
|
501
|
+
| `titlebar` | Whether the title bar is shown, true by default. Without it the panel can not be moved by the user. |
|
|
502
|
+
| `layer` | Panels in a higher layer are always above those in a lower one. Within a layer the panel the user worked in last is at the front. |
|
|
503
|
+
|
|
504
|
+
`x`, `y`, `width`, `height` and `hidden` are changed by the user, by moving, sizing and auto hiding the panel. Each is changeable when it is a writable state, which the panel writes, or when it is not given, then the panel keeps it itself. A fixed value can not be changed, so `x: 4` with a state for `y` moves only up and down. A panel without a position starts centered.
|
|
505
|
+
|
|
506
|
+
The position is kept as given, the panel only shows it clamped so its title bar stays on the page. When the window gets smaller and then bigger again, or the scale changes, the panel goes back to where it was.
|
|
507
|
+
|
|
508
|
+
- **`panel.close()`** closes the panel and its content, **`panel.on_close()`** resolves when it is closed.
|
|
509
|
+
- **`panel.content`** is the content it shows.
|
|
510
|
+
- **`comp.panel_container().active_panel`** is the panel the user worked in last.
|
|
511
|
+
|
|
512
|
+
#### Customization
|
|
513
|
+
|
|
514
|
+
Content with the settings of the library: theme, UI scale, input mode and animations. The app adds its own settings with `main`, shown under the theme, and `advanced`, shown last in the collapsed advanced section. Each is an array of form elements, or a state of one, a state in error shows none.
|
|
515
|
+
|
|
516
|
+
```ts
|
|
517
|
+
const settings = comp.attach_customization_panel_to_element(
|
|
518
|
+
settings_button,
|
|
519
|
+
CompAnchor.BOT_RIGHT,
|
|
520
|
+
CompAnchor.TOP_RIGHT,
|
|
521
|
+
);
|
|
522
|
+
settings.content.set({
|
|
523
|
+
main: [
|
|
524
|
+
form.text({ text: "Units" }),
|
|
525
|
+
form.toggle_button().bind({ value: units }),
|
|
526
|
+
],
|
|
527
|
+
});
|
|
528
|
+
```
|
|
529
|
+
|
|
530
|
+
- **`comp.customization(options)`** makes the content, to show in any panel. Title, icon, closable and minimum size have defaults, give them to change them.
|
|
531
|
+
- **`comp.customization_panel(options, owner?)`** puts it in a modal panel that starts hidden and hides again when the user presses outside it. It returns `{ panel, content, hidden }`, write `false` to `hidden` to show it, change the panel with `panel.set`, like its position.
|
|
532
|
+
- **`comp.attach_customization_panel_to_element(element, element_anchor, panel_anchor, c_panel?)`** shows the panel when the element is clicked, with `panel_anchor` of the panel at `element_anchor` of the element.
|
|
533
|
+
|
|
82
534
|
## Module @chocbite/ts-lib-ui/context-menu
|
|
83
535
|
|
|
84
536
|
### @chocbite/ts-lib-ui/context-menu
|
|
@@ -320,6 +772,63 @@ Theming via `#theme`.
|
|
|
320
772
|
|
|
321
773
|
MIT
|
|
322
774
|
|
|
775
|
+
## Module @chocbite/ts-lib-ui/depot_ui
|
|
776
|
+
|
|
777
|
+
### @chocbite/ts-lib-ui/depot_ui
|
|
778
|
+
|
|
779
|
+
Selectors for the depot of `@chocbite/ts-lib/depot`.
|
|
780
|
+
|
|
781
|
+
Importing `@chocbite/ts-lib-ui` types depot icons as `SVGFunc`, so `type`, `group` and `add` take an icon as their last argument.
|
|
782
|
+
|
|
783
|
+
#### `depot_ui.select(from, options?)`
|
|
784
|
+
|
|
785
|
+
Opens a selector over the page for the entries of a type or group, and returns a promise of the selected entries. Cancelling, with the Cancel button or a press on the backdrop, gives an empty array.
|
|
786
|
+
|
|
787
|
+
```ts
|
|
788
|
+
import depot from "@chocbite/ts-lib/depot";
|
|
789
|
+
import depot_ui from "@chocbite/ts-lib-ui/depot_ui";
|
|
790
|
+
|
|
791
|
+
const picked = await depot_ui.select(widgets, {
|
|
792
|
+
mode: "multi",
|
|
793
|
+
filter: (entry) => entry.parent === basic, // only basic widgets can be picked
|
|
794
|
+
});
|
|
795
|
+
for (const entry of picked) console.log(entry.path);
|
|
796
|
+
```
|
|
797
|
+
|
|
798
|
+
Options:
|
|
799
|
+
|
|
800
|
+
- `mode`: `"single"` (default) or `"multi"`. In single mode a double click on an entry picks it right away.
|
|
801
|
+
- `filter(entry)`: only entries passing the filter are shown and can be selected, groups with no shown entry below them are hidden. Use it for what the caller needs.
|
|
802
|
+
- `selected`: entries selected when the selector opens.
|
|
803
|
+
- `title`: shown at the top, the name of the group when undefined.
|
|
804
|
+
|
|
805
|
+
Groups can not be selected, only entries. The search box filters while typing on names and paths without case, and opens the groups while a search is set. The selector follows the depot while it is open, entries registered or removed show right away.
|
|
806
|
+
|
|
807
|
+
#### `depot_ui.select_state(options?)`
|
|
808
|
+
|
|
809
|
+
The selector for the states type, with a column of the live value of every state. It works like `select`, the entries it gives hold the state as `entry.value`.
|
|
810
|
+
|
|
811
|
+
```ts
|
|
812
|
+
const [entry] = await depot_ui.select_state({ writable: true, kind: "number" });
|
|
813
|
+
if (entry) bind_to(entry.path, entry.value);
|
|
814
|
+
```
|
|
815
|
+
|
|
816
|
+
Options, besides `mode`, `filter`, `selected` and `title` of `select`:
|
|
817
|
+
|
|
818
|
+
- `from`: a group of the states type to select from, all states when undefined. A group of another type throws.
|
|
819
|
+
- `writable`: only writable states can be selected.
|
|
820
|
+
- `kind`: `"number"`, `"string"`, `"boolean"`, `"enum"` or an array of them, only states of these kinds can be selected. The kind comes from the helper of the state (`state.n`, `state.s`, `state.b`, `state.e`), or else from the current value of a sync state. A state whose kind can not be known, like an async state without a helper, is hidden when `kind` is given. The kind is worked out when the tree changes, a sync state without a helper changing kind while the selector is open is not followed.
|
|
821
|
+
|
|
822
|
+
The value column uses the unit and decimals of a number helper and the names of an enum helper, when those are sync states. Errors are shown dimmed. Values are only subscribed while their row is shown.
|
|
823
|
+
|
|
824
|
+
#### `DepotTree`
|
|
825
|
+
|
|
826
|
+
The filtered view the selector is built on, for building other selectors. `new DepotTree(group, filter?)` gives `rows(group?)`, a state of the shown children of a group, made for the rows and sub rows of a `list` container. Set `search` to filter by text, and call `dispose()` when done to drop the subscriptions to the depot. Changes in the depot are applied once after a burst of changes, in a microtask.
|
|
827
|
+
|
|
828
|
+
#### Theme
|
|
829
|
+
|
|
830
|
+
The colors of the selector are the theme variables under `depot.colors`: `backdrop`, `background`, `text` and `shadow`.
|
|
831
|
+
|
|
323
832
|
## Module @chocbite/ts-lib-ui/icons
|
|
324
833
|
|
|
325
834
|
### Mixins
|
|
@@ -469,6 +978,43 @@ list.container(columns, transform, files, {
|
|
|
469
978
|
|
|
470
979
|
Selected rows get the `selected` class and the theme variables `list.colors.background.row_selected` and `row_selected_hover`. The radio buttons, checkboxes and drag handles are glyphs of the bundled Material icon font, colored by `list.colors.icon.check` and `list.colors.icon.drag`. The drop line, the box around a row dropped into and the focus use `list.colors.focus.normal`. Dragged rows are dimmed until the move comes back from the state.
|
|
471
980
|
|
|
981
|
+
## Module @chocbite/ts-lib-ui/prompts
|
|
982
|
+
|
|
983
|
+
### @chocbite/ts-lib-ui/prompts
|
|
984
|
+
|
|
985
|
+
Modal prompts that ask the user something and give the answer as a promise. A prompt opens in a panel of `composition`, in the middle of the page, and darkens the page behind it. Each resolves with `some(answer)`, or `none()` when the user closes it with the close button or Escape.
|
|
986
|
+
|
|
987
|
+
```ts
|
|
988
|
+
import { prompts } from "@chocbite/ts-lib-ui/prompts";
|
|
989
|
+
```
|
|
990
|
+
|
|
991
|
+
#### Buttons
|
|
992
|
+
|
|
993
|
+
```ts
|
|
994
|
+
const answer = await prompts.buttons("Discard changes?", [
|
|
995
|
+
{ text: "Discard", value: true, icon: material_delete_rounded },
|
|
996
|
+
{ text: "Keep", value: false },
|
|
997
|
+
]);
|
|
998
|
+
if (answer.some && answer.value) discard();
|
|
999
|
+
```
|
|
1000
|
+
|
|
1001
|
+
Resolves with the `value` of the clicked button. A button's `click` is called after the prompt has closed.
|
|
1002
|
+
|
|
1003
|
+
#### Form
|
|
1004
|
+
|
|
1005
|
+
```ts
|
|
1006
|
+
const result = await prompts.form(
|
|
1007
|
+
"New user",
|
|
1008
|
+
[form.text({ text: "Name" }), form.text_input({ id: "name" })],
|
|
1009
|
+
{ text: "Create" },
|
|
1010
|
+
);
|
|
1011
|
+
if (result.some) create(result.value.name);
|
|
1012
|
+
```
|
|
1013
|
+
|
|
1014
|
+
Resolves with the values the user changed, by `id` of the form elements, typed from the elements. The first element the user can change gets the focus, and Enter submits with the last button.
|
|
1015
|
+
|
|
1016
|
+
A submit button's `click(group, close)` runs on submit. Returning `true` keeps the prompt open, for example to check the values first, and `close(result)` closes it later. Options set the columns and rows of the form and of the submit buttons.
|
|
1017
|
+
|
|
472
1018
|
## Module @chocbite/ts-lib-ui/state_ui
|
|
473
1019
|
|
|
474
1020
|
### State UI
|
|
@@ -734,14 +1280,6 @@ document.body.appendChild(canvas);
|
|
|
734
1280
|
|
|
735
1281
|
MIT
|
|
736
1282
|
|
|
737
|
-
## Module @chocbite/ts-lib-ui/test
|
|
738
|
-
|
|
739
|
-
### @chocbite/ts-lib-ui/test
|
|
740
|
-
|
|
741
|
-
Temporary trial of declaring elements with their inputs in the constructor, as `T | State<T>`, instead of setters and getters. Try it on the dev page `dev/pages/ui/test.ts`.
|
|
742
|
-
|
|
743
|
-
Delete this module or move `attach_input` to `Base` before the next release, otherwise it gets published.
|
|
744
|
-
|
|
745
1283
|
## Module @chocbite/ts-lib-ui/theme
|
|
746
1284
|
|
|
747
1285
|
### Theme
|
package/README.md
CHANGED
|
@@ -50,6 +50,7 @@ SCSS mixins are available for use in your own styles:
|
|
|
50
50
|
|
|
51
51
|
- `@chocbite/ts-lib-ui/base`
|
|
52
52
|
- `@chocbite/ts-lib-ui/canvas`
|
|
53
|
+
- `@chocbite/ts-lib-ui/composition`
|
|
53
54
|
- `@chocbite/ts-lib-ui/context-menu`
|
|
54
55
|
- `@chocbite/ts-lib-ui/document`
|
|
55
56
|
- `@chocbite/ts-lib-ui/dom`
|
|
@@ -57,8 +58,10 @@ SCSS mixins are available for use in your own styles:
|
|
|
57
58
|
- `@chocbite/ts-lib-ui/icons`
|
|
58
59
|
- `@chocbite/ts-lib-ui/keyboard`
|
|
59
60
|
- `@chocbite/ts-lib-ui/list`
|
|
61
|
+
- `@chocbite/ts-lib-ui/prompts`
|
|
60
62
|
- `@chocbite/ts-lib-ui/selection`
|
|
61
63
|
- `@chocbite/ts-lib-ui/settings`
|
|
62
64
|
- `@chocbite/ts-lib-ui/spinner`
|
|
65
|
+
- `@chocbite/ts-lib-ui/state_ui`
|
|
63
66
|
- `@chocbite/ts-lib-ui/svg`
|
|
64
67
|
- `@chocbite/ts-lib-ui/theme`
|