npm - cabloy - Versions diffs - 5.1.49 → 5.1.51 - Mend

cabloy 5.1.49 → 5.1.51

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.

Files changed (276) hide show

package/cabloy-docs/frontend/ssr-seo-meta.md ADDED Viewed

@@ -0,0 +1,52 @@
+# SSR SEO Meta
+This guide explains how SSR SEO metadata works in Zova within the Cabloy monorepo.
+## What SEO meta covers
+SEO meta is not only about the page title.
+It can also control:
+- `<meta>` tags
+- `<html>` attributes
+- `<body>` attributes
+- `<style>` and `<script>` tags in the document head
+- `<noscript>` tags
+## `$useMeta`
+Zova provides `$useMeta` on `BeanBase` so SSR-aware metadata can be declared in application code.
+Representative shape:
+```typescript
+this.$useMeta({
+  title: 'Index Page',
+  titleTemplate: title => `${title} - My Website`,
+  meta: {
+    description: { name: 'description', content: 'Page 1' },
+  },
+});
+```
+## Static and reactive metadata
+Two useful modes are supported:
+- **static meta** for values known at initialization time
+- **reactive meta** for values that should update when bound state changes
+That makes SEO metadata part of the reactive application model, not just a one-time page constant.
+## Overwrite behavior
+Calling `$useMeta` multiple times can overwrite earlier values for the same keys, so SSR metadata should be designed deliberately when multiple layers participate.
+## Implementation checks for SSR SEO metadata changes
+When adding or editing SEO behavior:
+1. use `$useMeta` rather than inventing a parallel metadata system
+2. decide whether the metadata is static or reactive
+3. remember that SSR is what makes many SEO-related tags meaningful to crawlers and downstream consumers

package/cabloy-docs/frontend/system-startup-guide.md ADDED Viewed

