cabloy 5.1.49 → 5.1.51

package/cabloy-docs/editions/cabloy-start.md

@@ -0,0 +1,24 @@
+# Cabloy Start
+
+Cabloy Start is a sibling private repository that shares the Cabloy fullstack direction while intentionally differing from Cabloy Basic.
+
+## Repository marker
+
+The Cabloy Start root contains:
+
+- `__CABLOY_START__`
+
+Use that marker before choosing examples, UI assumptions, or automation behavior.
+
+## Typical role
+
+Use Cabloy Start as the edition-aware target when work depends on:
+
+- Vuetify-specific frontend workflows
+- Cabloy Start flavor names in frontend scripts
+- modules that exist in the private Start repository but not in Basic
+- private value-add project composition
+
+## Relationship to this docs site
+
+This unified docs site treats Cabloy Start as a supported edition, not as a clone of Cabloy Basic. Shared architecture should remain shared, but any Start-specific script, module path, or UI workflow must be labeled explicitly.

package/cabloy-docs/editions/detection.md

@@ -0,0 +1,31 @@
+# Edition Detection
+
+Edition detection is a first-class requirement for documentation, rules, and skills.
+
+## Repository markers
+
+Use these root markers:
+
+- `__CABLOY_BASIC__` → Cabloy Basic
+- `__CABLOY_START__` → Cabloy Start
+
+## Why this matters
+
+The two editions share many concepts but differ in important operational details, especially around:
+
+- frontend UI library assumptions
+- flavor-specific frontend scripts
+- module availability
+- value-add project content in the private Start repository
+
+If an agent skips edition detection, it may generate the wrong instructions, recommend the wrong module, or use the wrong UI stack.
+
+## Recommended rule for skills and repo guidance
+
+Before suggesting a cross-stack implementation path:
+
+1. check the repository marker
+2. verify the relevant root scripts or package scripts
+3. only then choose the edition-specific example or workflow branch
+
+When neither marker is present, fall back to code inspection and ask the user before making a strong edition-specific assumption.

package/cabloy-docs/editions/overview.md

@@ -0,0 +1,44 @@
+# Editions Overview
+
+Cabloy currently needs to support two related but distinct repositories:
+
+- **Cabloy Basic**
+- **Cabloy Start**
+
+They share the same core architectural direction, but they are not interchangeable.
+
+## Shared core
+
+Both editions use the Cabloy fullstack model built around:
+
+- Vona as the backend framework
+- Zova as the frontend framework
+- root-level `npm run vona` and `npm run zova` entrypoints
+- CLI-backed workflows for generation, refactoring, metadata, and verification
+
+## Why the editions differ
+
+The editions exist to support different product and distribution goals.
+
+### Cabloy Basic
+
+- public repository
+- baseline fullstack reference implementation
+- current default examples in this public monorepo
+
+### Cabloy Start
+
+- sibling private repository
+- created from `npm create cabloy`
+- uses a different UI strategy centered on Vuetify
+- contains different Vona/Zova modules and value-add project structure
+
+## Documentation rule
+
+Write shared explanations once. Only split or annotate when a workflow changes because of:
+
+- UI library assumptions
+- frontend flavor names
+- different modules or assets
+- private-value product boundaries
+- edition-specific scripts or generated outputs

package/cabloy-docs/frontend/api-guide.md

