@chocbite/ts-lib-ui 1.0.5 → 1.1.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 +164 -3
- package/SOURCE.md +2000 -268
- package/base/index.mjs +7 -7
- package/base/index.mjs.map +1 -1
- package/canvas/index.mjs +8 -8
- package/canvas/index.mjs.map +1 -1
- package/context-menu/index.d.mts +2 -2
- package/context-menu/index.mjs +1 -1
- package/{context-menu-CA4o4fXx.mjs → context-menu-DE3EUtY8.mjs} +149 -111
- package/context-menu-DE3EUtY8.mjs.map +1 -0
- package/document/index.mjs +1 -1
- package/document/index.mjs.map +1 -1
- package/dom/index.mjs +1 -1
- package/dom/index.mjs.map +1 -1
- package/form/index.d.mts +4 -3
- package/form/index.mjs +30 -29
- package/form/index.mjs.map +1 -1
- package/icons/index.mjs +1 -1
- package/{icons-e2J_Ojic.mjs → icons-B88i-7MC.mjs} +2 -2
- package/index-Cw4AcuUl.d.mts +371 -0
- package/{index-DhRb2iA8.d.mts → index-YNZjMIO7.d.mts} +32 -16
- package/keyboard/index.mjs +12 -12
- package/keyboard/index.mjs.map +1 -1
- package/list/index.d.mts +2 -2
- package/list/index.mjs +1 -1
- package/list-D08epOjk.mjs +1566 -0
- package/list-D08epOjk.mjs.map +1 -0
- package/package.json +5 -80
- package/selection/index.mjs +1 -1
- package/selection/index.mjs.map +1 -1
- package/settings/index.mjs +1 -1
- package/settings/index.mjs.map +1 -1
- package/spinner/index.mjs +3 -3
- package/spinner/index.mjs.map +1 -1
- package/state_ui/index.mjs +1 -1
- package/{state_ui-Bm3TeKNL.mjs → state_ui-Dtm2y5RU.mjs} +3 -3
- package/state_ui-Dtm2y5RU.mjs.map +1 -0
- package/style.css +307 -63
- package/svg/index.mjs +1 -1
- package/{svg-1bp-yIPC.mjs → svg-Yz7elqnU.mjs} +16 -16
- package/svg-Yz7elqnU.mjs.map +1 -0
- package/test/index.mjs +1 -1
- package/test/index.mjs.map +1 -1
- package/theme/index.mjs +1 -1
- package/{theme-ChmpRObz.mjs → theme-BJS5z1iW.mjs} +9 -9
- package/theme-BJS5z1iW.mjs.map +1 -0
- package/context-menu-CA4o4fXx.mjs.map +0 -1
- package/index-DCn7acFY.d.mts +0 -173
- package/list-CNYJ3sm-.mjs +0 -715
- package/list-CNYJ3sm-.mjs.map +0 -1
- package/state_ui-Bm3TeKNL.mjs.map +0 -1
- package/svg-1bp-yIPC.mjs.map +0 -1
- package/theme-ChmpRObz.mjs.map +0 -1
package/AGENTS.md
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
# @chocbite/ts-lib-ui, notes for agents
|
|
2
2
|
|
|
3
|
-
@chocbite/ts-lib-ui 1.0
|
|
3
|
+
@chocbite/ts-lib-ui 1.1.0, built from ssh://git@forgejo.nsns.dk:2222/chocbite/ts-lib.git at commit 8de9a71, with uncommitted changes.
|
|
4
4
|
|
|
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
|
|
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
|
|
|
7
7
|
This package builds on `@chocbite/ts-lib`, its notes and source are in `node_modules/@chocbite/ts-lib/AGENTS.md` and `SOURCE.md`.
|
|
8
8
|
|
|
@@ -181,6 +181,36 @@ const menu = ctm.menu([
|
|
|
181
181
|
|
|
182
182
|
---
|
|
183
183
|
|
|
184
|
+
##### `ctm.combine(...groups)`
|
|
185
|
+
|
|
186
|
+
Combines groups of lines and menus into one menu, with a devider between the groups. It returns a menu factory for `ctm.attach`, or anything else taking one, like the `context_menu` row option of the list.
|
|
187
|
+
|
|
188
|
+
- A group is an array of lines, a menu, a function giving lines, a menu or an option of a menu (what `ctm.attach` takes), or `undefined` for no group.
|
|
189
|
+
- Functions are called and the menu is built every time it opens, so lines can show the state at that moment.
|
|
190
|
+
- A menu gives its lines, so two finished menus can be joined, like extra lines in front of a menu that came from somewhere else.
|
|
191
|
+
- Empty groups are left out with their devider, `undefined` lines are skipped like in `ctm.menu`.
|
|
192
|
+
- When all groups are empty there is no menu.
|
|
193
|
+
|
|
194
|
+
```ts
|
|
195
|
+
ctm.attach(
|
|
196
|
+
el,
|
|
197
|
+
ctm.combine(
|
|
198
|
+
[ctm.line("Cut", () => cut()), ctm.line("Copy", () => copy())],
|
|
199
|
+
() => (canDelete() ? [ctm.line("Delete", () => remove())] : []),
|
|
200
|
+
isAdmin ? [ctm.line("Admin Panel", () => openAdmin())] : undefined,
|
|
201
|
+
),
|
|
202
|
+
);
|
|
203
|
+
|
|
204
|
+
// Lines in front of a finished menu, or of a menu factory given by someone else
|
|
205
|
+
ctm.attach(el, ctm.combine([ctm.line("Select", () => select())], other_menu));
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
Lines are elements that live in one menu at a time. The combined menu takes the lines of a menu group while it is open, the menu takes them back when it opens on its own. An array group is fine because only one menu is open at a time, but give a function when the same lines should also be used in another menu that can be open at the same time.
|
|
209
|
+
|
|
210
|
+
A menu group with promised lines makes the combined menu wait for all groups with a spinner, like `ctm.menu` with a promise. The combined menu then always opens, even when the lines turn out empty.
|
|
211
|
+
|
|
212
|
+
---
|
|
213
|
+
|
|
184
214
|
##### `ctm.attach(element, lines, block?)`
|
|
185
215
|
|
|
186
216
|
Binds a context menu to a DOM element.
|
|
@@ -300,6 +330,137 @@ Use icon font mixin like so
|
|
|
300
330
|
@use "@chocbite/ts-lib-ui/icons/mixins" as iconfont;
|
|
301
331
|
```
|
|
302
332
|
|
|
333
|
+
## Module @chocbite/ts-lib-ui/list
|
|
334
|
+
|
|
335
|
+
### List
|
|
336
|
+
|
|
337
|
+
Table-like lists of rows with resizable columns, optional sub rows, add row buttons and row selection. Rows come from an array or an array state. Only the rows that changed are touched when an array state changes.
|
|
338
|
+
|
|
339
|
+
```ts
|
|
340
|
+
import list from "@chocbite/ts-lib-ui/list";
|
|
341
|
+
import { ok } from "@chocbite/ts-lib/result";
|
|
342
|
+
```
|
|
343
|
+
|
|
344
|
+
#### `list.container(columns, transform, rows, options?)`
|
|
345
|
+
|
|
346
|
+
- `columns`: an object of columns made with `list.column({...})` or `list.column_string(title)`. The keys are the column keys.
|
|
347
|
+
- `transform(data, row, rows)`: turns the data of a row into row options. It returns `ok({ values, ... })`, where `values` has a value per column key. Returning `err(text)` makes the row invalid: the text replaces its fields, and it gets no sub rows, add row, context menu or selection.
|
|
348
|
+
- `rows`: an array or an array state of row data.
|
|
349
|
+
- `options`: `headless`, `sub_rows`, `add_row`, `observer` and `selection`.
|
|
350
|
+
|
|
351
|
+
```ts
|
|
352
|
+
const users = state.ok_w([{ id: 1, name: "Ann" }]);
|
|
353
|
+
const container = list.container(
|
|
354
|
+
{ name: list.column_string("Name") },
|
|
355
|
+
(user) => ok({ values: { name: user.name } }),
|
|
356
|
+
users,
|
|
357
|
+
);
|
|
358
|
+
```
|
|
359
|
+
|
|
360
|
+
Row options besides `values`: `openable`, `opened`, `sub_rows` (with the `sub_rows` container option), `key_field`, `add_row`, `context_menu` and `selectable`.
|
|
361
|
+
|
|
362
|
+
With sub rows, add rows and error texts sit in the key field after the tree lines and run from the key column to the end of the row. A list can therefore have no value columns at all, `{}` as columns with the names as key field text.
|
|
363
|
+
|
|
364
|
+
#### Resizing columns
|
|
365
|
+
|
|
366
|
+
Columns without a `fixed_width` get a handle at the right of their header, a double click on it resets the column. The first resize gives every auto width column the width it has, so only the dragged column changes. The key field column of sub rows never gets smaller than its widest key field needs for the indent, the opener, the icon and 4rem of the text, so it grows when deeper sub rows open. Text that does not fit wraps.
|
|
367
|
+
|
|
368
|
+
#### Selection
|
|
369
|
+
|
|
370
|
+
The `selection` option lets the user select rows. It adds a column in front of the rows, with radio buttons in single mode and checkboxes in multi mode, so selection works on touch without modifier keys.
|
|
371
|
+
|
|
372
|
+
The selection is an array state of keys owned by the app, given to the list with `bind`, the same way form elements take their value. Several lists, or any other element, can share one state.
|
|
373
|
+
|
|
374
|
+
```ts
|
|
375
|
+
const selected = state.ok_w<number[]>([]);
|
|
376
|
+
const container = list
|
|
377
|
+
.container(columns, transform, users, {
|
|
378
|
+
selection: { mode: "multi", key: (user) => user.id },
|
|
379
|
+
})
|
|
380
|
+
.bind({ selection: selected });
|
|
381
|
+
|
|
382
|
+
selected.sub((keys) => console.log("selected", keys.value));
|
|
383
|
+
selected.write([1, 4]); // selects the rows with these keys
|
|
384
|
+
```
|
|
385
|
+
|
|
386
|
+
Options:
|
|
387
|
+
|
|
388
|
+
- `mode`: `"single"` (radio buttons) or `"multi"` (checkboxes). In multi mode the header checkbox selects all rows or clears, and shows whether some or all rows are selected. Right click (or long press) on it opens a menu with "Select all" and "Deselect all". In single mode the header cell is empty.
|
|
389
|
+
- `key`: the identity of the data of a row. Defaults to the data itself. Give a key whenever the data can be equal between rows, like primitives, or is replaced by new objects on updates. Keys must be unique among all rows, sub rows included.
|
|
390
|
+
|
|
391
|
+
A row with `selectable: false` in its row options, or an invalid row, can not be selected. Its radio button or checkbox cell is empty.
|
|
392
|
+
|
|
393
|
+
##### The state
|
|
394
|
+
|
|
395
|
+
- The list shows a row as selected when its key is in the state. Keys without a visible row are kept in the state, they show as soon as their row is visible again, for example when its parent is opened, or the row comes back in the data.
|
|
396
|
+
- The list writes the state only on user actions, never on its own. Rows that are removed, closed away, become invalid or unselectable, or get another key do not change the state.
|
|
397
|
+
- Writes use array write instructions, so only the changed keys are sent and only their rows are touched: a toggle writes a `push` or `delete`, while a plain click, a range and single mode replace the selection with a `fresh` array. The bound state must apply these instructions, which local writable states like `state.ok_w` do.
|
|
398
|
+
- A toggle or ctrl shift range keeps the keys the list does not show, so lists showing different rows can share a state. Select all replaces the selection with all visible selectable rows of the list, deselect all and escape clear the whole selection.
|
|
399
|
+
- The rows show a change when the state gives it back, so a state that rejects a write, or writes asynchronously, is shown as it is. The reason of a rejected write is shown at the row as the validation message of the browser, like the form elements do. An error of the state shows nothing selected.
|
|
400
|
+
- The state is attached while the list is in the document, like other element states.
|
|
401
|
+
- Without `bind` the selection is kept in a state of the list nobody else can reach, `bind({})` goes back to that.
|
|
402
|
+
|
|
403
|
+
The selection follows the data, not the row elements. When a whole new array reuses row elements by position, each row shows the selection of its new key.
|
|
404
|
+
|
|
405
|
+
##### Input
|
|
406
|
+
|
|
407
|
+
| Input | single | multi |
|
|
408
|
+
| ----------------------------- | ------------------------------------------------------------- | ------------------------------------------ |
|
|
409
|
+
| click | select only it | select only it |
|
|
410
|
+
| ctrl click | toggle | toggle |
|
|
411
|
+
| shift click | select only it | select the range from the last clicked row |
|
|
412
|
+
| ctrl shift click | select only it | add the range |
|
|
413
|
+
| radio button / checkbox click | select only it | toggle |
|
|
414
|
+
| right click | only opens the menu of the row, the selection does not change | same |
|
|
415
|
+
|
|
416
|
+
The keyboard works in the key field (lists with sub rows), or else in the radio button or checkbox cell:
|
|
417
|
+
|
|
418
|
+
- Arrow up and down only move the focus, the selection changes with space.
|
|
419
|
+
- Shift with arrows extends the range (multi).
|
|
420
|
+
- Space selects only the focused row in single mode, and toggles it in multi mode or with ctrl.
|
|
421
|
+
- Enter opens and closes sub rows. Right and left open and close.
|
|
422
|
+
- Ctrl+A selects all visible rows (multi). Escape clears.
|
|
423
|
+
|
|
424
|
+
##### Row menu
|
|
425
|
+
|
|
426
|
+
The list adds lines in front of the row's own `context_menu`, each group with a devider after it:
|
|
427
|
+
|
|
428
|
+
1. "Open" or "Close" for a row that can be opened, in lists with sub rows, with or without selection.
|
|
429
|
+
2. "Select" or "Deselect" for a selectable row, and in multi mode "Select all" and "Deselect all".
|
|
430
|
+
3. The row's own lines.
|
|
431
|
+
|
|
432
|
+
Nothing has to be done for it, `context_menu` stays a menu or a function giving an option of a menu.
|
|
433
|
+
|
|
434
|
+
The menu is combined with `ctm.combine` of the context menu module when it opens, so it shows the open state and the selection at that moment (also for an `openable` state), and rows that are never right clicked cost nothing. A right click never changes the selection by itself, so the row line says "Select" or "Deselect" by the state of the row. A row with nothing to open or select uses its own menu as it is, and has no menu without one.
|
|
435
|
+
|
|
436
|
+
#### Reorder
|
|
437
|
+
|
|
438
|
+
The `reorder` option adds a column of drag handles in front of the rows, before the selection column. Rows are moved by dragging their handle, or with alt and arrow up or down in the key field or selection cell.
|
|
439
|
+
|
|
440
|
+
```ts
|
|
441
|
+
const group = list.drag_group<File>();
|
|
442
|
+
list.container(columns, transform, files, {
|
|
443
|
+
sub_rows: true,
|
|
444
|
+
reorder: {
|
|
445
|
+
group, // optional, lists of one group give rows to each other
|
|
446
|
+
can_drop: (file, target) => target.parent?.kind !== "file",
|
|
447
|
+
},
|
|
448
|
+
});
|
|
449
|
+
```
|
|
450
|
+
|
|
451
|
+
- Only rows in a writable array state can be moved, they show a handle. Rows of a plain array or a read only state have an empty handle cell.
|
|
452
|
+
- Like the selection, the list only writes the moves to the rows states, the rows move when the states give the change back. A rejected write leaves the rows where they are and shows the reason at the row, like the form elements do.
|
|
453
|
+
- A drop goes before or after a row, or into an openable row as its last sub rows. Dropping after an open row puts the rows first in its sub rows. Hovering into a closed row opens it after a moment, and a drop into it opens it. Below the last row drops at the end. Escape cancels a drag.
|
|
454
|
+
- Inside one parent a move is one `move` write. Moving to another parent or list first inserts into the target and then removes from the source, so a failed write can leave a row in both places but never loses it. If the app removes rows itself when they are added somewhere else, `no_remove: true` on the list the rows are dragged from makes it only insert.
|
|
455
|
+
- Dragging a selected row in multi mode moves all visible selected rows, in their order. Rows next to each other in one parent move with one write. Sub rows of a dragged row move with it.
|
|
456
|
+
- A row can not be dropped into itself or its sub rows. `can_drop(data, target)` decides the rest, `target.parent` is the data of the row the rows go into, undefined for the top level, and `target.list` the list.
|
|
457
|
+
- `list.drag_group<R>()` makes a group of lists that can give rows to each other. Only lists with exactly the same row type can join a group. Without a group rows only move inside their list.
|
|
458
|
+
- A row moved to another parent is a new row element, so its sub rows close.
|
|
459
|
+
|
|
460
|
+
#### Look
|
|
461
|
+
|
|
462
|
+
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.
|
|
463
|
+
|
|
303
464
|
## Module @chocbite/ts-lib-ui/state_ui
|
|
304
465
|
|
|
305
466
|
### State UI
|
|
@@ -307,7 +468,7 @@ Use icon font mixin like so
|
|
|
307
468
|
Shows states of `@chocbite/ts-lib/state` in the document. Everything is on the `state_ui` object, named so it does not collide with `state` of `@chocbite/ts-lib/state`, which has array features of its own. Like `state`, short and long names point to the same thing: `state_ui.a` is `state_ui.array`.
|
|
308
469
|
|
|
309
470
|
```ts
|
|
310
|
-
import state_ui from "@chocbite/ts-lib-ui/
|
|
471
|
+
import state_ui from "@chocbite/ts-lib-ui/state_ui";
|
|
311
472
|
```
|
|
312
473
|
|
|
313
474
|
#### `state_ui.a.apply(parent, array, handlers)`
|