caspian-utils 0.0.2 → 0.0.3

package/dist/docs/components.md

@@ -0,0 +1,249 @@
+---
+title: Components
+description: Create reusable Caspian components as `@component` Python functions, import them into templates as `<MyComponent />`, and split interactive UI into same-name HTML templates when PulsePoint logic is involved.
+related:
+  title: Related docs
+  description: Use the structure guide for file placement, the routing guide for route templates, the PulsePoint guide for browser-side scripts, and the data guide for component-owned RPC flows.
+  links:
+    - /docs/project-structure
+    - /docs/routing
+    - /docs/pulsepoint
+    - /docs/fetch-data
+    - /docs/index
+---
+
+Components in Caspian are Python functions decorated with `@component`.
+
+Import them into a template with an `@import` comment, then render them with JSX-style tags such as `<MyComponent />` or `<MyComponent>...</MyComponent>`.
+
+For the current workspace, component tooling scans Python files under the paths listed in `caspian.config.json`. Right now that means `src/`, so `src/components/` is the clean default location for reusable UI, even though any scanned path under `src/` can work.
+
+## Mental Model
+
+- Use a Python component when you want a reusable server-rendered UI building block.
+- Return an HTML string directly for small presentational components.
+- Use `render_html(...)` with a same-name `.html` file when the component has more markup, PulsePoint behavior, or clearer separation between Python logic and UI.
+- Keep page-level workflows in `src/app/`, and move reusable UI into components.
+
+## Basic Component
+
+This is the simplest pattern: accept props, merge classes or attributes, and return HTML.
+
+```python
+from casp.component_decorator import component
+from casp.html_attrs import get_attributes, merge_classes
+
+@component
+def Container(children: str = "", **props) -> str:
+    incoming_class = props.pop("class", "")
+    final_class = merge_classes("mx-auto max-w-7xl px-4", incoming_class)
+
+    attributes = get_attributes({
+        "class": final_class,
+    }, props)
+
+    return f'<div {attributes}>{children}</div>'
+```
+
+Notes:
+
+- `children` receives the inner content passed between opening and closing tags.
+- `**props` lets the component accept additional HTML attributes such as `id`, `data-*`, and `aria-*`.
+- The runtime normalizes `class`, `className`, and `class_name` into a merged `class` value before the component is called.
+
+## Import And Use Components
+
+Import components inside the HTML template where they are used.
+
+```html
+<!-- @import Container from "../components" -->
+
+<Container class="py-10">
+  <h1>Dashboard</h1>
+</Container>
+```
+
+The import comment is the bridge between the Python component file and the JSX-style tag.
+
+- `<!-- @import Container from "../components" -->` resolves `Container.py` from that folder.
+- The component function name should match the tag name you render, such as `Container` for `<Container />`.
+- Grouped imports and aliases are also supported, for example `<!-- @import { Button, Card as UserCard } from "../components/ui" -->`.
+
+## Template-Backed Components
+
+When a component includes richer UI or PulsePoint behavior, keep the Python file focused on props or server-side preparation and move the markup into a same-name HTML file.
+
+`Counter.py`
+
+```python
+from casp.component_decorator import component, render_html
+
+@component
+def Counter(label: str = "Clicks") -> str:
+    return render_html(__file__, {
+        "label": label,
+    })
+```
+
+`Counter.html`
+
+```html
+<div>
+  <h3>[[ label ]]</h3>
+  <button onclick="setCount(count + 1)">
+    {count}
+  </button>
+
+  <script type="text/pp">
+    const [count, setCount] = pp.state(0);
+  </script>
+</div>
+```
+
+Use this split when:
+
+- Python is shaping props, loading data, or exposing server-side helpers.
+- The template has enough markup that returning a raw f-string becomes noisy.
+- PulsePoint state, effects, refs, or event handlers belong next to the component markup.
+
+This keeps the component easy to read: Python owns the server-side logic and template context, while the HTML file owns the rendered UI and browser behavior.
+
+## Auto-Injected `pp-component` And PulsePoint Scripts
+
+Treat `pp-component="componentName"` as framework output, not authored source.
+
+- Do not manually add `pp-component` to route templates or component HTML files.
+- The Python render pipeline injects `pp-component` onto the single root element during render.
+- Add `<script type="text/pp">` only when the route or component actually needs PulsePoint logic.
+- When you do add a PulsePoint script, keep it inside that single root element.
+
+Examples in runtime docs often show rendered HTML that already contains `pp-component`. That is the final output shape, not the normal authoring pattern.
+
+### Authored Source vs Rendered Output
+
+Author this:
+
+`Counter.html`
+
+```html
+<div>
+  <h3>[[ label ]]</h3>
+  <button onclick="setCount(count + 1)">
+    {count}
+  </button>
+
+  <script type="text/pp">
+    const [count, setCount] = pp.state(0);
+  </script>
+</div>
+```
+
+Do not author this by hand:
+
+```html
+<div pp-component="counter_ab12cd34">
+  <h3>Clicks</h3>
+  <button onclick="setCount(count + 1)">0</button>
+
+  <script type="text/pp">
+    const [count, setCount] = pp.state(0);
+  </script>
+</div>
+```
+
+The second example is the runtime shape after the Python side injects `pp-component` onto the component root.
+
+## Single-Root Rule
+
+Every component HTML template must render exactly one top-level lowercase HTML element.
+
+The same rule applies to route templates such as `src/app/**/index.html`: one root element, no sibling roots, and no manual `pp-component` authoring.
+
+This is not just style guidance. The installed compiler injects `pp-component` onto the root element, and it raises an error when the template has no root, multiple sibling roots, stray top-level text, or a component tag as the root.
+
+Valid:
+
+```html
+<div class="card">
+  <h2>Title</h2>
+</div>
+```
+
+Invalid:
+
+```html
+<h2>Title</h2>
+<p>Body</p>
+```
+
+Also avoid making another component tag the root of the HTML file. The root must be a normal lowercase HTML element such as `<div>`, `<section>`, or `<article>`.
+
+Think about this rule the same way you would in a React component: one parent element per template root. In Caspian, that requirement exists so the Python renderer has exactly one place to attach `pp-component`.
+
+## Props, Types, And Children
+
+Props come from the attributes on the component tag.
+
+```python
+from typing import Any, Literal
+
+from casp.component_decorator import component
+from casp.html_attrs import get_attributes, merge_classes
+
+ButtonVariant = Literal["default", "outline", "destructive"]
+
+@component
+def Button(
+    children: Any = "",
+    variant: ButtonVariant = "default",
+    **props,
+) -> str:
+    classes = {
+        "default": "btn btn-primary",
+        "outline": "btn btn-outline",
+        "destructive": "btn btn-danger",
+    }
+
+    incoming_class = props.pop("class", "")
+    attrs = get_attributes({
+        "class": merge_classes(classes[variant], incoming_class),
+    }, props)
+
+    return f'<button {attrs}>{children}</button>'
+```
+
+Use typed parameters when you want better editor hints and stricter component APIs. `Literal[...]` is a good fit for variants, sizes, or other closed sets of values.
+
+## Async Components
+
+Components can also be async. Use this only when the component render contract really depends on awaited work such as a database query, service call, or file read.
+
+```python
+from casp.component_decorator import component, render_html
+
+@component
+async def ProfileCard(user_id: str) -> str:
+    user = await get_user_by_id(user_id)
+
+    return render_html(__file__, {
+        "user": user,
+    })
+```
+
+Keep synchronous components as the default. Switch to `async def` only when the component itself needs awaited I/O.
+
+## Best Practices
+
+- Put reusable components in `src/components/` and keep route files in `src/app/`.
+- If the component includes PulsePoint behavior, prefer a thin Python wrapper plus a same-name `.html` template.
+- Keep the component file name, exported function name, and tag name aligned, such as `Button.py`, `def Button(...)`, and `<Button />`.
+- Accept `children` or `**props` when the component should support nested content.
+- Keep page-level data loading in `page()` when the data is not intrinsic to the component itself.
+- If you add `@rpc()` functions inside a component file, keep their names globally unique because component RPCs are not route-scoped.
+
+## Related Reading
+
+- Read [project-structure.md](./project-structure.md) for where reusable components should live.
+- Read [routing.md](./routing.md) when importing components into route templates.
+- Read [pulsepoint.md](./pulsepoint.md) for the runtime contract of `pp-component`, `script[type="text/pp"]`, props, and browser-side reactivity.
+- Read [fetch-data.md](./fetch-data.md) when a component needs browser-triggered `pp.rpc()` calls or component-owned server actions.

