cabloy 5.1.50 → 5.1.52

package/cabloy-docs/frontend/openapi-sdk-guide.md

@@ -0,0 +1,102 @@
+# OpenAPI SDK Guide
+
+This guide explains how the Zova OpenAPI SDK workflow fits into the Cabloy monorepo.
+
+## Why OpenAPI SDK matters
+
+Zova can generate frontend client SDKs from backend Swagger/OpenAPI metadata.
+
+This is one of the most important fullstack links in Cabloy, because it lets backend contracts drive frontend integration more directly and reduces redundant hand-written API code.
+
+## This page’s role in the contract loop
+
+A practical split is:
+
+- backend docs explain contract authoring and OpenAPI emission
+- the fullstack bridge doc explains how emitted OpenAPI becomes generated frontend SDKs
+- this page explains frontend configuration, generation, and usage choices after that contract reaches Zova
+
+For the bridge view, also see [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk).
+
+For the broader frontend contract-consumption ladder, also see [Server Data](/frontend/server-data), [API Schema Guide](/frontend/api-schema-guide), and [SDK Guide](/frontend/sdk-guide).
+
+## Initialize OpenAPI config
+
+Example: initialize OpenAPI config for module `demo-student`.
+
+```bash
+npm run zova :openapi:config demo-student
+```
+
+## Module-level config
+
+Each module can control which backend operations belong to it.
+
+Representative idea:
+
+- configure matching rules in the module OpenAPI config
+- keep API ownership aligned with the module boundary
+
+This modular split matters because Cabloy does not treat the frontend as one flat API client surface.
+
+## Project-level config
+
+The project-level OpenAPI config defines where Swagger/OpenAPI metadata is downloaded from.
+
+Representative use case:
+
+- point the frontend project at the correct backend Swagger JSON source
+- then generate only the SDK slices needed by the current module
+
+## Generate the SDK
+
+Example: generate OpenAPI-based frontend services for module `demo-student`.
+
+```bash
+npm run zova :openapi:generate demo-student
+```
+
+## Build the rest-contract output
+
+For Cabloy Basic, representative contract-build commands include:
+
+```bash
+cd zova && npm run build:rest:cabloyBasicAdmin
+cd zova && npm run build:rest:cabloyBasicWeb
+```
+
+This matters because SDK generation and rest-contract build steps are related, but not identical.
+
+## Important convention
+
+One important rule is that a module should usually standardize on one API-service creation style.
+
+That means a module should generally choose between:
+
+- manually authored API services
+- OpenAPI-generated API services
+
+Mixing both styles carelessly inside one module makes the codebase harder to reason about.
+
+## Relationship to backend authoring
+
+This page is about frontend consumption and generation, not backend contract authoring.
+
+If the backend contract itself changes, first inspect or update the backend contract pages such as:
+
+- [Controller Guide](/backend/controller-guide)
+- [OpenAPI Guide](/backend/openapi-guide)
+- [DTO Guide](/backend/dto-guide)
+
+Then return to this page for the frontend regeneration step.
+
+## Implementation checks for SDK regeneration decisions
+
+When evaluating a request that depends on backend contracts, ask:
+
+1. is this module already using generated OpenAPI services?
+2. should the SDK be regenerated instead of hand-writing a new frontend service?
+3. is the real source of truth the backend OpenAPI metadata rather than the current frontend code?
+4. is the current task backend authoring, bridge regeneration, or frontend consumption?
+
+That helps keep frontend integration aligned with the backend contract.

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

