caspian-utils 0.0.6 → 0.0.7
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
|
@@ -70,6 +70,8 @@ Treat `<!-- @import ... -->` as a file-level directive, not as rendered markup.
|
|
|
70
70
|
- `<!-- @import Container from "../components" -->` resolves `Container.py` from that folder.
|
|
71
71
|
- The component function name should match the tag name you render, such as `Container` for `<Container />`.
|
|
72
72
|
- Grouped imports and aliases are also supported, for example `<!-- @import { Button, Card as UserCard } from "../components/ui" -->`.
|
|
73
|
+
- If one Python file exports several `@component` functions, point `from` at that exact file instead of assuming one file per tag.
|
|
74
|
+
- In that case, prefer one grouped import so every rendered tag resolves back to the same Python module.
|
|
73
75
|
|
|
74
76
|
Good:
|
|
75
77
|
|
|
@@ -92,6 +94,38 @@ Bad:
|
|
|
92
94
|
</section>
|
|
93
95
|
```
|
|
94
96
|
|
|
97
|
+
### Same-File Component Exports
|
|
98
|
+
|
|
99
|
+
Caspian does not require one Python file per component. A single file can export a main component plus related subcomponents.
|
|
100
|
+
|
|
101
|
+
If `Breadcrumb.py` defines `Breadcrumb`, `BreadcrumbList`, `BreadcrumbItem`, `BreadcrumbLink`, `BreadcrumbPage`, and `BreadcrumbSeparator`, import those names from `Breadcrumb.py` itself.
|
|
102
|
+
|
|
103
|
+
```html
|
|
104
|
+
<!-- @import { Breadcrumb, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbPage, BreadcrumbSeparator } from "../maddex/Breadcrumb.py" -->
|
|
105
|
+
|
|
106
|
+
<div class="dashboard-topbar">
|
|
107
|
+
<Breadcrumb class="dashboard-breadcrumbs" aria-label="Dashboard breadcrumbs">
|
|
108
|
+
<BreadcrumbList class="dashboard-breadcrumbs__list">
|
|
109
|
+
<BreadcrumbItem class="dashboard-breadcrumbs__item">
|
|
110
|
+
<BreadcrumbLink href="/dashboard">Dashboard</BreadcrumbLink>
|
|
111
|
+
</BreadcrumbItem>
|
|
112
|
+
<BreadcrumbSeparator class="dashboard-breadcrumbs__separator" />
|
|
113
|
+
<BreadcrumbItem class="dashboard-breadcrumbs__item">
|
|
114
|
+
<BreadcrumbPage class="dashboard-breadcrumbs__page">Reports</BreadcrumbPage>
|
|
115
|
+
</BreadcrumbItem>
|
|
116
|
+
</BreadcrumbList>
|
|
117
|
+
</Breadcrumb>
|
|
118
|
+
</div>
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
If you only need one component from that file, keep the same file path:
|
|
122
|
+
|
|
123
|
+
```html
|
|
124
|
+
<!-- @import Breadcrumb from "../maddex/Breadcrumb.py" -->
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
Do not invent folder-level imports for symbols that do not have their own file. If `BreadcrumbItem` lives inside `Breadcrumb.py`, import it from `Breadcrumb.py`, not from `../maddex` as if `BreadcrumbItem.py` existed.
|
|
128
|
+
|
|
95
129
|
## Template-Backed Components
|
|
96
130
|
|
|
97
131
|
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.
|
package/dist/docs/index.md
CHANGED
|
@@ -58,7 +58,7 @@ Preferred lookup order:
|
|
|
58
58
|
1. Read `node_modules/caspian-utils/dist/docs/index.md` to discover available local docs.
|
|
59
59
|
2. Read `./caspian.config.json` before making any feature assumption. Use it to confirm which project capabilities are enabled and which directories or tooling rules apply.
|
|
60
60
|
3. 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.
|
|
61
|
-
4. 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>`.
|
|
61
|
+
4. 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" -->`.
|
|
62
62
|
5. Prefer local docs before generating code, commands, or migration guidance.
|
|
63
63
|
6. Check `node_modules/caspian-utils/dist/docs/` for packaged Caspian docs when local docs need more detail.
|
|
64
64
|
7. Only fall back to upstream documentation when local and packaged markdown do not cover the topic.
|
|
@@ -98,6 +98,8 @@ Use this folder for reusable UI components that should be imported into route te
|
|
|
98
98
|
|
|
99
99
|
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.
|
|
100
100
|
|
|
101
|
+
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.
|
|
102
|
+
|
|
101
103
|
For component HTML files, follow the same one-parent rule as route HTML files: one top-level lowercase HTML element only, with no sibling roots and no top-level script sitting outside that root.
|
|
102
104
|
|
|
103
105
|
Do not handwrite `pp-component="..."` or `type="text/pp"` in component source templates either. Write plain `<script>` inside the single root and let the render pipeline inject the runtime shape.
|