package/dist/docs/index.md

@@ -1,13 +1,14 @@
 ---
 title: Caspian Docs
-description: Caspian documentation with AI-aware routing to the right local docs before framework-specific code generation or project setup changes, with PulsePoint, RPC, and Validate as the default app stack.
+description: Caspian documentation with AI-aware routing to the right local docs before framework-specific code generation or project setup changes, with components, PulsePoint, RPC, and Validate as the default app stack.
 related:
   title: Next Steps
-  description: Start with installation, review the CLI commands, then use the structure guide to place Caspian files correctly.
+  description: Start with installation, review the CLI commands, then use the structure and component guides to place Caspian files correctly.
   links:
     - /docs/installation
     - /docs/commands
     - /docs/project-structure
+    - /docs/components
 ---
 
 This directory contains the local Caspian documentation set for quick reference and AI-aware routing.
@@ -36,6 +37,7 @@ The packaged Caspian docs distributed by the current toolchain also live here:
 - `commands.md` - Main Caspian CLI workflows for project creation, generation, updates, and config-aware maintenance
 - `database.md` - Prisma schema, migration, seed, and client-generation workflow for the current workspace, plus Python-side helper caveats
 - `auth.md` - Session-backed authentication with `casp.auth`, centralized `auth_config.py`, decorators, RBAC, and OAuth provider helpers