@@ -0,0 +1,93 @@
+# API Guide
+
+This guide explains how `$api` works in Zova within the Cabloy monorepo.
+
+## What `$api` is for
+
+Zova provides business-oriented API services on top of lower-level request access.
+
+That means frontend code does not need to scatter raw request details everywhere. Instead, API calls can be encapsulated into named services that match business intent.
+
+## Create an API service
+
+Example: create an API service named `menu` in module `demo-student`.
+
+```bash
+npm run zova :create:bean api menu -- --module=demo-student
+```
+
+## API definition
+
+Representative pattern:
+
+```typescript
+export interface ApiMenuRetrieveMenusResult {
+  title: string;
+  link: string;
+}
+
+@Api()
+export class ApiMenu extends BeanApiBase {
+  retrieveMenus() {
+    return this.$fetch.get<any, ApiMenuRetrieveMenusResult>('/home/base/menu/');
+  }
+}
+```
+
+This shows the intended layering clearly:
+
+- `$fetch` handles the lower-level request
+- the API service exposes a business-oriented method such as `retrieveMenus()`
+
+API is also one of the core module-scope resource categories; see [Module Scope](/frontend/module-scope).
+
+## Using the API through module scope
+
+Typical pattern:
+
+```typescript
+class ControllerTest {
+  async retrieveMenus() {
+    const menus = await this.scope.api.menu.retrieveMenus();
+  }
+}
+```
+
+## Cross-module API access
+
+Cross-module usage is also supported through scope injection.
+
+Representative pattern:
+
+```typescript
+@UseScope()
+$$scopeDemoStudent: ScopeModuleDemoStudent;
+
+const menus = await this.$$scopeDemoStudent.api.menu.retrieveMenus();
+```
+
+## Built-in `$api` access
+
+The framework also supports accessing certain API services through `this.$api` on bean instances.
+
+Representative pattern:
+
+```typescript
+const menus = await this.$api.homeBaseMenu.retrieveMenus({
+  params: { publicPath: '' },
+});
+```
+
+## Implementation checks for frontend data-access changes
+
+When adding frontend data access, avoid jumping straight from UI code to ad hoc request logic.
+
+A better default is:
+
+1. decide whether the request belongs in a named API service
+2. create or reuse that API service
+3. let pages, components, or models consume the API service instead of duplicating request details
+
+That keeps the frontend code more business-oriented and easier to evolve.
+
+When the backend contract is not ready yet, a temporary frontend-side mock route may be the right bridge; see [Mock Guide](/frontend/mock-guide).

package/cabloy-docs/frontend/api-schema-guide.md

@@ -0,0 +1,43 @@
+# API Schema Guide
+
+This page expands the legacy `$apiSchema` placeholder into a practical guidance page for the new docs site.
+
+## What `$apiSchema` represents
+
+`$apiSchema` is the schema-oriented layer of the server-data model.
+
+While `$api` and generated SDKs focus on calling backend operations, `$apiSchema` focuses on the API metadata itself.
+
+That matters when frontend behavior needs to be driven by schema, not just by returned values.
+
+## Why schema access matters
+
+In the Cabloy/Zova model, schema metadata can support higher-level frontend behavior such as:
+
+- validation
+- automatic form rendering
+- automatic field behavior
+- metadata-driven UI logic
+
+This is one reason the server-data thread in Zova is more powerful than a plain request library.
+
+## How to think about `$apiSchema`
+
+Use `$apiSchema` when the frontend needs to inspect what the backend contract says, not just call the backend endpoint.
+
+That usually means the problem is shifting from “fetch data” to “use metadata to drive behavior.”
+
+## Read together with
+
+Use this page together with:
+
+- [Server Data](/frontend/server-data)
+- [OpenAPI SDK Guide](/frontend/openapi-sdk-guide)
+- [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk)
+- [SDK Guide](/frontend/sdk-guide)
+
+## Implementation checks for schema-driven UI changes
+
+When asked to build dynamic forms, metadata-driven UI, or schema-aware validation, consider whether the right source is `$apiSchema` rather than hand-authored frontend-only field definitions.
+
+That keeps the frontend closer to backend truth and reduces duplicate configuration.

package/cabloy-docs/frontend/app-startup-guide.md

