mono-jsx-dom 0.1.12 → 0.1.13

package/README.md

@@ -382,84 +382,129 @@ function Counter(this: FC<{ count: number }>, props: { initialCount?: number })
 }
 ```
 
-You can use `this.store` to create a signal store. You can use getters to create derived (computed) signals.
+### Atom signals
+
+Call `this.atom(initialValue)` inside a component to get a reactive atom tied to that instance. It updates the view when you call `set`, and you can read the current value with `get` (for example in `effect` callbacks).
 
 ```tsx
-function App(this: FC<{ count: number }>) {
-  const counter = this.store({
-    value: 0,
-    // double is a derived(computed) signal
-    get double() {
-      return this.value * 2;
-    }
+function Counter(this: FC) {
+  const count = this.atom(0);
+  this.effect(() => {
+    console.log("count changed:", count.get());
   });
-
   return (
     <div>
-      <span>count:{counter.value}</span>
-      <span>double: {counter.double}</span>
-      <button onClick={() => counter.value++}>+</button>
+      <span>{count}</span>
+      <button onClick={() => count.set((prev) => prev + 1)}>Increment</button>
     </div>
-  )
+  );
 }
 ```
 
-### Using `atom` and `store`
+For state shared across the whole app (or a module), import `atom` and define it at the top level. Any component that reads that atom in JSX or effects stays in sync.
 
-mono-jsx-dom provides two functions that allow you to define shared global signals. You can use them to share signals between components.
+```tsx
+import { atom } from "mono-jsx-dom";
 
-- `atom(initValue)`: Creates an atom signal.
-- `store(initValue)`: Creates a signal store.
+const count = atom(0);
+const double = count.ref((value) => value * 2);
+
+function Counter(this: FC) {
+  this.effect(() => {
+    console.log("count changed:", count.get());
+  });
+  return (
+    <div>
+      <p>count: {count}</p>
+      <p>double: {double}</p>
+    </div>
+  );
+}
+
+function App(this: FC) {
+  return (
+    <div>
+      <Counter />
+      <button onClick={() => count.set((prev) => prev + 1)}>Increment</button>
+    </div>
+  );
+}
+```
+
+The type of atom signals is defined as follows:
 
 ```ts
 export interface Atom<T> {
+  /** Read the current value. */
   get(): T;
-  set(value: T | ((prev: T) => T)): void;
-  map(callback: (value: T extends (infer V)[] ? V : T, index: number) => JSX.ChildPrimitiveType): JSX.ChildPrimitiveType[];
+  /** Assign a new value or compute one from the previous value. */
+  set(value: T): void;
+  set(fn: (value: T) => T): void;
+  /** When `T` is an array, map each item to a child for list rendering. */
+  map(
+    callback: (value: T extends (infer V)[] ? V : T, index: number) => ChildPrimitiveType,
+  ): ChildPrimitiveType[];
+  /** Create signal ref to the atom. */
   ref(): T;
+  /** Derived reactive value from the atom. */
   ref<V>(callback: (value: T) => V): V;
+  /** Run `callback` when the atom changes; pass `signal` to tie lifetime to an `AbortSignal`. */
+  watch(callback: () => void, signal?: AbortSignal): void;
 }
-
-export const atom: <T>(initValue: T) => Atom<T>;
-export const store: <T extends Record<string, unknown>>(initValue: T) => T;
 ```
 
-Example:
+### Signal stores
 
-```tsx
-import { atom, store } from "mono-jsx-dom";
-
-const count = atom(0);
-const store = store({ text: 'Count:' });
+The `this.store({ ... })` method in a component builds a reactive object: plain fields are signals, and getters become derived signals.
 
-function Counter(this: FC) {
-  this.effect(() => {
-    console.log("count changed:", count.get());
+```tsx
+function App(this: FC) {
+  const counter = this.store({
+    value: 0,
+    get double() {
+      return this.value * 2;
+    },
   });
+
   return (
-   <span>{store.text}{count}</span>
-  )
+    <div>
+      <span>count: {counter.value}</span>
+      <span>double: {counter.double}</span>
+      <button onClick={() => counter.value++}>+</button>
+    </div>
+  );
 }
+```
+
+You can also use the `store` function to create a global signal store. Like `atom` function, the global signals store is shared between all components.
 
-function Buttons(this: FC) {
+```tsx
+import { store } from "mono-jsx-dom";
+
+const counter = store({
+  value: 0,
+  get double() {
+    return this.value * 2;
+  },
+});
+
+function Counter(this: FC) {
   return (
-    <>
-      <button onClick={() => count.set(prev => prev+1)}>+</button>
-      <button onClick={() => store.text = store.text === 'Count:' ? 'Count:' : '计数:'}>English/中文</button>
-    </>
-  )
+    <div>
+      <span>{counter.value}</span>
+      <span>{counter.double}</span>
+    </div>
+  );
 }
 
 function App(this: FC) {
   return (
-    <>
+    <div>
       <Counter />
-      <Buttons />
-    </>
-  )
+      <button onClick={() => counter.value++}>Increment</button>
+    </div>
+  );
 }
-
-document.body.mount(<App />);
 ```
 
 ### Using Computed Signals

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mono-jsx-dom",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "description": "A JSX runtime for browsers.",
   "keywords": [
     "jsx",

package/types/jsx-runtime.d.ts

@@ -4,7 +4,7 @@ export const html: JSX.Raw;
 export const JSX: typeof globalThis.JSX;
 export const Fragment: (props: {}) => VNode;
 export const jsx: (tag: string | ComponentType, props: Record<string, unknown>, key?: string | number) => VNode;
-export const render: (scope: null, node: VNode, container: HTMLElement, aboutSignal?: AbortSignal) => void;
+export const render: (scope: null, node: VNode, container: HTMLElement | DocumentFragment | ShadowRoot, aboutSignal?: AbortSignal) => void;
 
 // aliases
 export { html as css, html as js, jsx as jsxDEV, jsx as jsxs };

package/types/jsx.d.ts

@@ -97,11 +97,21 @@ export interface MonoBuiltinElements {
 }
 
 export interface Atom<T> {
+  /** Read the current value. */
   get(): T;
-  set(value: T | ((prev: T) => T)): void;
-  map(callback: (value: T extends (infer V)[] ? V : T, index: number) => ChildPrimitiveType): ChildPrimitiveType[];
+  /** Assign a new value or compute one from the previous value. */
+  set(value: T): void;
+  set(fn: (value: T) => T): void;
+  /** When `T` is an array, map each item to a child for list rendering. */
+  map(
+    callback: (value: T extends (infer V)[] ? V : T, index: number) => ChildPrimitiveType,
+  ): ChildPrimitiveType[];
+  /** Create signal ref to the atom. */
   ref(): T;
+  /** Derived reactive value from the atom. */
   ref<V>(callback: (value: T) => V): V;
+  /** Run `callback` when the atom changes; pass `signal` to tie lifetime to an `AbortSignal`. */
+  watch(callback: () => void, signal?: AbortSignal): void;
 }
 
 declare global {