xote 1.0.1 → 1.0.3

package/README.md

@@ -1,23 +1,36 @@
 # xote (pronounced [ˈʃɔtʃi])
+[![npm version](https://img.shields.io/npm/v/xote.svg)](https://www.npmjs.com/package/xote)
 
-A lightweight, zero-dependency UI library for ReScript with fine-grained reactivity powered by signals. Build reactive web applications with automatic dependency tracking and efficient updates.
+A lightweight, zero-dependency UI library for ReScript with fine-grained reactivity based on the [TC39 Signals proposal](https://github.com/tc39/proposal-signals). Build reactive web applications with automatic dependency tracking and efficient updates.
 
 ## Features
 
-- **Zero dependencies** - No runtime dependencies, pure ReScript implementation
-- **Reactive primitives** - Signals, computed values, and effects
-- **Component system** - Declarative UI components with automatic reactive updates
-- **Automatic dependency tracking** - No manual subscription management
-- **Batching and control** - Support for untracked reads and batched updates
-- **Lightweight** - Small bundle size, minimal overhead
+- Zero dependencies: pure ReScript implementation
+- Lightweight and efficient runtime
+- Declarative components for building reactive UIs (JSX support comming up soon)
+- Reactive primitives: signals, computed values, and effects
+- Automatic dependency tracking: no manual subscription management
+- Fine-grained updates: direct DOM updates without a virtual DOM
 
 ## Getting Started
 
-Comming soon.
-
 ### Installation
 
-Comming soon.
+```bash
+npm install xote
+# or
+yarn add xote
+# or
+pnpm add xote
+```
+
+Then, add it to your ReScript project’s dependencies in `rescript.json`:
+
+```json
+{
+  "bs-dependencies": ["xote"]
+}
+```
 
 ### Quick Example
 
@@ -27,13 +40,13 @@ open Xote
 // Create reactive state
 let count = Signal.make(0)
 
-// Create computed values
+// Derived value
 let doubled = Computed.make(() => Signal.get(count) * 2)
 
-// Define event handlers
+// Event handler
 let increment = (_evt: Dom.event) => Signal.update(count, n => n + 1)
 
-// Build your UI
+// Build the UI
 let app = Component.div(
   ~children=[
     Component.h1(~children=[Component.text("Counter")], ()),
@@ -51,266 +64,26 @@ let app = Component.div(
   ()
 )
 
-// Mount to DOM
+// Mount to the DOM
 Component.mountById(app, "app")
 ```
 
-## API Reference
-
-### Signals - Reactive State
-
-Signals are the foundation of reactive state management in Xote.
-
-```rescript
-// Create a signal with initial value
-let count = Signal.make(0)
-
-// Read signal value (tracks dependencies)
-let value = Signal.get(count) // => 0
-
-// Read without tracking
-let value = Signal.peek(count) // => 0
-
-// Update signal value
-Signal.set(count, 1)
-
-// Update with a function
-Signal.update(count, n => n + 1)
-```
-
-### Computed - Derived State
-
-Computed values automatically update when their dependencies change.
-
-```rescript
-let count = Signal.make(5)
-
-// Computed values are signals that derive from other signals
-let doubled = Computed.make(() => Signal.get(count) * 2)
-
-Signal.get(doubled) // => 10
-
-Signal.set(count, 10)
-Signal.get(doubled) // => 20
-```
-
-### Effects - Side Effects
-
-Effects run automatically when their dependencies change.
-
-```rescript
-let count = Signal.make(0)
-
-// Effect runs immediately and re-runs when count changes
-let disposer = Effect.run(() => {
-  Console.log("Count is now: " ++ Int.toString(Signal.get(count)))
-})
-
-Signal.set(count, 1) // Logs: "Count is now: 1"
-
-// Clean up effect
-disposer.dispose()
-```
-
-### Components - Building UI
-
-#### Basic Elements
-
-```rescript
-// Text nodes
-Component.text("Hello, world!")
-
-// Reactive text from signals
-let name = Signal.make("Alice")
-Component.textSignal(
-  Computed.make(() => "Hello, " ++ Signal.get(name))
-)
-
-// HTML elements
-Component.div(
-  ~attrs=[("class", "container"), ("id", "main")],
-  ~events=[("click", handleClick)],
-  ~children=[
-    Component.h1(~children=[Component.text("Title")], ()),
-    Component.p(~children=[Component.text("Content")], ())
-  ],
-  ()
-)
-```
-
-#### Reactive Lists
-
-Render lists that automatically update when data changes:
-
-```rescript
-let todos = Signal.make([
-  {id: 1, text: "Learn Xote"},
-  {id: 2, text: "Build an app"}
-])
-
-let todoItem = (todo) => {
-  Component.li(~children=[Component.text(todo.text)], ())
-}
-
-Component.ul(
-  ~children=[Component.list(todos, todoItem)],
-  ()
-)
-// List updates automatically when todos signal changes!
-```
-
-#### Event Handling
-
-```rescript
-let handleClick = (evt: Dom.event) => {
-  Console.log("Clicked!")
-}
-
-Component.button(
-  ~events=[("click", handleClick), ("mouseenter", handleHover)],
-  ~children=[Component.text("Click me")],
-  ()
-)
-```
-
-### Utilities
-
-#### Untracked Reads
-
-Read signals without creating dependencies.
-
-```rescript
-Core.untrack(() => {
-  let value = Signal.get(count) // Won't track this read
-  Console.log(value)
-})
-```
-
-#### Batching Updates
-
-Group multiple updates to run effects only once.
-
-```rescript
-Core.batch(() => {
-  Signal.set(count1, 10)
-  Signal.set(count2, 20)
-  Signal.set(count3, 30)
-})
-// Effects run once after all updates
-```
-
-## Complete Example
-
-### Counter Application
-
-```rescript
-open Xote
-
-// State management
-let counterValue = Signal.make(0)
-
-// Derived state
-let counterDisplay = Computed.make(() =>
-  "Count: " ++ Int.toString(Signal.get(counterValue))
-)
-
-let isEven = Computed.make(() =>
-  mod(Signal.get(counterValue), 2) == 0
-)
-
-// Event handlers
-let increment = (_evt: Dom.event) => {
-  Signal.update(counterValue, n => n + 1)
-}
-
-let decrement = (_evt: Dom.event) => {
-  Signal.update(counterValue, n => n - 1)
-}
-
-let reset = (_evt: Dom.event) => {
-  Signal.set(counterValue, 0)
-}
-
-// Side effects
-let _ = Effect.run(() => {
-  Console.log("Counter changed: " ++ Int.toString(Signal.get(counterValue)))
-})
-
-// UI Component
-let app = Component.div(
-  ~attrs=[("class", "app")],
-  ~children=[
-    Component.h1(~children=[Component.text("Xote Counter")], ()),
-
-    Component.div(
-      ~attrs=[("class", "counter-display")],
-      ~children=[
-        Component.h2(~children=[Component.textSignal(counterDisplay)], ()),
-        Component.p(~children=[
-          Component.textSignal(
-            Computed.make(() =>
-              Signal.get(isEven) ? "Even" : "Odd"
-            )
-          )
-        ], ())
-      ],
-      ()
-    ),
-
-    Component.div(
-      ~attrs=[("class", "controls")],
-      ~children=[
-        Component.button(
-          ~events=[("click", decrement)],
-          ~children=[Component.text("-")],
-          ()
-        ),
-        Component.button(
-          ~events=[("click", reset)],
-          ~children=[Component.text("Reset")],
-          ()
-        ),
-        Component.button(
-          ~events=[("click", increment)],
-          ~children=[Component.text("+")],
-          ()
-        )
-      ],
-      ()
-    )
-  ],
-  ()
-)
-
-// Mount to DOM
-Component.mountById(app, "app")
-```
+Classic counter: when you click the button, the counter updates reactively.
 
-## How It Works
+## Philosophy
 
-### Reactive System
+Xote focuses on clarity, control, and performance. It brings reactive programming to ReScript with minimal abstractions and no runtime dependencies. The goal is to offer precise, fine-grained updates and predictable behavior without a virtual DOM.
 
-- **Automatic dependency tracking** - When you read a signal with `Signal.get()` inside a computed or effect, it automatically tracks that dependency
-- **Fine-grained updates** - Only the specific computeds and effects that depend on changed signals are re-executed
-- **Synchronous by default** - Updates happen immediately and synchronously for predictable behavior
-- **Batching support** - Group multiple updates to minimize re-computation
+## Core Concepts
 
-### Component Rendering
+- **Signal**: Reactive state container  
+- **Computed**: Derived reactive value that updates automatically  
+- **Effect**: Function that re-runs when dependencies change  
+- **Component**: Declarative UI builder using ReScript functions  
 
-- **Initial render** - Components are rendered to real DOM elements on mount
-- **Reactive text** - `textSignal()` creates text nodes that automatically update when their signal changes
-- **Reactive lists** - `Component.list()` creates lists that automatically update when data changes
-- **Direct DOM manipulation** - No virtual DOM diffing, updates are precise and efficient
-- **Effect-based** - Signal changes trigger effects that update specific DOM nodes automatically
+For a more complete example, see a full [todo list app example](https://github.com/brnrdog/xote/blob/main/src/demo/TodoApp.res).
 
-## Best Practices
 
-1. **Keep signals at the top level** - Define signals outside component definitions for proper reactivity
-2. **Use computed for derived state** - Don't repeat calculations, use `Computed.make()`
-3. **Use `Component.list()` for reactive arrays** - Let the framework handle list updates automatically
-4. **Batch related updates** - Use `Core.batch()` when updating multiple signals together
-5. **Dispose effects when done** - Call `disposer.dispose()` for effects you no longer need
-6. **Use `peek()` when you don't want tracking** - Read signal values without creating dependencies
 
 ## License
 

package/dist/xote.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});var V=(function(n,e){for(var r in n)e(r)});function j(n,e){if(n===e)return!0;var r=typeof n;if(r==="string"||r==="number"||r==="bigint"||r==="boolean"||r==="undefined"||n===null)return!1;var t=typeof e;if(r==="function"||t==="function")throw{RE_EXN_ID:"Invalid_argument",_1:"equal: functional value",Error:new Error};if(t==="number"||t==="bigint"||t==="undefined"||e===null)return!1;var u=n.TAG,i=e.TAG;if(u===248)return n[1]===e[1];if(u===251)throw{RE_EXN_ID:"Invalid_argument",_1:"equal: abstract value",Error:new Error};if(u!==i)return!1;var o=n.length|0,a=e.length|0;if(o===a)if(Array.isArray(n))for(var f=0;;){var c=f;if(c===o)return!0;if(!j(n[c],e[c]))return!1;f=c+1|0}else{if(n instanceof Date&&e instanceof Date)return!(n>e||n<e);var g={contents:!0},nn=function(b){if(!Object.prototype.hasOwnProperty.call(e,b)){g.contents=!1;return}},en=function(b){if(!Object.prototype.hasOwnProperty.call(n,b)||!j(e[b],n[b])){g.contents=!1;return}};return V(n,nn),g.contents&&V(e,en),g.contents}else return!1}function X(n,e,r){for(var t=new Array(r),u=0,i=e;u<r;)t[u]=n[i],u=u+1|0,i=i+1|0;return t}function L(n,e){for(;;){var r=e,t=n,u=t.length,i=u===0?1:u,o=r.length,a=i-o|0;if(a===0)return t.apply(null,r);if(a>=0)return(function(f,c){return function(g){return L(f,c.concat([g]))}})(t,r);e=X(r,i,-a|0),n=t.apply(null,X(r,0,i))}}function rn(n,e){var r=n.length;if(r===1)return n(e);switch(r){case 1:return n(e);case 2:return function(t){return n(e,t)};case 3:return function(t,u){return n(e,t,u)};case 4:return function(t,u,i){return n(e,t,u,i)};case 5:return function(t,u,i,o){return n(e,t,u,i,o)};case 6:return function(t,u,i,o,a){return n(e,t,u,i,o,a)};case 7:return function(t,u,i,o,a,f){return n(e,t,u,i,o,a,f)};default:return L(n,[e])}}function tn(n){var e=n.length;return e===1?n:function(r){return rn(n,r)}}function un(n){return n===void 0?{BS_PRIVATE_NESTED_SOME_NONE:0}:n!==null&&n.BS_PRIVATE_NESTED_SOME_NONE!==void 0?{BS_PRIVATE_NESTED_SOME_NONE:n.BS_PRIVATE_NESTED_SOME_NONE+1|0}:n}function G(n){if(!(n!==null&&n.BS_PRIVATE_NESTED_SOME_NONE!==void 0))return n;var e=n.BS_PRIVATE_NESTED_SOME_NONE;if(e!==0)return{BS_PRIVATE_NESTED_SOME_NONE:e-1|0}}function S(n){return n!==void 0?n.h:0}function l(n,e,r,t){var u=S(n),i=S(t);return{k:e,v:r,h:u>=i?u+1|0:i+1|0,l:n,r:t}}function an(n,e){return{k:n,v:e,h:1,l:void 0,r:void 0}}function on(n,e){return n.v===e?n:{k:n.k,v:e,h:n.h,l:n.l,r:n.r}}function O(n,e,r,t){var u=n!==void 0?n.h:0,i=t!==void 0?t.h:0;if(u>(i+2|0)){var o=n.l,a=n.r;return S(o)>=S(a)?l(o,n.k,n.v,l(a,e,r,t)):l(l(o,n.k,n.v,a.l),a.k,a.v,l(a.r,e,r,t))}if(i<=(u+2|0))return{k:e,v:r,h:u>=i?u+1|0:i+1|0,l:n,r:t};var f=t.l,c=t.r;return S(c)>=S(f)?l(l(n,e,r,f),t.k,t.v,c):l(l(n,e,r,f.l),f.k,f.v,l(f.r,t.k,t.v,c))}function H(n,e,r){var t=n.l;return t!==void 0?O(H(t,e,r),n.k,n.v,n.r):(e.contents=n.k,r.contents=n.v,n.r)}function fn(n,e){for(;;){var r=n;if(r===void 0)return;var t=r.k;if(e===t)return un(r.v);n=e<t?r.l:r.r}}function E(n,e,r){if(n===void 0)return an(e,r);var t=n.k;if(e===t)return on(n,r);var u=n.v;return e<t?O(E(n.l,e,r),t,u,n.r):O(n.l,t,u,E(n.r,e,r))}function R(n,e){var r=n.k,t=n.l,u=n.r;if(e===r){if(t===void 0)return u;if(u===void 0)return t;var i={contents:u.k},o={contents:u.v},a=H(u,i,o);return O(t,i.contents,o.contents,a)}if(e<r){if(t===void 0)return n;var f=R(t,e);return f===t?n:O(f,r,n.v,u)}if(u===void 0)return n;var c=R(u,e);return O(t,r,n.v,c)}function cn(n,e){if(n!==void 0)return R(n,e)}var m=fn;function z(n){if(n!==void 0)return G(n);throw{RE_EXN_ID:"Not_found",Error:new Error}}function p(n,e,r){var t=n!==void 0?n.h:0,u=r!==void 0?r.h:0;return{v:e,h:(t>=u?t:u)+1|0,l:n,r}}function vn(n){return{v:n,h:1,l:void 0,r:void 0}}function q(n,e){return e!==void 0?n!==void 0?n.h>=e.h:!1:!0}function T(n,e,r){var t=n!==void 0?n.h:0,u=r!==void 0?r.h:0;if(t>(u+2|0)){var i=n.l,o=n.r;return q(i,o)?p(i,n.v,p(o,e,r)):p(p(i,n.v,o.l),o.v,p(o.r,e,r))}if(u<=(t+2|0))return{v:e,h:(t>=u?t:u)+1|0,l:n,r};var a=r.l,f=r.r;return q(f,a)?p(p(n,e,a),r.v,f):p(p(n,e,a.l),a.v,p(a.r,r.v,f))}function W(n,e){var r=n.l;return r!==void 0?T(W(r,e),n.v,n.r):(e.contents=n.v,n.r)}function U(n,e){for(;;){var r=n;if(r===void 0)return;U(r.l,e),e(r.v),n=r.r}}function dn(n,e){U(n,tn(e))}function sn(n,e){for(;;){var r=n;if(r===void 0)return!1;var t=r.v;if(e===t)return!0;n=e<t?r.l:r.r}}function N(n,e){if(n===void 0)return vn(e);var r=n.v;if(e===r)return n;var t=n.l,u=n.r;if(e<r){var i=N(t,e);return i===t?n:T(i,r,u)}var o=N(u,e);return o===u?n:T(t,r,o)}function D(n,e){if(n===void 0)return n;var r=n.v,t=n.l,u=n.r;if(e===r){if(t===void 0)return u;if(u===void 0)return t;var i={contents:u.v},o=W(u,i);return T(t,i.contents,o)}if(e<r){var a=D(t,e);return a===t?n:T(a,r,u)}var f=D(u,e);return f===u?n:T(t,r,f)}var ln=sn,k=dn,_={contents:void 0},d={contents:void 0},pn={contents:void 0},v={contents:void 0},h={contents:void 0},I={contents:!1};function M(n){var e=m(d.contents,n);if(e===void 0){d.contents=E(d.contents,n,void 0);return}}function J(n,e){M(e);var r=z(m(_.contents,n));if(j(v.contents,n)&&ln(r.deps,e)===!1){r.deps=N(r.deps,e);var t=z(m(d.contents,e));d.contents=E(d.contents,e,N(t,n))}}function y(n){k(n.deps,(function(e){var r=m(d.contents,e);if(r!==void 0){d.contents=E(d.contents,e,D(G(r),n.id));return}})),n.deps=void 0}function w(n){if(h.contents=N(h.contents,n),I.contents===!1){var e=h.contents;h.contents=void 0,k(e,(function(r){var t=m(_.contents,r);if(t!==void 0){y(t),v.contents=r,t.run(),v.contents=void 0;return}}))}}function Q(n){M(n);var e=m(d.contents,n);if(e!==void 0)return k(G(e),w)}function _n(n){var e=v.contents;v.contents=void 0;var r=n();return v.contents=e,r}function hn(n){var e=I.contents;I.contents=!0;var r=n();if(I.contents=e,h.contents!==void 0){var t=h.contents;h.contents=void 0,k(t,(function(u){w(u)}))}return r}var En,mn,gn,Sn;const On=Object.freeze(Object.defineProperty({__proto__:null,Id:Sn,IntMap:mn,IntSet:En,Observer:gn,addDep:J,batch:hn,batching:I,clearDeps:y,currentObserverId:v,ensureSignalBucket:M,notify:Q,observers:_,pending:h,schedule:w,signalObservers:d,signalPeeks:pn,untrack:_n},Symbol.toStringTag,{value:"Module"}));var P={contents:0};function F(){return P.contents=P.contents+1|0,P.contents}function B(n){var e=F(),r={id:e,kind:"Effect",run:(function(){n()}),deps:void 0};_.contents=E(_.contents,e,r),y(r),v.contents=e,r.run(),v.contents=void 0;var t=function(){var u=m(_.contents,e);if(u!==void 0){y(u),_.contents=cn(_.contents,e);return}};return{dispose:t}}var Tn,bn,In,$n,Nn,yn;const An=Object.freeze(Object.defineProperty({__proto__:null,Core:yn,Id:In,IntMap:bn,IntSet:Tn,Observer:$n,Signal:Nn,run:B},Symbol.toStringTag,{value:"Module"}));function Y(n){var e=F();return M(e),{id:e,value:{contents:n},version:{contents:0}}}function A(n){var e=v.contents;return e!==void 0&&J(e,n.id),n.value.contents}function Z(n){return n.value.contents}function C(n,e){n.value.contents=e,n.version.contents=n.version.contents+1|0,Q(n.id)}function Cn(n,e){C(n,e(n.value.contents))}var kn,Mn,Pn,jn,Rn;const Dn=Object.freeze(Object.defineProperty({__proto__:null,Core:Rn,Id:jn,IntMap:Mn,IntSet:kn,Observer:Pn,get:A,make:Y,peek:Z,set:C,update:Cn},Symbol.toStringTag,{value:"Module"}));function K(n){var e=Y(),r={contents:!1},t=F(),u=function(){var o=n();return r.contents===!1&&(r.contents=!0),C(e,o)},i={id:t,kind:{NAME:"Computed",VAL:e.id},run:u,deps:void 0};return _.contents=E(_.contents,t,i),y(i),v.contents=t,i.run(),v.contents=void 0,e}var Bn,Gn,wn,Fn,Vn,Xn;const zn=Object.freeze(Object.defineProperty({__proto__:null,Core:Fn,Id:Xn,IntMap:Gn,IntSet:Bn,Observer:Vn,Signal:wn,make:K},Symbol.toStringTag,{value:"Module"}));function qn(n){return{TAG:"Text",_0:n}}function Ln(n){return{TAG:"SignalText",_0:n}}function Hn(n){return{TAG:"Fragment",_0:n}}function Wn(n){return{TAG:"SignalFragment",_0:n}}function Un(n,e){var r=K(function(){return A(n).map(e)});return{TAG:"SignalFragment",_0:r}}function s(n,e,r,t,u){var i=e!==void 0?e:[].map(function(f){return f}),o=r!==void 0?r:[].map(function(f){return f}),a=t!==void 0?t:[].map(function(f){return f});return{TAG:"Element",tag:n,attrs:i,events:o,children:a}}function Jn(n,e,r,t){return s("div",n,e,r)}function Qn(n,e,r,t){return s("span",n,e,r)}function Yn(n,e,r,t){return s("button",n,e,r)}function Zn(n,e,r){return s("input",n,e,void 0)}function Kn(n,e,r,t){return s("h1",n,e,r)}function xn(n,e,r,t){return s("h2",n,e,r)}function ne(n,e,r,t){return s("h3",n,e,r)}function ee(n,e,r,t){return s("p",n,e,r)}function re(n,e,r,t){return s("ul",n,e,r)}function te(n,e,r,t){return s("li",n,e,r)}function $(n){switch(n.TAG){case"Element":var e=document.createElement(n.tag);return n.attrs.forEach(function(a){e.setAttribute(a[0],a[1])}),n.events.forEach(function(a){e.addEventListener(a[0],a[1])}),n.children.forEach(function(a){var f=$(a);e.appendChild(f)}),e;case"Text":return document.createTextNode(n._0);case"SignalText":var r=n._0,t=document.createTextNode(Z(r));return B(function(){var a=A(r);t.textContent=a}),t;case"Fragment":var u=document.createDocumentFragment();return n._0.forEach(function(a){var f=$(a);u.appendChild(f)}),u;case"SignalFragment":var i=n._0,o=document.createElement("div");return o.setAttribute("data-signal-fragment","true"),o.setAttribute("style","display: contents"),B(function(){var a=A(i);o.innerHTML="",a.forEach(function(f){var c=$(f);o.appendChild(c)})}),o}}function x(n,e){var r=$(n);e.appendChild(r)}function ue(n,e){var r=document.getElementById(e);if(r==null){console.error("Container element not found: "+e);return}else return x(n,r)}var ie,ae,oe,fe;const ce=Object.freeze(Object.defineProperty({__proto__:null,Computed:fe,Core:oe,Effect:ae,Signal:ie,button:Yn,div:Jn,element:s,fragment:Hn,h1:Kn,h2:xn,h3:ne,input:Zn,li:te,list:Un,mount:x,mountById:ue,p:ee,render:$,signalFragment:Wn,span:Qn,text:qn,textSignal:Ln,ul:re},Symbol.toStringTag,{value:"Module"}));var ve=ce,de=zn,se=On,le=An,pe=Dn;exports.Component=ve;exports.Computed=de;exports.Core=se;exports.Effect=le;exports.Signal=pe;