caspian-utils 0.0.13 → 0.0.14
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/docs/components.md
CHANGED
|
@@ -18,12 +18,14 @@ Import them into a template with an `@import` comment, then render them with JSX
|
|
|
18
18
|
|
|
19
19
|
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.
|
|
20
20
|
|
|
21
|
+
As the app grows, treat `src/components/` as the default home for reusable application UI. Keep route-owned markup in `src/app/`, and keep non-UI helpers or services in `src/lib/`.
|
|
22
|
+
|
|
21
23
|
## Mental Model
|
|
22
24
|
|
|
23
25
|
- Use a Python component when you want a reusable server-rendered UI building block.
|
|
24
26
|
- Return an HTML string directly for small presentational components.
|
|
25
27
|
- 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.
|
|
26
|
-
- Keep page-level workflows in `src/app/`,
|
|
28
|
+
- Keep page-level workflows in `src/app/`, move reusable UI into `src/components/`, and keep helpers, services, validators, and adapters in `src/lib/`.
|
|
27
29
|
|
|
28
30
|
## Basic Component
|
|
29
31
|
|
package/dist/docs/index.md
CHANGED
|
@@ -51,7 +51,7 @@ The packaged Caspian docs distributed by the current toolchain also live here:
|
|
|
51
51
|
- `validation.md` - Input validation and sanitization with `Validate`, `Rule`, direct field checks, and multi-rule workflows for routes and RPC actions
|
|
52
52
|
- `metadata.md` - Static and dynamic metadata, SEO inheritance, and Open Graph or Twitter card tags
|
|
53
53
|
- `routing.md` - Next.js App Router-style file-based routing with `src/app`, dynamic segments, route groups, nested layouts, and single-root route templates
|
|
54
|
-
- `project-structure.md` - Default Caspian layout and where
|
|
54
|
+
- `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
|
|
55
55
|
|
|
56
56
|
## AI Awareness Notes
|
|
57
57
|
|
|
@@ -66,10 +66,11 @@ Preferred lookup order:
|
|
|
66
66
|
5. Treat generated outputs such as `public/css/styles.css`, `settings/component-map.json`, `settings/files-list.json`, `__pycache__/`, and `.pyc` files as framework-managed artifacts when the local stack is intentionally running. They are not authored source files and should not be kept in the final diff unless the task explicitly requires them.
|
|
67
67
|
6. Analyze `settings/component-map.json` and `settings/files-list.json` when you need the current generated view of components or routes, but do not hand-edit them. The framework regenerates them through `settings/component-map.ts` and `settings/files-list.ts` when the dev or build pipeline intentionally runs.
|
|
68
68
|
7. Read `database.md` only when `caspian.config.json` enables Prisma, read `mcp.md` only when `caspian.config.json` enables MCP, and use `auth.md`, `components.md`, `pulsepoint.md`, `fetch-data.md`, `state.md`, `cache.md`, and `validation.md` as the next routing docs for those non-flagged concerns.
|
|
69
|
-
8.
|
|
70
|
-
9.
|
|
71
|
-
10.
|
|
72
|
-
11.
|
|
69
|
+
8. As the app grows, standardize on `src/app/` for route-owned files, `src/components/` for reusable rendered UI, and `src/lib/` for reusable non-UI support code such as services, validators, adapters, and shared helpers.
|
|
70
|
+
9. For authored component, route, and layout HTML files, generate exactly one top-level lowercase HTML element. Think React-style single parent wrapper: keep any owned PulsePoint logic in a plain `<script>` inside that root, do not handwrite `pp-component="..."` or `type="text/pp"` because Caspian injects those runtime attributes automatically, and treat `<!-- @import ... -->` comments as file-level directives that belong above the authored root element instead of inside `<div>`, `<section>`, or `<html>`. When several component tags come from one Python file, import them from that exact file path, for example `<!-- @import { Breadcrumb, BreadcrumbItem, BreadcrumbList } from "../components/Breadcrumb.py" -->`.
|
|
71
|
+
10. Prefer local docs before generating code, commands, or migration guidance.
|
|
72
|
+
11. Check `node_modules/caspian-utils/dist/docs/` for packaged Caspian docs when local docs need more detail.
|
|
73
|
+
12. Only fall back to upstream documentation when local and packaged markdown do not cover the topic.
|
|
73
74
|
|
|
74
75
|
## Maintenance
|
|
75
76
|
|
|
@@ -21,6 +21,8 @@ This page explains the default layout of a Caspian application, where Caspian co
|
|
|
21
21
|
|
|
22
22
|
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.
|
|
23
23
|
|
|
24
|
+
As an app grows, keep reusable rendered UI in `src/components/`, keep reusable non-UI support code in `src/lib/`, and keep route-owned files in `src/app/`. That split keeps page composition separate from shared component and service code.
|
|
25
|
+
|
|
24
26
|
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.
|
|
25
27
|
|
|
26
28
|
For public pages that can safely reuse rendered HTML, Caspian also supports route-level page caching through `casp.cache_handler`.
|
|
@@ -31,8 +33,9 @@ Treat `caspian.config.json` as the single source of truth for optional feature e
|
|
|
31
33
|
|
|
32
34
|
## Top-Level Areas
|
|
33
35
|
|
|
34
|
-
- `src/` contains routes, page templates, styles, and shared libraries.
|
|
35
|
-
- `src/components/` contains reusable
|
|
36
|
+
- `src/` contains routes, page templates, styles, reusable components, and shared libraries.
|
|
37
|
+
- `src/components/` contains reusable application UI components and optional same-name HTML templates.
|
|
38
|
+
- `src/lib/` contains reusable non-UI code such as helpers, services, validators, adapters, and shared support modules.
|
|
36
39
|
- `src/lib/auth/auth_config.py` contains auth-specific configuration for the app.
|
|
37
40
|
- `src/lib/mcp/` contains the app-owned FastMCP server and nested FastMCP config when MCP is enabled.
|
|
38
41
|
- `prisma/` contains the Prisma schema and seed scripts.
|
|
@@ -105,6 +108,8 @@ See `routing.md` for the full App Router-style rules for dynamic segments, route
|
|
|
105
108
|
|
|
106
109
|
Use this folder for reusable UI components that should be imported into route templates or other component templates.
|
|
107
110
|
|
|
111
|
+
As the app grows, default to `src/components/` for application-level UI that will be shared across routes or features. Keep page-only markup close to the route in `src/app/`, but move shared cards, forms, shells, navigation, and other reusable visual building blocks into `src/components/`.
|
|
112
|
+
|
|
108
113
|
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.
|
|
109
114
|
|
|
110
115
|
One Python file can also export multiple related `@component` functions. When that happens, import those tags from that exact file path in HTML, for example `<!-- @import { Breadcrumb, BreadcrumbItem, BreadcrumbList } from "../components/Breadcrumb.py" -->`, instead of assuming each tag has its own sibling `.py` file.
|
|
@@ -117,7 +122,9 @@ This workspace's component tooling scans `src/` based on `caspian.config.json`,
|
|
|
117
122
|
|
|
118
123
|
### `src/lib/`
|
|
119
124
|
|
|
120
|
-
Use this folder for shared helpers, reusable validators, RPC-facing service wrappers,
|
|
125
|
+
Use this folder for shared helpers, reusable validators, RPC-facing service wrappers, data-access helpers, formatting utilities, and other app-level support code that is not itself a reusable rendered component.
|
|
126
|
+
|
|
127
|
+
If the code is primarily rendered UI that will be imported as a component tag, prefer `src/components/`. If the code is a helper, service, adapter, validator, or other non-visual support module, prefer `src/lib/`.
|
|
121
128
|
|
|
122
129
|
This workspace already includes an app-owned Python database layer under `src/lib/prisma/`. Reuse that package for Python-side data access and keep any additional shared database helpers in `src/lib/`.
|
|
123
130
|
|
|
@@ -241,8 +248,10 @@ If an AI agent is deciding where to make changes, use these rules first.
|
|
|
241
248
|
- Treat `__pycache__/` directories, `.pyc` files, `public/css/styles.css`, `settings/component-map.json`, and `settings/files-list.json` as generated artifacts when the local stack is intentionally running. They are not authored source files.
|
|
242
249
|
- Inspect `settings/component-map.json` and `settings/files-list.json` when you need the generated component or route inventory, but do not hand-edit them. The workspace regenerates them from `settings/component-map.ts` and `settings/files-list.ts`.
|
|
243
250
|
- Put route templates and route-specific backend logic in `src/app/`.
|
|
251
|
+
- As the app grows, keep route-owned code in `src/app/`, reusable rendered UI in `src/components/`, and reusable non-UI support code in `src/lib/`.
|
|
244
252
|
- Check [routing.md](./routing.md) when you need URL segment rules, layout nesting behavior, or dynamic route conventions.
|
|
245
253
|
- 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.
|
|
254
|
+
- When deciding between `src/components/` and `src/lib/`, use `src/components/` for anything rendered as reusable UI and `src/lib/` for helpers, services, validators, adapters, and shared business logic.
|
|
246
255
|
- Use [mcp.md](./mcp.md) only when `caspian.config.json` enables MCP and the task involves FastMCP tool definitions, nested config discovery, or local MCP commands.
|
|
247
256
|
- Keep `<!-- @import ... -->` comments above the single authored root element in route, layout, and component HTML files.
|
|
248
257
|
- For route and component HTML files, always emit one top-level lowercase HTML element. Good: one wrapper containing the content and a plain `<script>` when needed. Bad: a wrapper element followed by a sibling top-level `<script>`, or handwritten `pp-component="..."` and `type="text/pp"` attributes in source.
|