prisma-php 0.0.1

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

@@ -0,0 +1,589 @@
+---
+title: Prisma PHP Components for AI Awareness
+description: Learn how AI agents should understand, locate, import, and generate Prisma PHP components using the official PHPX and ImportComponent patterns.
+related:
+  title: Related docs
+  description: Read the official Prisma PHP component docs before generating or editing components.
+  links:
+    - /docs/get-started-phpx
+    - /docs/import-component
+    - /docs/fragment
+    - /docs/icon-component
+    - /docs/button-component
+    - /docs/accordion-component
+---
+
+Prisma PHP components should be generated using the official **PHPX** and **ImportComponent** models, not assumptions from React, Vue, Blade components, or generic PHP templating.
+
+If a task involves component creation, component editing, component composition, PHPX rendering rules, or importing PHP partials as PulsePoint-ready islands, AI agents should read the relevant local Prisma PHP docs first and use the installed framework conventions before generating code.
+
+## AI rule: read the component docs first
+
+Before generating, editing, or reviewing components, use this order:
+
+1. Read `./prisma-php.json`.
+2. Read the installed local docs in `node_modules/prisma-php/dist/docs`.
+3. Inspect the existing local component structure.
+4. Inspect Prisma PHP core internals only when the docs do not answer the task.
+
+Do not assume JSX, TSX, Blade, Vue SFC, React, or generic PHP partial behavior applies directly.
+
+## Read this doc when you need
+
+- **PHPX component basics, naming, file placement, props, children, or reactive props** → `get-started-phpx`
+- **importing a PHP partial as a component, component islands, `ImportComponent::render(...)`, or server-first PulsePoint boundaries** → `import-component`
+- **multiple sibling nodes, wrapperless output, or `<>...</>` usage** → `fragment`
+- **custom SVG icon components** → `icon-component`
+- **button component structure, variants, sizes, or theme-aware classes** → `button-component`
+- **accordion components, grouped sub-components, `StateManager`, or injected JS lifecycle rules** → `accordion-component`
+
+## Two component models AI must not confuse
+
+Prisma PHP has **two related but different component models**.
+
+### 1. PHPX class-based components
+
+Use this model when building reusable PHP component classes such as:
+
+- `Button`
+- `Accordion`
+- `Search`
+- `Card`
+- `Icon`
+
+These components:
+
+- extend the PHPX base class
+- usually live in a component namespace such as `src/app/Lib/Components`
+- render HTML from `render(): string`
+- use class-based props and helpers such as `$this->children`, `$this->class`, and `$this->getAttributes(...)`
+
+### 2. `ImportComponent` partial-based components
+
+Use this model when a plain PHP file or partial should become a **real PulsePoint component boundary**.
+
+This is the right mental model for:
+
+- server-first pages with small reactive islands
+- imported PHP partials that must receive props as HTML attributes
+- componentized partials that PulsePoint should hydrate later
+- keeping PHP templating ergonomics while still producing component-aware markup
+
+AI must not collapse these two models into one.
+
+- **PHPX** is for class-based component authoring.
+- **`ImportComponent`** is for importing PHP partial files as single-root component islands.
+
+## Important AI rules for Prisma PHP components
+
+- treat the official Prisma PHP component docs as the source of truth
+- use **PHPX** for class-based reusable components
+- use **`ImportComponent`** when a PHP partial should become a PulsePoint-ready component boundary
+- keep file names and class names aligned for PHPX class components
+- prefer the documented component directories and naming patterns
+- do not invent undocumented lifecycle hooks, props APIs, or import behavior
+- preserve Prisma PHP XML-style markup rules when returning component markup
+- use `$this->children`, `$this->props`, `$this->class`, and `$this->getAttributes(...)` following the documented PHPX pattern
+- when a component needs reactivity, distinguish between static PHP props and reactive PulsePoint props
+- when a component requires grouped sub-components, follow the documented same-file naming pattern like `Accordion`, `AccordionItem`, `AccordionTrigger`, and `AccordionContent`
+- when using `ImportComponent`, always ensure the imported file renders **exactly one root element**
+
+## Component file placement and naming
+
+The official PHPX docs describe a file and naming convention centered on class-based components.
+
+A standard component should usually live in a component-oriented path such as:
+
+```txt
+src/app/Lib/Components/Button.php
+```
+
+The class name should match the file name.
+
+Examples:
+
+- `Button.php` → `class Button`
+- `Search.php` → `class Search`
+- `Accordion.php` → `class Accordion`
+
+### Related component naming
+
+When a component is made of multiple related sub-components, the official docs recommend keeping them grouped under the same naming family.
+
+Example naming group:
+
+- `Accordion`
+- `AccordionItem`
+- `AccordionTrigger`
+- `AccordionContent`
+
+These related classes can live in the same file, and each class name should begin with the shared main component prefix.
+
+Example path:
+
+```txt
+src/app/Lib/PHPX/Components/Accordion.php
+```
+
+### Imported partial component paths
+
+For `ImportComponent`, the input is a **PHP file path**, not a PHPX class reference.
+
+Common examples:
+
+```txt
+APP_PATH . '/inc/Hero.php'
+APP_PATH . '/inc/SearchBox.php'
+APP_PATH . '/components/UserCard.php'
+```
+
+AI should preserve the project's actual partial locations instead of inventing a new component folder structure when the task is specifically about imported partials.
+
+## Base PHPX component shape
+
+A Prisma PHPX component should generally:
+
+1. extend the PHPX base class
+2. accept `array $props = []` in the constructor
+3. call `parent::__construct($props)`
+4. render a string from `render(): string`
+5. use helper methods such as `getMergeClasses(...)` and `getAttributes(...)` when appropriate
+
+Typical shape:
+
+```php
+<?php
+
+namespace Lib\Components;
+
+use Lib\PHPX\PHPX;
+
+class ClassName extends PHPX
+{
+    public ?string $class = '';
+    public mixed $children = null;
+
+    public function __construct(array $props = [])
+    {
+        parent::__construct($props);
+    }
+
+    public function render(): string
+    {
+        $class = $this->getMergeClasses($this->class);
+        $attributes = $this->getAttributes([
+            'class' => $class,
+        ]);
+
+        return <<<HTML
+        <div {$attributes}>
+            {$this->children}
+        </div>
+        HTML;
+    }
+}
+```
+
+## Core PHPX props model
+
+The official PHPX docs describe these important component properties:
+
+- `$props` → all incoming props and attributes
+- `$children` → inner rendered content
+- `$class` → CSS class input for styling
+- `$attributesArray` → HTML attributes prepared for rendering
+
+AI should not invent alternative prop containers when the PHPX base model already provides these.
+
+## Static props vs reactive props
+
+Prisma PHP components separate normal server-side props from reactive PulsePoint props.
+
+### Static props
+
+Static props are plain PHP values and should be treated as normal typed component inputs.
+
+Examples:
+
+```xml
+<Button type="submit" class="w-full" />
+<TestComponent isChildren="true" />
+```
+
+### Reactive props
+
+Reactive PulsePoint props must use mustache syntax.
+
+Examples:
+
+```xml
+<TestComponent counter="{count}" setCounter="{setCount}" />
+```
+
+### AI rule for reactive props
+
+- use normal quoted props for static PHP values
+- use mustache syntax for PulsePoint signals and client-reactive values
+- do not mix the two models casually
+- when a child component must receive browser-side state, pass it in mustache form
+
+## `ImportComponent` rules
+
+The official `ImportComponent` docs describe it as the utility that turns a PHP partial into a real PulsePoint component boundary.
+
+### What `ImportComponent` does
+
+When you call:
+
+```php
+ImportComponent::render($filePath, $props);
+```
+
+Prisma PHP:
+
+1. executes the component file in an isolated namespace
+2. captures the produced HTML output
+3. parses it as an XML fragment
+4. enforces exactly one root element
+5. injects a stable `pp-component` attribute
+6. serializes props into HTML attributes on the root element
+7. stores a snapshot accessible through `ImportComponent::sections()`
+
+### AI rules for `ImportComponent`
+
+- use `ImportComponent` for PHP partials, not for PHPX class components
+- require exactly one root element in the imported file
+- treat the imported output as a PulsePoint-ready island boundary
+- pass server data as props and let Prisma PHP serialize them into attributes
+- use mustache-valued props when passing reactive PulsePoint bindings into imported partials
+- do not assume multiple top-level siblings are allowed
+- do not manually inject `pp-component`; let `ImportComponent` do it
+
+### Basic usage
+
+```php
+<?php
+
+use PP\ImportComponent;
+
+ImportComponent::render(APP_PATH . '/inc/Hero.php');
+```
+
+### Passing props
+
+```php
+<?php
+
+use PP\ImportComponent;
+
+$user = ['id' => 7, 'name' => 'Jefferson'];
+
+ImportComponent::render(APP_PATH . '/inc/UserCard.php', [
+    'user' => $user,
+    'variant' => 'compact',
+    'isOnline' => true,
+]);
+```
+
+### Reactive PulsePoint bindings
+
+```php
+<?php
+
+use PP\ImportComponent;
+?>
+
+<div class="space-y-4">
+    <?php ImportComponent::render(APP_PATH . '/inc/SearchBox.php', [
+        'query' => '{query}',
+        'setQuery' => '{setQuery}',
+    ]); ?>
+
+    <script type="text/pp">
+        const [query, setQuery] = pp.state('');
+    </script>
+</div>
+```
+
+### Imported file requirements
+
+The imported PHP file must output **exactly one root element**.
+
+Correct:
+
+```php
+<div class="rounded-lg border bg-card p-4">
+    <h2 class="font-medium">Search</h2>
+    <input value="{query}" oninput="{(e) => setQuery(e.target.value)}" />
+</div>
+```
+
+Incorrect:
+
+```php
+<h2 class="font-medium">Search</h2>
+<input value="{query}" oninput="{(e) => setQuery(e.target.value)}" />
+```
+
+## `ImportComponent` prop serialization rules
+
+The official docs define these serialization rules:
+
+- `null` props are skipped
+- booleans become `"true"` or `"false"`
+- scalar values become strings
+- arrays and objects become JSON
+- when a prop value contains PulsePoint mustache syntax like `{count}`, Prisma PHP converts camelCase prop keys to kebab-case attribute names when needed for HTML-safe output
+
+### AI implications
+
+- pass normal PHP arrays and objects directly; do not pre-JSON-encode them manually unless the project already does that intentionally
+- expect reactive props like `setCount` to become an HTML attribute such as `set-count` when the value contains mustache syntax
+- do not rely on camelCase HTML attributes surviving unchanged in mustache-driven import cases
+
+## Exposed functions inside imported components
+
+The official `ImportComponent` docs also note an automatic exposed-function registry behavior during isolated execution.
+
+That means an imported component file can define an exposed PHP function, and Prisma PHP can register it for later use through the exposed-function tooling.
+
+Example:
+
+```php
+<?php
+
+use PP\Attributes\Exposed;
+
+#[Exposed]
+function saveDraft(array $payload): array
+{
+    return ['ok' => true];
+}
+?>
+
+<div class="rounded-md border p-4">
+    Draft editor
+</div>
+```
+
+### AI rule
+
+If a component file imported via `ImportComponent` defines `#[Exposed]` functions, do not move them out just because they are inside the imported file. Preserve the documented pattern unless the user explicitly wants a different structure.
+
+## Fragment rules
+
+The official `Fragment` component exists so PHPX components can return multiple sibling elements in heredoc output without forcing an unnecessary wrapper element.
+
+Use `<Fragment>` or the shorthand fragment syntax:
+
+```php
+return <<<HTML
+<>
+    <h1 class="text-2xl font-bold">Heading</h1>
+    <p class="text-muted-foreground">Paragraph</p>
+</>
+HTML;
+```
+
+### When to use `Fragment`
+
+Use it when:
+
+- a PHPX component must return multiple siblings
+- you want to avoid an unnecessary wrapper `div`
+- semantic HTML would be harmed by adding an extra wrapper
+- you are using heredoc output and PHPX still needs a single parseable root structure
+
+### Important distinction
+
+`Fragment` is a **PHPX rendering tool**.
+
+It is **not** the same as `ImportComponent`'s single-root partial rule.
+
+- in **PHPX**, `Fragment` is how multiple siblings can be represented
+- in **`ImportComponent`**, the imported partial itself must still resolve to exactly one root element
+
+AI should not misuse fragment concepts to bypass the `ImportComponent` single-root requirement.
+
+## Icon component rules
+
+The official icon component docs recommend SVG as the preferred format for custom icon components because SVG is lightweight, vector-based, and easy to style with utility classes.
+
+A manual icon component follows the normal PHPX class pattern.
+
+Typical structure:
+
+```php
+<?php
+
+namespace Lib\GoogleIcons;
+
+use PP\PHPX\PHPX;
+
+class Search extends PHPX
+{
+    public ?string $class = '';
+
+    public function __construct(array $props = [])
+    {
+        parent::__construct($props);
+    }
+
+    public function render(): string
+    {
+        $class = $this->getMergeClasses($this->class);
+        $attributes = $this->getAttributes([
+            'class' => $class,
+        ]);
+
+        return <<<HTML
+        <svg xmlns="http://www.w3.org/2000/svg" fill="currentColor" {$attributes}>
+            <path d="..." />
+        </svg>
+        HTML;
+    }
+}
+```
+
+### AI rules for icon components
+
+- prefer SVG over raster formats when creating reusable icons
+- expose `class` so the icon can be styled from the caller
+- use `fill="currentColor"` when the icon should follow text color
+- keep the component small and focused on rendering the SVG
+- do not hardcode visual styling when utility classes can control it
+
+## Button component rules
+
+The official Button component docs present Button as a reusable PHPX component with:
+
+- variants
+- sizes
+- theme-aware utility classes
+- support for normal button rendering and anchor-style rendering
+
+### AI rules for button components
+
+- place button components in a standard component path such as `src/app/Lib/Components/Button.php`
+- extend the PHPX base class
+- use props like `variant` and `size` from `$this->props`
+- compute classes centrally in a helper such as `getComputedClasses()`
+- prefer theme token utilities like `bg-primary`, `text-primary-foreground`, `bg-destructive`, and `border-input` instead of hardcoded colors
+- preserve accessibility-related states such as focus rings and disabled styles
+
+### Common button structure
+
+A documented button pattern typically includes:
+
+- base classes for layout, typography, focus, and disabled state
+- a variant map
+- a size map
+- merged user classes from `$class`
+- optional rendering differences when the component should behave like a link
+
+## Accordion component rules
+
+The official Accordion docs define Accordion as a grouped PHPX component system with multiple classes working together.
+
+### Related classes
+
+- `Accordion`
+- `AccordionItem`
+- `AccordionTrigger`
+- `AccordionContent`
+
+### Important lifecycle rule
+
+The docs explicitly note that Prisma PHPX execution starts from the innermost child to the outermost parent. Because of that, the parent `Accordion` constructs last, and that is why the JavaScript is injected there after child IDs are ready.
+
+### AI rules for accordions
+
+- keep related accordion classes in the same naming family
+- use `StateManager` when following the documented ID-sharing pattern between trigger and content
+- inject shared accordion JavaScript from the parent component when using the documented lifecycle pattern
+- preserve WAI-ARIA attributes such as `aria-controls`, `aria-expanded`, `aria-labelledby`, and `role="region"`
+- keep default visibility and animation classes in the content container unless the design intentionally changes them
+
+### Sub-component responsibilities
+
+- `AccordionItem` wraps a single item pair
+- `AccordionTrigger` renders the clickable control and manages toggle-related IDs
+- `AccordionContent` renders the hidden content region using the shared item ID state
+
+## XML-style syntax rule for component output
+
+When AI generates Prisma PHP components, returned markup should follow strict XML-style rules used across Prisma PHP templates.
+
+Correct:
+
+```xml
+<hr />
+<input type="text" />
+<Search class="size-4" />
+```
+
+Incorrect:
+
+```xml
+<hr>
+<input type="text">
+<Search class=size-4>
+```
+
+Also:
+
+- close all tags properly
+- use double quotes for attributes
+- avoid shorthand boolean attributes
+
+## When AI should inspect framework internals
+
+If the installed docs and local project code are not enough, AI may inspect Prisma PHP core internals in:
+
+```txt
+vendor/tsnc/prisma-php/src
+```
+
+Important component-related files may include:
+
+- `vendor/tsnc/prisma-php/src/PHPX/PHPX.php`
+- `vendor/tsnc/prisma-php/src/PHPX/Fragment.php`
+- `vendor/tsnc/prisma-php/src/PHPX/TemplateCompiler.php`
+- `vendor/tsnc/prisma-php/src/PHPX/TwMerge.php`
+- `vendor/tsnc/prisma-php/src/PHPX/TypeCoercer.php`
+- `vendor/tsnc/prisma-php/src/ImportComponent.php`
+- `vendor/tsnc/prisma-php/src/StateManager.php`
+- `vendor/tsnc/prisma-php/src/Attributes/Exposed.php`
+
+Use these files to verify internals only when necessary. Do not treat vendor internals as the first stop when the installed docs already answer the task.
+
+## Recommended AI workflow for component tasks
+
+When asked to create or edit a Prisma PHP component, AI should follow this workflow:
+
+1. Read `prisma-php.json`.
+2. Read the relevant installed component docs.
+3. Decide whether the task is **PHPX class-based** or **`ImportComponent` partial-based**.
+4. Inspect the local component namespace and folder conventions.
+5. Match file name and class name for PHPX class components.
+6. Use XML-style markup in `render(): string` or in imported partial output.
+7. Use static props and reactive props correctly.
+8. Enforce the single-root rule for `ImportComponent` partials.
+9. Only inspect `vendor/tsnc/prisma-php/src` when the docs or local usage are not enough.
+
+## Quick component lookup table
+
+| Task                                      | Read first            | Typical location                               |
+| ----------------------------------------- | --------------------- | ---------------------------------------------- |
+| create a reusable PHPX component          | `get-started-phpx`    | `src/app/Lib/Components/ClassName.php`         |
+| import a PHP partial as a reactive island | `import-component`    | `APP_PATH . '/inc/ComponentName.php'`          |
+| return multiple siblings in PHPX          | `fragment`            | `vendor/tsnc/prisma-php/src/PHPX/Fragment.php` |
+| create an SVG icon component              | `icon-component`      | `src/app/Lib/GoogleIcons/Search.php`           |
+| create a theme-aware button               | `button-component`    | `src/app/Lib/Components/Button.php`            |
+| create a grouped accordion                | `accordion-component` | `src/app/Lib/Components/Accordion.php`         |
+
+## Final AI reminder
+
+For Prisma PHP components, do not guess.
+
+Read the official component docs first, decide whether the task belongs to **PHPX** or **`ImportComponent`**, preserve strict XML-style output, and only inspect Prisma PHP core internals when you truly need framework-level implementation details.