@lankajs/react 0.1.0

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@lankajs/react",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "module: One hook — `useLankaVM` — and the access tracking core already does.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lankajs/lanka.git",
+    "directory": "modules/bindings/react"
+  },
+  "homepage": "https://github.com/lankajs/lanka/tree/main/modules/bindings/react#readme",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "default": "./dist/testing.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md",
+    "skills"
+  ],
+  "dependencies": {
+    "lanka": "^2.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.3.0",
+    "@lankajs/tool-testing": "^2.0.0"
+  },
+  "peerDependencies": {
+    "react": "^19.2.0"
+  },
+  "peerDependenciesMeta": {
+    "@testing-library/react": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "lint": "eslint src _playground --max-warnings=0",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest",
+    "bench": "vitest bench --run",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}

package/skills/lanka-react/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: lanka-react
+description: Read a lanka ViewModel from a React component with useLankaVM, keep the useTodoVM() hook spelling with toLankaReactVM, and stop a selector from repainting for changes it did not pick with useLankaShallow. Use when writing or reviewing a React screen in a lanka application, when a component does not repaint after state changed, when a selector repaints a screen for changes it did not select, when deciding what a server component may read, or when reviewing code that imports `@lankajs/react`.
+license: MIT
+metadata:
+    author: lankajs
+    package: @lankajs/react
+    version: "0.1.0"
+---
+
+# @lankajs/react
+
+One call to read a ViewModel, two spellings, and one wrapper that makes a
+selector mean something. `reference.md` beside this file is the full guide.
+
+> [!NOTE]
+> Only what the framework or a gate refuses is binding. Everything else here is a
+> recommendation you can adapt.
+
+## Pick the call
+
+| The situation                              | Use                                                   |
+| ------------------------------------------ | ----------------------------------------------------- |
+| a component reads a ViewModel              | `useLankaVM(todoVM)`                                  |
+| it needs one derived value                 | `useLankaVM(todoVM, (s) => s.todos.length)`           |
+| the selector builds an **object or array** | `useLankaVM(todoVM, useLankaShallow((s) => ({ … })))` |
+| the codebase already writes `useTodoVM()`  | `toLankaReactVM(todoVM)`, once per file               |
+| outside a component — a handler, a module  | `todoVM.getState()`                                   |
+| a component test                           | `renderWithLanka` from `@lankajs/react/testing`       |
+
+```tsx
+import { useLankaVM } from "@lankajs/react";
+import { todoVM } from "./todoVM";
+
+export const TodoScreen = () => {
+	const { todos, isLoading, load } = useLankaVM(todoVM);
+
+	if (isLoading) return <p>loading</p>;
+
+	return (
+		<ul onClick={() => void load()}>
+			{todos.map((t) => (
+				<li key={t.id}>{t.title}</li>
+			))}
+		</ul>
+	);
+};
+```
+
+It answers **the state itself** — React's own idea of reactivity, which is the
+one thing the shelf does not make uniform.
+
+## The selector that repaints for everything
+
+`useLankaVM(vm, (s) => ({ a: s.a }))` is the commonest thing a React reader
+writes. It is safe — the binding runs a selector once per state object and holds
+the answer — but on its own it wakes the component for **every** change in the
+ViewModel, including the keys the selector exists to ignore: a fresh object is
+new whenever the state is new.
+
+```tsx
+import { useLankaShallow, useLankaVM } from "@lankajs/react";
+
+const { title, status } = useLankaVM(
+	missionVM,
+	useLankaShallow((s) => ({ title: s.title, status: s.status })),
+);
+```
+
+A selector answering a **primitive** never needed it, which is what makes the
+cost quiet: the shape that is free and the shape that repaints on everything
+look the same on the page. Wrap every selector whose answer is an object or an
+array.
+
+Before the binding held the selection, an unwrapped object selector **crashed on
+the first paint** with "Maximum update depth exceeded". If you meet that message,
+you are on a version older than this one.
+
+## The hook spelling, for a codebase that has it
+
+```ts
+import { toLankaReactVM } from "@lankajs/react";
+
+export const useFAQViewModel = toLankaReactVM(faqVM);
+```
+
+```tsx
+const supportLink = useFAQViewModel((state) => state.supportLink);
+useFAQViewModel.getState().trackSupportContacted("faq"); // in a handler
+```
+
+One wrapper per ViewModel file, no call site touched. It works on any ViewModel
+however it was built, wraps ONE store, adds no state, and laziness survives —
+reading `useFAQViewModel.name` constructs nothing.
+
+Which spelling is taste, with one thing to weigh: `useLankaVM(todoVM)` is what
+the other four bindings publish, so a screen written that way moves between
+frameworks unedited.
+
+## What re-renders
+
+Without a selector the value RECORDS which keys you read, and the next change
+repaints only if one of those moved. With a selector, the selector decides and
+tracking is bypassed.
+
+> [!WARNING]
+> **The blind spot.** Tracking sees keys you read DIRECTLY. A key reached only
+> inside a derived getter is invisible to it, so a change to that key repaints
+> nothing and the screen freezes with no error. Set
+> `enableAccessTrackingOptimization: false` on such a ViewModel. Do NOT read the
+> underlying keys in the view "for the side effect": that is dead code, and a
+> refactor or a lint autofix removes it. In development the framework announces
+> the mismatch by ViewModel and key name.
+
+## Server components
+
+`lanka/viewmodel` carries no `"use client"`, so a server component may read
+`todoVM.getState()`. This barrel does carry it, because `useLankaVM` is a hook —
+so a server component reads, and only what RENDERS is a client component.
+
+## Testing
+
+```tsx
+import { renderWithLanka } from "@lankajs/react/testing";
+
+renderWithLanka(<TodoScreen />, {
+	fakes: { gateways: { TodoGateway: { list: () => Promise.resolve([]) } } },
+});
+```
+
+It takes an **element**, not a component — React Testing Library's own shape.
+Every call gets a fresh instance and disposes the previous one.
+
+## Never do these
+
+- **Never pass an object-returning selector without `useLankaShallow`.** The
+  screen then repaints for every change in the ViewModel, selector or no selector.
+- **Never call `useLankaVM` outside a component.** It is a hook; use
+  `todoVM.getState()` in a handler or a module.
+- **Never import this barrel from a server component.** It carries
+  `"use client"`; read the ViewModel's state directly instead.
+- **Never subscribe by hand to "fix" the blind spot.** Turn the optimization off
+  on the ViewModel — that is the switch built for it.
+- **Never look for a `stop()`.** React releases the subscription on unmount; the
+  other bindings publish one because their call can happen outside a scope.
+
+## Symptom → cause
+
+| What you see                                      | What it is                                   |
+| ------------------------------------------------- | -------------------------------------------- |
+| a screen repainting for changes it never selected | an object selector without `useLankaShallow` |
+| the screen never updates, no error                | the tracking blind spot — a derived getter   |
+| "Invalid hook call"                               | `useLankaVM` outside a component             |
+| a build error about `"use client"`                | this barrel imported from a server component |
+| a test sees the previous test's state             | a render that bypassed `renderWithLanka`     |
+
+## More
+
+`reference.md` — the full guide: the tracking rules, the callable spelling in
+detail, and what this package deliberately is not.