@@ -0,0 +1,185 @@
+# App Startup Guide
+
+## Why app startup matters
+
+In Zova, application startup is a structured lifecycle rather than a single opaque bootstrap step.
+
+That matters because routing, guards, business initialization, and extension hooks often need to run at different startup phases.
+
+## App startup vs system startup
+
+App startup is not the same as system startup.
+
+In SSR scenarios especially, app startup can be request-scoped, while system startup is not.
+
+This guide focuses on the application lifecycle after the lower-level system wiring is already in place. For system-level lifecycle hooks such as route registration and config loading, see [System Startup Guide](/frontend/system-startup-guide).
+
+## App startup timings
+
+Zova provides three main app startup timings:
+
+- `appInitialize`
+- `appInitialized`
+- `appReady`
+
+These timings allow business modules to run initialization logic at the earliest appropriate stage.
+
+## App shutdown timing
+
+App shutdown is represented by:
+
+- `appClose`
+
+## Module load timings
+
+The app lifecycle also intersects with module loading:
+
+- `moduleLoading`
+- `moduleLoaded`
+
+These allow module-aware logic to participate before or after the app becomes fully ready.
+
+## Hook response scenarios
+
+Zova supports several implementation locations for these hooks:
+
+- **Module Main** in a module-local main file
+- **Module Monkey** in a module-local monkey file
+- **App Monkey** in the project frontend config area
+
+This makes startup behavior extensible at both module and project levels.
+
+## Hook interface model
+
+Different hooks correspond to different interfaces depending on where they are implemented.
+
+The important architectural point is not the exact interface matrix alone, but that startup behavior is typed and structured rather than improvised.
+
+A compact mental model is:
+
+- **Module Main** handles a module’s own loading lifecycle
+- **Module Monkey** lets a module participate in app-wide hook timings
+- **App Monkey** lets the project frontend config layer participate in the same hook system
+
+## Module Main
+
+A module can provide its own main lifecycle entrypoints.
+
+Representative creation command:
+
+```bash
+npm run zova :init:main demo-student
+```
+
+Representative pattern:
+
+```typescript
+export class Main extends BeanSimple implements IModuleMain {
+  async moduleLoading() {}
+  async moduleLoaded() {}
+}
+```
+
+## Module Monkey
+
+A module can also provide broader app hook behavior through a monkey entry.
+
+Representative creation command:
+
+```bash
+npm run zova :init:monkey demo-student
+```
+
+Representative pattern:
+
+```typescript
+export class Monkey
+  extends BeanSimple
+  implements
+    IMonkeyModule,
+    IMonkeyAppInitialize,
+    IMonkeyAppInitialized,
+    IMonkeyAppReady,
+    IMonkeyAppClose
+{
+  async moduleLoading(_module: IModule) {}
+  async moduleLoaded(_module: IModule) {}
+  async appInitialize() {}
+  async appInitialized() {}
+  async appReady() {}
+  async appClose() {}
+}
+```
+
+## App Monkey
+
+Project-level app lifecycle customization can be placed in the frontend config area.
+
+This is useful when startup behavior belongs to the application as a whole rather than to one module.
+
+Representative creation command:
+
+```bash
+npm run zova :init:appMonkey
+```
+
+Representative file location:
+
+```text
+src/front/config/monkey.ts
+```
+
+## Practical interpretation of the phases
+
+A useful rule of thumb is:
+
+- use the earliest timing that still satisfies the need
+- reserve later timings for behavior that depends on earlier framework or module setup already being finished
+
+That keeps initialization extensible without creating unnecessary ordering coupling.
+
+A representative lifecycle interpretation is:
+
+- `appInitialize` for the earliest app-level service setup
+- `appInitialized` when other modules should be able to react to the initialized state
+- `appReady` for behavior that depends on the app becoming operational, such as final router-facing readiness
+- `appClose` for teardown and listener cleanup
+
+## Relationship to routing and guards
+
+This page is the second half of the startup story: once system startup has registered routes and loaded config, app startup makes router services, guards, and first-screen navigation operational.
+
+Startup timing is closely related to frontend routing and guards, because route services and route-guard behavior often need to be initialized before the app is considered ready.
+
+The legacy startup docs explicitly used the router module as the core example:
+
+- `appInitialize` as an early route-guard service setup point
+- `appInitialized` as the point where route-guard events can begin involving other business modules
+- `appReady` as the point where Vue Router can be injected and initial navigation can run
+- `appClose` as the teardown point for route-guard listeners
+
+Read this guide together with [Navigation Guards Guide](/frontend/navigation-guards-guide) when route lifecycle is involved.
+
+A practical reading sequence is:
+
+1. [System Startup Guide](/frontend/system-startup-guide)
+2. this page for router/guard readiness
+3. [Page Route Guide](/frontend/page-route-guide)
+4. [Navigation Guards Guide](/frontend/navigation-guards-guide)
+
+## Relationship to environment/config selection
+
+The chosen scripts, mode, appMode, and flavor determine which config and env values are active while startup hooks run.
+
+Read this guide together with [Environment and Config Guide](/frontend/environment-config-guide).
+
+## Implementation checks for app-startup changes
+
+When editing frontend startup behavior, ask:
+
+1. does this logic belong to app startup or system startup?
+2. what is the earliest safe hook timing for this behavior?
+3. should the logic live in module main, module monkey, or app monkey?
+4. does the behavior depend on routing, SSR, or environment-specific config already being ready?
+
+That helps AI place initialization logic correctly instead of pushing everything into one late-stage bootstrap step.

