@verajs/lite 0.0.0-stage → 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/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,100 @@
1
- # Temporary Holding Version
1
+ # @verajs/lite
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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.17 KB<!--/size:lite.gzip--> | patches the values that changed, in place | small sites |
9
+ | `@verajs/core` + `@verajs/renderer` | <!--size:core.gzip-->8.05 KB<!--/size:core.gzip--> + <!--size:renderer.gzip-->6.26 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
+ **A render patches in place**, so focus, the caret, typed input and child components survive it. Lite binds text,
43
+ attributes (whole or partial), `?bool`, `.prop`, `!live`, `@event` (or `onClick=${…}`, as in `@verajs/core`), nested
44
+ 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
45
+ block (`<script type="application/json">`, any type ending in `json`) — a list there is its items' text, joined, and a
46
+ template is refused (`template-in-text`), as in `@verajs/core` and on the server; any other `<script>` refuses a value. Markup you
47
+ trust goes in through `.innerHTML=${markup}`, as in `@verajs/core`.
48
+
49
+ **SVG and MathML.** Markup inside an `<svg>` or `<math>` element is SVG or MathML already; a fragment rendered INTO one
50
+ from a template of its own is tagged `svg` or `mathml`, so the parser reads it in that namespace (as in `@verajs/core`).
51
+ An HTML element written in such a fragment breaks out of it, where the parser puts it, and is kept. Development names
52
+ an element placed where its namespace does not render, such as an `html`-tagged `<circle>` inside an `<svg>`
53
+ (`wrong-namespace`, `@verajs/core`'s words).
54
+
55
+ <!-- recipe -->
56
+ ```js
57
+ import { define, html, svg } from '@verajs/lite';
58
+
59
+ const dot = (x, color) => svg`<circle cx=${x} cy="5" r="4" fill=${color}/>`;
60
+
61
+ define({ tag: 'dot-row', props: { colors: ['tomato', 'teal', 'gold'] } }, (host) => () =>
62
+ html`<svg viewBox="0 0 30 10" width="90">${host.colors.map((color, i) => dot(5 + i * 10, color))}</svg>`);
63
+
64
+ document.body.append(document.createElement('dot-row'));
65
+ ```
66
+
67
+ **The HTML parser judges every template, once.** A hole the parser would move or drop (a `<div>` inside `<select>`, a
68
+ duplicate attribute, a hole inside a comment, `<noscript>`, `<iframe>` or `<template>`) is refused
69
+ (`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
70
+ against the parser's, which lowercases only ASCII, so a `.prop` or event name with a non-ASCII capital letter is refused
71
+ (`@verajs/core` binds it).
72
+
73
+ **What only `@verajs/core` has:** `createStore`, `computed`, `effect`, `keyed` lists, `spread`, refs, light-DOM slots,
74
+ hydration and an async setup. Importing one from lite fails when the module loads;
75
+ development names an option or a value only `@verajs/core` handles (`tier-needs-core`). An object shaped like a template
76
+ that is not one — data from `JSON.parse`, or a `{ strings, values }` wrapper core's `hold` and `tag` build — renders as the
77
+ text `[object Object]` and is never converted (development says `forged-template` or `template-wrapper`; core renders such
78
+ a wrapper as its template).
79
+
80
+ **Values render as they do in core:** a list or any other iterable (a `Set`, a `Map`) as its items, a property bound to
81
+ `undefined` gets `undefined` (the platform's setter writes it as the text "undefined" in a field, as core does), and
82
+ development says core's warnings in core's words — a boolean child that renders as a word (`boolean-child`), an attribute
83
+ value that is not text (`attribute-value`), a handler that cannot listen (`not-a-listener`), a misspelled event
84
+ (`event-name-typo`). Production carries none of the warnings.
85
+
86
+ **Moving up.** A component written for lite runs on `@verajs/core`: add `@verajs/core` and `@verajs/renderer`, change
87
+ the import, and `wire([renderer])`. The refusals are the same in both: escaped text, no script URLs (in an attribute or
88
+ a property), no bound inline handlers.
89
+
90
+ **Server rendering** (`@verajs/ssr`) renders lite components. Lite does not hydrate: on the client, a component's first
91
+ render replaces what the server sent (hydration is `@verajs/core`'s). The page looks the same throughout (measured on
92
+ Chromium, Firefox and WebKit: the same DOM, no frame painted empty, no layout shift), but **what a visitor did before
93
+ lite's module ran is lost**: typed text and focus, a ticked checkbox, a chosen `<select>` option, an opened `<details>`,
94
+ a scrolled container. Load lite's module early (a module script in the `<head>`, before the content), and serve
95
+ `@verajs/core` for pages whose forms people use before the scripts finish. **On the server, keep HTML out of SVG and
96
+ MathML content** (put it in a `<foreignObject>` or an `<mtext>`): a browser moves an HTML element written inside an
97
+ `<svg>` out of it, which the server's DOM does not reproduce, so a template with a hole in such a subtree is refused
98
+ there (`tier-hole-position`). **Speed:** lite is built to be small; on large
99
+ lists, `@verajs/core` with `@verajs/renderer` updates faster. **JSX** compiles for lite with
100
+ `veraJsx({ html: ['html', '@verajs/lite'], namespaces: false })`; `key` and `{...spread}` need `@verajs/core`.
@@ -0,0 +1,121 @@
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
+ /** The empty call first so a no-argument call matches it, the valued one last so `ReturnType` means the common case (as core). */
102
+ type SignalFactory = {
103
+ <T = undefined>(): Signal<T | undefined>;
104
+ <T>(initialValue: T): Signal<T>;
105
+ };
106
+ /**
107
+ * **A reactive box for one value, read and written as `.value`; shallow, as core's default.** Replacing `.value` re-renders
108
+ * every component that read it; mutating inside it does not. Core's `{ deep: true }` is core's alone.
109
+ */
110
+ declare const signal: SignalFactory;
111
+
112
+ /** The `html` tagged template. */
113
+ declare const html: (strings: TemplateStringsArray, ...values: unknown[]) => TemplateResult<1>;
114
+ /** The `svg` tagged template — markup parsed as SVG, for a fragment that is not inside an `<svg>` element. */
115
+ declare const svg: (strings: TemplateStringsArray, ...values: unknown[]) => TemplateResult<2>;
116
+ /** The `mathml` tagged template — markup parsed as MathML, for a fragment that is not inside a `<math>` element. */
117
+ declare const mathml: (strings: TemplateStringsArray, ...values: unknown[]) => TemplateResult<3>;
118
+
119
+ export { define, html, mathml, signal, svg };
120
+ export type { DefineOptions, DefinedClass, LiteElement, LiteRoot, Methods, ResultType, Signal, TemplateResult, WithAttributes };
121
+ //# sourceMappingURL=vera-lite.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"vera-lite.d.ts","sources":["../../src/define.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;;AC1BtE;AACA,KAAA,aAAkB;AAGlB,uBAAA,MAAA;AACA,0BAAsB,MAAA;AACtB;AAGA;;;;;;;;;;;;;;;","names":[]}