@@ -0,0 +1,223 @@
+# Page Guide
+
+This guide explains how pages work in Zova within the Cabloy monorepo.
+
+## What a page means in Zova
+
+A Zova page is not just a route target with a template attached.
+
+The page model is built around a controller-oriented structure that combines:
+
+- reactive state
+- TSX-based render logic
+- IOC-friendly composition
+- CSS-in-JS styling
+
+That combination is one of the clearest examples of Zova’s overall design philosophy.
+
+## Create a page
+
+Example: create a page named `counter` in module `demo-student`.
+
+```bash
+npm run zova :create:page counter -- --module=demo-student
+```
+
+## Route path generation
+
+Zova automatically derives the page path from the module and page names.
+
+Representative example:
+
+- module: `demo-student`
+- page: `counter`
+- generated page path: `/demo/student/counter`
+
+This matters because the framework already has conventions for route structure. AI should reuse those conventions rather than inventing unrelated paths.
+
+## Controller definition
+
+Representative page controller shape:
+
+```typescript
+@Controller()
+class ControllerPageCounter extends BeanControllerPageBase {
+  protected render() {
+    return null;
+  }
+}
+```
+
+## Add state
+
+Representative reactive state pattern:
+
+```typescript
+class ControllerPageCounter {
+  count: number = 0;
+
+  increment() {
+    this.count++;
+  }
+
+  decrement() {
+    this.count--;
+  }
+}
+```
+
+## Add render logic
+
+Representative TSX render pattern:
+
+```typescript
+class ControllerPageCounter {
+  protected render() {
+    return (
+      <div>
+        <div>count: {this.count}</div>
+        <button onClick={() => this.increment()}>Increment</button>
+        <button onClick={() => this.decrement()}>Decrement</button>
+      </div>
+    );
+  }
+}
+```
+
+## Add style
+
+Zova pages can also attach style through built-in CSS-in-JS support.
+
+For choosing among local `$style`, dedicated style beans, shared/global styles, and token/theme surfaces, also see [CSS-in-JS Guide](/frontend/css-in-js-guide).
+
+Representative pattern:
+
+```typescript
+class ControllerPageCounter {
+  cTextCenter: string;
+
+  protected async __init__() {
+    this.cTextCenter = this.$style({
+      textAlign: 'center',
+    });
+  }
+}
+```
+
+## Progressive code splitting
+
+As page complexity grows, Zova supports progressively splitting page logic into more files instead of forcing everything to remain in one controller file forever.
+
+A useful progression is:
+
+- **single-file** page structure for early-stage pages
+- **three-file** structure with controller, render, and style split out
+- **more-file** structure when additional render, style, or service beans are needed
+
+This matters because Zova encourages pages to start simple and then evolve into richer structures only when the business complexity justifies it.
+
+### Single-file to three-file
+
+A typical first step is keeping the page controller responsible for state while moving render and style into dedicated beans.
+
+#### Create the first render bean
+
+```bash
+npm run zova :refactor:firstRender page/counter -- --module=demo-student
+```
+
+Representative render bean shape:
+
+```typescript
+@Render()
+class RenderPageCounter extends BeanRenderBase {
+  public render() {
+    return (
+      <div class={this.cTextCenter}>
+        <div>count: {this.count}</div>
+        <button onClick={() => this.increment()}>Increment</button>
+        <button onClick={() => this.decrement()}>Decrement</button>
+      </div>
+    );
+  }
+}
+```
+
+#### Create the first style bean
+
+```bash
+npm run zova :refactor:firstStyle page/counter -- --module=demo-student
+```
+
+Representative style bean shape:
+
+```typescript
+@Style()
+class StylePageCounter extends BeanStyleBase {
+  cTextCenter: string;
+
+  protected async __init__() {
+    this.cTextCenter = this.$style({
+      textAlign: 'center',
+    });
+  }
+}
+```
+
+### More-file growth
+
+When the page continues to grow, you can keep splitting responsibilities instead of forcing one large controller or render bean to absorb everything.
+
+Representative refactors include:
+
+- additional render beans for larger UI regions
+- additional style beans for more isolated styling concerns
+- dedicated service beans when business state and behavior should move out of the page controller
+
+#### Create another render bean
+
+```bash
+npm run zova :refactor:anotherRender page/counter another -- --module=demo-student
+```
+
+#### Create another style bean
+
+```bash
+npm run zova :refactor:anotherStyle page/counter another -- --module=demo-student
+```
+
+#### Create a service bean for state management
+
+```bash
+npm run zova :create:bean service page/counter/counter -- --module=demo-student
+```
+
+Representative service bean shape:
+
+```typescript
+@Service()
+class ServiceCounter extends BeanBase {
+  count: number = 0;
+
+  increment() {
+    this.count++;
+  }
+
+  decrement() {
+    this.count--;
+  }
+}
+```
+
+These refactors are supported by Zova CLI commands rather than requiring a fully manual restructuring from scratch.
+
+## Practical implications for page implementation
+
+When generating or editing a Zova page, preserve the page/controller mental model instead of rewriting the code into a generic Vue single-file-component pattern.
+
+A better default is:
+
+1. use the Zova page generator
+2. keep state, render, and style inside the intended controller-oriented structure
+3. reuse existing routing and styling conventions
+4. verify whether the active edition changes page-level UI assumptions

