prisma-php 0.0.1

package/dist/docs/01-getting-started/pulsepoint.md

@@ -0,0 +1,434 @@
+# PulsePoint: always read the official docs before generating code
+
+> 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
+
+---
+
+## Read the PulsePoint docs first
+
+Before generating, editing, or reviewing any PulsePoint code, read the official PulsePoint docs:
+
+```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[])`
+
+### Markup directives
+
+1. `pp-for` _(only on `<template>`)_
+2. `pp-spread`
+3. `pp-ref`
+
+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
+
+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}" />
+```
+
+String branches in ternaries must be quoted correctly.
+
+- Correct: `{isActive ? 'text-blue-500' : 'text-gray-500'}`
+- Invalid: `{isActive ? text-blue-500' : 'text-gray-500'}`
+
+---
+
+## Refs with `pp-ref`
+
+### Single element ref
+
+```html
+<input type="text" pp-ref="{nameInput}" />
+<button onclick="nameInput.current?.focus()">Focus</button>
+
+<script>
+  const nameInput = pp.ref(null);
+</script>
+```
+
+### Dynamic ref registration
+
+```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>
+
+<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);
+  };
+
+  pp.effect(() => {
+    if (editingId && itemRefs.has(editingId)) {
+      itemRefs.get(editingId).focus();
+    }
+  }, [editingId]);
+</script>
+```
+
+Rules:
+
+- 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.
+
+---
+
+## 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
+
+```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>
+```
+
+Rules:
+
+- Later spreads override earlier spreads.
+- Explicit attributes on the element override spread values.
+
+---
+
+## Lists with `pp-for`
+
+```html
+<ul>
+  <template pp-for="todo in todos">
+    <li key="{todo.id}">
+      {todo.title}
+      <button onclick="removeTodo(todo.id)">Remove</button>
+    </li>
+  </template>
+</ul>
+
+<script>
+  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));
+  }
+</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:
+
+- 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.
+
+---
+
+## Input binding patterns
+
+### Checkbox
+
+```html
+<input
+  type="checkbox"
+  checked="{isActive}"
+  onchange="setIsActive(event.target.checked)"
+/>
+
+<script>
+  const [isActive, setIsActive] = pp.state(false);
+</script>
+```
+
+### Text input
+
+```html
+<input type="text" value="{name}" oninput="setName(event.target.value)" />
+
+<script>
+  const [name, setName] = pp.state("");
+</script>
+```
+
+Rules:
+
+- Inputs should read from state.
+- Inputs should write back through explicit setters.
+- Avoid mixing manual DOM querying with reactive state for the same value.
+
+---
+
+## Forbidden patterns
+
+Do not generate these unless the official PulsePoint docs explicitly document them:
+
+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
+
+---
+
+## How AI should respond when PulsePoint is involved
+
+When a user asks for PulsePoint code, the AI should:
+
+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
+
+---
+
+## 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.