@silkui/core 0.1.0 → 0.1.1

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.
Files changed (2) hide show
  1. package/README.md +178 -2
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,4 +1,180 @@
1
1
  # @silkui/core
2
2
 
3
- The nodes and events of a Silk UI tree for JavaScript applications that run on the embedded
4
- SilkJS engine. See [ui-js](../../README.md) for the API and the host.
3
+ The node and event API of a [Silk UI](https://github.com/silk-lang/SilkUI) tree, for
4
+ JavaScript apps that run on the SilkJS engine embedded in a Silk UI program. Its nodes are
5
+ the tree's own (box, text, input, rich input, image, icon, canvas). Its methods and its
6
+ event flow are the DOM's: `appendChild`, `addEventListener`, capture and bubble,
7
+ `preventDefault`.
8
+
9
+ `@silkui/react` and `@silkui/foldkit` are built on it. Use it directly for a plain
10
+ JavaScript or TypeScript app, or to draw on nodes from inside a framework app.
11
+
12
+ ## Install
13
+
14
+ The quickest start is a template, which sets up the Silk host, Vite and this package:
15
+
16
+ ```sh
17
+ silk init my-app -t ui-js # plain TypeScript; ui-react and ui-foldkit use this package too
18
+ cd my-app
19
+ silk task dev
20
+ ```
21
+
22
+ See [Get started](https://silk-ui-docs.juliaortiz-js.workers.dev/start/). To add it to an
23
+ existing Silk UI web project:
24
+
25
+ ```sh
26
+ npm install @silkui/core
27
+ ```
28
+
29
+ The package runs inside a Silk UI host (the native window, or the web canvas), which provides
30
+ the native functions it calls. It does not run in Node or in a plain browser page by itself.
31
+
32
+ ## Usage
33
+
34
+ ```ts
35
+ import { createBox, createText, mount } from "@silkui/core";
36
+
37
+ const label = createText("Clicked 0 times");
38
+ const button = createBox(
39
+ { paddingTop: 12, paddingBottom: 12, paddingLeft: 20, paddingRight: 20, borderRadius: 10, backgroundColor: "rgb(37, 99, 235)", color: "white" },
40
+ label,
41
+ );
42
+ button.tabIndex = 0;
43
+ button.look("hover").set({ backgroundColor: "rgb(59, 130, 246)" });
44
+
45
+ let clicks = 0;
46
+ button.addEventListener("click", () => {
47
+ clicks += 1;
48
+ label.data = `Clicked ${clicks} times`;
49
+ });
50
+
51
+ mount(createBox({ position: "absolute", inset: 0, display: "flex", alignItems: "center", justifyContent: "center" }, button));
52
+ ```
53
+
54
+ ## API
55
+
56
+ ### Nodes
57
+
58
+ | Export | What it does |
59
+ | --- | --- |
60
+ | `createBox(style?, ...children)` | A box with `style` as its base look. Strings among the children become text nodes |
61
+ | `createText(data?)` | A text node. It takes its look from its parent |
62
+ | `createInput(style?)` | An editable text field. `value`, `selectionStart`, `selectionEnd` and `setSelectionRange` work as on an `<input>` |
63
+ | `createRichInput(style?)` | A text field with marks and inline atoms (see below) |
64
+ | `createIcon(svg, style?)` | SVG markup drawn at the node's size, with its `color` as `currentColor` |
65
+ | `createNode(kind)` | A node of any kind: `"box"`, `"text"`, `"input"`, `"richinput"`, `"image"`, `"icon"`, `"canvas"` |
66
+ | `mount(node)` / `root()` | Makes a node the root of the window's tree, or returns it |
67
+ | `nodeById(id)` | The node with a tree id, for hosts and tools |
68
+
69
+ A node has `append`, `appendChild`, `insertBefore`, `removeChild`, `remove`, `contains`,
70
+ `parentNode`, `childNodes`, `firstChild`, `lastChild` and the sibling getters, as in the DOM.
71
+ A removed node keeps its state and can be inserted again. `destroy()` frees a node and its
72
+ subtree for good. `focus()` and `scrollTo(x, y)` do what their names say.
73
+
74
+ ### Style and looks
75
+
76
+ ```ts
77
+ node.style.set({ width: 120, flexGrow: 1, fontFamily: "Noto Sans, sans-serif" });
78
+ node.style = { height: 40 }; // replaces the base look
79
+ node.look("hover").set({ opacity: 0.8 }); // also "active", "focus", "focusVisible"
80
+ node.look("starting").set({ opacity: 0 }); // what transitions start from, as @starting-style
81
+ ```
82
+
83
+ - Properties use their camel case names, typed from `csstype`. Numbers are CSS pixels,
84
+ except for unitless properties such as `opacity`, `flexGrow`, `zIndex` and `lineHeight`.
85
+ `null` takes a property out.
86
+ - Layout is CSS: flex, grid (`gridTemplateColumns: "auto 1fr"`, `repeat()`, `minmax()`,
87
+ named lines, `gridTemplateAreas`, `gridArea`, `gridColumn: "span 2"`) and positioning.
88
+ Grid properties apply from the base look only.
89
+ - `fontFamily` takes CSS `font-family` text, resolved in the host's fonts.
90
+ - `transition` and `animation` work as in CSS. `defineKeyframes(name, { from: {...}, "50%": {...}, to: {...} })`
91
+ defines `@keyframes` for them.
92
+
93
+ ### Events
94
+
95
+ ```ts
96
+ node.addEventListener("pointerdown", (event) => event.preventDefault(), { capture: true });
97
+ ```
98
+
99
+ An event runs the capture phase from the root down, the target, then bubbles, with
100
+ `stopPropagation`, `stopImmediatePropagation`, `preventDefault` and `composedPath`, as on the
101
+ web. Listeners run before the tree's default action, so `preventDefault()` on a
102
+ `pointerdown` keeps the focus where it is. `dispatchEvent(event)` runs an `Event` you made
103
+ through the tree.
104
+
105
+ | Events | Members |
106
+ | --- | --- |
107
+ | `pointerdown`, `pointerup`, `click` | `clientX`, `clientY`, `button`, `detail` (2 for a double click), modifier keys |
108
+ | `pointermove`, `pointerenter`, `pointerleave`, `pointercancel` | `clientX`, `clientY`, modifier keys |
109
+ | `wheel` | `deltaX`, `deltaY` |
110
+ | `keydown`, `keyup` | `key`, `code`, `repeat`, modifier keys |
111
+ | `focus`, `blur`, `load`, `error`, `gotpointercapture`, `lostpointercapture` | |
112
+ | `input` | `value`, `inputType`, and `document` on a rich input |
113
+ | `selectionchange` | `selectionStart`, `selectionEnd` |
114
+ | `scroll` | `scrollLeft`, `scrollTop` |
115
+ | `layout` | `bounds`: where layout put the node, in window pixels |
116
+ | `transitionrun`, `transitionstart`, `transitionend`, `transitioncancel` | `propertyName`, `elapsedTime` |
117
+ | `animationstart`, `animationiteration`, `animationend`, `animationcancel` | `animationName`, `elapsedTime` |
118
+
119
+ A listener that throws does not stop the dispatch. `setErrorHandler(handler)` receives the
120
+ exception; without one the host reports it.
121
+
122
+ ### Attributes and accessibility
123
+
124
+ `setAttribute(name, value)` sets the tree's attributes: `tabIndex`, `disabled`, `label`,
125
+ `testId`, `placeholder`, `multiline`, `readOnly`, `checked`, `selected`, `expanded`,
126
+ `focusTrap`, `inert`, `href`, `cursor` and `transition`, plus `id`. A name the tree does not
127
+ have throws a `TypeError`. `tabIndex` and `disabled` are also properties.
128
+
129
+ - `role` and the ARIA attributes work as in the DOM, spelled `aria-label` or `ariaLabel`.
130
+ `aria-labelledby`, `aria-describedby`, `aria-controls` and `aria-activedescendant` name
131
+ other nodes by their `id`.
132
+ - `announce(message, { politeness })` has screen readers say a message nothing on screen shows.
133
+ - `inert` puts a subtree out of reach of focus, pointers and screen readers, as in HTML.
134
+ - A node with an `href` is a link: a click on it that no listener prevented opens the address.
135
+
136
+ ### Rich inputs
137
+
138
+ A rich input edits a document of styled text and inline atoms (mentions, chips):
139
+
140
+ ```ts
141
+ import { createRichInput, OBJECT } from "@silkui/core";
142
+
143
+ const field = createRichInput({ width: 400 });
144
+ field.defineMark("bold", { fontWeight: 700 });
145
+ field.defineAtom("mention", { backgroundColor: "rgb(219, 234, 254)", borderRadius: 4 });
146
+ field.document = { text: `Hi ${OBJECT}`, marks: [], atoms: [{ kind: "mention", label: "@ada", data: "user-1" }] };
147
+ field.addEventListener("input", (event) => save(event.document));
148
+ ```
149
+
150
+ - An atom sits in `text` as one `OBJECT` character (U+FFFC), so the caret steps over it and
151
+ Backspace deletes it whole. Offsets are string indices.
152
+ - `format(name, on)` and `toggleMark(name)` mark the selection, or the text typed next at a
153
+ caret. `activeMarks` holds the marks typed text gets.
154
+ - `insertAtom(start, end, atom)` replaces a range with an atom, such as a `@` trigger
155
+ turning into a mention. Listen for `selectionchange` to open a picker.
156
+ - Undo, IME and copy work as in a plain input.
157
+
158
+ ### Markdown
159
+
160
+ `parseMarkdown(text, options?)` returns the syntax tree of Markdown text in the shape of
161
+ [mdast](https://github.com/syntax-tree/mdast), the tree remark gives, so renderers written
162
+ for remark work on it and the app needs no Markdown parser in its bundle. It is CommonMark
163
+ with GitHub's tables, strikethrough, task lists and autolinks (`gfm: false` turns them off,
164
+ or set `tables`, `strikethrough`, `taskLists` and `autolinkLiterals` one by one).
165
+ `footnotes`, `frontmatter` and `alerts` (`> [!NOTE]`) turn on more. Nodes have no
166
+ `position`.
167
+
168
+ ## TypeScript
169
+
170
+ The package ships its types. Every node class, event and style property is typed, and
171
+ `addEventListener` gives each listener the event of its type. `parseMarkdown` returns the
172
+ `mdast` `Root` type.
173
+
174
+ ## More
175
+
176
+ - [The ui-js reference](https://github.com/silk-lang/SilkUI/blob/main/modules/js/README.md):
177
+ every package, the host, and the web globals a realm has.
178
+ - [Templates](https://github.com/silk-lang/examples) and
179
+ [Get started](https://silk-ui-docs.juliaortiz-js.workers.dev/start/).
180
+ - [Source](https://github.com/silk-lang/SilkUI/tree/main/modules/js/packages/core). MIT license.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@silkui/core",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "The node and event API of a Silk UI tree for JavaScript applications that run on the embedded SilkJS engine",
5
5
  "repository": {
6
6
  "type": "git",