@ilha/store 0.1.0

package/README.md

@@ -0,0 +1,215 @@
+# `@ilha/store`
+
+A zustand-shaped reactive store for [Ilha](https://github.com/ilhajs/ilha) islands. Backed by [alien-signals](https://github.com/stackblitz/alien-signals) — the same engine that powers `ilha` core state — for shared global state that lives outside any single island.
+
+---
+
+## Installation
+
+```bash
+bun add @ilha/store
+```
+
+---
+
+## Quick Start
+
+```ts
+import { createStore } from "@ilha/store";
+
+const store = createStore({ count: 0 });
+
+store.setState({ count: 1 });
+store.getState(); // → { count: 1 }
+```
+
+---
+
+## When to Use
+
+`ilha` state is **island-local** — signals are scoped to a single component instance. Use `@ilha/store` when you need state that is:
+
+- **Shared across multiple islands** — e.g. a cart, auth session, or theme
+- **Updated from outside an island** — e.g. from a WebSocket handler or a global event bus
+- **Persisted or derived globally** — e.g. synced to `localStorage` via a `subscribe` listener
+
+For state that only one island reads and writes, prefer `ilha`'s built-in `.state()`.
+
+---
+
+## API
+
+### `createStore(initialState, actions?)`
+
+Creates a store. Optionally accepts an actions creator for encapsulating state mutations.
+
+```ts
+// State only
+const store = createStore({ count: 0, name: "Ada" });
+
+// State + actions
+const store = createStore({ count: 0 }, (set, get) => ({
+  increment() {
+    set({ count: get().count + 1 });
+  },
+  reset() {
+    set({ count: 0 });
+  },
+}));
+
+store.getState().increment();
+store.getState().count; // → 1
+```
+
+The actions creator receives:
+
+| Argument                | Description                                          |
+| ----------------------- | ---------------------------------------------------- |
+| `set(patch \| updater)` | Merge a partial patch or apply an updater function   |
+| `get()`                 | Read the current live state (includes other actions) |
+| `getInitialState()`     | Read the frozen initial state snapshot               |
+
+---
+
+### `store.setState(update)`
+
+Merges a partial state update. Accepts a plain object or an updater function.
+
+```ts
+store.setState({ count: 5 });
+store.setState((s) => ({ count: s.count + 1 }));
+```
+
+---
+
+### `store.getState()`
+
+Returns the current state snapshot.
+
+```ts
+store.getState(); // → { count: 5 }
+```
+
+---
+
+### `store.getInitialState()`
+
+Returns the frozen initial state as it was at construction time.
+
+```ts
+store.getInitialState(); // → { count: 0 }
+```
+
+---
+
+### `store.subscribe(listener)`
+
+Subscribes to all state changes. The listener receives the next and previous state. Returns an unsubscribe function.
+
+```ts
+const unsub = store.subscribe((state, prev) => {
+  console.log(state.count, prev.count);
+});
+
+unsub(); // stop listening
+```
+
+### `store.subscribe(selector, listener)` — slice subscription
+
+Subscribes to a derived slice. The listener only fires when the selected value changes (compared with `Object.is`).
+
+```ts
+const unsub = store.subscribe(
+  (s) => s.count,
+  (count, prev) => console.log("count changed:", prev, "→", count),
+);
+```
+
+---
+
+### `store.bind(el, render)`
+
+Reactively renders a store-driven HTML string into a DOM element whenever state changes. The render function may return a plain string or an `html\`\`` tagged template.
+
+```ts
+import { html } from "@ilha/store";
+
+const unsub = store.bind(
+  document.getElementById("counter")!,
+  (state) => html`<p>Count: ${state.count}</p>`,
+);
+
+unsub(); // detach
+```
+
+### `store.bind(el, selector, render)` — slice bind
+
+Only re-renders when the selected slice changes.
+
+```ts
+store.bind(
+  document.getElementById("badge")!,
+  (s) => s.count,
+  (count) => html`<span>${count}</span>`,
+);
+```
+
+---
+
+## Usage with Ilha Islands
+
+The most common pattern is reading the store inside an island's `.effect()` and calling `store.subscribe()` to drive reactive re-renders:
+
+```ts
+import { createStore, html } from "@ilha/store";
+import ilha from "ilha";
+
+export const cartStore = createStore({ items: [] as string[] }, (set, get) => ({
+  add(item: string) {
+    set({ items: [...get().items, item] });
+  },
+  remove(item: string) {
+    set({ items: get().items.filter((i) => i !== item) });
+  },
+}));
+
+export const CartIsland = ilha
+  .state("items", cartStore.getState().items)
+  .effect(({ state }) => {
+    return cartStore.subscribe(
+      (s) => s.items,
+      (items) => state.items(items),
+    );
+  })
+  .render(
+    ({ state }) => html`
+      <ul>
+        ${state.items().map((item) => html`<li>${item}</li>`)}
+      </ul>
+    `,
+  );
+```
+
+---
+
+## TypeScript
+
+Key exported types:
+
+```ts
+import type {
+  StoreApi, // the store instance interface
+  SetState, // (patch | updater) => void
+  GetState, // () => T
+  Listener, // (state, prevState) => void
+  SliceListener, // (slice, prevSlice) => void
+  RenderResult, // string | RawHtml
+  Unsub, // () => void
+} from "@ilha/store";
+```
+
+---
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+import { effectScope } from "alien-signals";
+import { RawHtml } from "ilha";
+
+//#region src/index.d.ts
+interface SetState<T> {
+  (update: Partial<T>): void;
+  (updater: (state: T) => Partial<T>): void;
+}
+type GetState<T> = () => T;
+type Listener<T> = (state: T, prevState: T) => void;
+type SliceListener<_T, S> = (slice: S, prevSlice: S) => void;
+type Unsub = () => void;
+/** Accepted render output — either a plain string or an ilha RawHtml value. */
+type RenderResult = string | RawHtml;
+interface StoreApi<T extends object> {
+  setState(update: Partial<T> | ((state: T) => Partial<T>)): void;
+  getState(): T;
+  getInitialState(): T;
+  subscribe(listener: Listener<T>): Unsub;
+  subscribe<S>(selector: (state: T) => S, listener: SliceListener<T, S>): Unsub;
+  bind(el: Element, render: (state: T) => RenderResult): Unsub;
+  bind<S>(el: Element, selector: (state: T) => S, render: (slice: S) => RenderResult): Unsub;
+}
+type ActionsCreator<TState extends object, TActions extends object> = (set: SetState<TState>, get: GetState<any>, getInitialState: () => TState) => TActions;
+declare function createStore<TState extends object>(initialState: TState): StoreApi<TState>;
+declare function createStore<TState extends object, TActions extends object>(initialState: TState, actions: ActionsCreator<TState, TActions>): StoreApi<TState & TActions>;
+//#endregion
+export { GetState, Listener, RenderResult, SetState, SliceListener, StoreApi, Unsub, createStore, effectScope };

package/dist/index.js

@@ -0,0 +1,77 @@
+import { computed, effect, effectScope, signal } from "alien-signals";
+//#region src/index.ts
+function unwrap(result) {
+	if (typeof result === "string") return result;
+	return result.value;
+}
+function createStore(initialState, actionsCreator) {
+	const stateSignal = signal({});
+	function setState(update) {
+		const current = stateSignal();
+		const patch = typeof update === "function" ? update(current) : update;
+		stateSignal({
+			...current,
+			...patch
+		});
+	}
+	function getState() {
+		return stateSignal();
+	}
+	function subscribe(listenerOrSelector, maybeListener) {
+		if (maybeListener === void 0) {
+			const listener = listenerOrSelector;
+			let prev = stateSignal();
+			let first = true;
+			return effect(() => {
+				const current = stateSignal();
+				if (first) {
+					first = false;
+					return;
+				}
+				listener(current, prev);
+				prev = current;
+			});
+		}
+		const selector = listenerOrSelector;
+		const sliceComputed = computed(() => selector(stateSignal()));
+		let prevSlice = sliceComputed();
+		let first = true;
+		return effect(() => {
+			const currentSlice = sliceComputed();
+			if (first) {
+				first = false;
+				return;
+			}
+			if (!Object.is(currentSlice, prevSlice)) {
+				maybeListener(currentSlice, prevSlice);
+				prevSlice = currentSlice;
+			}
+		});
+	}
+	function bind(el, renderOrSelector, maybeRender) {
+		if (maybeRender === void 0) return effect(() => {
+			el.innerHTML = unwrap(renderOrSelector(stateSignal()));
+		});
+		const sliceComputed = computed(() => renderOrSelector(stateSignal()));
+		return effect(() => {
+			el.innerHTML = unwrap(maybeRender(sliceComputed()));
+		});
+	}
+	let resolvedInitialState;
+	const api = {
+		setState,
+		getState,
+		getInitialState: () => resolvedInitialState,
+		subscribe,
+		bind
+	};
+	const resolvedActions = actionsCreator ? actionsCreator(setState, getState, () => resolvedInitialState) : {};
+	resolvedInitialState = {
+		...initialState,
+		...resolvedActions
+	};
+	stateSignal(resolvedInitialState);
+	return api;
+}
+//#endregion
+export { createStore, effectScope };

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@ilha/store",
+  "version": "0.1.0",
+  "description": "Typed store.",
+  "license": "MIT",
+  "author": "Ryuz <ryuzer@proton.me>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ilhajs/ilha.git"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc && tsdown",
+    "test": "bun test",
+    "cleanup": "rimraf dist node_modules"
+  },
+  "dependencies": {
+    "alien-signals": "3.1.2",
+    "ilha": "0.1.0"
+  },
+  "devDependencies": {
+    "zod": "^4.3.6"
+  }
+}