@@ -0,0 +1,186 @@
+# System Startup Guide
+## Why system startup matters
+Zova separates system startup from application startup so system-level initialization can be reasoned about independently from request-scoped or app-instance-scoped behavior.
+That matters especially in SSR scenarios, where application startup may happen per request while system startup does not.
+## System startup vs app startup
+The critical distinction is:
+- **app startup** can be tied to individual application instances or requests
+- **system startup** is not request-scoped
+This separation makes it easier to place long-lived initialization logic in the correct lifecycle.
+## System startup timings
+Zova provides three main system startup timings:
+- `sysInitialize`
+- `sysInitialized`
+- `sysReady`
+These allow framework and project code to stage system-level initialization intentionally.
+## System shutdown timing
+System shutdown is represented by:
+- `sysClose`
+## Module load and config load timings
+System-level lifecycle also includes:
+- `moduleLoading`
+- `moduleLoaded`
+- `configLoaded`
+These hooks are especially useful when module registration or config mutation must happen before the system is considered fully ready.
+## Hook response scenarios
+System startup hooks can be implemented in several places:
+- **Module Main Sys**
+- **Module Monkey Sys**
+- **Sys Monkey**
+This allows both module-level and project-level system initialization logic to participate in a structured way.
+A compact mental model is:
+- **Module Main Sys** handles a module’s own system-facing load/config lifecycle
+- **Module Monkey Sys** lets a module participate in broader system-level hook timings
+- **Sys Monkey** lets the project frontend config layer participate in the same system hook system
+## Module Main Sys
+A module can provide system-level main lifecycle entrypoints.
+Representative creation command:
+```bash
+npm run zova :init:mainSys demo-student
+```
+Representative pattern:
+```typescript
+export class MainSys extends BeanSimple implements IModuleMainSys {
+  async moduleLoading() {}
+  async moduleLoaded() {}
+  async configLoaded(_config: any) {}
+}
+```
+## Module Monkey Sys
+A module can also attach richer system lifecycle behavior through monkey-based hooks.
+Representative creation command:
+```bash
+npm run zova :init:monkeySys demo-student
+```
+Representative pattern:
+```typescript
+export class MonkeySys
+  extends BeanSimple
+  implements
+    IMonkeyModuleSys,
+    IMonkeySysInitialize,
+    IMonkeySysInitialized,
+    IMonkeySysReady,
+    IMonkeySysClose
+{
+  async moduleLoading(_module: IModule) {}
+  async moduleLoaded(_module: IModule) {}
+  async configLoaded(_module: IModule, _config: any) {}
+  async sysInitialize() {}
+  async sysInitialized() {}
+  async sysReady() {}
+  async sysClose() {}
+}
+```
+## Sys Monkey
+Project-level system lifecycle customization can be placed in the frontend config area.
+This is useful when the behavior belongs to the frontend runtime as a whole rather than to one module.
+Representative creation command:
+```bash
+npm run zova :init:sysMonkey
+```
+Representative file location:
+```text
+src/front/config/monkeySys.ts
+```
+## Practical interpretation of the phases
+A representative lifecycle interpretation is:
+- `moduleLoading` for early module registration work such as route-table contribution
+- `moduleLoaded` once the module is available to the broader system
+- `configLoaded` when module or project config still needs inspection or mutation before readiness
+- `sysInitialize` for the earliest system-wide initialization
+- `sysInitialized` when other modules should be able to react to initialized system state
+- `sysReady` for long-lived runtime behavior that depends on the system being fully operational
+- `sysClose` for teardown of system-level resources
+## When to use system startup
+Use system startup when:
+- the behavior should not be repeated per app instance or per request
+- config-loading order matters at the system level
+- module registration or route-table wiring must happen before app startup flows begin
+- the concern belongs to long-lived runtime setup rather than page/app initialization
+## Relationship to environment/config selection
+System startup behavior still runs under a selected mode, appMode, and flavor.
+Read this guide together with [Environment and Config Guide](/frontend/environment-config-guide).
+## Relationship to app startup
+This guide is the first half of the frontend startup story, and the system-level companion to [App Startup Guide](/frontend/app-startup-guide).
+Use this guide for long-lived runtime setup such as route-table and config wiring, then read the app guide for the router-readiness and first-screen behavior that runs after that system wiring is in place.
+The legacy system-start docs used route registration as the clearest example boundary:
+- `moduleLoading` as an early point for registering module routes into the system routing table
+- app startup only after that lower-level system wiring is in place
+That distinction is especially important in SSR-capable systems, where app lifecycles can repeat while system-level route and config wiring should not.
+A practical reading sequence is:
+1. [Environment and Config Guide](/frontend/environment-config-guide)
+2. this page for system wiring
+3. [App Startup Guide](/frontend/app-startup-guide) for router/guard readiness
+4. [Page Route Guide](/frontend/page-route-guide) for shell/layout behavior
+## Implementation checks for system-startup changes
+When editing frontend lifecycle behavior, ask:
+1. is this a system concern or an app concern?
+2. does it need `configLoaded`, `moduleLoading`, or one of the `sys*` phases?
+3. should the logic live in module mainSys, module monkeySys, or sys monkey?
+4. does SSR change whether the code should be system-scoped instead of request-scoped?
+That helps AI place lifecycle logic in the correct layer instead of mixing system and app startup behavior together.

package/cabloy-docs/frontend/theme-guide.md ADDED Viewed