package/cabloy-docs/frontend/cli.md

@@ -0,0 +1,78 @@
+# Frontend CLI
+
+This guide explains how to use the Zova CLI in the Cabloy monorepo.
+
+## Why the CLI matters
+
+Zova provides a large number of CLI commands for generating code skeletons and running frontend workflows.
+
+For AI-assisted development, the CLI should be the default starting point whenever a generator or refactor command already exists.
+
+## Example
+
+Create a `component` named `test` in module `demo-student`:
+
+```bash
+npm run zova :create:component test -- --module=demo-student
+```
+
+## Command discovery pattern
+
+Zova commands follow a consistent discovery model.
+
+### 1. List all command groups and commands
+
+```bash
+npm run zova :
+```
+
+### 2. List commands for a specific group
+
+```bash
+npm run zova :create
+```
+
+### 3. Inspect help for one command
+
+```bash
+npm run zova :create:component --help
+```
+
+## High-value command families
+
+From the current source tree, the most useful Zova command families for day-to-day development are:
+
+- `bin:*`
+- `create:*`
+- `init:*`
+- `refactor:*`
+- `tools:*`
+- `openapi:*`
+
+Typical use cases include:
+
+- scaffold suites, modules, pages, components, mocks, and beans
+- initialize frontend config, locale, constants, assets, and typing helpers
+- run focused refactors such as page query, page params, component props, generic component updates, and related migrations
+- generate OpenAPI-related output
+- refresh metadata and dependency-related output
+
+## VS Code menus and the CLI
+
+In practice, Zova workflows can be reached from two surfaces:
+
+- VS Code menus for discovery and ergonomics
+- the CLI for explicit, scriptable command execution
+
+A practical rule is:
+
+- use menus when you want to discover the available workflow quickly in the editor
+- use the CLI when you want reproducible automation, explicit command history, or terminal-first documentation
+
+These are not competing workflow systems. They are two entrypoints to the same underlying Zova command families.
+
+## Practical workflow rule
+
+When creating or refactoring frontend code, inspect `npm run zova :` or the relevant command family first, prefer the matching generator or refactor command, inspect the generated or transformed output, and only then make minimal follow-up edits.
+
+This keeps frontend work aligned with Zova conventions and avoids avoidable manual scaffolding.

package/cabloy-docs/frontend/component-guide.md