+- `components.md` - Create reusable Python components, template-backed UI, JSX-style imports, and single-root component templates
 - `pulsepoint.md` - Default reactive frontend runtime contract for component scripts, state, effects, directives, and client-side behaviors
 - `fetch-data.md` - Initial server-side data loading and browser-triggered RPC flows with `pp.rpc()`, streaming, uploads, and auth-aware actions
 - `state.md` - Request-scoped server state with `StateManager`, session-backed JSON persistence, and listener callbacks for transient flows
@@ -52,7 +54,7 @@ If an AI tool needs Caspian project documentation, start with this directory and
 Preferred lookup order:
 
 1. Read `node_modules/caspian-utils/dist/docs/index.md` to discover available local docs.
-2. Read `database.md` for Prisma setup and ORM usage, `auth.md` for session auth and route protection, `pulsepoint.md` for reactive frontend work, `fetch-data.md` for data flows, `state.md` for transient request-scoped state, `cache.md` for page caching, and `validation.md` for input boundaries.
+2. Read `database.md` for Prisma setup and ORM usage, `auth.md` for session auth and route protection, `components.md` for reusable UI authoring, `pulsepoint.md` for browser-side reactive runtime behavior, `fetch-data.md` for data flows, `state.md` for transient request-scoped state, `cache.md` for page caching, and `validation.md` for input boundaries.
 3. Prefer local docs before generating code, commands, or migration guidance.
 4. Check `node_modules/caspian-utils/dist/docs/` for packaged Caspian docs when local docs need more detail.
 5. Only fall back to upstream documentation when local and packaged markdown do not cover the topic.

package/dist/docs/project-structure.md

@@ -1,11 +1,12 @@
 ---
 title: Project Structure
-description: Understand the default Caspian project layout so AI agents place files in the correct directories before generating PulsePoint templates, RPC actions, validation helpers, auth code, configuration, or database changes.
+description: Understand the default Caspian project layout so AI agents place routes, reusable components, PulsePoint templates, RPC actions, validation helpers, auth code, configuration, and database changes in the correct directories.
 related:
   title: Related docs
-  description: Start with installation for new apps, then use the auth guide for bootstrap and session wiring, the routing guide to map URLs correctly, and the cache guide when route HTML should be reused safely.
+  description: Start with installation for new apps, then use the component guide for reusable UI, the auth guide for bootstrap and session wiring, the routing guide to map URLs correctly, and the cache guide when route HTML should be reused safely.
   links:
     - /docs/installation
+    - /docs/components
     - /docs/auth
     - /docs/routing
     - /docs/cache
@@ -19,13 +20,14 @@ This page explains the default layout of a Caspian application, where Caspian co
 
 Caspian uses a lean project layout that keeps application code in `src`, database files in `prisma`, static assets in `public`, configuration in `caspian.config.json`, and framework internals in the installed package.
 
-In that layout, the default stack is PulsePoint in route templates, RPC for browser-triggered server calls, and `casp.validate` for input validation at route and action boundaries.
+In that layout, the default stack is Python components for reusable UI, PulsePoint in templates for reactive browser behavior, RPC for browser-triggered server calls, and `casp.validate` for input validation at route and action boundaries.
 
 For public pages that can safely reuse rendered HTML, Caspian also supports route-level page caching through `casp.cache_handler`.
 
 ## Top-Level Areas
 
 - `src/` contains routes, page templates, styles, and shared libraries.
