@silkui/core 0.0.0-canary.0 → 0.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/README.md CHANGED
@@ -1,3 +1,4 @@
1
1
  # @silkui/core
2
2
 
3
- Placeholder release. Nothing to use here yet.
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.
package/package.json CHANGED
@@ -1,11 +1,26 @@
1
1
  {
2
2
  "name": "@silkui/core",
3
- "version": "0.0.0-canary.0",
4
- "description": "Placeholder release. The first real version of @silkui/core is published from silk-lang/lib-ui.",
5
- "license": "MIT",
3
+ "version": "0.1.0",
4
+ "description": "The node and event API of a Silk UI tree for JavaScript applications that run on the embedded SilkJS engine",
6
5
  "repository": {
7
6
  "type": "git",
8
- "url": "git+https://github.com/silk-lang/lib-ui.git"
7
+ "url": "git+https://github.com/silk-lang/SilkUI.git",
8
+ "directory": "modules/js/packages/core"
9
+ },
10
+ "type": "module",
11
+ "exports": {
12
+ ".": {
13
+ "types": "./src/index.d.ts",
14
+ "default": "./src/index.js"
15
+ }
9
16
  },
10
- "files": ["README.md"]
17
+ "files": [
18
+ "src"
19
+ ],
20
+ "sideEffects": true,
21
+ "license": "MIT",
22
+ "dependencies": {
23
+ "@types/mdast": "^4.0.4",
24
+ "csstype": "^3.1.3"
25
+ }
11
26
  }