@@ -0,0 +1,154 @@
+# Theme Guide
+This guide explains how themes work in Zova within the Cabloy monorepo.
+## Why Zova themes matter
+Zova provides a theme system that is independent of any one UI library and supports theme switching out of the box.
+This matters because Cabloy needs a frontend architecture that can survive across different edition-specific UI stacks.
+## Two theme dimensions
+Two major dimensions of theme switching are:
+- **light/dark mode** with `light`, `dark`, and `auto`
+- **brand style** changes, often centered on brand colors but not limited to them
+This is an important design point: theming is not only dark-mode toggling. It is also a broader token and branding system.
+## `$theme`
+Zova injects `$theme` into `BeanBase`, so any bean instance can access theme state through `this.$theme`.
+Important properties include:
+- `name`
+- `darkMode`
+- `dark`
+- `token`
+Representative method:
+- `toggleDark`
+This is also why `$theme` and `$token` should be read together rather than as unrelated APIs.
+## Tokens as the contract between style and theme
+A token is the design-value layer that sits between CSS-in-JS styles and the active theme.
+A practical split is:
+- styles decide where values are consumed
+- tokens define the reusable design vocabulary
+- themes provide the concrete active token values
+That is why token-driven styling scales better than scattering hardcoded values across many pages and components.
+## Why token shape is shared in architecture but not fixed across UI libraries
+The token architecture is shared across Cabloy Basic and Cabloy Start, but the exact token shape can still vary.
+A practical distinction is:
+- the idea of token-driven styling is shared
+- the concrete token fields can still reflect the active UI library, component conventions, or project theme design
+This matters because edition-sensitive UI differences should not be mistaken for a different styling architecture.
+## Theme beans
+Each UI library provides a default theme bean, and theme beans are responsible for returning token values and deeper theme customizations.
+A practical lifecycle is:
+- theme bean code defines the concrete token payload
+- the active theme exposes that payload through `$theme.token`
+- pages and components consume those values through `$token`
+- runtime theme switching swaps the active token set without changing the broader styling architecture
+Representative pattern:
+```typescript
+@Theme()
+export class ThemeDefault implements IThemeBase {
+  async apply({ dark }: IThemeApplyParams) {
+    const token: ThemeToken = {
+      color: {
+        primary: '#1976d2',
+      },
+      var: {
+        borderColor: '#297acc',
+      },
+      component: {
+        page: {
+          background: dark ? '#121212' : '#fff',
+          color: dark ? '#fff' : '#000',
+        },
+      },
+    };
+    return { token };
+  }
+}
+```
+## Custom themes
+Custom theme beans can also be created by following the same pattern.
+That makes the theme system programmable rather than locked to a small fixed set of predefined skins.
+## Consume tokens in pages and components
+In practice, pages and components usually should not hardcode design values when those values belong to the theme vocabulary.
+A practical rule is:
+- use `$token` when a page or component is consuming theme-defined design values
+- use `$theme` when code needs to inspect or switch the current theme state itself
+This keeps token consumption separate from theme-state control while still letting both surfaces work together.
+## Runtime theme switching
+Representative usage pattern:
+```typescript
+this.$theme.name =
+  this.$theme.name === 'home-theme:default' ? 'home-theme:orange' : 'home-theme:default';
+```
+This illustrates that theme switching is an ordinary part of the application model and can be driven directly from code.
+A useful distinction is:
+- dark-mode switching changes the light/dark state of the active theme flow
+- brand-theme switching changes which named theme provides the token set
+- both still work through the same `$theme` and token architecture
+## What stays shared across editions
+Across Cabloy Basic and Cabloy Start, the core theme architecture remains shared:
+- theme beans provide token values
+- pages and components consume those values through `$token`
+- runtime code can inspect or switch theme state through `$theme`
+- dark mode and brand-theme switching stay part of the same model
+What may still vary by edition or UI library is:
+- the exact token shape
+- concrete default token values
+- integration details for a specific component library or visual system
+## Implementation checks for theme-related changes
+When changing theme behavior, ask:
+1. should this change live in a theme bean instead of inlining colors into components?
+2. is the change about dark mode, brand style, or both?
+3. should the change be token-driven instead of component-specific?
+4. does the active edition change the UI component library while preserving the same theme architecture?
+That helps keep theme work scalable and edition-aware.

package/cabloy-docs/frontend/zod-guide.md ADDED Viewed

