sprae 11.5.1 → 11.5.3

package/readme.md

@@ -2,8 +2,8 @@
 
 > DOM tree microhydration
 
-_Sprae_ is open & minimalistic progressive enhancement framework with _preact-signals_ based reactivity.<br/>
-Perfect for small-scale websites, static pages, landings, prototypes, lightweight UI or SSR companion (see [JSX](#JSX)).<br/>
+_Sprae_ is open & minimalistic progressive enhancement framework with _preact-signals_ reactivity.<br/>
+Perfect for small websites, static pages, prototypes, lightweight UI or SSR.<br/>
 A light and fast alternative to _alpine_, _petite-vue_, _lucia_ etc (see [why](#justification)).
 
 ## Usage
@@ -27,18 +27,9 @@ A light and fast alternative to _alpine_, _petite-vue_, _lucia_ etc (see [why](#
 
 Sprae evaluates `:`-directives and evaporates them, returning reactive state for updates.
 
-### Autoinit
-
-`sprae.auto` autoinits sprae on document, which is useful for SPA, [SSR](#jsx) etc.
-
-```html
-<!-- Optional attr `prefix` (by default ':'). -->
-<script src="https://unpkg.com/sprae" prefix="s-"></script>
-```
-
 ### UMD
 
-`sprae.umd` enables sprae via CDN, as CJS, AMD etc.
+`sprae.umd` enables sprae via CDN, CJS, AMD etc.
 
 ```html
 <script src="https://unpkg.com/sprae/dist/sprae.umd"></script>
@@ -47,6 +38,15 @@ Sprae evaluates `:`-directives and evaporates them, returning reactive state for
 </script>
 ```
 
+### Autoinit
+
+`sprae.auto` autoinits sprae on document body.
+
+```html
+<!-- Optional attr `prefix` (by default ':'). -->
+<script src="https://unpkg.com/sprae/dist/sprae.auto" prefix="js-"></script>
+```
+
 
 ## Directives
 
@@ -361,11 +361,42 @@ sprae.use({
   // configure compiler
   compile,
 
-  // custom prefix
-  prefix: 's-'
+  // custom prefix, default is `:`
+  prefix: 'js-'
 })
 ```
 
+## JSX
+
+Sprae works with JSX via custom prefix.
+
+Case: Next.js server components fail at dynamic UI – active nav, tabs, sliders etc. Converting to client components screws up data fetching and adds overhead. Sprae can offload UI logic to keep server components intact.
+
+```jsx
+// app/page.jsx - server component
+export default function Page() {
+  return <>
+    <nav id="nav">
+      <a href="/" js-class="location.pathname === '/' && 'active'">Home</a>
+      <a href="/about" js-class="location.pathname === '/about' && 'active'">About</a>
+    </nav>
+    ...
+  </>
+}
+```
+
+```jsx
+// layout.jsx
+import Script from 'next/script'
+
+export default function Layout({ children }) {
+  return <>
+    {children}
+    <Script src="https://unpkg.com/sprae" prefix="js-" />
+  </>
+}
+```
+
 ## Hints
 
 * To prevent [FOUC](https://en.wikipedia.org/wiki/Flash_of_unstyled_content) add `<style>[:each],[:if],[:else] {visibility: hidden}</style>`.
@@ -468,36 +499,6 @@ npm run results
 * [hmpl](https://github.com/hmpl-language/hmpl)
  -->
 
-## JSX
-
-Sprae can work with JSX via custom prefix, eg. `s-`.
-
-Useful as Next.js companion for SSR. Server components fail at dynamic UI – active nav, tabs, sliders etc. Converting to client components screws up data fetching and adds overhead. Sprae can offload UI logic to keep server components intact.
-
-```jsx
-// app/page.jsx - server component
-export default function Page() {
-  return <>
-    <nav id="nav">
-      <a href="/" s-class="location.path === '/' && 'active'">Home</a>
-      <a href="/about" s-class="location.path === '/about' && 'active'">About</a>
-    </nav>
-    ...
-  </>
-}
-```
-
-```jsx
-// layout.jsx
-import Script from 'next/script'
-
-export default function Layout({ children }) {
-  return <>
-    {children}
-    <Script type="module" src="https://unpkg.com/sprae/dist/sprae.auto" prefix="s-" />
-  </>
-}
-```
 
 ## Examples
 

package/signal.js

@@ -41,6 +41,7 @@ export let signal = (v, s, obs = new Set) => (
   ),
   batch = fn => fn(),
   untracked = batch,
+  // untracked = (fn, prev, v) => (prev = current, current = null, v = fn(), current = prev, v),
 
   // signals adapter - allows switching signals implementation and not depend on core
   use = (s) => (

package/sprae.js

@@ -17,4 +17,7 @@ import './directive/data.js'
 // default compiler (indirect new Function to avoid detector)
 sprae.use({ compile: expr => sprae.constructor(`with (arguments[0]) { return ${expr} };`) })
 
+export * from './store.js'
+export * from './signal.js'
+
 export default sprae

package/store.js

@@ -1,7 +1,10 @@
 // signals-based proxy
 import { signal, computed, batch } from './signal.js'
+import { parse } from './core.js';
 
-export const _signals = Symbol('signals'), _change = Symbol('change'),
+export const _signals = Symbol('signals'),
+    _change = Symbol('change'),
+    _stash = '__',
 
   // object store is not lazy
   store = (values, parent) => {
@@ -13,31 +16,33 @@ export const _signals = Symbol('signals'), _change = Symbol('change'),
     // non-objects: for array redirect to list
     if (values.constructor !== Object) return Array.isArray(values) ? list(values) : values
 
-    // NOTE: if you decide to unlazy values, think about large arrays - init upfront can be costly
-    let signals = { ...parent?.[_signals] }, _len = signal(Object.values(values).length),
+    // we must inherit signals to allow dynamic extend of parent state
+    let signals = Object.create(parent?.[_signals] || {}),
+    _len = signal(Object.keys(values).length),
+    stash
 
       // proxy conducts prop access to signals
-      state = new Proxy(signals, {
-        get: (_, key) => key === _change ? _len : key === _signals ? signals : signals[key]?.valueOf(),
-        set: (_, key, v, s) => (s = signals[key], set(signals, key, v), s ?? (++_len.value), 1), // bump length for new signal
-        deleteProperty: (_, key) => (signals[key] && (signals[key][Symbol.dispose]?.(), delete signals[key], _len.value--), 1),
+    let state = new Proxy(signals, {
+        get: (_, k) => k === _change ? _len : k === _signals ? signals : k === _stash ? stash : k in signals ? signals[k]?.valueOf() : globalThis[k],
+        set: (_, k, v, s) => k === _stash ? (stash = v, 1) : (s = k in signals, set(signals, k, v), s || ++_len.value), // bump length for new signal
+        deleteProperty: (_, k) => (signals[k] && (signals[k][Symbol.dispose]?.(), delete signals[k], _len.value--), 1),
         // subscribe to length when object is spread
         ownKeys: () => (_len.value, Reflect.ownKeys(signals)),
+        has: _ => true // sandbox prevents writing to global
       }),
 
       // init signals for values
-      descs = Object.getOwnPropertyDescriptors(values),
-      desc
+      descs = Object.getOwnPropertyDescriptors(values)
 
-    for (let key in values) {
+    for (let k in values) {
       // getter turns into computed
-      if ((desc = descs[key])?.get)
+      if (descs[k]?.get)
         // stash setter
-        (signals[key] = computed(desc.get.bind(state)))._set = desc.set?.bind(state);
+        (signals[k] = computed(descs[k].get.bind(state)))._set = descs[k].set?.bind(state);
 
       else
         // init blank signal - make sure we don't take prototype one
-        signals[key] = null, set(signals, key, values[key]);
+        signals[k] = null, set(signals, k, values[k]);
     }
 
     return state
@@ -56,40 +61,39 @@ export const _signals = Symbol('signals'), _change = Symbol('change'),
 
       // proxy conducts prop access to signals
       state = new Proxy(signals, {
-        get(_, key) {
+        get(_, k) {
           // covers Symbol.isConcatSpreadable etc.
-          if (typeof key === 'symbol') return key === _change ? _len : key === _signals ? signals : signals[key]
+          if (typeof k === 'symbol') return k === _change ? _len : k === _signals ? signals : signals[k]
 
           // if .length is read within .push/etc - peek signal to avoid recursive subscription
-          if (key === 'length') return mut.includes(lastProp) ? _len.peek() : _len.value;
-
-          lastProp = key;
+          if (k === 'length') return mut.includes(lastProp) ? _len.peek() : _len.value;
 
-          if (signals[key]) return signals[key].valueOf()
+          lastProp = k;
 
-          // I hope reading values here won't diverge from signals
-          if (key < signals.length) return (signals[key] = signal(store(values[key]))).value
+          // create signal (lazy)
+          // NOTE: if you decide to unlazy values, think about large arrays - init upfront can be costly
+          return (signals[k] ?? (signals[k] = signal(store(values[k])))).valueOf()
         },
 
-        set(_, key, v) {
+        set(_, k, v) {
           // .length
-          if (key === 'length') {
+          if (k === 'length') {
             // force cleaning up tail
             for (let i = v; i < signals.length; i++) delete state[i]
             // .length = N directly
             _len.value = signals.length = v;
           }
           else {
-            set(signals, key, v)
+            set(signals, k, v)
 
             // force changing length, if eg. a=[]; a[1]=1 - need to come after setting the item
-            if (key >= _len.peek()) _len.value = signals.length = +key + 1
+            if (k >= _len.peek()) _len.value = signals.length = +k + 1
           }
 
           return 1
         },
 
-        deleteProperty: (_, key) => (signals[key]?.[Symbol.dispose]?.(), delete signals[key], 1),
+        deleteProperty: (_, k) => (signals[k]?.[Symbol.dispose]?.(), delete signals[k], 1),
       })
 
     return state
@@ -99,13 +103,13 @@ export const _signals = Symbol('signals'), _change = Symbol('change'),
 const mut = ['push', 'pop', 'shift', 'unshift', 'splice']
 
 // set/update signal value
-const set = (signals, key, v) => {
-  let s = signals[key], cur
+const set = (signals, k, v) => {
+  let s = signals[k], cur
 
   // untracked
-  if (key[0] === '_') signals[key] = v
+  if (k[0] === '_') signals[k] = v
   // new property. preserve signal value as is
-  else if (!s) signals[key] = s = v?.peek ? v : signal(store(v))
+  else if (!s) signals[k] = s = v?.peek ? v : signal(store(v))
   // skip unchanged (although can be handled by last condition - we skip a few checks this way)
   else if (v === (cur = s.peek()));
   // stashed _set for value with getter/setter
@@ -123,4 +127,16 @@ const set = (signals, key, v) => {
   else s.value = store(v)
 }
 
+// create expression setter, reflecting value back to state
+export const setter = (expr, set = parse(`${expr}=${_stash}`)) => (
+  (state, value) => (
+    state[_stash] = value, // save value to stash
+    set(state)
+  )
+)
+
+// make sure state contains first element of path, eg. `a` from `a.b[c]`
+// NOTE: we don't need since we force proxy sandbox
+// export const ensure = (state, expr, name = expr.match(/^\w+(?=\s*(?:\.|\[|$))/)) => name && (state[_signals][name[0]] ??= null)
+
 export default store