package/src/index.d.ts ADDED
@@ -0,0 +1,319 @@
1
+ import type * as CSS from "csstype";
2
+
3
+ /** The node kinds of the tree. `richinput` is an `input` with marks and atoms. */
4
+ export type NodeKind = "box" | "text" | "input" | "richinput" | "image" | "icon" | "canvas";
5
+
6
+ /** The looks a state lays over the base look: `:hover`, `:active`, `:focus`, `:focus-visible`, `@starting-style`. */
7
+ export type LookState = "base" | "hover" | "active" | "focus" | "focusVisible" | "starting";
8
+
9
+ /**
10
+ * Style properties by their camel case names. Numbers are CSS pixels except for unitless
11
+ * properties (`opacity`, `flexGrow`, `zIndex`, `fontWeight`, `lineHeight` and the like).
12
+ * `null`, `undefined` and `""` take a property out.
13
+ */
14
+ export type Style = {
15
+ [K in keyof CSS.Properties<string | number>]?: CSS.Properties<string | number>[K] | null;
16
+ };
17
+
18
+ /** The declarations of one look of a node. */
19
+ export interface Look {
20
+ /** Sets properties over the ones the look has. */
21
+ set(properties: Style): void;
22
+ /** Replaces the whole look. */
23
+ replace(properties: Style): void;
24
+ /** A property as the tree got it, in CSS text (`"120px"`). */
25
+ get(name: keyof Style): string | undefined;
26
+ readonly cssText: string;
27
+ }
28
+
29
+ export type Listener<E extends Event = Event> = ((this: Node, event: E) => void) | { handleEvent(event: E): void };
30
+ export type ListenerOptions = boolean | { capture?: boolean; once?: boolean };
31
+
32
+ /** A node of the tree. Make one with `createBox`, `createText`, `createInput` or `createNode`. */
33
+ export class Node {
34
+ constructor(kind: NodeKind);
35
+ /** The tree's number for the node (not the DOM `id`: that is `setAttribute("id", ...)`). */
36
+ readonly id: number;
37
+ readonly kind: NodeKind;
38
+ readonly parentNode: Node | null;
39
+ readonly childNodes: readonly Node[];
40
+ readonly firstChild: Node | null;
41
+ readonly lastChild: Node | null;
42
+ readonly nextSibling: Node | null;
43
+ readonly previousSibling: Node | null;
44
+ /** Whether `other` is this node or inside it. */
45
+ contains(other: Node | null): boolean;
46
+ /** Inserts `child` before `before`, or last without it. A child already in the tree moves. */
47
+ insertBefore<T extends Node>(child: T, before?: Node | null): T;
48
+ appendChild<T extends Node>(child: T): T;
49
+ /** Appends nodes, and strings as text nodes. */
50
+ append(...children: (Node | string)[]): void;
51
+ /** Detaches `child` and its subtree. It keeps its state and can be inserted again. */
52
+ removeChild<T extends Node>(child: T): T;
53
+ remove(): void;
54
+ /** Detaches and frees this node and its subtree. They cannot be used again. */
55
+ destroy(): void;
56
+ /** The base look: `node.style.set({ width: 120 })` sets properties, `node.style = { ... }` replaces it. */
57
+ get style(): Look;
58
+ set style(properties: Style);
59
+ /** The look the tree lays over the base in `state`. */
60
+ look(state: LookState): Look;
61
+ /**
62
+ * Sets a tree attribute (`tabIndex`, `disabled`, `label`, `testId`, `placeholder`, `href`,
63
+ * `cursor`, `multiline`, `readOnly`, `inert`, `focusTrap`, `transition`), `id`, `role`, or
64
+ * an ARIA attribute spelled `aria-checked` or `ariaChecked`.
65
+ */
66
+ setAttribute(name: string, value: unknown): void;
67
+ set tabIndex(value: number);
68
+ set disabled(value: boolean);
69
+ focus(): void;
70
+ scrollTo(x: number, y: number): void;
71
+ addEventListener<K extends keyof EventMap>(type: K, listener: Listener<EventMap[K]>, options?: ListenerOptions): void;
72
+ removeEventListener<K extends keyof EventMap>(type: K, listener: Listener<EventMap[K]>, options?: ListenerOptions): void;
73
+ }
74
+
75
+ /** A text leaf. It takes its look from its parent. */
76
+ export class Text extends Node {
77
+ constructor(data?: string);
78
+ data: string;
79
+ textContent: string;
80
+ }
81
+
82
+ /** An editable text field. `value` follows what the user types. */
83
+ export class Input extends Node {
84
+ constructor();
85
+ value: string;
86
+ readonly selectionStart: number;
87
+ readonly selectionEnd: number;
88
+ /** Selects from `anchor` to `focus`, as UTF-8 byte offsets in the value. */
89
+ setSelectionRange(anchor: number, focus: number): void;
90
+ }
91
+
92
+ /** An inline atom of a rich input: a mention or a chip. */
93
+ export interface RichAtom {
94
+ kind: string;
95
+ label: string;
96
+ data: string;
97
+ }
98
+
99
+ /** A styled run of a rich input's text. */
100
+ export interface RichMarks {
101
+ start: number;
102
+ end: number;
103
+ marks: readonly string[];
104
+ }
105
+
106
+ /**
107
+ * A rich input's content. Each atom sits in `text` as one `OBJECT` character; `atoms` lists
108
+ * them in text order. Offsets are string indices.
109
+ */
110
+ export interface RichDocument {
111
+ text: string;
112
+ marks: readonly RichMarks[];
113
+ atoms: readonly RichAtom[];
114
+ }
115
+
116
+ /** Where an atom sits in a rich input's text: U+FFFC OBJECT REPLACEMENT CHARACTER. */
117
+ export const OBJECT: string;
118
+
119
+ /** A rich text field: marks and inline atoms over the text the user edits. */
120
+ export class RichInput extends Input {
121
+ /** The marks text typed at the caret gets, as of the last change. */
122
+ readonly activeMarks: readonly string[];
123
+ /** Replacing it moves the caret to the end and forgets the undo history. */
124
+ get document(): RichDocument;
125
+ set document(document: Partial<RichDocument>);
126
+ /** What text with mark `name` looks like. */
127
+ defineMark(name: string, style: Style): void;
128
+ /** What atoms of `kind` look like: the inline block holding the label. */
129
+ defineAtom(kind: string, style: Style): void;
130
+ /** Turns mark `name` on or off over the selection, or for the text typed next. */
131
+ format(name: string, on?: boolean): void;
132
+ toggleMark(name: string): void;
133
+ /** Replaces the text from `start` to `end` with `atom`. */
134
+ insertAtom(start: number, end: number, atom: RichAtom): void;
135
+ /** Selects from `anchor` to `focus`, as string indices. */
136
+ setSelectionRange(anchor: number, focus: number): void;
137
+ }
138
+
139
+ /** An icon: SVG markup drawn at the node's CSS size, with its `color` as `currentColor`. */
140
+ export class Icon extends Node {
141
+ constructor(svg?: string);
142
+ svg: string;
143
+ }
144
+
145
+ /** An event of the tree, with the members of the DOM event it corresponds to. */
146
+ export class Event {
147
+ constructor(type: keyof EventMap, target: Node);
148
+ readonly type: keyof EventMap;
149
+ readonly target: Node;
150
+ readonly currentTarget: Node | null;
151
+ /** 0 none, 1 capturing, 2 at the target, 3 bubbling. */
152
+ readonly eventPhase: 0 | 1 | 2 | 3;
153
+ readonly bubbles: boolean;
154
+ readonly cancelable: boolean;
155
+ readonly defaultPrevented: boolean;
156
+ preventDefault(): void;
157
+ stopPropagation(): void;
158
+ stopImmediatePropagation(): void;
159
+ /** The nodes the event passes, target first. */
160
+ composedPath(): Node[];
161
+ }
162
+
163
+ export interface ModifierEvent extends Event {
164
+ readonly shiftKey: boolean;
165
+ readonly ctrlKey: boolean;
166
+ readonly altKey: boolean;
167
+ readonly metaKey: boolean;
168
+ }
169
+
170
+ export interface PointerEvent extends ModifierEvent {
171
+ readonly clientX: number;
172
+ readonly clientY: number;
173
+ readonly x: number;
174
+ readonly y: number;
175
+ }
176
+
177
+ /** `pointerdown`, `pointerup` and `click`. */
178
+ export interface PointerButtonEvent extends PointerEvent {
179
+ readonly button: number;
180
+ /** The click count: 2 for a double click. */
181
+ readonly detail: number;
182
+ }
183
+
184
+ export interface WheelEvent extends PointerEvent {
185
+ readonly deltaX: number;
186
+ readonly deltaY: number;
187
+ }
188
+
189
+ export interface KeyboardEvent extends ModifierEvent {
190
+ readonly key: string;
191
+ readonly code: string;
192
+ readonly repeat: boolean;
193
+ }
194
+
195
+ /** An input or selection event's target: the field itself, or a field inside a node that listens. */
196
+ type FieldOf<T extends Node> = T extends Input ? T : Input;
197
+
198
+ export interface InputEvent<T extends Node = Input> extends Event {
199
+ readonly target: FieldOf<T>;
200
+ readonly value: string;
201
+ readonly inputType: string;
202
+ /** On a rich input: its document after the change. */
203
+ readonly document: FieldOf<T> extends RichInput ? RichDocument : RichDocument | undefined;
204
+ }
205
+
206
+ export interface SelectionEvent<T extends Node = Input> extends Event {
207
+ readonly target: FieldOf<T>;
208
+ readonly selectionStart: number;
209
+ readonly selectionEnd: number;
210
+ }
211
+
212
+ export interface ScrollEvent extends Event {
213
+ readonly scrollLeft: number;
214
+ readonly scrollTop: number;
215
+ }
216
+
217
+ /** Where layout put the node, in window pixels. */
218
+ export interface LayoutEvent extends Event {
219
+ readonly bounds: { x: number; y: number; width: number; height: number };
220
+ }
221
+
222
+ export interface TransitionEvent extends Event {
223
+ readonly propertyName: string;
224
+ readonly elapsedTime: number;
225
+ readonly pseudoElement: string;
226
+ }
227
+
228
+ export interface AnimationEvent extends Event {
229
+ readonly animationName: string;
230
+ readonly elapsedTime: number;
231
+ readonly pseudoElement: string;
232
+ }
233
+
234
+ /** The events of the tree by type. */
235
+ export interface EventMap {
236
+ pointerdown: PointerButtonEvent;
237
+ pointerup: PointerButtonEvent;
238
+ click: PointerButtonEvent;
239
+ pointermove: PointerEvent;
240
+ pointerenter: PointerEvent;
241
+ pointerleave: PointerEvent;
242
+ pointercancel: PointerEvent;
243
+ wheel: WheelEvent;
244
+ keydown: KeyboardEvent;
245
+ keyup: KeyboardEvent;
246
+ focus: Event;
247
+ blur: Event;
248
+ input: InputEvent;
249
+ selectionchange: SelectionEvent;
250
+ scroll: ScrollEvent;
251
+ layout: LayoutEvent;
252
+ gotpointercapture: Event;
253
+ lostpointercapture: Event;
254
+ load: Event;
255
+ error: Event;
256
+ transitionrun: TransitionEvent;
257
+ transitionstart: TransitionEvent;
258
+ transitionend: TransitionEvent;
259
+ transitioncancel: TransitionEvent;
260
+ animationstart: AnimationEvent;
261
+ animationiteration: AnimationEvent;
262
+ animationend: AnimationEvent;
263
+ animationcancel: AnimationEvent;
264
+ }
265
+
266
+ export function createNode(kind: "text"): Text;
267
+ export function createNode(kind: "input"): Input;
268
+ export function createNode(kind: "richinput"): RichInput;
269
+ export function createNode(kind: "icon"): Icon;
270
+ export function createNode(kind: NodeKind): Node;
271
+
272
+ /** A box with `style` as its base look and `children` appended. */
273
+ export function createBox(style?: Style | null, ...children: (Node | string)[]): Node;
274
+ export function createText(data?: string): Text;
275
+ export function createInput(style?: Style | null): Input;
276
+ export function createRichInput(style?: Style | null): RichInput;
277
+ /** An icon showing `svg` markup, with `style` as its base look. */
278
+ export function createIcon(svg: string, style?: Style | null): Icon;
279
+
280
+ /**
281
+ * Defines `@keyframes name`: `{ from: { opacity: 0 }, "50%": { ... }, to: { ... } }`.
282
+ * Defining a name again replaces its rule.
283
+ */
284
+ export function defineKeyframes(name: string, frames: Record<string, Style>): void;
285
+
286
+ /** Makes `node` the root of the window's tree. */
287
+ export function mount<T extends Node>(node: T): T;
288
+ export function root(): Node | null;
289
+
290
+ /** Has screen readers say `message` without showing it. */
291
+ export function announce(message: string, options?: { politeness?: "polite" | "assertive" }): void;
292
+
293
+ /** The node with tree id `id`, for hosts and tools. */
294
+ export function nodeById(id: number): Node | null;
295
+
296
+ /** Runs `event` through the tree as the DOM does. Returns false when a listener prevented the default. */
297
+ export function dispatchEvent(event: Event): boolean;
298
+
299
+ export interface MarkdownOptions {
300
+ /** GitHub's tables, strikethrough, task lists and autolinks. Default true. */
301
+ gfm?: boolean;
302
+ tables?: boolean;
303
+ strikethrough?: boolean;
304
+ taskLists?: boolean;
305
+ autolinkLiterals?: boolean;
306
+ footnotes?: boolean;
307
+ frontmatter?: boolean;
308
+ /** `> [!NOTE]` blocks, as nodes of type `alert` with a `kind`. */
309
+ alerts?: boolean;
310
+ }
311
+
312
+ /**
313
+ * The syntax tree of Markdown `text` in the shape of mdast, without positions. Install
314
+ * `@types/mdast` for its node types.
315
+ */
316
+ export function parseMarkdown(text: string, options?: MarkdownOptions): import("mdast").Root;
317
+
318
+ /** What happens to an exception a listener throws. Without a handler, the host reports it. */
319
+ export function setErrorHandler(handler: ((error: unknown) => void) | null): void;