caspian-utils 0.1.17 → 0.1.19

package/dist/docs/components.md

@@ -1,6 +1,6 @@
 ---
 title: Components
-description: Use this page when the task mentions `@component`, reusable UI, HTML-first `x-*` component tags, component imports, same-name `.html` templates, `merge_classes(...)`, `twMerge(...)`, or where shared components belong in a Caspian project.
+description: Use this page when the task mentions `@component`, reusable UI, HTML-first `x-*` component tags, component imports, same-name `.html` templates, forwarding Python component props to `pp.props`, `get_attributes(...)`, `merge_classes(...)`, `twMerge(...)`, or where shared components belong in a Caspian project.
 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.
@@ -257,8 +257,110 @@ def UserCard(user, **props):
     """, attrs=attrs, user=user)
 ```
 
-The returned value is `Markup`, so the normal pipeline still injects `pp-component` on the single root and `transform_scripts(...)` rewrites the plain `<script>` to `type="text/pp"`. A single-file component renders identically to the two-file `render_html(...)` form; the choice is purely about readability.
-
+The returned value is `Markup`, so the normal pipeline still injects `pp-component` on the single root and `transform_scripts(...)` rewrites the plain `<script>` to `type="text/pp"`. A single-file component renders identically to the two-file `render_html(...)` form; the choice is purely about readability.
+
+### Receiving Props In A Python Component
+
+There are two separate prop handoffs in a single-file Python component, and the Python component is the bridge between them:
+
+1. Caspian converts attributes on the parent-authored `x-*` tag from kebab-case to camelCase and calls the Python component with them as string keyword arguments. PulsePoint expressions are not evaluated at this stage: `open="{permOpen}"` arrives in Python as the literal string `"{permOpen}"`, and `on-apply="{applyPermissions}"` arrives as `onApply="{applyPermissions}"`.
+2. The Python component must deliberately re-emit the props it wants the browser component to receive as attributes on its rendered root. Build those attributes with `get_attributes({...}, props)`, place `{{ attributes }}` on the single native root, and pass `attributes=attributes` to `html(...)`.
+3. PulsePoint derives `pp.props` from that rendered root. It evaluates pure `{expression}` attribute values in the parent component's scope, then exposes kebab-case root attribute names as camelCase keys such as `on-apply` -> `pp.props.onApply`.
+
+Python function parameters do not automatically become root attributes or browser props. A parameter that is accepted but not included in `get_attributes(...)` is server-only and is discarded when the Python call returns.
+
+Minimal end-to-end example:
+
+Parent template:
+
+```html
+<!-- @import { UserPermissionsDialog } from "../../components/UserPermissionsDialog.py" -->
+
+<div>
+  <button onclick="setPermOpen(true)">Edit permissions</button>
+  <x-user-permissions-dialog
+    open="{permOpen}"
+    value="{permValue}"
+    on-open-change="{setPermOpen}"
+    on-apply="{applyPermissions}"
+  />
+
+  <script>
+    const [permOpen, setPermOpen] = pp.state(false);
+    const [permValue, setPermValue] = pp.state([]);
+
+    function applyPermissions(nextValue) {
+      setPermValue(nextValue);
+      setPermOpen(false);
+    }
+  </script>
+</div>
+```
+
+`UserPermissionsDialog.py`:
+
+```python
+from casp.component_decorator import component, html
+from casp.html_attrs import get_attributes, merge_classes
+
+@component
+def UserPermissionsDialog(
+    open=None,
+    value=None,
+    onOpenChange=None,
+    onApply=None,
+    **props,
+):
+    incoming_class = props.pop("class", "")
+    attributes = get_attributes({
+        "class": merge_classes("permissions-dialog", incoming_class),
+        "open": open,
+        "value": value,
+        "onOpenChange": onOpenChange,
+        "onApply": onApply,
+    }, props)
+
+    # html
+    return html("""
+      <section {{ attributes }} hidden="{!open}">
+        <p>Selected permissions: {value.length}</p>
+        <button onclick="onOpenChange(false)">Cancel</button>
+        <button onclick="onApply(value)">Apply</button>
+
+        <script>
+          const { open, value, onOpenChange, onApply } = pp.props;
+        </script>
+      </section>
+    """, attributes=attributes)
+```
+
+The browser can evaluate `permOpen`, `permValue`, `setPermOpen`, and `applyPermissions` because their literal brace expressions survived the Python render and were placed on the child root. If `{{ attributes }}` or `attributes=attributes` is missing, `pp.props` has none of those forwarded keys and may be completely empty.
+
+Pitfalls:
+
+- **Silent empty `pp.props`:** accepting `open`, `value`, or callback parameters in Python without re-emitting them on the root raises no server error and no browser warning. The component renders, but those keys are absent from `pp.props` and values such as `pp.props.open` are `undefined`.
+- **Reserved/native attribute collisions:** forwarded props are real DOM attributes. A prop named `title` produces the native `title="..."` tooltip on the root. Prefer a component-specific non-native name such as `user-name` (Python `userName`, browser `pp.props.userName`) when native behavior is not intended.
+- `get_attributes(...)` omits empty strings. To pass a reactive boolean, prefer a pure expression such as `disabled="{isDisabled}"` rather than relying on a bare empty attribute to survive the Python bridge.
+
+### HTML Attribute Helper Contract
+
+`casp.html_attrs.get_attributes(defaults, overrides=None)` builds one Jinja-safe attribute string for a component root:
+
+- It processes the first dictionary, then the optional second dictionary. A non-empty value in `overrides` replaces the same normalized key from `defaults`. An omitted/empty override does not delete an already-renderable default. This is why the usual component pattern passes authored defaults first and remaining `**props` second.
+- It resolves Python-safe aliases before normalization: `class_name` and `className` become `class`, `html_for` and `htmlFor` become `for`, `defaultValue` becomes `defaultvalue`, and `defaultChecked` becomes `defaultchecked`.
+- It converts every other camelCase key to kebab-case, so `onOpenChange` renders as `on-open-change` and later becomes `pp.props.onOpenChange` in PulsePoint.
+- It omits keys whose value is `None`, `False`, an empty string, or an empty/falsy list, tuple, or set. `True` renders as the explicit string `"true"`; non-empty iterables are space-joined.
+- It HTML-escapes attribute values and returns `Markup`, so `{{ attributes }}` is not double-escaped by Jinja.
+- Passing `**props` as the second dictionary is the passthrough contract for unconsumed `id`, `data-*`, `aria-*`, reactive expressions, callbacks, and other boundary attributes. Pop or otherwise consume a prop first when it should not be forwarded or when it has already been merged into a default.
+
+`casp.html_attrs.merge_classes(*classes)` flattens truthy strings and truthy items from lists, tuples, or sets:
+
+- When `caspian.config.json` has `tailwindcss: false`, it joins the class parts with spaces.
+- When `tailwindcss: true`, it emits a PulsePoint expression such as `{twMerge("base classes", incomingClass)}` so the browser's global `twMerge(...)` resolves Tailwind conflicts after parent-scope prop evaluation.
+- An incoming pure `{expression}` becomes an expression argument rather than a quoted string. An existing `{twMerge(...)}` expression is preserved or incorporated without nesting another `twMerge(...)` call.
+- Empty inputs produce an empty string, which `get_attributes(...)` omits.
+- When combining a default class with incoming `**props`, remove the incoming `class` from `props` before passing `props` as overrides; otherwise that later override replaces the merged class attribute.
+
 Rules for inline `html(...)`:
 
 - The single-root rule still applies: exactly one top-level element with any `<script>` nested inside it.

package/dist/docs/index.md

@@ -16,6 +16,7 @@ related:
     - /docs/file-conventions
     - /docs/project-structure
     - /docs/components
+    - /docs/testing
 ---
 
 This directory contains the packaged Caspian documentation set for AI-aware feature discovery, task routing, and file-placement guidance.
@@ -94,6 +95,7 @@ The packaged Caspian docs referenced by this index live here:
 - `metadata.md` - Static and dynamic metadata, SEO inheritance, and Open Graph or Twitter card tags
 - `routing.md` - Next.js App Router-style file-based routing with `src/app`, dynamic segments, dashboard and section layouts, route groups, nested layouts, shared-shell scroll-reset ownership, single-parent authored templates, and backend Python companions that do not own visible markup
 - `project-structure.md` - Default Caspian layout and where route files, reusable UI in `src/components/`, reusable non-UI code in `src/lib/`, and database files belong
+- `testing.md` - Recommended app-owned testing, type-checking, and linting gate over `main.py` and `src/**` (pyrefly + ruff + pytest behind one command); not a shipped feature and not gated by a `caspian.config.json` flag, so verify the actual command, tools, and config in the project
 
 ## AI Retrieval Notes
 
@@ -115,6 +117,7 @@ Preferred lookup order:
 12. Prefer packaged Caspian docs before upstream documentation when generating code, commands, or migration guidance.
 13. Use `ai-validation-checklist.md` when you want to verify that the docs lead AI to the correct files and behavior checkpoints.
 14. Keep `index.md` and cross-links aligned so AI can quickly discover the right doc.
+15. If the task is about tests, type checking, linting, a quality gate, CI checks, or making an app production-ready, read `testing.md`. It is an app-owned convention (not a shipped feature and not gated by a `caspian.config.json` flag), so confirm the actual gate command in `package.json`, the orchestrator in `settings/`, and the tools and config in `pyproject.toml` before assuming they exist.
 
 ## Maintenance
 

package/dist/docs/pulsepoint.md

@@ -567,9 +567,11 @@ Consumer example for a child component that receives the token through props:
 
 When a child component needs the same token object, pass it from the provider scope as a prop such as `theme-token="{ThemeContext}"`.
 
-## Props and nested components
-
-- Child component props are derived from DOM attributes.
+## Props and nested components
+
+In Caspian single-file Python components, the root element's attributes must be authored via `get_attributes(...)` and `{{ attributes }}`; see [components.md](./components.md#receiving-props-in-a-python-component). Attributes accepted from an `x-*` tag but not forwarded to the rendered root are dropped and never reach `pp.props`.
+
+- Child component props are derived from DOM attributes.
 - Attribute names are converted from kebab-case to camelCase for the prop bag.
 - Native `on*` attributes and `pp-component` are not included in props.
 - Empty attributes become boolean `true` props.

package/dist/docs/testing.md

@@ -0,0 +1,92 @@
+---
+title: Testing And Quality Gate
+description: Use this page when the task mentions tests, pytest, type checking, pyrefly, linting, ruff, a quality gate, CI checks, or "make the code production-ready" for a Caspian app's own Python. Explains the recommended one-command gate over `main.py` and `src/**`.
+related:
+  title: Related docs
+  description: Pair the quality gate with the runtime map when a failing check points into core files, and with the structure and command docs when deciding where tests and tooling belong.
+  links:
+    - /docs/core-runtime-map
+    - /docs/project-structure
+    - /docs/commands
+    - /docs/auth
+    - /docs/index
+---
+
+This page describes the recommended way to add tests, type checking, and linting to a Caspian application's **own** Python (`main.py` and `src/**`).
+
+Caspian does not ship a test runner, type checker, or linter. Quality tooling is an app-owned convention layered on top of the framework, so treat everything here as a recommended setup to scaffold per project, not as a built-in feature that already exists in every Caspian app. The framework runtime under `.venv/Lib/site-packages/casp/**` is out of scope for app tests.
+
+## When Does This Doc Apply
+
+- The task is to add or extend tests for app code, add type checking, add linting, wire a CI/pre-commit check, or prepare an app for production.
+- A prior change touched `main.py`, `src/lib/**`, or route `index.py` files and needs verification.
+- Not gated by any `caspian.config.json` flag. It applies to any Caspian app; it does not depend on `prisma`, `mcp`, `websocket`, or `typescript`.
+
+## Recommended Shape: One Command
+
+Expose a single gate command so an agent or CI has exactly one thing to run. The recommended command runs three tools in one pass and reports every problem with its exact location:
+
+- **type check** — [pyrefly](https://pyrefly.org) over `main.py` and `src/**`
+- **lint** — [ruff](https://docs.astral.sh/ruff/)
+- **tests** — [pytest](https://docs.pytest.org)
+
+The command should print each problem as `path:line:col [tool:code] message` and exit non-zero when any check fails, so the file and line to fix are always explicit. Prefer a single `npm run check` script (backed by an app-owned orchestrator such as `settings/check.py`) over separate `test` / `lint` / `typecheck` scripts, so the surface stays minimal. Keep a per-tool escape hatch (for example `--only pyrefly`) for debugging rather than as additional npm scripts.
+
+## Source Of Truth
+
+- The gate command and its tool list are app-owned. Confirm the actual script name in the project's `package.json` and the orchestrator file (commonly `settings/check.py`) before assuming a command exists.
+- Tooling versions and configuration are app-owned in `pyproject.toml`. Do not assume a tool is installed just because this doc mentions it; check the project's dependency group and `uv.lock`.
+- App tests live in a top-level `tests/` directory. Framework internals under `.venv/Lib/site-packages/casp/**` are never the test target.
+
+## Recommended Layout
+
+```
+tests/
+  conftest.py            # put project root on sys.path; set safe dev env defaults
+  test_*.py              # app-level unit + integration tests
+settings/check.py        # orchestrator: runs the tools, prints path:line:col report
+```
+
+- `conftest.py` should add the project root to `sys.path` and set safe development defaults (for example `APP_ENV=development` and a throwaway `AUTH_SECRET`) so importing `main` never fails during collection.
+- Test `main.py` through its pure helpers and through `starlette.testclient.TestClient` against `main.app` (for example the always-on `/health` route, which exercises the middleware stack). Test `src/lib/**` policy such as `auth_config.py` directly.
+
+## Recommended `pyproject.toml` Configuration
+
+Keep the dev tooling in a dependency group and install it with `uv sync --group dev`:
+
+```toml
+[dependency-groups]
+dev = [
+    "pyrefly>=0.16",
+    "ruff>=0.6",
+    "pytest>=8.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.ruff]
+include = ["main.py", "src/**/*.py", "tests/**/*.py", "settings/check.py"]
+extend-exclude = [".venv", "node_modules"]
+
+[tool.ruff.lint]
+# Correctness-focused; leave cosmetic rules off the generated starter code.
+select = ["E", "F", "W"]
+ignore = ["E501"]
+
+[tool.pyrefly]
+project-includes = ["main.py", "src/**"]
+search-path = [".", "src"]
+```
+
+## Things To Verify Before Editing Or Explaining
+
+- Confirm the gate command name and orchestrator path in `package.json` and `settings/`, since they are app-owned and may differ per project.
+- Confirm the dev tools are actually installed (`[dependency-groups]` in `pyproject.toml`, resolved in `uv.lock`) before telling a user to run the gate.
+- Check `[tool.pyrefly.errors]` in `pyproject.toml`. A project may suppress specific error kinds (commonly `bad-return` and `bad-assignment`); those are then not reported by the gate, so do not assume every annotation mismatch is caught.
+- Keep the scope on app code. If a check points into `.venv/Lib/site-packages/casp/**`, use [core-runtime-map.md](./core-runtime-map.md) to understand the runtime, but do not add framework files to the app's test, lint, or type-check scope.
+
+## Working Rule For Agents
+
+When you add or change app-owned Python (`main.py`, `src/**`), add or extend the matching test under `tests/`, write annotated and type-checkable code, and run the single gate command until it passes before treating the change as done. Fix problems at the exact `path:line:col` the gate reports.

package/package.json

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