sprae 11.1.2 → 11.2.0

package/readme.md

@@ -3,7 +3,7 @@
 > 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, or lightweight UI.<br/>
+Perfect for small-scale websites, static pages, landings, prototypes, lightweight UI or as [nextjs / SSR companion](#JSX).<br/>
 A light and fast alternative to _alpine_, _petite-vue_ etc (see [why](#justification)).
 
 ## Usage
@@ -32,17 +32,18 @@ Sprae evaluates `:`-directives and evaporates them, returning reactive state for
 UMD version enables sprae via CDN, as CJS, AMD etc.
 
 ```html
-<!-- `init` attribute autoinits sprae on document with initial state (optional) -->
+<!-- `init` autoinits sprae on document with initial state (optional) -->
 <script src="https://cdn.jsdelivr.net/npm/sprae/dist/sprae.umd.js" init="{ user: 'buddy' }"></script>
 
 <script>
-  window.sprae(el); // global standalone
+  window.sprae; // global standalone
 </script>
 ```
 
-
 ## Directives
 
+Directives can be either `:` or `s-` prefixed, which is identical.
+
 #### `:if="condition"`, `:else`
 
 Control flow of elements.
@@ -61,8 +62,7 @@ Control flow of elements.
 Multiply element.
 
 ```html
-<!-- :text order matters -->
-<ul><li :each="item in items" :text="item"/></ul>
+<ul><li :each="item in items" :text="item" /></ul>
 
 <!-- cases -->
 <li :each="item, idx in array" />
@@ -84,7 +84,7 @@ Set text content of an element.
 Welcome, <span :text="user.name">Guest</span>.
 
 <!-- fragment -->
-Welcome, <template :text="user.name" />.
+Welcome, <template :text="user.name"><template>.
 ```
 
 #### `:class="value"`
@@ -92,11 +92,13 @@ Welcome, <template :text="user.name" />.
 Set class value.
 
 ```html
-<!-- appends class -->
-<div class="foo" :class="bar"></div>
+<div :class="foo"></div>
+
+<!-- appends to static class -->
+<div class="bar" :class="baz"></div>
 
 <!-- array/object, a-la clsx -->
-<div :class="[foo && 'foo', {bar: bar}]"></div>
+<div :class="['foo', bar && 'bar', { baz }]"></div>
 ```
 
 #### `:style="value"`
@@ -104,13 +106,15 @@ Set class value.
 Set style value.
 
 ```html
-<!-- extends style -->
+<span style="'display: inline-block'"></span>
+
+<!-- extends static style -->
 <div style="foo: bar" :style="'bar-baz: qux'">
 
 <!-- object -->
 <div :style="{barBaz: 'qux'}"></div>
 
-<!-- CSS variable -->
+<!-- set CSS variable -->
 <div :style="{'--bar-baz': qux}"></div>
 ```
 
@@ -194,7 +198,7 @@ Attach event(s) listener with optional modifiers.
 <input :value="text" :oninput:onchange="e => text = e.target.value">
 
 <!-- sequence of events -->
-<button :onfocus..onblur="e => ( handleFocus(), e => handleBlur())">
+<button :onfocus..onblur="e => (handleFocus(), e => handleBlur())">
 
 <!-- modifiers -->
 <button :onclick.throttle-500="handler">Not too often</button>
@@ -309,9 +313,10 @@ sprae.use({compile: justin}) // set up justin as default compiler
 
 ###### Operators:
 
-`++ -- ! - + ** * / %  && || ??`<br/>
+`++ -- ! - + * / % ** && || ??`<br/>
 `= < <= > >= == != === !==`<br/>
-`<< >> & ^ | ~ ?: . ?. [] ()=>{} in`
+`<< >> >>> & ^ | ~ ?: . ?. [] ()=>{} in`<br/>
+`= += -= *= /= %= **= &&= ||= ??= ... ,`
 
 ###### Primitives:
 
@@ -352,7 +357,7 @@ sprae.use({ compile })
 
 * To prevent [FOUC](https://en.wikipedia.org/wiki/Flash_of_unstyled_content) add `<style>[:each],[:if],[:else] {visibility: hidden}</style>`.
 * Attributes order matters, eg. `<li :each="el in els" :text="el.name"></li>` is not the same as `<li :text="el.name" :each="el in els"></li>`.
-* Invalid self-closing tags like `<a :text="item" />` will cause error. Valid self-closing tags are: `li`, `p`, `dt`, `dd`, `option`, `tr`, `td`, `th`.
+* Invalid self-closing tags like `<a :text="item" />` will cause error. Valid self-closing tags are: `li`, `p`, `dt`, `dd`, `option`, `tr`, `td`, `th`, `input`, `img`, `br`.
 * Properties prefixed with `_` are untracked: `let state = sprae(el, {_x:2}); state._x++; // no effect`.
 * To destroy state and detach sprae handlers, call `element[Symbol.dispose]()`.
 * State getters/setters work as computed effects, eg. `sprae(el, { x:1, get x2(){ return this.x * 2} })`.
@@ -360,22 +365,27 @@ sprae.use({ compile })
 * `event` is not used, `:on*` attributes expect a function with event argument `:onevt="event => handle()"`, see [#46](https://github.com/dy/sprae/issues/46).
 * `key` is not used, `:each` uses direct list mapping instead of DOM diffing.
 * `await` is not supported in attributes, it’s a strong indicator you need to put these methods into state.
+* `:ref` comes after `:if` for mount/unmount events `<div :if="cond" :ref="(init(), ()=>dispose())"></div>`.
+* Directives be `s-` prefixed instead of `:` for JSX.
 
 ## Justification
 
-Modern frontend stack is obese and unhealthy, like non-organic processed food. There are leaner alternatives, but:
+Modern frontend stack is obese and unhealthy, like non-organic processed food. There are healthy alternatives, but:
 
 * [Template-parts](https://github.com/dy/template-parts) is stuck with native HTML quirks ([parsing table](https://github.com/github/template-parts/issues/24), [SVG attributes](https://github.com/github/template-parts/issues/25), [liquid syntax](https://shopify.github.io/liquid/tags/template/#raw) conflict etc).
 * [Alpine](https://github.com/alpinejs/alpine) / [petite-vue](https://github.com/vuejs/petite-vue) / [lucia](https://github.com/aidenyabi/lucia) escape native HTML quirks, but have excessive API (`:`, `x-`, `{}`, `@`, `$`), tend to [self-encapsulate](https://github.com/alpinejs/alpine/discussions/3223) and not care about size/performance.
 
 _Sprae_ holds open & minimalistic philosophy:
 
-* Slim `:` API, _signals_ for reactivity.
-* Pluggable directives & configurable internals.
+* Minimal syntax `:`.
+* _Signals_ for reactivity.
+* Pluggable directives, configurable internals.
 * Small, safe & performant.
 * Bits of organic sugar.
 * Aims at making developers happy 🫰
 
+> Perfection is not when there is nothing to add, but when there is nothing to take away.
+
 <!--
 |                       | [AlpineJS](https://github.com/alpinejs/alpine)          | [Petite-Vue](https://github.com/vuejs/petite-vue)        | Sprae            |
 |-----------------------|-------------------|-------------------|------------------|
@@ -445,6 +455,26 @@ npm run results
 * [nuejs](https://github.com/nuejs/nuejs)
  -->
 
+## JSX
+
+Sprae works with JSX, eg. Next.js companion for SSR via `s-` prefixed attributes.
+
+Next.js server components fall short for dynamic UI, like active nav items, collapsible sections, tabs etc. That forces into client components, which screws up data fetching, bloats hydration and adds overhead.`<Script>` is heavy and clunky hack.
+
+Sprae can offload UI logic to keep server components intact.
+
+```jsx
+// app/page.jsx
+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>
+    <script src="https://unpkg.com/sprae" init></script>
+  </>
+}
+```
 
 ## Examples