@@ -0,0 +1,161 @@
+# Zod Guide
+## Why Zod matters in Zova
+Zova uses Zod as the schema foundation for typed page params, typed page query handling, and other frontend schema-driven behaviors.
+That matters because route-driven data should not be handled as raw strings once the framework already provides a stronger schema model.
+## Zova’s `z` wrapper
+Zova encapsulates Zod and provides an enhanced `z` surface.
+The goal is not only generic schema validation. The goal is schema validation that fits Zova’s routing and page-controller model.
+## Basic schema usage
+Representative examples include:
+```typescript
+const name = z.string();
+const age = z.number();
+const enabled = z.boolean();
+```
+Optional values and defaults are also first-class:
+```typescript
+const name = z.string().optional();
+const title = z.string().optional().default('');
+```
+## Common object schemas
+Representative object schema:
+```typescript
+const user = z.object({
+  name: z.string().optional(),
+  age: z.number().optional(),
+});
+```
+This is the foundation used by typed page params and page query support.
+## Type coercion
+One of the most important Zova enhancements is automatic coercion.
+This matters because route params and query values often arrive as strings, while the page controller wants the final typed values.
+That is why schemas such as:
+```typescript
+z.number();
+```
+can still support route-driven values more naturally than raw parsing code.
+## Boolean coercion
+Zova also applies special handling for boolean-like string values.
+Representative false-like values include:
+- `'false'`
+- `'undefined'`
+- `'null'`
+- `'0'`
+This makes route/query handling more practical in real app flows.
+## JSON object support in query
+Zova can support JSON-shaped data in query values.
+Representative pattern:
+```typescript
+export const QuerySchema = z.object({
+  user: z
+    .object({
+      name: z.string(),
+      age: z.number(),
+    })
+    .optional(),
+});
+```
+That allows page code to work with typed nested query objects instead of flattening everything into ad hoc string logic.
+## Array support in query
+Zova can also support array-shaped query values.
+Representative pattern:
+```typescript
+export const QuerySchema = z.object({
+  colors: z.array(z.string()).optional(),
+});
+```
+This is especially useful for filter-like or multi-select page behavior.
+## Representative page-oriented schemas
+A page can combine param and query schemas so route-driven input stays typed end to end.
+Representative patterns:
+```typescript
+export const ControllerPageCounterSchemaParams = z.object({
+  id: z.number().optional().default(0),
+});
+export const ControllerPageCounterSchemaQuery = z.object({
+  user: z
+    .object({
+      name: z.string(),
+      age: z.number(),
+    })
+    .optional(),
+  colors: z.array(z.string()).optional(),
+});
+```
+Representative page access pattern:
+```typescript
+class ControllerPageCounter {
+  render() {
+    return (
+      <div>
+        <div>id: {this.$params.id}</div>
+        <div>name: {this.$query.user?.name}</div>
+        <div>colors: {this.$query.colors?.join(',')}</div>
+      </div>
+    );
+  }
+}
+```
+## Relationship to page params and query
+Zod is most often encountered in the frontend docs through:
+- [Page Params Guide](/frontend/page-params-guide)
+- [Page Query Guide](/frontend/page-query-guide)
+Those guides explain how the schemas are attached to routing behavior, while this guide focuses on the schema model itself.
+## Implementation checks for schema-driven route-state changes
+When editing Zova route-driven page behavior, ask:
+1. should this page value be expressed through a Zod schema instead of manual parsing?
+2. does the schema need coercion, default values, nested objects, or arrays?
+3. is this concern really page params, page query, or a broader reusable schema?
+4. should the typed schema be shared rather than duplicated across pages?
+That helps AI keep frontend routing behavior aligned with Zova’s schema-first page model.

package/cabloy-docs/fullstack/edition-collaboration-differences.md ADDED Viewed

