@chocbite/ts-lib-ui 1.0.4 → 1.0.5
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 +609 -0
- package/SOURCE.md +17135 -0
- package/base/index.mjs +1 -1
- package/base/index.mjs.map +1 -1
- package/canvas/index.mjs +35 -19
- package/canvas/index.mjs.map +1 -1
- package/context-menu/index.mjs +1 -1
- package/{context-menu-Cz9rqUaM.mjs → context-menu-CA4o4fXx.mjs} +2 -2
- package/{context-menu-Cz9rqUaM.mjs.map → context-menu-CA4o4fXx.mjs.map} +1 -1
- package/form/index.mjs +2 -2
- package/keyboard/index.mjs +1 -1
- package/list/index.mjs +1 -1
- package/{list-DXkEJKjx.mjs → list-CNYJ3sm-.mjs} +4 -4
- package/list-CNYJ3sm-.mjs.map +1 -0
- package/package.json +7 -2
- package/spinner/index.mjs +1 -1
- package/state_ui/index.mjs +2 -0
- package/{state-OCzEmq3j.mjs → state_ui-Bm3TeKNL.mjs} +3 -3
- package/state_ui-Bm3TeKNL.mjs.map +1 -0
- package/test/index.d.mts +98 -0
- package/test/index.mjs +193 -0
- package/test/index.mjs.map +1 -0
- package/theme/index.mjs +1 -1
- package/{theme-CFeGnUuF.mjs → theme-ChmpRObz.mjs} +2 -2
- package/{theme-CFeGnUuF.mjs.map → theme-ChmpRObz.mjs.map} +1 -1
- package/list-DXkEJKjx.mjs.map +0 -1
- package/state/index.mjs +0 -2
- package/state-OCzEmq3j.mjs.map +0 -1
- /package/{state → state_ui}/index.d.mts +0 -0
package/AGENTS.md
ADDED
|
@@ -0,0 +1,609 @@
|
|
|
1
|
+
# @chocbite/ts-lib-ui, notes for agents
|
|
2
|
+
|
|
3
|
+
@chocbite/ts-lib-ui 1.0.5, built from ssh://git@forgejo.nsns.dk:2222/chocbite/ts-lib.git at commit d2afd90, with uncommitted changes.
|
|
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/src/<module>/` to find a module.
|
|
6
|
+
|
|
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
|
+
|
|
9
|
+
## Reporting problems with this library
|
|
10
|
+
|
|
11
|
+
This library is developed alongside the projects that use it, problems found while using it should be fixed in the library. If something is wrong, missing, undocumented or awkward to use:
|
|
12
|
+
|
|
13
|
+
- Do not patch it in `node_modules` and do not silently work around it.
|
|
14
|
+
- Tell the user, with the package name and version, the repo path and function or class from `SOURCE.md`, what you expected, what happened, and what you did instead.
|
|
15
|
+
- Append the same to `chocbite-feedback.md` in the root of the project you are working on, create it if missing, so the report is not lost when the conversation ends.
|
|
16
|
+
|
|
17
|
+
## @chocbite/ts-lib-ui
|
|
18
|
+
|
|
19
|
+
Browser UI TypeScript libraries, built on [@chocbite/ts-lib](https://www.npmjs.com/package/@chocbite/ts-lib).
|
|
20
|
+
|
|
21
|
+
### Install
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
npm install @chocbite/ts-lib-ui
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
`@chocbite/ts-lib` is installed with it as a dependency.
|
|
28
|
+
|
|
29
|
+
### Usage
|
|
30
|
+
|
|
31
|
+
Every module is its own subpath export, there is no root export.
|
|
32
|
+
|
|
33
|
+
```ts
|
|
34
|
+
import ctm from "@chocbite/ts-lib-ui/context-menu";
|
|
35
|
+
import { svg } from "@chocbite/ts-lib-ui/svg";
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
#### Creating elements
|
|
39
|
+
|
|
40
|
+
Elements are created in code, with their factory functions (e.g. `form_button()`) or `new`. HTML is not supported: `document.createElement`, elements written in HTML, `innerHTML` and `cloneNode` do not work. Elements build their children in their constructor, which the browser only allows for `new`, and many constructors need arguments.
|
|
41
|
+
|
|
42
|
+
#### Names of stored settings
|
|
43
|
+
|
|
44
|
+
Settings like the theme are stored in the local storage under the name of their package, e.g. `@chocbite/ts-lib-theme/theme`. `settings_set_name_transform` renames them for every package. The settings are read when their module is imported, so it must be called in a module that is imported before any other module of this library:
|
|
45
|
+
|
|
46
|
+
```ts
|
|
47
|
+
//setup.ts, the first import of main.ts
|
|
48
|
+
import { settings_set_name_transform } from "@chocbite/ts-lib-ui/settings";
|
|
49
|
+
settings_set_name_transform((name) => name.replace("@chocbite/ts-lib", "myapp"));
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
Called later, it reports the settings that already use their name with `console.error`. Renaming starts from empty settings, values stored under the old names are not moved.
|
|
53
|
+
|
|
54
|
+
### CSS
|
|
55
|
+
|
|
56
|
+
All styles are in one `style.css`, which every module imports itself. A bundler that handles CSS imports (e.g. Vite) picks it up automatically, nothing needs to be imported by hand.
|
|
57
|
+
|
|
58
|
+
SCSS mixins are available for use in your own styles:
|
|
59
|
+
|
|
60
|
+
```scss
|
|
61
|
+
@use "@chocbite/ts-lib-ui/theme/mixins" as scrollbar;
|
|
62
|
+
@use "@chocbite/ts-lib-ui/icons/mixins" as iconfont;
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
### Modules
|
|
66
|
+
|
|
67
|
+
- `@chocbite/ts-lib-ui/base`
|
|
68
|
+
- `@chocbite/ts-lib-ui/canvas`
|
|
69
|
+
- `@chocbite/ts-lib-ui/context-menu`
|
|
70
|
+
- `@chocbite/ts-lib-ui/document`
|
|
71
|
+
- `@chocbite/ts-lib-ui/dom`
|
|
72
|
+
- `@chocbite/ts-lib-ui/form`
|
|
73
|
+
- `@chocbite/ts-lib-ui/icons`
|
|
74
|
+
- `@chocbite/ts-lib-ui/keyboard`
|
|
75
|
+
- `@chocbite/ts-lib-ui/list`
|
|
76
|
+
- `@chocbite/ts-lib-ui/selection`
|
|
77
|
+
- `@chocbite/ts-lib-ui/settings`
|
|
78
|
+
- `@chocbite/ts-lib-ui/spinner`
|
|
79
|
+
- `@chocbite/ts-lib-ui/svg`
|
|
80
|
+
- `@chocbite/ts-lib-ui/theme`
|
|
81
|
+
|
|
82
|
+
## Module @chocbite/ts-lib-ui/context-menu
|
|
83
|
+
|
|
84
|
+
### @chocbite/ts-lib-ui/context-menu
|
|
85
|
+
|
|
86
|
+
Framework-agnostic TypeScript library for right-click / touch-and-hold context menus built on native Web Components.
|
|
87
|
+
|
|
88
|
+
#### Basic Usage
|
|
89
|
+
|
|
90
|
+
Import the library and attach a context menu to an element. The CSS is auto-injected on import.
|
|
91
|
+
|
|
92
|
+
```ts
|
|
93
|
+
import ctm from "@chocbite/ts-lib-ui/context-menu";
|
|
94
|
+
|
|
95
|
+
ctm.attach(
|
|
96
|
+
document.getElementById("editor")!,
|
|
97
|
+
ctm.menu([
|
|
98
|
+
ctm.line("Cut", () => document.execCommand("cut")),
|
|
99
|
+
ctm.line("Copy", () => document.execCommand("copy")),
|
|
100
|
+
ctm.line("Paste", () => document.execCommand("paste")),
|
|
101
|
+
]),
|
|
102
|
+
);
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
Right-click (or long-press) the element to open the menu.
|
|
106
|
+
|
|
107
|
+
#### API
|
|
108
|
+
|
|
109
|
+
##### `ctm.menu(lines)`
|
|
110
|
+
|
|
111
|
+
Creates a menu panel. `lines` can be a static array, a lazy factory, or a Promise/async factory (shows a spinner while loading).
|
|
112
|
+
|
|
113
|
+
```ts
|
|
114
|
+
// Static array
|
|
115
|
+
const menu = ctm.menu([
|
|
116
|
+
ctm.line("Option A", () => console.log("A")),
|
|
117
|
+
ctm.line("Option B", () => console.log("B")),
|
|
118
|
+
]);
|
|
119
|
+
|
|
120
|
+
// Factory — evaluated on every open
|
|
121
|
+
const menu = ctm.menu(() => [
|
|
122
|
+
ctm.line("Timestamp", () => console.log(Date.now())),
|
|
123
|
+
]);
|
|
124
|
+
|
|
125
|
+
// Async factory — shows a spinner until the Promise resolves
|
|
126
|
+
const menu = ctm.menu(async () => {
|
|
127
|
+
const items = await fetchMenuItems();
|
|
128
|
+
return items.map((item) => ctm.line(item.label, item.action));
|
|
129
|
+
});
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
---
|
|
133
|
+
|
|
134
|
+
##### `ctm.line(text, func, icon?, shortcut?, checkmark?)`
|
|
135
|
+
|
|
136
|
+
Creates a clickable menu item.
|
|
137
|
+
|
|
138
|
+
```ts
|
|
139
|
+
import { material_delete_rounded } from "@chocbite/ts-lib-ui/icons";
|
|
140
|
+
|
|
141
|
+
ctm.line("Delete", () => deleteFile());
|
|
142
|
+
ctm.line("Delete", () => deleteFile(), material_delete_rounded());
|
|
143
|
+
ctm.line("Save", () => save(), undefined, "Ctrl+S");
|
|
144
|
+
ctm.line("Mute", () => toggleMute(), undefined, undefined, isMuted);
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
---
|
|
148
|
+
|
|
149
|
+
##### `ctm.sub(text, menu, icon?)`
|
|
150
|
+
|
|
151
|
+
Creates a submenu trigger. Hover (300 ms) or keyboard (→ / Enter / Space) opens the nested menu.
|
|
152
|
+
|
|
153
|
+
```ts
|
|
154
|
+
const colorMenu = ctm.menu([
|
|
155
|
+
ctm.line("Red", () => setColor("red")),
|
|
156
|
+
ctm.line("Green", () => setColor("green")),
|
|
157
|
+
ctm.line("Blue", () => setColor("blue")),
|
|
158
|
+
]);
|
|
159
|
+
|
|
160
|
+
const menu = ctm.menu([
|
|
161
|
+
ctm.line("Copy", () => copy()),
|
|
162
|
+
ctm.sub("Color", colorMenu),
|
|
163
|
+
ctm.line("Delete", () => remove()),
|
|
164
|
+
]);
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
---
|
|
168
|
+
|
|
169
|
+
##### `ctm.devider()`
|
|
170
|
+
|
|
171
|
+
Inserts a horizontal separator.
|
|
172
|
+
|
|
173
|
+
```ts
|
|
174
|
+
const menu = ctm.menu([
|
|
175
|
+
ctm.line("Cut", () => cut()),
|
|
176
|
+
ctm.line("Copy", () => copy()),
|
|
177
|
+
ctm.devider(),
|
|
178
|
+
ctm.line("Delete", () => remove()),
|
|
179
|
+
]);
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
---
|
|
183
|
+
|
|
184
|
+
##### `ctm.attach(element, lines, block?)`
|
|
185
|
+
|
|
186
|
+
Binds a context menu to a DOM element.
|
|
187
|
+
|
|
188
|
+
```ts
|
|
189
|
+
// Static menu
|
|
190
|
+
ctm.attach(el, menu);
|
|
191
|
+
|
|
192
|
+
// Dynamic menu — factory called on each open
|
|
193
|
+
import { some, none } from "@chocbite/ts-lib/result";
|
|
194
|
+
|
|
195
|
+
ctm.attach(el, () =>
|
|
196
|
+
some(
|
|
197
|
+
ctm.menu([
|
|
198
|
+
ctm.line("Edit", () => edit(el)),
|
|
199
|
+
ctm.line("Delete", () => remove(el)),
|
|
200
|
+
]),
|
|
201
|
+
),
|
|
202
|
+
);
|
|
203
|
+
|
|
204
|
+
// Conditionally suppress the menu
|
|
205
|
+
ctm.attach(el, menu, () => el.dataset.readonly === "true");
|
|
206
|
+
|
|
207
|
+
// Return None to suppress for a specific open
|
|
208
|
+
ctm.attach(el, () => (isLocked(el) ? none() : some(menu)));
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
---
|
|
212
|
+
|
|
213
|
+
##### `ctm.detach(element)`
|
|
214
|
+
|
|
215
|
+
Removes a previously attached context menu.
|
|
216
|
+
|
|
217
|
+
```ts
|
|
218
|
+
ctm.detach(el);
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
---
|
|
222
|
+
|
|
223
|
+
##### `ctm.summon(menu, element?, x?, y?, dont_cover?)`
|
|
224
|
+
|
|
225
|
+
Opens a menu programmatically — no right-click needed.
|
|
226
|
+
|
|
227
|
+
```ts
|
|
228
|
+
// At specific coordinates, in main document
|
|
229
|
+
ctm.summon(menu, undefined, event.clientX, event.clientY);
|
|
230
|
+
|
|
231
|
+
// Centered on an element, in same document as buttonEl
|
|
232
|
+
ctm.summon(menu, buttonEl);
|
|
233
|
+
|
|
234
|
+
// Positioned beside an element, in same document as buttonEl, without covering it
|
|
235
|
+
ctm.summon(menu, buttonEl, undefined, undefined, true);
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
---
|
|
239
|
+
|
|
240
|
+
##### `ctm.default(lines | false | undefined)`
|
|
241
|
+
|
|
242
|
+
Sets a document-wide fallback context menu shown on any right-click with no element-specific menu.
|
|
243
|
+
It applies to every registered document, also documents registered later.
|
|
244
|
+
|
|
245
|
+
```ts
|
|
246
|
+
// Apply a global fallback
|
|
247
|
+
ctm.default(
|
|
248
|
+
ctm.menu([
|
|
249
|
+
ctm.line("View source", () => window.open("view-source:" + location.href)),
|
|
250
|
+
ctm.line("Inspect", () => console.log("inspect")),
|
|
251
|
+
]),
|
|
252
|
+
);
|
|
253
|
+
|
|
254
|
+
// Suppress the browser's native context menu everywhere
|
|
255
|
+
ctm.default(false);
|
|
256
|
+
|
|
257
|
+
// Give the browser's native context menu back
|
|
258
|
+
ctm.default(undefined);
|
|
259
|
+
```
|
|
260
|
+
|
|
261
|
+
---
|
|
262
|
+
|
|
263
|
+
##### `ctm.has(element)`
|
|
264
|
+
|
|
265
|
+
Returns `true` if a menu is attached to the element.
|
|
266
|
+
|
|
267
|
+
```ts
|
|
268
|
+
if (!ctm.has(el)) {
|
|
269
|
+
ctm.attach(el, menu);
|
|
270
|
+
}
|
|
271
|
+
```
|
|
272
|
+
|
|
273
|
+
#### Conditional Items
|
|
274
|
+
|
|
275
|
+
`undefined` values in a lines array are silently skipped, making conditional items clean:
|
|
276
|
+
|
|
277
|
+
```ts
|
|
278
|
+
ctm.menu(() => [
|
|
279
|
+
ctm.line("Edit", () => edit()),
|
|
280
|
+
canDelete ? ctm.line("Delete", () => remove()) : undefined,
|
|
281
|
+
isAdmin ? ctm.line("Admin Panel", () => openAdmin()) : undefined,
|
|
282
|
+
]);
|
|
283
|
+
```
|
|
284
|
+
|
|
285
|
+
#### Theming
|
|
286
|
+
|
|
287
|
+
Theming via `#theme`.
|
|
288
|
+
|
|
289
|
+
#### License
|
|
290
|
+
|
|
291
|
+
MIT
|
|
292
|
+
|
|
293
|
+
## Module @chocbite/ts-lib-ui/icons
|
|
294
|
+
|
|
295
|
+
### Mixins
|
|
296
|
+
|
|
297
|
+
Use icon font mixin like so
|
|
298
|
+
|
|
299
|
+
```
|
|
300
|
+
@use "@chocbite/ts-lib-ui/icons/mixins" as iconfont;
|
|
301
|
+
```
|
|
302
|
+
|
|
303
|
+
## Module @chocbite/ts-lib-ui/state_ui
|
|
304
|
+
|
|
305
|
+
### State UI
|
|
306
|
+
|
|
307
|
+
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
|
+
|
|
309
|
+
```ts
|
|
310
|
+
import state_ui from "@chocbite/ts-lib-ui/state";
|
|
311
|
+
```
|
|
312
|
+
|
|
313
|
+
#### `state_ui.a.apply(parent, array, handlers)`
|
|
314
|
+
|
|
315
|
+
Applies an array to the child nodes of a parent, one node per value. Arrays from array states carry what changed (added, removed, changed, moved), so only those nodes are touched. A plain array is applied as a whole.
|
|
316
|
+
|
|
317
|
+
```ts
|
|
318
|
+
const list = document.createElement("div");
|
|
319
|
+
names.sub((names) => {
|
|
320
|
+
state_ui.a.apply(list, names.ok ? names.value : [], {
|
|
321
|
+
create: (name) => {
|
|
322
|
+
const line = document.createElement("div");
|
|
323
|
+
line.textContent = name;
|
|
324
|
+
return line;
|
|
325
|
+
},
|
|
326
|
+
update: (line, name) => (line.textContent = name),
|
|
327
|
+
destroy: (line) => console.log("removed", line.textContent),
|
|
328
|
+
});
|
|
329
|
+
}, true);
|
|
330
|
+
```
|
|
331
|
+
|
|
332
|
+
Handlers, typed as `StateUIArrayApplyHandlers`:
|
|
333
|
+
|
|
334
|
+
- `create` gives the node for a value.
|
|
335
|
+
- `update` is optional. When given, nodes are reused: changed values update their node, and a whole new array updates the existing nodes before adding or removing the difference. Without it, nodes of changed values are replaced.
|
|
336
|
+
- `destroy` is optional, called for every node that is removed or replaced.
|
|
337
|
+
|
|
338
|
+
The parent must contain nothing but the nodes made for the array.
|
|
339
|
+
|
|
340
|
+
## Module @chocbite/ts-lib-ui/svg
|
|
341
|
+
|
|
342
|
+
### @chocbite/ts-lib-ui/svg
|
|
343
|
+
|
|
344
|
+
A TypeScript library for programmatic SVG generation with a fluent, chainable API.
|
|
345
|
+
|
|
346
|
+
#### Quick Start
|
|
347
|
+
|
|
348
|
+
```ts
|
|
349
|
+
import { svg } from "@chocbite/ts-lib-ui/svg";
|
|
350
|
+
|
|
351
|
+
// Create an SVG canvas and append a red circle
|
|
352
|
+
const canvas = svg.svg(200, 200).elem;
|
|
353
|
+
canvas.appendChild(
|
|
354
|
+
svg.circle(100, 100, 40).fill("red").stroke("black").stroke_width(2).elem
|
|
355
|
+
);
|
|
356
|
+
document.body.appendChild(canvas);
|
|
357
|
+
```
|
|
358
|
+
|
|
359
|
+
#### API
|
|
360
|
+
|
|
361
|
+
All drawing functions return an `SVGAttributes` wrapper that supports chaining. Call `.elem` to get the underlying `SVGElement`.
|
|
362
|
+
|
|
363
|
+
##### Primitives
|
|
364
|
+
|
|
365
|
+
###### `svg.svg(width, height, viewbox?)`
|
|
366
|
+
|
|
367
|
+
Creates an `<svg>` root element. The viewbox defaults to `"0 0 <width> <height>"`.
|
|
368
|
+
|
|
369
|
+
```ts
|
|
370
|
+
const canvas = svg.svg(400, 300).elem;
|
|
371
|
+
```
|
|
372
|
+
|
|
373
|
+
###### `svg.circle(center_x, center_y, radius)`
|
|
374
|
+
|
|
375
|
+
Creates a `<circle>` element.
|
|
376
|
+
|
|
377
|
+
```ts
|
|
378
|
+
svg.circle(50, 50, 25).fill("blue").elem;
|
|
379
|
+
```
|
|
380
|
+
|
|
381
|
+
###### `svg.ellipse(center_x, center_y, radius_x, radius_y)`
|
|
382
|
+
|
|
383
|
+
Creates an `<ellipse>` element.
|
|
384
|
+
|
|
385
|
+
```ts
|
|
386
|
+
svg.ellipse(100, 100, 60, 30).fill("green").stroke("black").elem;
|
|
387
|
+
```
|
|
388
|
+
|
|
389
|
+
###### `svg.rectangle_from_center(center_x, center_y, width, height, corner_radius)`
|
|
390
|
+
|
|
391
|
+
Creates a `<rect>` positioned by its center point.
|
|
392
|
+
|
|
393
|
+
```ts
|
|
394
|
+
svg.rectangle_from_center(100, 100, 80, 40, 5).fill("orange").elem;
|
|
395
|
+
```
|
|
396
|
+
|
|
397
|
+
###### `svg.rectangle_from_corner(start_x, start_y, width, height, corner_radius)`
|
|
398
|
+
|
|
399
|
+
Creates a `<rect>` positioned by its top-left corner.
|
|
400
|
+
|
|
401
|
+
```ts
|
|
402
|
+
svg.rectangle_from_corner(10, 10, 80, 40, 0).fill("purple").elem;
|
|
403
|
+
```
|
|
404
|
+
|
|
405
|
+
###### `svg.line(start_x, start_y, end_x, end_y)`
|
|
406
|
+
|
|
407
|
+
Creates a `<line>` element.
|
|
408
|
+
|
|
409
|
+
```ts
|
|
410
|
+
svg.line(0, 0, 100, 100).stroke("black").stroke_width(2).elem;
|
|
411
|
+
```
|
|
412
|
+
|
|
413
|
+
###### `svg.path(d)`
|
|
414
|
+
|
|
415
|
+
Creates a `<path>` element with the given path data string.
|
|
416
|
+
|
|
417
|
+
```ts
|
|
418
|
+
svg.path("M 10 80 C 40 10, 65 10, 95 80").stroke("black").fill("none").elem;
|
|
419
|
+
```
|
|
420
|
+
|
|
421
|
+
###### `svg.isosceles_triangle(center_x, center_y, width, height)`
|
|
422
|
+
|
|
423
|
+
Creates an isosceles triangle as a `<path>`.
|
|
424
|
+
|
|
425
|
+
```ts
|
|
426
|
+
svg.isosceles_triangle(100, 100, 60, 80).fill("yellow").stroke("black").elem;
|
|
427
|
+
```
|
|
428
|
+
|
|
429
|
+
###### `svg.circle_arc(center_x, center_y, radius, start_angle, end_angle)`
|
|
430
|
+
|
|
431
|
+
Draws a circular arc. Angles are in degrees.
|
|
432
|
+
|
|
433
|
+
```ts
|
|
434
|
+
svg.circle_arc(100, 100, 50, 0, 90).stroke("red").fill("none").stroke_width(2).elem;
|
|
435
|
+
```
|
|
436
|
+
|
|
437
|
+
###### `svg.ellipse_arc(center_x, center_y, radius_x, radius_y, start_angle, end_angle)`
|
|
438
|
+
|
|
439
|
+
Draws an elliptical arc. Angles are in degrees.
|
|
440
|
+
|
|
441
|
+
```ts
|
|
442
|
+
svg.ellipse_arc(100, 100, 60, 30, 0, 180).stroke("blue").fill("none").elem;
|
|
443
|
+
```
|
|
444
|
+
|
|
445
|
+
###### `svg.text(x, y, text, size, anchor)`
|
|
446
|
+
|
|
447
|
+
Creates a single-line `<text>` element. The `anchor` parameter controls text alignment using `SVGAnchorPoint`.
|
|
448
|
+
|
|
449
|
+
```ts
|
|
450
|
+
import { svg, SVGAnchorPoint } from "@chocbite/ts-lib-ui/svg";
|
|
451
|
+
|
|
452
|
+
svg.text(100, 50, "Hello", 16, SVGAnchorPoint.middleCenter).fill("black").elem;
|
|
453
|
+
```
|
|
454
|
+
|
|
455
|
+
###### `svg.multi_line_text(x, y, width, height, text, size, anchor)`
|
|
456
|
+
|
|
457
|
+
Creates a multi-line text block using a `<foreignObject>` with an inner `<div>`.
|
|
458
|
+
|
|
459
|
+
```ts
|
|
460
|
+
svg.multi_line_text(10, 10, 200, 100, "Long text that wraps", 14, SVGAnchorPoint.topLeft).elem;
|
|
461
|
+
```
|
|
462
|
+
|
|
463
|
+
###### `svg.group()`
|
|
464
|
+
|
|
465
|
+
Creates a `<g>` group element. Append child elements to it.
|
|
466
|
+
|
|
467
|
+
```ts
|
|
468
|
+
const g = svg.group().translate(50, 50).elem;
|
|
469
|
+
g.appendChild(svg.circle(0, 0, 20).fill("red").elem);
|
|
470
|
+
g.appendChild(svg.circle(40, 0, 20).fill("blue").elem);
|
|
471
|
+
```
|
|
472
|
+
|
|
473
|
+
###### `svg.create(tagName)`
|
|
474
|
+
|
|
475
|
+
Creates an arbitrary SVG element by tag name (e.g. `"defs"`, `"clipPath"`).
|
|
476
|
+
|
|
477
|
+
```ts
|
|
478
|
+
const defs = svg.create("defs").elem;
|
|
479
|
+
```
|
|
480
|
+
|
|
481
|
+
##### Chaining Attributes
|
|
482
|
+
|
|
483
|
+
Every primitive returns an `SVGAttributes` wrapper with chainable methods:
|
|
484
|
+
|
|
485
|
+
| Method | Shorthand | Description |
|
|
486
|
+
|---|---|---|
|
|
487
|
+
| `.fill(color)` | `.f(color)` | Set fill color |
|
|
488
|
+
| `.stroke(color)` | `.s(color)` | Set stroke color |
|
|
489
|
+
| `.stroke_width(n)` | `.sw(n)` | Set stroke width |
|
|
490
|
+
| `.class_list(...names)` | `.cl(...names)` | Add CSS class names |
|
|
491
|
+
| `.attribute(name, value)` | `.a(name, value)` | Set any attribute |
|
|
492
|
+
| `.translate(x, y)` | | Apply translate transform |
|
|
493
|
+
| `.rotate(angle, cx?, cy?)` | | Apply rotate transform |
|
|
494
|
+
| `.scale(sx, sy?)` | | Apply scale transform |
|
|
495
|
+
| `.skewX(angle)` | | Apply skewX transform |
|
|
496
|
+
| `.skewY(angle)` | | Apply skewY transform |
|
|
497
|
+
| `.transform(str)` | | Apply a custom transform string |
|
|
498
|
+
| `.elem` | | Get the underlying `SVGElement` |
|
|
499
|
+
|
|
500
|
+
Transforms are accumulated and written to the `transform` attribute when `.elem` is accessed.
|
|
501
|
+
|
|
502
|
+
```ts
|
|
503
|
+
svg.circle(0, 0, 10)
|
|
504
|
+
.fill("red")
|
|
505
|
+
.stroke("black")
|
|
506
|
+
.stroke_width(1)
|
|
507
|
+
.class_list("my-circle")
|
|
508
|
+
.translate(50, 50)
|
|
509
|
+
.rotate(45)
|
|
510
|
+
.elem;
|
|
511
|
+
```
|
|
512
|
+
|
|
513
|
+
##### Utilities
|
|
514
|
+
|
|
515
|
+
###### `SVGAnchorPoint`
|
|
516
|
+
|
|
517
|
+
An enum-like object describing text anchor positions:
|
|
518
|
+
|
|
519
|
+
```ts
|
|
520
|
+
import { SVGAnchorPoint } from "@chocbite/ts-lib-ui/svg";
|
|
521
|
+
|
|
522
|
+
SVGAnchorPoint.topLeft; // 2
|
|
523
|
+
SVGAnchorPoint.topCenter; // 3
|
|
524
|
+
SVGAnchorPoint.topRight; // 4
|
|
525
|
+
SVGAnchorPoint.middleLeft; // 1
|
|
526
|
+
SVGAnchorPoint.middleCenter; // 8
|
|
527
|
+
SVGAnchorPoint.middleRight; // 5
|
|
528
|
+
SVGAnchorPoint.bottomLeft; // 0
|
|
529
|
+
SVGAnchorPoint.bottomCenter; // 7
|
|
530
|
+
SVGAnchorPoint.bottomRight; // 6
|
|
531
|
+
```
|
|
532
|
+
|
|
533
|
+
###### `svg.angle_to_anchor_point(angle)`
|
|
534
|
+
|
|
535
|
+
Converts an angle (in radians) to the nearest `SVGAnchorPoint`. Useful for placing labels around a circle.
|
|
536
|
+
|
|
537
|
+
```ts
|
|
538
|
+
const anchor = svg.angle_to_anchor_point(Math.PI / 4); // bottomRight
|
|
539
|
+
```
|
|
540
|
+
|
|
541
|
+
#### Full Example
|
|
542
|
+
|
|
543
|
+
```ts
|
|
544
|
+
import { svg, SVGAnchorPoint } from "@chocbite/ts-lib-ui/svg";
|
|
545
|
+
|
|
546
|
+
const canvas = svg.svg(300, 300).elem;
|
|
547
|
+
|
|
548
|
+
// Background
|
|
549
|
+
canvas.appendChild(
|
|
550
|
+
svg.rectangle_from_corner(0, 0, 300, 300, 0).fill("#f0f0f0").elem
|
|
551
|
+
);
|
|
552
|
+
|
|
553
|
+
// Grouped shapes
|
|
554
|
+
const g = svg.group().translate(150, 150).elem;
|
|
555
|
+
g.appendChild(svg.circle(0, 0, 50).fill("none").stroke("steelblue").stroke_width(2).elem);
|
|
556
|
+
g.appendChild(svg.line(-50, 0, 50, 0).stroke("gray").stroke_width(1).elem);
|
|
557
|
+
g.appendChild(svg.line(0, -50, 0, 50).stroke("gray").stroke_width(1).elem);
|
|
558
|
+
g.appendChild(svg.text(0, -60, "Center", 12, SVGAnchorPoint.bottomCenter).fill("black").elem);
|
|
559
|
+
canvas.appendChild(g);
|
|
560
|
+
|
|
561
|
+
document.body.appendChild(canvas);
|
|
562
|
+
```
|
|
563
|
+
|
|
564
|
+
#### License
|
|
565
|
+
|
|
566
|
+
MIT
|
|
567
|
+
|
|
568
|
+
## Module @chocbite/ts-lib-ui/test
|
|
569
|
+
|
|
570
|
+
### @chocbite/ts-lib-ui/test
|
|
571
|
+
|
|
572
|
+
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`.
|
|
573
|
+
|
|
574
|
+
Delete this module or move `attach_input` to `Base` before the next release, otherwise it gets published.
|
|
575
|
+
|
|
576
|
+
## Module @chocbite/ts-lib-ui/theme
|
|
577
|
+
|
|
578
|
+
### Theme
|
|
579
|
+
|
|
580
|
+
Colors, scale, scrollbar size, input mode and animations for the UI, stored as user settings.
|
|
581
|
+
|
|
582
|
+
#### Starting the theme
|
|
583
|
+
|
|
584
|
+
The app must call `theme_init` once, nothing of the theme is applied to the page before that.
|
|
585
|
+
|
|
586
|
+
```ts
|
|
587
|
+
import { theme_init, Themes } from "@chocbite/ts-lib-ui/theme";
|
|
588
|
+
|
|
589
|
+
// Device with an operating system dark mode, the user can pick Light, Dark or System
|
|
590
|
+
theme_init({ system: true });
|
|
591
|
+
|
|
592
|
+
// Device without it, for example decided from the user agent, the user can pick Light or Dark
|
|
593
|
+
theme_init({ default: Themes.Dark });
|
|
594
|
+
```
|
|
595
|
+
|
|
596
|
+
Options:
|
|
597
|
+
|
|
598
|
+
- `system` offers the System theme, which follows the light or dark mode of the operating system. Only with `system` on is the operating system dark mode read. The System choice shows the active theme, for example "System (Dark)".
|
|
599
|
+
- `default` is the theme used until the user chooses one, it defaults to System with `system` on and Light otherwise. The default is not stored, a theme is only stored when the user chooses one.
|
|
600
|
+
|
|
601
|
+
`theme_init` throws when called twice, or when System is the default without `system` on.
|
|
602
|
+
|
|
603
|
+
#### Mixins
|
|
604
|
+
|
|
605
|
+
Use scrollbar mixin like so
|
|
606
|
+
|
|
607
|
+
```
|
|
608
|
+
@use "@chocbite/ts-lib-ui/theme/mixins" as scrollbar;
|
|
609
|
+
```
|