sprae 2.14.1 → 3.0.0

package/package.json

@@ -1,14 +1,11 @@
 {
   "name": "sprae",
   "description": "DOM microhydration.",
-  "version": "2.14.1",
+  "version": "3.0.0",
   "main": "src/index.js",
   "module": "src/index.js",
   "type": "module",
   "dependencies": {
-    "@preact/signals-core": "^1.2.3",
-    "primitive-pool": "^2.0.0",
-    "signal-struct": "^1.10.0",
     "swapdom": "^1.1.1"
   },
   "devDependencies": {
@@ -17,6 +14,7 @@
     "esbuild": "^0.15.14",
     "hyperf": "^1.5.0",
     "jsdom": "^21.1.0",
+    "signal-struct": "^1.10.0",
     "terser": "^5.15.1",
     "tst": "^7.1.1",
     "usignal": "^0.8.9",
@@ -25,7 +23,7 @@
   },
   "scripts": {
     "test": "node -r ./test/register.cjs test/test.js",
-    "build": "esbuild --bundle ./src/index.js --outfile=sprae.js --format=esm",
+    "build": "esbuild --bundle ./src/index.js --outfile=sprae.js --format=esm && npm run min",
     "watch": "esbuild --bundle ./src/index.js --outfile=sprae.js --format=esm --sourcemap --watch",
     "min": "terser sprae.js -o sprae.min.js --module -c passes=3 -m"
   },

package/r&d.md

@@ -320,7 +320,7 @@
   + it has better control over serialization
   + `:onchange:oninput="e=>xyz"` is very good
 
-## [ ] Sandbox? -> too complex for now. Waiting for use-cases
+## [x] Sandbox? -> we need it anyways via Proxy, so yes
 
 1. Use subscript?
   + solves access to any internal signals on syntactic level
@@ -359,12 +359,13 @@
     ? maybe define setters such that when they're set
 
 2. Use sandboxed proxy
-  - tough evaluation
-  - implementation hiccups
-  - screwed up data
-  - no full protection
+  - tougher evaluation
+  - no full protection (Function.constructor)
   - relatively slow
   + does minimal catch
+  + allows scope control
+  + allows dynamic subscription to requested fields ( no need for preact/signals neither for signal-struct )
+  + we anyways need sandbox even in case of subscript
 
 ## [x] :onclick="direct code" ? -> no: immediately invoked.
 
@@ -447,30 +448,32 @@
       * onkey.after, onkey.microtask, onkey.defer, onkey.immediate
       * onkey.tick-1?
 
-## [x] Mods design -> use event modifiers, not props modifiers
-
-  * [ ] Prop modifiers
-    - overall seems code complication without much benefit
-    * [ ] value.bind? value.watch?
-      - let's wait for use-case: value can be too big to set it every time
-    * [ ] prop.reflect, prop.observe
-      - let's wait for use-case
-    * [ ] prop.boolean, .number, .string, .array, .object
-      - let's wait for use-case
-    * [ ] prop.once, prop.fx ? prop.init?
-      - doesn't seem required, let's wait for use case
-    * [ ] prop.change - run only if value changes
-      - seems like unnecessary manual optimization that must be done always automatically
-      ? are there cases where force-update is necessary?
-    * [ ] prop.throttle-xxx, prop.debounce-xxx
-      - let's wait until that's really a problem
-    * [ ] prop.class
-      ? what's the use-case
-    * [ ] prop.next="" - run update after other DOM updates happen
-    * [ ] prop.fx="" - run effect without changing property
-    * [ ] x.prop="xyz" - set element property, rather than attribute (following topic)
-    * [ ] x.raf="abc" - run regularly?
-    * [ ] x.watch-xyz - update by change of any of the deps
+### [ ] onkey.unfocusable
+
+## [ ] Prop modifiers
+
+  - overall seems code complication without much benefit
+  * [ ] value.bind? value.watch?
+    - let's wait for use-case: value can be too big to set it every time
+  * [ ] prop.reflect, prop.observe
+    - let's wait for use-case
+  * [ ] prop.boolean, .number, .string, .array, .object
+    - let's wait for use-case
+  * [ ] prop.once, prop.fx ? prop.init?
+    - doesn't seem required, let's wait for use case
+  * [ ] prop.change - run only if value changes
+    - seems like unnecessary manual optimization that must be done always automatically
+    ? are there cases where force-update is necessary?
+  * [ ] prop.throttle-xxx, prop.debounce-xxx
+    - let's wait until that's really a problem
+  * [ ] prop.class
+    ? what's the use-case
+  * [ ] prop.next="" - run update after other DOM updates happen
+  * [ ] prop.fx="" - run effect without changing property
+  * [ ] x.prop="xyz" - set element property, rather than attribute (following topic)
+  * [ ] x.raf="abc" - run regularly?
+  * [ ] x.watch-a-b-c - update by change of any of the deps
+  * [ ] :x.always - update by _any_ dep change
 
 ## [x] Writing props on elements (like ones in :each) -> nah, just use `:x="this.x=abc"`
 
@@ -522,4 +525,4 @@
   ? does it replace element or puts a content?
 
   1. :use="ref-id"
-  2. :
+  2. :

package/readme.md

@@ -22,6 +22,7 @@ Sprae defines attributes starting with `:` as directives:
 
 * `sprae` initializes subtree with data and immediately evaporates `:` attrs.
 * `state` is object reflecting current values, changing any of its props rerenders subtree.
+* To batch-update multiple properties `sprae` can be run repeatedly as: `sprae(container, newValues)`
 
 <!--
 <details>
@@ -139,7 +140,7 @@ Set any attribute value or run effect.
 <!-- Bulk properties -->
 <input :="{ id: name, name, type:'text', value }" />
 
-<!-- Effect (triggers any time foo or bar changes) -->
+<!-- Effects (trigger any time foo or bar changes) -->
 <div :="if (foo) bar()" :fx="void bar()" ></div>
 ```
 
@@ -251,96 +252,13 @@ Expose element to data scope with the `id`:
 </script>
 ```
 
+## Sandbox
 
-<!--
-
-### Reactivity
-
-_sprae_ is built on top of [_@preact/signals_](https://ghub.io/@preact/signals). That gives:
-
-* Expressions don't require explicit access to `.value` (see [signal-struct](https://github.com/dy/signal-struct))
-* Expressions support any reactive values in data (see [sube](https://github.com/dy/sube))
-* Updates happen minimally only when used values update
-* Subscription is weak and get disposed when element is disposed.
-
-Directive expressions are natively reactive, ie. data may contain any async/reactive values, such as:
-
-* _Promise_ / _Thenable_
-* _Observable_ / _Subject_ / _Subscribable_
-* _AsyncIterable_
-* _observ-*_
-* etc., see [sube](https://github.com/dy/sube/blob/main/README.md) for the full list.
-
-This way, for example, _@preact/signals_ or _rxjs_ can be connected directly bypassing subscription or reading value.
--->
-
-## Hints
-
-**1.** To batch-update state (avoid multiple DOM changes), rerun sprae with new state:
-
-```html
-<li :each="item, id in items" :key="id" :text="item"></li>
-
-<script type="module">
-  sprae(el, {items: ['foo', 'bar', 'baz']})
-  // <li>foo</li><li>bar</li><li>baz</li>
-
-  sprae(el, {items: ['foo', 'qux']})
-  // <li>foo</li><li>qux</li>
-</script>
-```
-
-**2.** Data supports signal values, which can be an alternative way to control template state:
-
-```html
-<div id="done" :text="loading ? 'loading' : result">...</div>
-
-<script type="module">
-  import sprae from 'sprae';
-  import { signal } from '@preact/signals';
+Expressions are sandboxed, ie. have no access to global or window.
 
-  // <div id="done">...</div>
+Default sandbox provides: _Array_, _Object_, _Number_, _String_, _Boolean_, _Date_, _console_.
 
-  const loading = signal(true), result = signal(false);
-  sprae(done, { loading, result })
-  setTimeout(() => (loading.value = true, result.value = 'done'), 1000)
-
-  // <div id="done">loading</div>
-
-  // ... 1s after
-  // <div id="done">done</div>
-</script>
-```
-
-**3.** Data recognizes reactive values as inputs as well: _Promise_ / _Thenable_, _Observable_ / _Subscribable_, _AsyncIterable_ (etc., see [sube](https://github.com/dy/sube/blob/main/README.md)). This way, for example, _rxjs_ can be connected to template directly.
-
-```html
-<div :text="clicks">#</div> clicks
-
-<script type="module">
-  import sprae from 'sprae';
-  import { fromEvent, scan } from 'rxjs';
-  sprae(document, {
-    clicks: fromEvent(document, 'click').pipe(scan((count) => count + 1, 0))
-  });
-</script>
-```
-
-**4.** Getters turn into computed values automatically (setters remain as is):
-
-```html
-<div id="x-plus-y">
-  <span :text="x">x</span> + <span :text="y">y</span> = <span :text="z">z</span>
-</div>
-
-<script type="module">
-  import sprae from 'sprae';
-  let state = sprae(document, { x:1, y:1, get z() { return this.x + this.y } })
-
-  state.x = 2, state.y = 2
-  state.z // 4
-</script>
-```
+Sandbox can be extended via `Object.assign(sprae.sandbox, { BigInt, window, document })` etc.
 
 ## Examples