package/skills/lanka-react/reference.md

@@ -0,0 +1,262 @@
+<!-- Generated from modules/bindings/react/GUIDE.md by scripts/skills.mjs. Edit the guide. -->
+
+> **`@lankajs/react@0.1.0`** — this document describes that version.
+>
+> Install: `npm install @lankajs/react react zustand` (the peers are not optional; only npm adds a missing one for you).
+>
+> Complete code, compiled and run in CI: [modules/bindings/react/_playground/playground.test.tsx](https://github.com/lankajs/lanka/blob/main/modules/bindings/react/_playground/playground.test.tsx)
+
+# @lankajs/react — user guide
+
+How a React component reads a lanka ViewModel.
+
+## You will learn
+
+- the one call this package publishes, and what it answers
+- how to keep React's familiar `useTodoVM()` spelling, if you had it
+- why a selector that returns an object needs `useLankaShallow`, and what happens without it
+- when a component re-renders and when it deliberately does not
+- what to do about a ViewModel that derives what the screen shows
+- how to test a React component with a live framework behind it
+
+## When to reach for this
+
+Reach for it the moment a React component has to read a lanka ViewModel — that
+is the whole job, and there is no other supported way to do it. Install this one
+package and no other binding: one application installs one, and `@lankajs/react`
+serves React Native too.
+
+You do NOT need it to reach the rest of the framework. Gateways, scenarios and
+the locator are plain calls with no view in them, and `viewModel.getState()`
+works anywhere, including on a server.
+
+> [!NOTE]
+> Everything below is how this package is _meant_ to be used, not how it must
+> be. The framework bends at the seams it publishes — see
+> [ARCHITECTURE.md](https://github.com/lankajs/lanka/blob/main/ARCHITECTURE.md) for what is checked and what is
+> merely advice.
+
+## Install
+
+```bash
+npm install @lankajs/react react zustand
+```
+
+> [!IMPORTANT]
+> `react` is already in your project; `zustand` is `lanka`'s own peer. npm adds
+> a missing peer for you and pnpm does not, so the line names all of them.
+
+## The one call
+
+`useLankaVM` is a hook. Every member of `modules/bindings/` publishes that same
+name, so moving a screen from one framework to another rewrites the view and not
+the vocabulary.
+
+```tsx
+import { useLankaVM } from "@lankajs/react";
+import { todoVM } from "./todoVM";
+
+export const TodoScreen = () => {
+	const { todos, isLoading, load } = useLankaVM(todoVM);
+
+	if (isLoading) return <p>loading</p>;
+
+	return (
+		<ul onClick={() => void load()}>
+			{todos.map((todo) => (
+				<li key={todo.id}>{todo.title}</li>
+			))}
+		</ul>
+	);
+};
+```
+
+It answers **the state itself** — the one thing this shelf does not make uniform,
+because that is React's own idea of reactivity and a binding that hid it
+would be a second reactivity system fighting the first.
+
+## The React spelling, if you prefer it
+
+Until 2.0 a ViewModel WAS a hook: `createLankaVM` answered a callable, and every
+screen called it. Core cannot do that any more — it may not know what a hook is —
+but this package may, and it does:
+
+```ts
+import { toLankaReactVM } from "@lankajs/react";
+import { createLazyLankaVM } from "lanka/viewmodel";
+
+export const useFAQViewModel = toLankaReactVM(
+	createLazyLankaVM<IFAQState, IFAQActions>({ … }),
+);
+```
+
+```tsx
+const supportLink = useFAQViewModel((state) => state.supportLink);
+const { supportLink, fetchSupportLink } = useFAQViewModel();
+useFAQViewModel.getState().trackSupportContacted("faq"); // in a handler, as always
+```
+
+That is the entire migration for a codebase on 1.x: one wrapper per ViewModel
+file, and not one call site touched.
+
+It works on any ViewModel, however it was built — the factory, the lazy factory,
+`ALankaVM`'s `build()`, a shared-store ViewModel — and it wraps ONE store: the
+call forwards to `useLankaVM` and every member forwards to the ViewModel, so
+notification, access tracking and lazy construction are the ones documented
+below. A ViewModel read through this and the same one read in Vue answer
+identically.
+
+**Laziness survives.** A lazily declared ViewModel still builds on first use:
+reading `useFAQViewModel.name` answers from the config and constructs nothing,
+and `dispose` is still there.
+
+Which spelling to use is taste, with one thing to weigh: `useLankaVM(todoVM)` is
+what the other four bindings publish, so a screen written that way moves between
+frameworks unedited. `toLankaReactVM` is for a React codebase that already has
+hundreds of `useTodoVM()` call sites, and for one that simply prefers them.
+
+## What re-renders, and what does not
+
+Without a selector you get a value that RECORDS which keys you read. The next
+change re-renders only if one of those moved:
+
+```ts
+// reads `todos`; a change to `isLoading` alone repaints nothing
+```
+
+With a selector, the selector decides and tracking is bypassed:
+
+```ts
+const count = useLankaVM(todoVM, (state) => state.todos.length);
+```
+
+> [!WARNING]
+> **The blind spot.** Tracking sees keys you read DIRECTLY. A key reached only
+> inside a derived getter — an action calling `get()` — is invisible to it, so a
+> change to that key re-renders nothing and the screen freezes with no error.
+>
+> Set `enableAccessTrackingOptimization: false` on such a ViewModel. Do NOT patch
+> it in the view by reading the underlying keys "for the side effect": that is
+> dead code, and a refactor or a lint autofix removes it.
+>
+> In development the framework announces the mismatch by ViewModel and key name.
+
+## A selector that returns an object
+
+`useLankaVM(vm, (state) => ({ … }))` is the commonest thing a React reader
+writes, and it is safe: the binding runs a selector once per state object and
+holds the answer, so the two snapshot reads of one commit see the same
+reference.
+
+What it does NOT get on its own is the thing you took a selector for. A fresh
+object is new whenever the state is new, so the component wakes for **every**
+change in the ViewModel — including the keys your selector exists to ignore.
+`useLankaShallow` is the comparison that makes the selection mean something:
+
+```tsx
+import { useLankaShallow, useLankaVM } from "@lankajs/react";
+
+const { title, status } = useLankaVM(
+	missionVM,
+	useLankaShallow((state) => ({ title: state.title, status: state.status })),
+);
+```
+
+It compares the selection one level deep — own keys, same count, `Object.is` on
+each value, arrays included — and hands back the previous object when nothing in
+it moved.
+
+The comparison itself is `createLankaShallowHold` in `lanka/viewmodel`, and every
+binding on the shelf can reach it. React gets a hook over it because React needs
+one: a component re-runs `useLankaShallow` on every render, so the holding has to
+survive a render while the selector stays the current one — which is what makes a
+selection computed from props safe here. Use the hook; the core name is what the
+other four bindings write.
+
+A selector answering a PRIMITIVE never needed it, which is what makes the cost
+quiet: the shape that is free and the shape that repaints on everything look the
+same on the page. So the rule is simple — **wrap every selector whose answer is
+an object or an array**, and leave the rest alone.
+
+> [!NOTE]
+> This used to be worse. Until the binding held the selection, an unwrapped
+> object selector **crashed on the first paint** with "Maximum update depth
+> exceeded" and a stack pointing at React rather than at your selector. If you
+> are reading that message in an older version, this is what it was.
+
+<details><summary><b>Deep dive:</b> why a wrapper and not an equality argument</summary>
+
+`useLankaVM(vm, selector, isEqual)` was the other option, and it puts the
+comparison in the binding for every caller — including the ones whose selection
+is a string and would pay for a comparison they cannot fail. A wrapper is opt in
+at the call site, which is also where a reader can see it. The shape is React's
+own: a hook returning a selector, so a consumer arriving from zustand has typed
+`useShallow` already.
+
+</details>
+## Releasing the subscription
+
+React releases the subscription when the component unmounts, and there is
+nothing for you to call: a hook cannot be used outside a component, so the case
+the other bindings publish a `stop` for cannot arise here.
+
+## Server components
+
+`lanka/viewmodel` carries no `"use client"` — a ViewModel is a store, and a
+server component may read its state with `todoVM.getState()`. This package's
+barrel does carry the directive, because `useLankaVM` is a hook. So the split is
+the useful one: a server component reads, and only what RENDERS is a client
+component.
+
+```tsx
+// app/page.tsx — a server component
+import { todoVM } from "./todoVM";
+
+export default function Page() {
+	return <TodoScreen initial={todoVM.getState().todos} />;
+}
+```
+
+## Testing
+
+`@lankajs/react/testing` renders a component with a bootstrapped framework, so a component
+test needs no bootstrap preamble of its own:
+
+```tsx
+import { renderWithLanka } from "@lankajs/react/testing";
+
+renderWithLanka(<TodoScreen />, {
+	fakes: { gateways: { TodoGateway: { list: () => Promise.resolve([]) } } },
+});
+```
+
+It takes an ELEMENT and not a component, which is React Testing Library's own
+shape — the other four bindings take the component, because theirs do.
+
+Every call gets a FRESH instance and disposes the previous one, so a test never
+inherits its neighbour's subscriptions.
+
+## What this package is not
+
+It is a subscription and a render trigger, and nothing else. The recording of
+which keys you read, the comparison that decides whether a change is worth a
+render, and the blind-spot warning are all in `lanka` itself — which is why the
+behaviour you see is the framework's rather than this package's reading of it,
+and why `lankaViewBindingConformance` can hold every binding to one list.
+
+If this package ever needs more than the ViewModel port gives it, the port has
+the defect and the fix belongs in `lanka`, for every framework at once.
+
+## Recap
+
+- `useLankaVM(todoVM)` is the one call, and every binding publishes that name — a screen written with it moves between frameworks unedited.
+- Without a selector you get a value that records which keys you read, and only those keys re-render you.
+- A key reached only through a derived getter is invisible to tracking: set `enableAccessTrackingOptimization: false` on that ViewModel rather than patching the view.
+- Wrap every selector whose answer is an object or an array in `useLankaShallow`; a primitive selector needs nothing.
+- `toLankaReactVM` hands back the `useTodoVM()` spelling for a 1.x codebase, over the same store and with no behaviour of its own.
+- The barrel is `"use client"` and `lanka/viewmodel` is not, so a server component may read state and only what renders it is a client component.
+
+---
+
+Maintaining this package: [SKILL.md](https://github.com/lankajs/lanka/blob/main/modules/bindings/react/SKILL.md) · What it is:
+[README.md](https://github.com/lankajs/lanka/blob/main/modules/bindings/react/README.md) · Repository map: [../../../README.md](https://github.com/lankajs/lanka/blob/main/README.md)