package/cabloy-docs/frontend/page-params-guide.md

@@ -0,0 +1,87 @@
+# Page Params Guide
+
+This guide explains how typed page params work in Zova within the Cabloy monorepo.
+
+## Why page params support matters
+
+Zova enhances route params handling with typed support so page controllers can work with route parameters through a structured schema instead of ad hoc string access.
+
+## Add params support to a page
+
+Example: add params support for page `counter`.
+
+```bash
+npm run zova :refactor:pageParams counter -- --module=demo-student
+```
+
+## Add params schema
+
+Representative pattern:
+
+```typescript
+export const ControllerPageCounterSchemaParams = z.object({
+  id: z.number().optional().default(0),
+});
+```
+
+This is more than a type annotation.
+
+Because route params arrive as strings at the URL level, the schema is also where Zova’s `z` wrapper can coerce the route value into the typed value that the page controller wants to consume.
+
+## Route record requirements
+
+One important rule is that if a page supports params, the route should expose the proper route structure and route name.
+
+Representative route idea:
+
+```typescript
+{
+  name: 'counter',
+  path: 'counter/:id?',
+  component: ZPageCounter,
+}
+```
+
+## Regenerate metadata
+
+When the route definition changes, regenerate module metadata so the framework’s typed route information stays aligned.
+
+```bash
+npm run zova :tools:metadata demo-student
+```
+
+For the broader schema model behind `z`, coercion, defaults, and nested structures, see [Zod Guide](/frontend/zod-guide).
+
+## Use params in a page
+
+Representative pattern:
+
+```typescript
+class ControllerPageCounter {
+  render() {
+    return <div>{this.$params.id}</div>;
+  }
+}
+```
+
+## Pass params during navigation
+
+Representative pattern:
+
+```typescript
+const url = this.$router.getPagePath('/demo/student/counter/:id?', {
+  params: {
+    id: 1,
+  },
+});
+this.$router.push(url);
+```
+
+## Implementation checks for param-driven page changes
+
+When adding or editing param-driven page behavior:
+
+1. use the Zova refactor command when possible
+2. update the route record and route name deliberately
+3. regenerate metadata when route typing depends on it
+4. use `this.$params` and typed router helpers instead of manual parsing

package/cabloy-docs/frontend/page-query-guide.md

@@ -0,0 +1,96 @@
+# Page Query Guide
+
+This guide explains how typed page query handling works in Zova within the Cabloy monorepo.
+
+## Why page query support matters
+
+Zova enhances page query handling with type-aware support so routing data can be read and passed in a more structured way.
+
+That is important because query values are part of page behavior, not just incidental URL text.
+
+## Add query support to a page
+
+Example: add query support for page `counter`.
+
+```bash
+npm run zova :refactor:pageQuery counter -- --module=demo-student
+```
+
+## Add query schema
+
+Query support becomes explicit through a Zod schema.
+
+Representative pattern:
+
+```typescript
+export const ControllerPageCounterSchemaQuery = z.object({
+  name: z.string().optional(),
+  age: z.number().optional(),
+});
+```
+
+This matters because query parsing becomes typed and framework-aware instead of stringly-typed ad hoc access.
+
+## Use query values
+
+Representative pattern:
+
+```typescript
+class ControllerPageCounter {
+  render() {
+    return (
+      <div>
+        <div>{this.$query.name}</div>
+        <div>{this.$query.age}</div>
+      </div>
+    );
+  }
+}
+```
+
+## Pass query values during navigation
+
+Representative pattern:
+
+```typescript
+const url = this.$router.getPagePath('/demo/student/counter', {
+  query: {
+    name: 'tom',
+    age: 18,
+  },
+});
+this.$router.push(url);
+```
+
+## More complex query shapes
+
+Query schemas do not have to stop at flat primitives.
+
+Representative patterns include nested objects and arrays:
+
+```typescript
+export const ControllerPageCounterSchemaQuery = z.object({
+  user: z
+    .object({
+      name: z.string(),
+      age: z.number(),
+    })
+    .optional(),
+  colors: z.array(z.string()).optional(),
+});
+```
+
+That lets page code consume richer route-driven state such as filter collections or nested search payloads without dropping back to manual string parsing.
+
+## Implementation checks for page-query changes
+
+When adding page query behavior, do not fall back to raw string parsing.
+
+A better default is:
+
+1. add the query skeleton with the Zova refactor command
+2. define the schema explicitly
+3. use `this.$query` and typed navigation helpers
+4. keep query behavior aligned with the page controller model
+
+For the broader schema model behind `z`, coercion, nested objects, and array support, see [Zod Guide](/frontend/zod-guide).