+- `src/components/` contains reusable Python components and optional same-name HTML templates.
 - `src/lib/auth/auth_config.py` contains auth-specific configuration for the app.
 - `prisma/` contains the Prisma schema and seed scripts.
 - `public/` contains static assets served directly.
@@ -50,6 +52,11 @@ my-app/
       index.py
       index.html
       globals.css
+    components/
+      Container.py
+      ui/
+        Button.py
+        Button.html
     lib/
       auth/
         auth_config.py
@@ -79,6 +86,14 @@ This directory handles file-based routing. Route templates and route-specific ba
 
 See `routing.md` for the full App Router-style rules for dynamic segments, route groups, and nested layouts.
 
+### `src/components/`
+
+Use this folder for reusable UI components that should be imported into route templates or other component templates.
+
+The common Caspian pattern is a Python file such as `Button.py` with `@component`, optionally paired with a same-name HTML file such as `Button.html` when the component has richer markup or PulsePoint behavior.
+
+This workspace's component tooling scans `src/` based on `caspian.config.json`, so `src/components/` is a conventionally clean location, not a hard-coded runtime requirement.
+
 ### `src/lib/`
 
 Use this folder for shared helpers, reusable validators, RPC-facing service wrappers, reusable UI utilities, and app-level support code.
@@ -138,7 +153,9 @@ The backend logic for the route. This is where route behavior can load first-ren
 
 ### `src/app/index.html`
 
-The route template. It supports standard HTML, PulsePoint directives, and component imports, and it should be the default place for reactive frontend behavior in Caspian.
+The route template. It supports standard HTML, `<!-- @import ... -->` component imports, and PulsePoint directives, and it should be the default place for reactive frontend behavior in Caspian.
+
+Use `components.md` when the task involves authoring reusable `<MyComponent />` tags backed by Python files.
 
 ### `src/app/globals.css`
 
@@ -165,6 +182,7 @@ If an AI agent is deciding where to make changes, use these rules first.
 
 - Put route templates and route-specific backend logic in `src/app/`.
 - Check [routing.md](./routing.md) when you need URL segment rules, layout nesting behavior, or dynamic route conventions.
+- Put reusable component files in `src/components/` and check [components.md](./components.md) for `@component`, `render_html(__file__)`, import comments, and single-root template rules.
 - Put shared helpers and reusable libraries in `src/lib/`.
 - Use PulsePoint conventions in route templates for reactive frontend behavior.
 - Use `@rpc()` in route/backend code and `pp.rpc()` in client code for browser-triggered data flows.

package/dist/docs/pulsepoint.md

@@ -3,8 +3,9 @@ title: PulsePoint Runtime Guide
 description: Learn how AI agents should use PulsePoint as the default reactive frontend contract in Caspian, including the bundled runtime loaded from `public/js/main.js` and implemented in `public/js/pp-reactive-v2.js`, component script rules, and supported directives.
 related:
   title: Related docs
-  description: Read the routing, data-fetching, and project-structure docs alongside the PulsePoint runtime contract.
+  description: Read the components, routing, data-fetching, and project-structure docs alongside the PulsePoint runtime contract.
   links:
+    - /docs/components
     - /docs/routing
     - /docs/fetch-data
     - /docs/project-structure