@@ -0,0 +1,61 @@
+# Edition Differences in Fullstack Collaboration
+This page makes the Basic/Start differences in the collaboration loop explicit.
+## Why this page matters
+Most Cabloy architecture can be explained once.
+But the fullstack collaboration path becomes confusing if docs or AI systems silently reuse Cabloy Basic assumptions inside Cabloy Start workflows.
+This page exists to keep those differences visible.
+## Shared collaboration model
+Both editions share the same broad collaboration loop:
+- Vona provides backend runtime and OpenAPI-facing contract output
+- Zova provides frontend application structure and generated metadata
+- root scripts and CLI commands coordinate build, generation, and verification
+## Where the editions diverge
+The most important differences show up in:
+- frontend UI stack assumptions
+- frontend flavor names
+- frontend module composition
+- private value-add content in Cabloy Start
+- potentially different generated output paths or integration details
+## Cabloy Basic
+In the current public monorepo, Basic examples commonly align with:
+- DaisyUI + TailwindCSS oriented frontend assumptions
+- Basic-specific Zova flavors such as `cabloyBasicAdmin` and `cabloyBasicWeb`
+## Cabloy Start
+In the sibling private repo, Start examples commonly align with:
+- Vuetify-oriented frontend assumptions
+- Start-specific Zova flavors such as `cabloyStartAdmin` and `cabloyStartWeb`
+## Safe documentation and AI rule
+When documenting or automating a fullstack collaboration flow:
+1. explain the shared model once
+2. detect the active edition
+3. branch only where the workflow actually diverges
+4. verify flavor names and generated output paths in the active repo
+## Practical implications for edition-aware workflow decisions
+This rule prevents a common failure mode:
+- the model understands the shared architecture correctly
+- but gives the wrong operational example because it assumes the wrong edition
+That is exactly the kind of mistake good fullstack docs should prevent.

package/cabloy-docs/fullstack/frontend-metadata-to-backend.md ADDED Viewed

@@ -0,0 +1,64 @@
+# Frontend Metadata Back to Backend
+This page documents the reverse direction of Cabloy’s fullstack collaboration loop: frontend-generated metadata that improves backend-side development and tooling.
+## Why this path matters
+The fullstack collaboration loop in Cabloy is not one-way.
+For the forward contract-bridge direction from backend OpenAPI to frontend consumption, also see [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk).
+The backend does not only feed the frontend through OpenAPI. The frontend also generates information that can improve backend-side type hints and integration confidence.
+This is one of the unusual strengths of the Cabloy monorepo model.
+## What the frontend can generate
+The current script surface shows that Zova can generate metadata and type information for areas such as:
+- routes
+- components
+- icons
+- REST-related generated output
+That generated information can then be consumed by backend-side fullstack workflows and developer tooling.
+## Why this is valuable
+In a separated-repo world, this information is often harder to share, easier to stale, and more annoying for AI to rediscover.
+In the monorepo, the frontend-generated metadata can stay close to:
+- the frontend source that produced it
+- the backend workflows that consume or rely on it
+- the docs and skills that explain the collaboration path
+## Typical collaboration pattern
+A practical collaboration loop often looks like this:
+1. define or update frontend routes/components/icons
+2. regenerate the relevant frontend metadata or REST/type output
+3. let backend-side workflows, docs, or fullstack integration logic consume the generated information
+4. verify the collaboration path still matches the active edition
+## Edition awareness
+This path is especially sensitive to edition differences because Basic and Start do not expose the same frontend module and UI shape.
+So when AI reasons about frontend-generated metadata, it should verify:
+- which repo is active
+- which flavor is active
+- which generated output belongs to that edition
+## Implementation checks for frontend-metadata changes
+When changing frontend structural resources such as routes or components, ask:
+1. does metadata need regeneration?
+2. does backend-side tooling or fullstack integration rely on that metadata?
+3. is this a Basic-specific or Start-specific workflow?
+4. should the next action be generation and verification rather than only source edits?
+That keeps the reverse contract loop visible instead of accidental.