@verajs/lite 0.0.0-stage → 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/LICENSE +21 -0
- package/README.md +104 -2
- package/dist/development/vera-lite.d.ts +128 -0
- package/dist/development/vera-lite.d.ts.map +1 -0
- package/dist/development/vera-lite.js +1754 -0
- package/dist/development/vera-lite.js.map +1 -0
- package/dist/vera-lite.min.js +4 -0
- package/dist/vera-lite.min.js.map +1 -0
- package/package.json +111 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Brian Grider
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,105 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @verajs/lite
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
VeraJS's small tier: `define`, `signal` and the `html`, `svg` and `mathml` tags, with a renderer built in and nothing to
|
|
4
|
+
wire.
|
|
5
|
+
|
|
6
|
+
| Package | gzipped | A render | For |
|
|
7
|
+
| --- | ---: | --- | --- |
|
|
8
|
+
| `@verajs/lite` | <!--size:lite.gzip-->4.19 KB<!--/size:lite.gzip--> | patches the values that changed, in place | small sites |
|
|
9
|
+
| `@verajs/core` + `@verajs/renderer` | <!--size:core.gzip-->8.11 KB<!--/size:core.gzip--> + <!--size:renderer.gzip-->6.25 KB<!--/size:renderer.gzip--> | patches in place, keyed lists, hydration | everything else |
|
|
10
|
+
|
|
11
|
+
<!-- recipe -->
|
|
12
|
+
```js
|
|
13
|
+
import { define, html, signal } from '@verajs/lite';
|
|
14
|
+
|
|
15
|
+
const cart = signal([]); // module-level: every component that reads it re-renders when it is replaced
|
|
16
|
+
|
|
17
|
+
define({ tag: 'add-to-cart', props: { item: 'tea' } }, (host) => () =>
|
|
18
|
+
html`<button @click=${() => (cart.value = [...cart.value, host.item])}>Add ${host.item}</button>`);
|
|
19
|
+
|
|
20
|
+
define('cart-badge', () => () => html`<b>${cart.value.length} in the cart</b>`);
|
|
21
|
+
|
|
22
|
+
document.body.append(document.createElement('add-to-cart'), document.createElement('cart-badge'));
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
<!-- recipe -->
|
|
26
|
+
```js
|
|
27
|
+
import { define, html } from '@verajs/lite';
|
|
28
|
+
|
|
29
|
+
define({ tag: 'price-tag', attributes: ['amount', 'currency'] }, (host) => () =>
|
|
30
|
+
html`<span class="price">${host.amount ?? '—'} ${host.currency ?? ''}</span>`);
|
|
31
|
+
|
|
32
|
+
const price = document.createElement('price-tag');
|
|
33
|
+
price.setAttribute('amount', '12.50');
|
|
34
|
+
price.setAttribute('currency', 'EUR');
|
|
35
|
+
document.body.append(price);
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
**It is reactive.** A write to a declared prop or an observed attribute, or to a `signal` a render read, re-renders
|
|
39
|
+
the component once, in a microtask, however many writes came first. A `signal` is the one store: shallow, read and
|
|
40
|
+
written as `.value`, as in `@verajs/core`.
|
|
41
|
+
|
|
42
|
+
**`isServer()`** is `true` while `@verajs/ssr` renders and `false` in a browser, as in `@verajs/core`: guard per-user
|
|
43
|
+
state (storage, cookies, the viewport) with `if (!isServer()) …`, never `typeof localStorage` (a Node 26 server has one).
|
|
44
|
+
|
|
45
|
+
**A render patches in place**, so focus, the caret, typed input and child components survive it. Lite binds text,
|
|
46
|
+
attributes (whole or partial), `?bool`, `.prop`, `!live`, `@event` (or `onClick=${…}`, as in `@verajs/core`), nested
|
|
47
|
+
templates and arrays (unkeyed: items are reused by position). The text of a `<title>`, `<textarea>` or `<style>` takes a value as TEXT, and so does a JSON data
|
|
48
|
+
block (`<script type="application/json">`, any type ending in `json`) — a list there is its items' text, joined, and a
|
|
49
|
+
template is refused (`template-in-text`), as in `@verajs/core` and on the server; any other `<script>` refuses a value. Markup you
|
|
50
|
+
trust goes in through `.innerHTML=${markup}`, as in `@verajs/core`.
|
|
51
|
+
|
|
52
|
+
**SVG and MathML.** Markup inside an `<svg>` or `<math>` element is SVG or MathML already; a fragment rendered INTO one
|
|
53
|
+
from a template of its own is tagged `svg` or `mathml`, so the parser reads it in that namespace (as in `@verajs/core`).
|
|
54
|
+
An HTML element written in such a fragment breaks out of it, where the parser puts it, and is kept. Development names
|
|
55
|
+
an element placed where its namespace does not render, such as an `html`-tagged `<circle>` inside an `<svg>`
|
|
56
|
+
(`wrong-namespace`, `@verajs/core`'s words).
|
|
57
|
+
|
|
58
|
+
<!-- recipe -->
|
|
59
|
+
```js
|
|
60
|
+
import { define, html, svg } from '@verajs/lite';
|
|
61
|
+
|
|
62
|
+
const dot = (x, color) => svg`<circle cx=${x} cy="5" r="4" fill=${color}/>`;
|
|
63
|
+
|
|
64
|
+
define({ tag: 'dot-row', props: { colors: ['tomato', 'teal', 'gold'] } }, (host) => () =>
|
|
65
|
+
html`<svg viewBox="0 0 30 10" width="90">${host.colors.map((color, i) => dot(5 + i * 10, color))}</svg>`);
|
|
66
|
+
|
|
67
|
+
document.body.append(document.createElement('dot-row'));
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
**The HTML parser judges every template, once.** A hole the parser would move or drop (a `<div>` inside `<select>`, a
|
|
71
|
+
duplicate attribute, a hole inside a comment, `<noscript>`, `<iframe>` or `<template>`) is refused
|
|
72
|
+
(`tier-hole-position`), and so is a template that ends inside a tag (`unfinished-tag`). An `<iframe>` is set through its attributes (`src`, `title`), which work here; a `<noscript>` shows only with scripting off, when this tier never runs, so it belongs in the served page (or `@verajs/ssr`). A binding's name is checked
|
|
73
|
+
against the parser's, which lowercases only ASCII, so a `.prop` or event name with a non-ASCII capital letter is refused
|
|
74
|
+
(`@verajs/core` binds it).
|
|
75
|
+
|
|
76
|
+
**What only `@verajs/core` has:** `createStore`, `computed`, `effect`, `keyed` lists, `spread`, refs, light-DOM slots,
|
|
77
|
+
hydration and an async setup. Importing one from lite fails when the module loads;
|
|
78
|
+
development names an option or a value only `@verajs/core` handles (`tier-needs-core`). An object shaped like a template
|
|
79
|
+
that is not one — data from `JSON.parse`, or a `{ strings, values }` wrapper core's `hold` and `tag` build — renders as the
|
|
80
|
+
text `[object Object]` and is never converted (development says `forged-template` or `template-wrapper`; core renders such
|
|
81
|
+
a wrapper as its template).
|
|
82
|
+
|
|
83
|
+
**Values render as they do in core:** a list or any other iterable (a `Set`, a `Map`) as its items, a property bound to
|
|
84
|
+
`undefined` gets `undefined` (the platform's setter writes it as the text "undefined" in a field, as core does), and
|
|
85
|
+
development says core's warnings in core's words — a boolean child that renders as a word (`boolean-child`), an attribute
|
|
86
|
+
value that is not text (`attribute-value`), a handler that cannot listen (`not-a-listener`), a misspelled event
|
|
87
|
+
(`event-name-typo`). Production carries none of the warnings. One known difference, in the DOM's shape only: a hole that
|
|
88
|
+
is its element's only content and went from a list to text to `null` ends holding only lite's position marker (a comment)
|
|
89
|
+
where a fresh render holds an empty text node — the same text and the same rendering, a different node.
|
|
90
|
+
|
|
91
|
+
**Moving up.** A component written for lite runs on `@verajs/core`: add `@verajs/core` and `@verajs/renderer`, change
|
|
92
|
+
the import, and `wire([renderer])`. The refusals are the same in both: escaped text, no script URLs (in an attribute or
|
|
93
|
+
a property), no bound inline handlers.
|
|
94
|
+
|
|
95
|
+
**Server rendering** (`@verajs/ssr`) renders lite components. Lite does not hydrate: on the client, a component's first
|
|
96
|
+
render replaces what the server sent (hydration is `@verajs/core`'s). The page looks the same throughout (measured on
|
|
97
|
+
Chromium, Firefox and WebKit: the same DOM, no frame painted empty, no layout shift), but **what a visitor did before
|
|
98
|
+
lite's module ran is lost**: typed text and focus, a ticked checkbox, a chosen `<select>` option, an opened `<details>`,
|
|
99
|
+
a scrolled container. Load lite's module early (a module script in the `<head>`, before the content), and serve
|
|
100
|
+
`@verajs/core` for pages whose forms people use before the scripts finish. **On the server, keep HTML out of SVG and
|
|
101
|
+
MathML content** (put it in a `<foreignObject>` or an `<mtext>`): a browser moves an HTML element written inside an
|
|
102
|
+
`<svg>` out of it, which the server's DOM does not reproduce, so a template with a hole in such a subtree is refused
|
|
103
|
+
there (`tier-hole-position`). **Speed:** lite is built to be small; on large
|
|
104
|
+
lists, `@verajs/core` with `@verajs/renderer` updates faster. **JSX** compiles for lite with
|
|
105
|
+
`veraJsx({ html: ['html', '@verajs/lite'], namespaces: false })`; `key` and `{...spread}` need `@verajs/core`.
|
|
@@ -0,0 +1,128 @@
|
|
|
1
|
+
/** Which kind of template a result is, numbered as lit numbers them: 1 html, 2 svg, 3 mathml. */
|
|
2
|
+
type ResultType = 1 | 2 | 3;
|
|
3
|
+
/**
|
|
4
|
+
* The object core's `html`, `svg` and `mathml` tags produce. Structurally compatible with lit-html's
|
|
5
|
+
* `TemplateResult`, so a lit renderer consumes it directly.
|
|
6
|
+
*/
|
|
7
|
+
type TemplateResult<T extends ResultType = 1> = {
|
|
8
|
+
_$litType$: T;
|
|
9
|
+
strings: TemplateStringsArray;
|
|
10
|
+
values: unknown[];
|
|
11
|
+
};
|
|
12
|
+
/** `define`'s `methods`: functions only, installed on the generated prototype (an accessor is a prop's job). */
|
|
13
|
+
type Methods = Record<string, (...args: never[]) => unknown>;
|
|
14
|
+
/** `data-count` → `dataCount`: the prop an observed attribute arrives as. */
|
|
15
|
+
type Camel<S extends string> = S extends `${infer H}-${infer T}` ? `${H}${Capitalize<Camel<T>>}` : S;
|
|
16
|
+
/**
|
|
17
|
+
* The props once the observed attributes join them: each attribute is a `string | null` prop under its camel name, and a
|
|
18
|
+
* declared prop it SHARES widens to its default's type `| string | null` — the platform writes strings, so the type says so.
|
|
19
|
+
*/
|
|
20
|
+
type WithAttributes<P, A extends readonly string[]> = Omit<P, Camel<A[number]>> & {
|
|
21
|
+
[K in A[number] as Camel<K>]: (Camel<K> extends keyof P ? P[Camel<K>] : never) | string | null;
|
|
22
|
+
};
|
|
23
|
+
/** What `signal()` returns: one value, read and written as `.value`. */
|
|
24
|
+
type Signal<T> = {
|
|
25
|
+
value: T;
|
|
26
|
+
};
|
|
27
|
+
|
|
28
|
+
/**
|
|
29
|
+
* **`@verajs/lite`'s types** — its own (the element's fields, `define`'s options and class), and the ones it speaks with
|
|
30
|
+
* `@verajs/core` (shared-types', re-exported, so a component's types read the same in both).
|
|
31
|
+
*/
|
|
32
|
+
|
|
33
|
+
/**
|
|
34
|
+
* **A `@verajs/lite` component**: what its `define` keeps on the element, SIGILED as core's own
|
|
35
|
+
* fields are, reusing core's sigil where the meaning is the same. **Who reads them:** only this package's own modules
|
|
36
|
+
* (`define`, `schedule`, `signal`, `patch`), and its tests (`_$l$`); no other package. **Why sigiled, not `_`-named:**
|
|
37
|
+
* they sit on an AUTHOR's element, and the production mangler renames `/^_(?!p$)[a-z]/` to one- or two-letter names that
|
|
38
|
+
* could collide with the author's own fields; a `_$…$` name never matches, so it survives every build unchanged.
|
|
39
|
+
*/
|
|
40
|
+
interface LiteElement extends HTMLElement {
|
|
41
|
+
/** The declared props' values, built from the defaults at the first touch: `@verajs/core`'s `_$v$`, the same record. */
|
|
42
|
+
_$v$?: Record<string, unknown>;
|
|
43
|
+
/** The root it renders into: its shadow root, or itself (core's `_$r$`). */
|
|
44
|
+
_$r$?: LiteRoot;
|
|
45
|
+
/** Its render function: `undefined` until set up (and again once retired), `null` when the setup returned none. */
|
|
46
|
+
_$f$?: (() => unknown) | null;
|
|
47
|
+
/** A render is queued for the next microtask. */
|
|
48
|
+
_$u$?: boolean;
|
|
49
|
+
/** The readers of every signal it read: it leaves each when it is retired. */
|
|
50
|
+
_$l$?: Set<Set<LiteElement>>;
|
|
51
|
+
}
|
|
52
|
+
/**
|
|
53
|
+
* What the lite renderer keeps on the root it paints (`patch.ts`, its only reader): the root range, made on the first
|
|
54
|
+
* paint. Sigiled for the reason `LiteElement` gives: the root may be the author's own element.
|
|
55
|
+
*/
|
|
56
|
+
type RootRange = {
|
|
57
|
+
/** The root range's part: it commits the render's result into the whole root. */
|
|
58
|
+
_$t$?: (values: readonly unknown[], at: number) => void;
|
|
59
|
+
};
|
|
60
|
+
/** A small-tier component's shadow root, as the lite renderer paints it. */
|
|
61
|
+
interface LiteShadowRoot extends ShadowRoot, RootRange {
|
|
62
|
+
}
|
|
63
|
+
/** A small-tier component rendering into itself (no shadow root), as the lite renderer paints it. */
|
|
64
|
+
interface LiteHostRoot extends HTMLElement, RootRange {
|
|
65
|
+
}
|
|
66
|
+
/** Where a small-tier component renders: its shadow root or the element itself. */
|
|
67
|
+
type LiteRoot = LiteShadowRoot | LiteHostRoot;
|
|
68
|
+
/** `define`'s options: `@verajs/core`'s, less what only core does (`foreignNodes`, `persist`, a `ShadowRootInit`). */
|
|
69
|
+
type DefineOptions = {
|
|
70
|
+
tag: string;
|
|
71
|
+
shadow?: 'open' | 'closed' | false;
|
|
72
|
+
};
|
|
73
|
+
/** The class `define` returns: its instances carry the props, attributes and methods. */
|
|
74
|
+
type DefinedClass<M> = {
|
|
75
|
+
new (): HTMLElement & M;
|
|
76
|
+
prototype: HTMLElement & M;
|
|
77
|
+
};
|
|
78
|
+
|
|
79
|
+
/**
|
|
80
|
+
* **`@verajs/lite`'s `define`**, rendering through its one renderer (`patch.ts`, called by `render` in `schedule.ts`).
|
|
81
|
+
* `@verajs/core`'s call shape — `define(tag, setup)` or `define({ tag, props, attributes, methods, shadow }, setup)` — with the
|
|
82
|
+
* reactivity reduced to a setter: a declared prop is an accessor on the generated prototype over the element's ONE values
|
|
83
|
+
* record (`_$v$`, core's name and meaning), and a write that differs by `Object.is` queues one render. An observed
|
|
84
|
+
* attribute arrives as its camel-cased prop, one way, as in core.
|
|
85
|
+
*
|
|
86
|
+
* - **Setup runs once per life, as core's:** a component removed and re-added in the same task (a move) keeps it; one
|
|
87
|
+
* still out a microtask later is retired, and its next connect sets it up again. Props survive, as core's do.
|
|
88
|
+
* - **A value set before the tag was defined** is an own property hiding the accessor: handed over through it at connect.
|
|
89
|
+
* - **An own `__proto__` key** (`JSON.parse` makes one) is skipped in props and methods, as core skips it.
|
|
90
|
+
* - **A setup that returns a value, not a render function, draws it once** (core's behavior and core's development error);
|
|
91
|
+
* one that returns nothing, or a promise (an async setup, core's alone), draws nothing.
|
|
92
|
+
* - An author's `methods.disconnectedCallback` runs first on removal, as core chains it.
|
|
93
|
+
* - Development checks the definition in core's words (`checkDefinition`) and names every option only core has.
|
|
94
|
+
*/
|
|
95
|
+
declare const define: <M extends Methods = Record<never, never>, P extends object = Record<never, never>, A extends readonly string[] = []>(target: string | (DefineOptions & {
|
|
96
|
+
props?: P;
|
|
97
|
+
attributes?: A;
|
|
98
|
+
methods?: M & ThisType<HTMLElement & WithAttributes<P, A> & M>;
|
|
99
|
+
}), setup: (host: HTMLElement & WithAttributes<P, A> & M) => (() => unknown) | void) => DefinedClass<WithAttributes<P, A> & M>;
|
|
100
|
+
|
|
101
|
+
/**
|
|
102
|
+
* **Whether this code is running on the server** — `true` while `@verajs/ssr` renders, `false` in a browser: the same
|
|
103
|
+
* function as `@verajs/core`'s, so a component that guards per-user state with `if (!isServer()) …` runs unchanged on
|
|
104
|
+
* either tier. Its own copy, because lite imports nothing; both read the flag `@verajs/ssr` sets on the global, when called.
|
|
105
|
+
*/
|
|
106
|
+
declare const isServer: () => boolean;
|
|
107
|
+
|
|
108
|
+
/** The empty call first so a no-argument call matches it, the valued one last so `ReturnType` means the common case (as core). */
|
|
109
|
+
type SignalFactory = {
|
|
110
|
+
<T = undefined>(): Signal<T | undefined>;
|
|
111
|
+
<T>(initialValue: T): Signal<T>;
|
|
112
|
+
};
|
|
113
|
+
/**
|
|
114
|
+
* **A reactive box for one value, read and written as `.value`; shallow, as core's default.** Replacing `.value` re-renders
|
|
115
|
+
* every component that read it; mutating inside it does not. Core's `{ deep: true }` is core's alone.
|
|
116
|
+
*/
|
|
117
|
+
declare const signal: SignalFactory;
|
|
118
|
+
|
|
119
|
+
/** The `html` tagged template. */
|
|
120
|
+
declare const html: (strings: TemplateStringsArray, ...values: unknown[]) => TemplateResult<1>;
|
|
121
|
+
/** The `svg` tagged template — markup parsed as SVG, for a fragment that is not inside an `<svg>` element. */
|
|
122
|
+
declare const svg: (strings: TemplateStringsArray, ...values: unknown[]) => TemplateResult<2>;
|
|
123
|
+
/** The `mathml` tagged template — markup parsed as MathML, for a fragment that is not inside a `<math>` element. */
|
|
124
|
+
declare const mathml: (strings: TemplateStringsArray, ...values: unknown[]) => TemplateResult<3>;
|
|
125
|
+
|
|
126
|
+
export { define, html, isServer, mathml, signal, svg };
|
|
127
|
+
export type { DefineOptions, DefinedClass, LiteElement, LiteRoot, Methods, ResultType, Signal, TemplateResult, WithAttributes };
|
|
128
|
+
//# sourceMappingURL=vera-lite.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"vera-lite.d.ts","sources":["../../src/define.ts","../../src/isServer.ts","../../src/signal.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AACA;AACA;AAGA;AACA;AAGA;AACA;;AAEE;AACF;AAEA;AACA;AACE;AACE;;AAEJ;AAEA;;;AAGG;AACH,0BAA0B,YAAkC,GAAE,cAAE;AAC9D,kBAA+C,WAAW,GAAA,cAAU,0CAAA,YAAA,CAAA,cAAA;;AC3BtE;;;;AAIG;AACH,cAAa,QAAQ;;ACJrB;AACA,KAAA,aAAkB;AAGlB,uBAAA,MAAA;AACA,0BAAsB,MAAA;AACtB;AAGA;;;;;;;;;;;;;;;","names":[]}
|