Add handler closure transformation infrastructure

Author: mathpirate

packages/ts-transformers/docs/handler-closures-design.md

@@ -0,0 +1,124 @@
+# Handler Closures Transformation Spec
+
+## Background
+
+- The `dx1/unify-types` branch introduces a unified cell/stream type system
+  built on the new `CELL_BRAND` symbol and capability interfaces (`IReadable`,
+  `IWritable`, `IKeyable`, etc.).
+- API exports and `commontools.d.ts` now define `HandlerFunction` in terms of
+  `HandlerState<T>` and `StripCell<T>`, and the runner augments these interfaces
+  with runtime-specific behaviour.
+- Schema generator and opaque-ref transformers detect cell kinds via
+  `CELL_BRAND`, keeping the hierarchical capture utilities valid across
+  transformers.
+
+## Impact on Handler Closures
+
+- Generated handler callbacks must follow the public signature `(event, props)`
+  so that `HandlerState<T>` inference works and schema injection can attach
+  `toSchema` calls automatically.
+- Captured values should appear under the `params` object we pass to
+  `handler(...)`; we can reuse the hierarchical capture tree helpers we built
+  for map closures to keep names/structure intact.
+- Inline closures should only be rewritten when they are literal functions
+  supplied to `on*` JSX attributes and are not already wrapped in
+  `handler(...)`.
+
+## Behaviour Overview
+
+- Detect eligible JSX attributes using the existing `isEventHandlerJsxAttribute`
+  helper (prop name starts with `on`).
+- For inline arrow functions transform
+  ```tsx
+  <button onClick={() => counter.set(counter.get() + 1)} type="button" />;
+  ```
+  into
+  ```tsx
+  <button
+    onClick={handler((event, { counter }) => counter.set(counter.get() + 1))({
+      counter,
+    })}
+    type="button"
+  />;
+  ```
+  preserving user-supplied parameter patterns whenever present.
+- The params object mirrors the capture tree: nested state (`state.user.name`)
+  becomes `{ state: { user: { name: state.user.name } } }` and optional
+  chaining/computed keys are left untouched.
+- Inline handlers are rewritten even when no captures exist. This keeps JSX
+  syntax uniform and avoids downstream behaviour changes when captures are
+  introduced later.
+- Schema injection already recognises `handler(...)` calls and inserts
+  `toSchema` arguments, so no additional transformer work is required there.
+
+## Implementation Summary
+
+1. Extend `ClosureTransformer` with a visitor that:
+   - Finds JSX attributes whose name starts with `on`.
+   - Confirms the initializer is an inline arrow function literal (excluding
+     existing `handler(...)` invocations or other non-inline references).
+   - Reuses `collectCaptures` / `groupCapturesByRoot` to build the capture tree
+     for the handler body.
+2. Build the rewritten callback:
+   - Preserve explicit event/state parameters if the user provided them;
+     otherwise synthesise `(eventParam, paramsParam)` placeholders.
+   - Alias runtime names to originals via destructuring (e.g.
+     `({ params: { counter } })`).
+   - Leave the function body untouched except for computed-key caching
+     (identical to map closures).
+3. Emit the `handler(...)` call and params object; rely on schema injection to
+   add `toSchema` arguments.
+4. Capture regression coverage for: a basic increment handler; optional
+   chaining/captured state; computed property access (`list[nextKey()]`); and an
+   outer-variable collision (`const counter = …; onClick={() => counter}`).
+5. Run `deno lint` and `deno task test` to cover the closure, derive, and
+   handler suites.
+
+## Decisions and Constraints
+
+- We focus on inline arrow functions for now; other inline forms can be handled
+  later if necessary.
+- If the attribute already references a value returned from `handler(...)` (an
+  `OpaqueRef`/cell) or any non-inline identifier, we leave it as-is.
+- Captured cells/streams/opaque refs require no special casing—the capture tree
+  handles them generically.
+
+## Examples
+
+### Basic Capture
+
+```tsx
+// Before
+<button onClick={() => state.counter.set(state.counter.get() + 1)} type="button" />
+
+// After
+<button
+  type="button"
+  onClick={handler((event, { counter }) => counter.set(counter.get() + 1))({
+    counter,
+  })}
+/>
+```
+
+### Optional Chaining and Computed Key
+
+```tsx
+// Before
+<button
+  type="button"
+  onClick={() => recordMap[nextKey()]?.set(state.metrics.get() ?? 0)}
+/>
+
+// After
+<button
+  type="button"
+  onClick={handler((event, { recordMap, state }) =>
+    recordMap[nextKey()]?.set(state.metrics.get() ?? 0)
+  )({
+    recordMap,
+    state: {
+      metrics: state.metrics,
+    },
+  })}
+/>
+```