@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.
- package/README.md +178 -2
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,4 +1,180 @@
|
|
|
1
1
|
# @silkui/core
|
|
2
2
|
|
|
3
|
-
The
|
|
4
|
-
SilkJS engine
|
|
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.
|