@@ -17,6 +18,8 @@ This file documents the PulsePoint runtime that is currently shipped in `public/
 
 If a task involves `pp.state`, `pp.effect`, `pp.layoutEffect`, `pp-ref`, `pp-spread`, `pp-for`, context, portals, SPA navigation, or component boundary behavior, read this page first and keep generated code aligned with the runtime implemented in this repo.
 
+Use `components.md` for authoring Python `@component` files and same-name HTML templates. Use this page for the browser-side `pp-component` contract and `script[type="text/pp"]` behavior after those templates are rendered.
+
 PulsePoint is the default reactive frontend layer for Caspian.
 
 Do not assume React, Vue, Svelte, JSX, Alpine, HTMX, or older PulsePoint docs unless the task explicitly asks for a different frontend contract.
@@ -34,6 +37,7 @@ When a Caspian page needs reactive browser behavior, use PulsePoint.
 - Source authoring under `src/` may use convenience syntax that is transformed before it reaches the browser.
 - This page describes the bundled browser runtime shipped in `public/js/pp-reactive-v2.js`.
 - When source-layer examples conflict with the bundled runtime, follow the bundled runtime.
+- In authored route and component templates, do not add `pp-component` manually. The Python side injects it onto the template root during render.
 - In a `pp-component` root, component logic must live in `<script>`, not plain `<script>`.
 
 ## Runtime shape
@@ -45,6 +49,7 @@ A component root is any element with `pp-component`.
 Important:
 
 - `pp-component` is the instance id used for the component registry, saved state, cached template, parent tracking, and instance lookup.
+- In normal Caspian authoring, `pp-component` arrives from the Python render pipeline on route, layout, and component roots rather than being handwritten in source templates.
 - Reusing the same `pp-component` value for multiple live roots will destroy the previous registered instance and replace it with the new one.
 - If a root is manually constructed with an empty `pp-component`, the runtime will assign an anonymous id. AI-generated markup should still use stable unique ids.
 - `pp.mount()` bootstraps every `[pp-component]` in the document, so do not manually instantiate `Component` in authored app code.
@@ -55,6 +60,7 @@ Important:
 - The runtime only treats `script` as component logic.
 - The script lookup walks the current root and skips nested `pp-component` boundaries, so a parent does not consume a child component's script.
 - If multiple matching scripts exist in the same root, the first matching owned script wins. Generate one script per root.
+- Component HTML templates must have exactly one top-level lowercase HTML root because the compiler injects `pp-component` onto that root during render.
 - A scriptless component root still mounts and can receive props, refs, events, and nested children, but it has no local runtime scope beyond its props.
 - Component scripts are plain JavaScript executed with `new Function(...)`. Do not use `import`, `export`, or top-level `await` inside them.
 - The runtime auto-returns supported top-level bindings from the script. Do not rely on manual `return { ... }` objects.
@@ -93,6 +99,8 @@ Example:
 </div>
 ```
 
+That example shows runtime HTML after mountable roots already exist. In authored Caspian templates, you normally write the root without `pp-component` and let the Python renderer inject it before the browser runtime sees the HTML.
+
 ## Hooks and runtime API
 
 Hooks exposed inside component scripts through `pp`:

package/dist/docs/routing.md

@@ -1,11 +1,12 @@
 ---
 title: Routing
-description: Understand Caspian's Next.js App Router-style file-based routing, including src/app conventions, index files, dynamic segments, route groups, and nested layouts.
+description: Understand Caspian's Next.js App Router-style file-based routing, including src/app conventions, index files, dynamic segments, route groups, nested layouts, and component-friendly route templates.
 related:
   title: Related docs
-  description: Read the structure guide first, then use the metadata guide for SEO fields, the cache guide for route-level HTML reuse, and the PulsePoint runtime guide for interactive route templates.
+  description: Read the structure guide first, then use the components guide for reusable UI, the metadata guide for SEO fields, the cache guide for route-level HTML reuse, and the PulsePoint runtime guide for interactive route templates.
   links:
     - /docs/project-structure
+    - /docs/components
     - /docs/cache
     - /docs/metadata
     - /docs/pulsepoint
@@ -73,6 +74,42 @@ Examples:
 
 Use `index.html` for the route template. This is the route's view layer.
 
+Route templates can import reusable Python components with `<!-- @import ... -->` comments and render them with JSX-style tags such as `<Button />`. Use [components.md](./components.md) for the component authoring rules.
+
+Do not manually add `pp-component="..."` to the route root. The Python render pipeline injects that attribute onto the route's single top-level lowercase HTML element.
+
+That means route templates follow the same single-root discipline as component templates: one root element, no sibling roots, and PulsePoint scripts kept inside that root when needed.
+
+Example authored route template:
+
+```html
+<!-- @import StatsCard from "../components" -->
+
+<section class="dashboard-shell">
+  <StatsCard title="Users" value="42" />
+
+  <script type="text/pp">
+    const [filter, setFilter] = pp.state("all");
+  </script>
+</section>
+```
+
+Rendered shape at runtime:
+
+```html
+<section pp-component="page_a1b2c3d4" class="dashboard-shell">
+  <div pp-component="statscard_e5f6g7h8" title="Users" value="42">
+    ...
+  </div>
+
+  <script type="text/pp">
+    const [filter, setFilter] = pp.state("all");
+  </script>
+</section>
+```
+
+Write the first form. Caspian produces the second form.
+
 ### `index.py`
 
 Use `index.py` when the route needs metadata or async server-side logic. Because Caspian runs on FastAPI, the page entry should be async.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "caspian-utils",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "Caspian tooling",
   "main": "index.js",
   "scripts": {