@@ -0,0 +1,105 @@
+# Component Guide
+
+This guide explains how components work in Zova within the Cabloy monorepo.
+
+## What a component means in Zova
+
+A Zova component is not only a reusable render unit. It is also part of the controller-oriented architecture that gives Zova its specific coding style.
+
+That means component design is closely tied to:
+
+- controller-based logic organization
+- TSX rendering
+- IOC-friendly instance access
+- async-friendly module loading
+- CSS-in-JS styling through the same controller-oriented architecture
+
+For the practical styling decision map around local `$style`, dedicated style beans, shared/global styles, and token/theme surfaces, also see [CSS-in-JS Guide](/frontend/css-in-js-guide).
+
+## Create a component
+
+Example: create a component named `card` in module `demo-student`.
+
+```bash
+npm run zova :create:component card -- --module=demo-student
+```
+
+## Controller definition
+
+Representative component controller shape:
+
+```typescript
+@Controller()
+class ControllerCard extends BeanControllerBase {
+  protected render() {
+    return null;
+  }
+}
+```
+
+## Component wrapper
+
+Zova automatically creates a wrapper component for each component.
+
+Representative example:
+
+- component: `card`
+- wrapper: `ZCard`
+
+The `Z` prefix is useful because it makes framework components easy to identify quickly inside TSX.
+
+## Use a component
+
+Representative usage pattern:
+
+```typescript
+import { ZCard } from 'zova-module-demo-student';
+
+class RenderPageCounter {
+  render() {
+    return <ZCard />;
+  }
+}
+```
+
+## Async loading behavior
+
+Component wrappers can also participate in asynchronous loading behavior automatically.
+
+This matters because the wrapper is not just a naming convenience. It is part of how Zova turns modular code into practical runtime behavior.
+
+## Reference the component instance
+
+Instead of relying on template refs in the usual Vue style, Zova prefers direct access to the component controller instance.
+
+Representative pattern:
+
+```typescript
+import type { ControllerCard } from 'zova-module-demo-student';
+import { ZCard } from 'zova-module-demo-student';
+
+class RenderPageCounter {
+  cardRef: ControllerCard;
+
+  render() {
+    return (
+      <ZCard
+        controllerRef={ref => {
+          this.cardRef = ref;
+        }}
+      />
+    );
+  }
+}
+```
+
+## Practical implications for component implementation
+
+When working on Zova components, do not automatically fall back to generic Vue component habits.
+
+A better default is:
+
+1. use the component generator
+2. preserve the wrapper-based usage model
+3. treat controller access as the primary instance-reference pattern
+4. remember that wrapper behavior and async loading are part of the framework design

package/cabloy-docs/frontend/component-props-guide.md

@@ -0,0 +1,97 @@
+# Component Props Guide
+
+This guide explains how component props work in Zova within the Cabloy monorepo.
+
+## Why Zova props feel different
+
+In Zova, component design does not force a hard separation between `Props`, `Emits`, and `Slots` in the same way many Vue codebases do.
+
+Zova uses a more unified approach centered on component props, which makes the programming model more concise and TypeScript-friendly.
+
+## Add props support
+
+Example: add props support to component `card`.
+
+```bash
+npm run zova :refactor:componentProps card -- --module=demo-student
+```
+
+## Define props
+
+Representative pattern:
+
+```typescript
+import { ISlot } from 'zova';
+
+export interface ControllerCardProps {
+  content?: string;
+  onReset?: () => void;
+  slotHeader?: ISlot;
+  slotDefault?: (name: string) => VNode;
+}
+```
+
+This is important because the props contract can describe ordinary values, callbacks, and slot-like behavior in one consistent shape.
+
+## Default values
+
+Representative pattern:
+
+```typescript
+class ControllerCard {
+  static $propsDefault = {
+    content: 'no content',
+  };
+}
+```
+
+## Use props in the controller
+
+Zova injects `$props` into the controller base class.
+
+Representative pattern:
+
+```typescript
+class ControllerCard {
+  render() {
+    return (
+      <div>
+        <div>{this.$props.slotHeader?.()}</div>
+        <div>{this.$slotDefault?.('tom')}</div>
+        <div>{this.$props.content}</div>
+        <button onClick={() => this.$props.onReset?.()}>Reset</button>
+      </div>
+    );
+  }
+}
+```
+
+## Pass props to child components
+
+Representative pattern:
+
+```typescript
+<ZCard
+  content="custom content"
+  onReset={() => {
+    console.log('onReset is invoked');
+  }}
+  slotHeader={() => {
+    return <div>custom header</div>;
+  }}
+  slotDefault={name => {
+    return <div>{name}</div>;
+  }}
+/>
+```
+
+## Practical implications for component API design
+
+When creating or refactoring Zova components, do not automatically impose a generic Vue component API style.
+
+A better default is:
+
+1. use the Zova refactor command to add the props skeleton
+2. keep the props contract explicit and typed
+3. treat props as the main contract surface for values, callbacks, and slot-like behavior
+4. preserve the controller-oriented way of consuming props inside the component