prisma-php 0.0.2 → 0.0.4

package/dist/docs/pulsepoint.md

@@ -1,434 +1,212 @@
-# PulsePoint: always read the official docs before generating code
+# PulsePoint Runtime Guide
 
-> Purpose: eliminate guessing and make AI-generated PulsePoint code accurate, copy-pasteable, and aligned with the real runtime.
->
-> Scope: this document covers the **core PulsePoint runtime** only — browser-side state, effects, refs, and markup directives. It does **not** assume any specific backend or server framework.
->
-> Official docs: [https://pulsepoint.tsnc.tech/llms](https://pulsepoint.tsnc.tech/llms)
->
-> Version: 3.0.0
+## Purpose
 
----
+This file describes the PulsePoint runtime that is actually implemented in the current TypeScript source of this repo. Use it as the working contract for AI-generated code.
 
-## Read the PulsePoint docs first
+If `src/` is available, read it first. If the app only exposes a plain HTML page plus a minified or bundled runtime loaded by a script tag, inspect those artifacts instead and follow the same behavior. Do not assume React, Vue, Svelte, or older PulsePoint docs.
 
-Before generating, editing, or reviewing any PulsePoint code, read the official PulsePoint docs:
+## What the runtime actually does
 
-```txt
-https://pulsepoint.tsnc.tech/llms
-```
-
-Treat the PulsePoint docs as the source of truth for:
-
-- supported runtime APIs
-- supported directives and markup behavior
-- syntax rules
-- state and effect patterns
-- ref usage
-- limitations and forbidden patterns
-
-Do not rely on assumptions from React, Vue, Alpine, Svelte, Livewire, jQuery, or any other framework.
-
-If the docs do not show a feature or API, do **not** invent it.
-
----
-
-## Prisma PHP integration rule
-
-When PulsePoint is used inside a Prisma PHP application, the default full-stack pattern is:
-
-- PulsePoint for reactive browser state and UI updates
-- `pp.fetchFunction(...)` for frontend-to-PHP server calls
-- `#[Exposed]` on PHP functions or methods that the frontend should be allowed to call
-- `PP\Validator` on the PHP side for authoritative input validation and normalization
-
-Do not invent parallel client/server patterns when the built-in Prisma PHP RPC flow already fits the task. In typical Prisma PHP page work, prefer PulsePoint plus `pp.fetchFunction(...)` over ad hoc API wiring.
-
-Use `route.php` only when you explicitly need a standalone endpoint such as a webhook, public JSON route, external integration endpoint, or other no-view handler.
-
-## Validation boundary
-
-PulsePoint can help with local UX such as:
-
-- showing inline hints
-- disabling submit buttons
-- rendering field-level error messages
-- debouncing live validation requests
-
-But the final validation still belongs on the PHP side.
-
-In Prisma PHP, the default boundary is:
-
-- **PulsePoint** for local UI state and feedback
-- **`pp.fetchFunction(...)`** for sending data to PHP
-- **`PP\Validator`** for authoritative backend validation
-
-Do not present browser-only checks as the final source of truth.
-
----
-
-## What PulsePoint is responsible for
-
-PulsePoint is the **browser-side reactive runtime**.
-
-It is responsible for UI interactivity such as:
-
-- local reactive state
-- reactive effects
-- DOM refs
-- list rendering
-- attribute spreading
-- simple interactive bindings
-
-PulsePoint is **not** the backend.
-
-That means an AI agent must keep these concerns separate:
-
-- **PulsePoint docs** decide how frontend runtime code should be written.
-- **Project/backend docs** decide how data is loaded, validated, saved, authenticated, or routed on the server.
-
----
-
-## Allowed runtime surface
-
-Only use the runtime surface explicitly allowed here unless the official docs say otherwise.
-
-### Core JavaScript API
-
-1. `pp.state<T>(initial)` → `[state, setState]`
-2. `pp.ref<T>(initial: T | null)`
-3. `pp.effect(fn: () => void | (() => void), deps?: Dependency[])`
+PulsePoint is a browser-side component runtime. It renders HTML, binds state and events, and morphs the DOM in place.
 
-### Markup directives
+A component root is any element with `pp-component`.
 
-1. `pp-for` _(only on `<template>`)_
-2. `pp-spread`
-3. `pp-ref`
+## Component roots and scripts
 
-If a symbol is not listed above and is not documented in the official PulsePoint docs, treat it as unsupported.
-
----
-
-## Decision rules for AI agents
-
-When working with PulsePoint, follow these rules:
-
-1. Read the official PulsePoint docs before making runtime decisions.
-2. Do not invent undocumented helpers, directives, lifecycle APIs, or magic globals.
-3. Keep backend assumptions out of PulsePoint-only examples.
-4. Prefer simple, explicit patterns over framework-inspired abstractions.
-5. Generate code that is valid immediately, not pseudo-code.
-6. When uncertain, reduce scope to documented PulsePoint primitives.
-7. If a project also includes framework-specific rules, apply them **after** the PulsePoint docs for backend concerns, but keep PulsePoint runtime syntax aligned with the official PulsePoint docs.
-
----
-
-## Priority order
-
-When generating code that uses PulsePoint, use this order of truth:
-
-1. The user’s explicit request
-2. The official PulsePoint docs: `https://pulsepoint.tsnc.tech/llms`
-3. Project-specific agent rules or local project docs
-4. Existing project code and structure
-5. General framework knowledge
-
-If any assumption conflicts with the official PulsePoint docs, follow the PulsePoint docs.
-
----
-
-## File layout rules
-
-For PulsePoint runtime code, keep a predictable layout:
-
-1. HTML markup first
-2. One `<script>` block at the bottom
+- Each component root may contain one inline `<script type="text/pp">` block for component logic.
+- The script is plain JavaScript, not a module. Do not use `import` or `export` inside it.
+- Top-level bindings from the script are exported automatically to the template. Do not manually `return { ... }`.
+- Top-level `const`, `let`, `function`, and supported destructuring patterns become template bindings.
+- `pp.props` contains the current prop bag for the component.
+- `children` contains the component's initial inner HTML.
+- Nested `pp-component` roots are boundaries and are not flattened by a parent component.
 
 Example:
 
 ```html
-<ul>
-  <template pp-for="user in users">
-    <li key="{user.id}">{user.name}</li>
-  </template>
-</ul>
-
-<script>
-  const [users, setUsers] = pp.state([
-    { id: 1, name: "Alice" },
-    { id: 2, name: "Bob" },
-  ]);
-</script>
-```
-
-Rules:
-
-- Use **exactly one** `<script>` block per page or component unless the project explicitly requires something else.
-- Place the script block **after** the markup.
-- JavaScript should only reference data that already exists when the script runs.
-- Do not scatter PulsePoint runtime logic across multiple disconnected script blocks unless the docs or project structure explicitly requires it.
-
----
-
-## Conditionals and booleans
-
-Prefer visibility toggles instead of complex conditional markup.
-
-### Preferred
-
-```html
-<div hidden="{!isOpen}">Shown when open</div>
-<div hidden="{isOpen}">Shown when closed</div>
-```
-
-### Text or attribute ternaries
-
-```html
-<span class="{isActive ? 'text-green-600' : 'text-red-600'}">
-  {isActive ? 'Active' : 'Inactive'}
-</span>
-```
-
-### Boolean attributes
-
-```html
-<input type="checkbox" checked="{isActive}" />
+<div pp-component="counter-card">
+  <h2>{title}</h2>
+  <p>Count: {count}</p>
+  <button onclick="setCount(count + 1)">Increment</button>
+
+  <script type="text/pp">
+    const { title } = pp.props;
+    const [count, setCount] = pp.state(0);
+    const doubled = count * 2;
+
+    function reset() {
+      setCount(0);
+    }
+  </script>
+</div>
 ```
 
-String branches in ternaries must be quoted correctly.
+## Hooks exposed through `pp`
 
-- Correct: `{isActive ? 'text-blue-500' : 'text-gray-500'}`
-- Invalid: `{isActive ? text-blue-500' : 'text-gray-500'}`
+- `pp.state(initial)` returns `[value, setValue]`.
+- `pp.effect(callback, deps?)` runs after render and can return cleanup.
+- `pp.layoutEffect(callback, deps?)` runs synchronously after DOM mutation.
+- `pp.ref(initialValue?)` returns `{ current }`.
+- `pp.memo(factory, deps)` memoizes a computed value.
+- `pp.callback(callback, deps)` memoizes a function.
+- `pp.reducer(reducer, initialState)` returns `[state, dispatch]`.
+- `pp.portal(ref, target?)` portals a ref-managed element into a target.
+- `pp.props` exposes the current props.
 
----
+Notes:
 
-## Refs with `pp-ref`
+- `pp.state` setters accept either a value or an updater function.
+- `pp.effect` and `pp.layoutEffect` use dependency arrays like React, but only the hooks listed here exist.
+- Keep template-facing bindings at the top level so the AST-based exporter can see them.
 
-### Single element ref
-
-```html
-<input type="text" pp-ref="{nameInput}" />
-<button onclick="nameInput.current?.focus()">Focus</button>
+## Template expressions and attributes
 
-<script>
-  const nameInput = pp.ref(null);
-</script>
-```
+- Use `{expression}` in text nodes and attribute values.
+- Pure bindings like `value="{count}"` are evaluated as expressions.
+- Mixed text like `class="card {isActive ? 'active' : ''}"` is supported.
+- Boolean attributes are normalized for supported boolean names.
+- Use `pp-spread="{...attrs}"` to spread one object expression into attributes.
+- Use plain `key` for keyed diffing. `pp-key` is not implemented in the current source.
 
-### Dynamic ref registration
+Example:
 
 ```html
-<ul>
-  <template pp-for="item in items">
-    <li key="{item.id}">
-      <input pp-ref="{registerRef(item.id)}" hidden="{editingId !== item.id}" />
-      <button onclick="setEditingId(item.id)">Edit</button>
-    </li>
-  </template>
-</ul>
+<button pp-spread="{...buttonAttrs}" hidden="{isLoading}">Save</button>
 
-<script>
-  const [items, setItems] = pp.state([
-    { id: 1, name: "Task A" },
-    { id: 2, name: "Task B" },
-  ]);
-  const [editingId, setEditingId] = pp.state(null);
-
-  const itemRefs = new Map();
-
-  const registerRef = (id) => (el) => {
-    if (el) itemRefs.set(id, el);
-    else itemRefs.delete(id);
+<script type="text/pp">
+  const buttonAttrs = {
+    class: "btn btn-primary",
+    "aria-label": "save",
   };
-
-  pp.effect(() => {
-    if (editingId && itemRefs.has(editingId)) {
-      itemRefs.get(editingId).focus();
-    }
-  }, [editingId]);
+  const isLoading = false;
 </script>
 ```
 
-Rules:
+## Refs
 
-- Initialize refs with `pp.ref(null)`.
-- Null-check ref access where appropriate.
-- Use refs for DOM access and imperative behavior, not as general reactive state storage.
+- Use `pp-ref="nameInput"` when the value is a ref object or callback already in scope.
+- Use `pp-ref="{registerRef(id)}"` when you need a dynamic expression.
+- `pp.ref(null)` is the normal way to create a ref object.
+- The runtime generates `data-pp-ref` internally. Do not author it.
+- Do not author `pp-event-owner`, `pp-owner`, or `pp-dynamic-*` attributes by hand.
 
----
-
-## Spread with `pp-spread`
-
-### Basic usage
-
-```html
-<button pp-spread="{...btn}">Submit</button>
-
-<script>
-  const [btn] = pp.state({
-    class: "px-3 py-2 rounded-md",
-    "aria-label": "submit",
-  });
-</script>
-```
-
-### Multiple spreads
+Example:
 
 ```html
-<input pp-spread="{...base, ...validation}" placeholder="Name" />
-
-<script>
-  const [base] = pp.state({ class: "input-base", required: true });
-  const [validation] = pp.state({ pattern: "[A-Za-z]+" });
-</script>
+<div pp-component="focus-box">
+  <input pp-ref="nameInput" />
+  <button onclick="nameInput.current?.focus()">Focus</button>
+
+  <script type="text/pp">
+    const nameInput = pp.ref(null);
+  </script>
+</div>
 ```
 
-Rules:
+## Lists and loops
 
-- Later spreads override earlier spreads.
-- Explicit attributes on the element override spread values.
-
----
+- Use `pp-for` only on `<template>`.
+- Supported forms are `item in items` and `(item, index) in items`.
+- The collection must be an array. Non-arrays are treated as empty lists.
+- Loop content can contain interpolations, events, refs, and nested components.
+- Use stable unique `key` values on repeated elements.
+- Duplicate keys can trigger warnings, so do not use random keys.
 
-## Lists with `pp-for`
+Example:
 
 ```html
 <ul>
-  <template pp-for="todo in todos">
+  <template pp-for="(todo, index) in todos">
     <li key="{todo.id}">
-      {todo.title}
+      {index + 1}. {todo.title}
       <button onclick="removeTodo(todo.id)">Remove</button>
     </li>
   </template>
 </ul>
 
-<script>
+<script type="text/pp">
   const [todos, setTodos] = pp.state([
     { id: 1, title: "First task" },
     { id: 2, title: "Second task" },
   ]);
 
   function removeTodo(id) {
-    setTodos(todos.filter((item) => item.id !== id));
+    setTodos(todos.filter((todo) => todo.id !== id));
   }
 </script>
 ```
 
-Rules:
-
-- Use `pp-for` only on `<template>`.
-- Always use stable keys such as IDs or stable indices.
-- Never use random keys.
-- Prefer immutable updates through setters.
-
----
-
-## Effects with `pp.effect`
-
-```html
-<script>
-  pp.effect(() => console.log("Any change"));
-
-  pp.effect(() => {
-    return () => {
-      // cleanup
-    };
-  }, []);
-
-  const [count, setCount] = pp.state(0);
-
-  pp.effect(() => {
-    console.log("count", count);
-  }, [count]);
-</script>
-```
-
-Rules:
+## Events
 
-- Use `[]` for one-time setup and cleanup.
-- Use dependency arrays to react to specific state changes.
-- Avoid unconditional setter calls inside effects.
-- Guard effect-driven updates to prevent loops.
+- Use native `on*` attributes such as `onclick`, `oninput`, and `onsubmit`.
+- Event values may be raw code or wrapped in `{...}`.
+- The runtime injects `event`, `e`, `$event`, `target`, `currentTarget`, and `el`.
+- Do not use hyphenated event attrs like `on-click`.
+- Handlers are rebound after DOM morphing, so do not assume one-time binding.
 
----
+## SPA, loading, and navigation helpers
 
-## Input binding patterns
+- `body[pp-spa="true"]` enables client-side navigation interception.
+- `a[pp-spa="false"]` disables interception for that link.
+- `pp-loading-content="true"` marks the page region that gets swapped during navigation.
+- `pp-loading-url` selects route-specific loading states.
+- `pp-loading-transition` accepts JSON with `fadeIn` and `fadeOut` timing values.
+- `pp-reset-scroll="true"` resets scroll positions during navigation.
 
-### Checkbox
+The runtime also exposes navigation and bridge helpers through `pp`:
 
-```html
-<input
-  type="checkbox"
-  checked="{isActive}"
-  onchange="setIsActive(event.target.checked)"
-/>
-
-<script>
-  const [isActive, setIsActive] = pp.state(false);
-</script>
-```
-
-### Text input
+- `pp.mount()`
+- `pp.redirect(url)`
+- `pp.fetchFunction(name, data?, optionsOrAbort?)`
+- `pp.enablePerf()`
+- `pp.disablePerf()`
+- `pp.getPerfStats()`
+- `pp.resetPerfStats()`
 
-```html
-<input type="text" value="{name}" oninput="setName(event.target.value)" />
-
-<script>
-  const [name, setName] = pp.state("");
-</script>
-```
+Notes:
 
-Rules:
+- `pp.redirect()` uses SPA navigation when it is enabled and the URL is same-origin; otherwise it falls back to normal navigation.
+- `pp.fetchFunction()` is the runtime RPC bridge. It posts to the current route, attaches the wire headers the backend expects, and can switch to FormData for files, report upload progress, abort the previous request, or stream responses when supported.
+- The bundle mounts the runtime automatically once the global `pp` singleton is accessed after DOMContentLoaded, but `pp.mount()` exists if you want to trigger it explicitly.
 
-- Inputs should read from state.
-- Inputs should write back through explicit setters.
-- Avoid mixing manual DOM querying with reactive state for the same value.
+## Plain HTML bundle usage
 
----
+When the app is shipped as plain HTML plus a minified bundle:
 
-## Forbidden patterns
+- Keep the component markup in the HTML.
+- Load the bundle with a script tag after the markup or with `defer`.
+- Keep component logic inside `<script type="text/pp">` blocks in the HTML.
+- Do not assume access to the TypeScript source at runtime.
 
-Do not generate these unless the official PulsePoint docs explicitly document them:
+## What to avoid
 
-1. Undocumented runtime APIs
-2. Undocumented directives
-3. `pp-for` on non-`<template>` elements
-4. Random keys in rendered lists
-5. Multiple scattered script blocks for normal PulsePoint pages
-6. Direct DOM mutation for stateful UI that should be reactive
-7. Backend-specific assumptions in PulsePoint-only snippets
-8. Syntax copied from another framework without PulsePoint documentation support
+Do not generate these unless the current source explicitly supports them:
 
----
+- `pp-context`
+- `pp-key`
+- `data-pp-ref`
+- `pp-owner`
+- `pp-event-owner`
+- `pp-dynamic-script`
+- `pp-dynamic-meta`
+- `pp-dynamic-link`
+- plain `<script>` for component logic inside a component root
+- React, Vue, Svelte, or JSX-style component patterns that are not implemented here
+- made-up hooks, directives, or globals not present in the current TypeScript source
 
-## How AI should respond when PulsePoint is involved
+## AI checklist
 
-When a user asks for PulsePoint code, the AI should:
+When working on PulsePoint code, follow this order:
 
-1. Check the official PulsePoint docs first.
-2. Keep the solution inside documented PulsePoint primitives.
-3. Separate frontend PulsePoint behavior from backend implementation details.
-4. Avoid claiming a PulsePoint feature exists unless the docs support it.
-5. Prefer working examples that are ready to paste into a project.
-
-A good PulsePoint answer should feel:
-
-- minimal
-- explicit
-- backend-agnostic when appropriate
-- syntactically valid
-- faithful to the documented runtime
-
----
+- Use the current TypeScript source when it is available.
+- If only HTML plus a minified bundle exists, inspect those artifacts and follow the runtime behavior implemented there.
+- Keep template-facing variables at the top level of the component script.
+- Use only the hooks, directives, and attributes listed above.
+- Keep `pp-for` on `<template>` and use plain `key`.
+- Use refs and events as implemented, not as they work in another framework.
+- Avoid generating internal runtime attributes.
 
 ## Final reminder
 
-If you are generating, reviewing, or refactoring PulsePoint code, do **not** guess.
-
-Read the official docs first:
-
-```txt
-https://pulsepoint.tsnc.tech/llms
-```
-
-Then generate code using documented PulsePoint behavior only.
+If a feature is not implemented in the current runtime source, do not invent it.

package/dist/docs/route-handlers.md

@@ -7,6 +7,7 @@ related:
   description: Learn more about route handlers in Prisma PHP.
   links:
     - /docs/route-php
+    - /docs/php-validator
     - /docs/index-php
     - /docs/pages-and-layouts
 ---
@@ -109,6 +110,7 @@ A good handler pattern is:
 5. return structured JSON for expected validation failures
 
 This keeps the handler consistent whether the request came from a form, a `fetch()` call, or another client.
+For the full local validation guidance, read `validator.md` alongside this page.
 
 ## Request Helper