package/cabloy-docs/frontend/page-route-guide.md

@@ -0,0 +1,147 @@
+# Page Route Guide
+
+This guide explains how page route records work in Zova within the Cabloy monorepo.
+
+## Why route records matter
+
+When a page is created, Zova automatically creates a route record.
+
+That route record is the framework-level description of how the page is reached, loaded, authenticated, and rendered within the broader application model and app shell.
+
+## Representative route record
+
+```typescript
+import { ZPageCounter } from './.metadata/page/counter.js';
+
+export const routes: IModuleRoute[] = [
+  {
+    name: 'counter',
+    path: 'counter/:id?',
+    component: ZPageCounter,
+  },
+];
+```
+
+## Core route fields
+
+These route fields are the most important:
+
+- `path`
+- `name`
+- `component`
+- `alias`
+- `meta`
+
+These are the main surface area for page routing behavior.
+
+## `path`
+
+`path` defines the route path relative to the module. The framework then combines it with the module prefix to form the absolute route path.
+
+This matters because path generation is modular by default.
+
+## `name`
+
+If a page uses params, the route name becomes especially important because typed param-aware routing depends on it.
+
+## `component`
+
+`component` points to the generated page wrapper such as `ZPageCounter`.
+
+## `alias`
+
+Aliases are supported, but alias handling belongs in the broader routing configuration rather than being treated as an isolated route-local trick.
+
+## `meta`
+
+The route meta surface includes important behavior such as:
+
+- absolute-path behavior
+- layout choice
+- authentication requirement
+- locale handling
+- component key behavior
+- keepAlive behavior
+- SSR transfer-cache behavior
+
+This is one reason route records matter so much: they are not just URL declarations. They are an application-behavior surface.
+
+## Route -> shell -> routed page
+
+A useful frontend mental model is:
+
+1. the route record identifies the page
+2. route metadata chooses the logical shell/layout
+3. the resolved shell hosts the routed page
+4. guards and aliases can still affect how the page is reached
+
+That is why routing in Zova is not only about URLs. It is also about how the app shell and navigation policy shape the visible screen.
+
+### Layout selection
+
+If a page route does not specify a layout, Zova uses the default layout.
+
+Representative route shape:
+
+```typescript
+export const routes: IModuleRoute[] = [
+  {
+    path: 'counter',
+    component: ZPageCounter,
+    meta: {
+      layout: 'default',
+    },
+  },
+];
+```
+
+The system also distinguishes common built-in layout placeholders such as:
+
+- `empty`
+- `default`
+
+These names act as logical layout choices rather than hard-coded component filenames.
+
+A representative env mapping looks like this:
+
+```txt
+env/.env
+LAYOUT_COMPONENT_EMPTY = home-layout:layoutEmpty
+LAYOUT_COMPONENT_DEFAULT = home-layout:layoutTabs
+```
+
+That means route metadata chooses the logical layout, while env/config decides which actual layout component should back that choice for the active runtime variant.
+
+This is the practical app-shell boundary in Zova: routed pages do not appear alone. They appear inside the resolved layout shell for the current runtime variant.
+
+In the current Basic source, that shell is represented concretely by admin-style, web-style, and empty/minimal layout implementations.
+
+For the broader runtime-selection model behind env and flavor-aware configuration, see [Environment and Config Guide](/frontend/environment-config-guide).
+For the onboarding path that leads into shell selection, also see [Frontend Quickstart](/frontend/quickstart).
+
+## Relationship to guards and aliases
+
+Layout selection, navigation guards, and aliases are closely related but they solve different problems:
+
+- route metadata chooses the logical shell and route behavior
+- guards decide whether navigation should continue, redirect, or enrich route state
+- aliases provide alternate entry paths without changing the main route identity model
+
+Read together with:
+
+- [Navigation Guards Guide](/frontend/navigation-guards-guide)
+- [Route Alias Guide](/frontend/route-alias-guide)
+- [Frontend Quickstart](/frontend/quickstart)
+
+## Implementation checks for page-routing changes
+
+When editing page routing, do not only change the URL string.
+
+It should also check whether the route change affects:
+
+- params typing
+- auth behavior
+- layout behavior
+- locale behavior
+- SSR behavior
+- metadata regeneration