cabloy 5.1.49 → 5.1.51

package/cabloy-docs/frontend/quickstart.md

@@ -0,0 +1,201 @@
+# Frontend Quickstart
+
+This guide explains the fastest way to get oriented on the frontend side of the Cabloy framework repository.
+
+If you want to create and use a Cabloy project, start with [Fullstack Quickstart](/fullstack/quickstart).
+
+## When to use this page
+
+Use this page when you want to move from the framework repository root to the first visible routed screen in Zova with the right edition and script assumptions.
+
+This page is the frontend narrative hub for framework-repository work such as:
+
+- detecting the active edition
+- choosing the right root scripts and frontend flavors
+- understanding how startup and routing make the app routable
+- understanding the app shell around routed pages
+- reaching the first routed page and knowing what to read next
+
+## Step 1: detect the edition first
+
+Before choosing frontend examples, scripts, or shell assumptions, detect whether you are working in:
+
+- **Cabloy Basic**
+- **Cabloy Start**
+
+When working in this framework repository, the active edition is **Cabloy Basic**.
+
+That matters because edition choice affects:
+
+- frontend flavor names
+- UI-library assumptions
+- available modules and layouts
+- which examples in the docs match the current repo directly
+
+Read together with:
+
+- [Edition Detection](/editions/detection)
+- [Cabloy Basic](/editions/cabloy-basic)
+- [Cabloy Start](/editions/cabloy-start)
+
+## Step 2: start from root scripts
+
+When working in the framework repository, begin from the root repository scripts.
+
+These commands are repository-root workflows for framework development and verification, not the default bootstrap path for a normal Cabloy project.
+
+### Install and initialize the framework workspace
+
+```bash
+npm run init
+```
+
+### Start frontend development for Cabloy Basic
+
+```bash
+npm run dev:zova:admin
+npm run dev:zova:web
+```
+
+These root wrappers currently map to the Basic flavors:
+
+- `cabloyBasicAdmin`
+- `cabloyBasicWeb`
+
+### Build frontend output for Cabloy Basic
+
+```bash
+npm run build:zova
+```
+
+Use the root wrappers as the normal entrypoint for this framework repository, then read the deeper script guide when you need appMode/flavor detail.
+
+Read together with:
+
+- [Repo Scripts](/reference/repo-scripts)
+- [Frontend Scripts](/frontend/scripts)
+
+## Step 3: understand runtime selection
+
+Frontend behavior is not chosen by one flag only. It is shaped by:
+
+- `mode`
+- `appMode`
+- `flavor`
+
+Those runtime choices affect:
+
+- which config and env values are active
+- which shell/layout components are resolved
+- how startup and routing behave in the current frontend variant
+- which edition-specific script examples apply
+
+Read next:
+
+- [Environment and Config Guide](/frontend/environment-config-guide)
+
+## Step 4: understand how the app becomes routable
+
+A practical startup split is:
+
+- **system startup** registers routes and loads system-level config before the app can really become routable
+- **app startup** makes router, guards, and first-navigation behavior operational for the running app instance
+
+That means the first visible screen is not only a page concern. It depends on the startup sequence that prepares routing and navigation behavior first.
+
+Read in sequence:
+
+1. [System Startup Guide](/frontend/system-startup-guide)
+2. [App Startup Guide](/frontend/app-startup-guide)
+
+## Step 5: understand the app shell
+
+A routed page does not appear alone. It appears inside an app shell.
+
+In practice, the shell is the layout layer around the routed page. Route metadata chooses a logical layout such as `default` or `empty`, and env/config resolves that logical choice into the actual layout component for the active runtime variant.
+
+In the current Basic source, the most important shell shapes are represented by:
+
+- admin-style layout behavior
+- web-style layout behavior
+- empty/minimal layout behavior
+
+This is why route metadata, guards, aliases, and theme/header/menu behavior should be understood together rather than as unrelated features.
+
+Read together with:
+
+- [Page Route Guide](/frontend/page-route-guide)
+- [Navigation Guards Guide](/frontend/navigation-guards-guide)
+- [Route Alias Guide](/frontend/route-alias-guide)
+- [Theme Guide](/frontend/theme-guide)
+
+## Step 6: reach the first routed page
+
+Once the edition and runtime path are clear, the fastest practical next step is to create a page and understand where it appears.
+
+A useful frontend-first sequence is:
+
+1. create or choose a module
+2. create a page in that module
+3. let Zova generate the route record and page path
+4. confirm which shell/layout the route should use
+5. run the matching frontend flavor and inspect the result
+
+The generated route path follows Zova’s module-oriented naming conventions, so the first page is part of the broader routing and shell model rather than a free-form standalone screen.
+
+Read next:
+
+- [Frontend CLI](/frontend/cli)
+- [Page Guide](/frontend/page-guide)
+- [Page Route Guide](/frontend/page-route-guide)
+
+## Step 7: understand menu and CLI ergonomics
+
+Zova supports both command-line and editor-driven workflows.
+
+A practical distinction is:
+
+- **CLI** is the canonical automation and scriptable workflow surface
+- **editor menus** improve discoverability and ergonomics for the same underlying workflows
+
+That means frontend onboarding should not force a choice between the two. Use menus when they help you discover commands quickly, and use the CLI when you need reproducible automation or explicit command history.
+
+Read next:
+
+- [Frontend CLI](/frontend/cli)
+
+## Recommended next paths
+
+### I want to run and inspect the frontend shell
+
+- [Frontend Scripts](/frontend/scripts)
+- [Environment and Config Guide](/frontend/environment-config-guide)
+- [Page Route Guide](/frontend/page-route-guide)
+- [Theme Guide](/frontend/theme-guide)
+
+### I want to understand startup and routing
+
+- [System Startup Guide](/frontend/system-startup-guide)
+- [App Startup Guide](/frontend/app-startup-guide)
+- [Page Route Guide](/frontend/page-route-guide)
+- [Navigation Guards Guide](/frontend/navigation-guards-guide)
+- [Route Alias Guide](/frontend/route-alias-guide)
+
+### I want to create my first page
+
+- [Frontend CLI](/frontend/cli)
+- [Page Guide](/frontend/page-guide)
+- [Page Route Guide](/frontend/page-route-guide)
+
+### I need edition-sensitive guidance
+
+- [Edition Detection](/editions/detection)
+- [Cabloy Basic](/editions/cabloy-basic)
+- [Cabloy Start](/editions/cabloy-start)
+- [Frontend Scripts](/frontend/scripts)
+
+### I want the broader frontend architecture story
+
+- [Frontend (Zova)](/frontend/introduction)
+- [Frontend Foundation](/frontend/foundation)
+- [Design Principles](/frontend/design-principles)

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

@@ -0,0 +1,61 @@
+# Route Alias Guide
+
+This guide explains how route aliases work in Zova within the Cabloy monorepo.
+
+## Why route aliases exist
+
+In a modular routing system, the real page path and the user-facing path are not always the same.
+
+A home-page example shows this clearly:
+
+- a module may provide a real internal page path
+- users may still expect a simpler public-facing path such as `/`
+
+Route aliases bridge that gap.
+
+## Basic routing flow
+
+The navigation flow can be described in terms of:
+
+1. navigate to a path
+2. resolve the owning module
+3. load the module
+4. inject the module routes into the route table
+5. find the matching route and render the component
+
+This is important because route aliasing is part of module-aware navigation, not an isolated string rewrite.
+
+## Global config for aliases
+
+Aliases belong in global config.
+
+Representative pattern:
+
+```typescript
+config.routes = {
+  path: {
+    '/home/index': { alias: '/' },
+    '/home/login': { alias: '/login' },
+  },
+  name: {
+    'demo-todo:item': { alias: '/todo/:id' },
+  },
+};
+```
+
+## `path` vs `name`
+
+The distinction matters:
+
+- use `routes.path` for normal path-based aliases
+- use `routes.name` when the route depends on params-aware naming
+
+## Implementation checks for route-alias changes
+
+When changing user-facing routes, ask:
+
+1. is this a real route change or just an alias change?
+2. does the alias belong in global config?
+3. is the page params-aware, meaning the name-based alias path is the correct layer?
+
+That helps avoid breaking modular routing semantics.

package/cabloy-docs/frontend/scripts.md

@@ -0,0 +1,86 @@
+# Frontend Scripts
+
+This guide explains the main Zova script workflows in the Cabloy monorepo.
+
+## Shared rule
+
+Zova can build `SSR`, `SPA`, `Web`, and `Admin` modes in one codebase. In Cabloy, contributors should usually start from the root scripts first, then drop into `zova/package.json` only when they need edition-specific detail.
+
+## Detect the edition first
+
+Before choosing script examples, detect whether you are working in Cabloy Basic or Cabloy Start.
+
+A practical rule is:
+
+1. detect the edition first
+2. then choose the correct script, flavor, and appMode path
+3. only then document or automate edition-specific frontend examples
+
+For the edition-detection workflow, also see [Edition Detection](/editions/detection).
+
+## Cabloy Basic root wrappers
+
+From the current root repository:
+
+```bash
+npm run dev:zova:admin
+npm run dev:zova:web
+npm run build:zova
+```
+
+These map to Basic-specific Zova flavors in this repository.
+
+## Zova script model
+
+The underlying Zova package still organizes scripts around app mode and flavor.
+
+Examples from the current source include:
+
+- `dev:ssr:admin`
+- `build:ssr:admin`
+- `preview:ssr:admin`
+- `dev:ssr:web`
+- `build:ssr:web`
+- `preview:ssr:web`
+- `dev:ssr:cabloyBasicAdmin`
+- `build:ssr:cabloyBasicAdmin`
+- `build:rest:cabloyBasicAdmin`
+- `dev:ssr:cabloyBasicWeb`
+- `build:ssr:cabloyBasicWeb`
+- `build:rest:cabloyBasicWeb`
+
+## Cabloy Basic
+
+The current public repository documents and scripts support Basic-specific flavors such as:
+
+- `cabloyBasicAdmin`
+- `cabloyBasicWeb`
+
+Representative Zova commands inside this repo include:
+
+```bash
+cd zova && npm run dev:ssr:cabloyBasicAdmin
+cd zova && npm run build:ssr:cabloyBasicAdmin
+cd zova && npm run build:rest:cabloyBasicAdmin
+```
+
+## Cabloy Start
+
+The sibling `cabloy-start` repository uses Start-specific flavors such as:
+
+- `cabloyStartAdmin`
+- `cabloyStartWeb`
+
+Those commands are not driven by the current Basic repo root wrappers, so verify the Start repo’s `package.json` before documenting or automating them.
+
+## Workflow guidance
+
+When documenting or automating frontend scripts:
+
+- start from root wrappers for normal Cabloy Basic workflows
+- detect the edition before choosing flavor-specific examples
+- verify the exact flavor before writing edition-specific examples
+- use REST/type generation commands deliberately when backend integration depends on them
+- understand the mode/appMode/flavor model before changing script families; see [Environment and Config Guide](/frontend/environment-config-guide)
+- enable or package frontend mock support deliberately when development depends on fake-server behavior; see [Mock Guide](/frontend/mock-guide)
+- use [Frontend Quickstart](/frontend/quickstart) when the reader first needs the end-to-end onboarding story rather than only a script reference

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

@@ -0,0 +1,45 @@
+# SDK Guide
+
+This page expands the legacy `$sdk` placeholder into a practical guidance page for the new docs site.
+
+## What `$sdk` is for
+
+`$sdk` can be understood as a more generalized schema-driven access layer built on the same broader server-data model.
+
+If `$apiSchema` exposes the metadata directly, `$sdk` represents a more application-friendly way to package schema-driven capabilities into a unified development experience.
+
+## Why `$sdk` matters
+
+The server-data thread in Zova is not only about calling endpoints. It is also about turning backend metadata into reusable frontend capabilities.
+
+That is the context in which `$sdk` matters.
+
+## How to think about the layers together
+
+- `$fetch` → direct transport-oriented calls
+- `$api` → business-oriented request services
+- `Model` → cached remote state and UI-facing reuse
+- `OpenAPI SDK` → generated client services from backend metadata
+- `$apiSchema` → direct schema access
+- `$sdk` → a more generalized schema-driven integration layer
+
+## Read together with
+
+Use this page together with:
+
+- [Server Data](/frontend/server-data)
+- [OpenAPI SDK Guide](/frontend/openapi-sdk-guide)
+- [API Schema Guide](/frontend/api-schema-guide)
+- [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk)
+
+## Implementation checks for metadata-driven frontend integration
+
+When asked to build metadata-driven frontend behavior, do not stop at “can I call the API?”
+
+It should also ask:
+
+- should this use the generated SDK?
+- should this use schema metadata?
+- should this be packaged into a more reusable `$sdk`-style abstraction?
+
+That mindset produces more reusable frontend architecture.

package/cabloy-docs/frontend/server-data.md

@@ -0,0 +1,74 @@
+# Server Data
+
+This guide explains the server-data abstraction layers in Zova within the Cabloy monorepo.
+
+## Why this layer exists
+
+Zova provides several levels of abstraction for accessing server data.
+
+The point is not to force one access style for every problem. The point is to let developers choose the right level of abstraction for the current business need while still staying within a coherent framework model.
+
+## The abstraction ladder
+
+These layers define the server-data abstraction ladder:
+
+| Name          | Description                                                     |
+| ------------- | --------------------------------------------------------------- |
+| `$fetch`      | low-level request wrapper                                       |
+| `$api`        | business-oriented API services on top of `$fetch`               |
+| `Model`       | remote-data state and caching patterns on top of service access |
+| `OpenAPI SDK` | generated client SDK based on backend Swagger/OpenAPI metadata  |
+| `$apiSchema`  | direct access to API schema metadata                            |
+| `$sdk`        | more generalized schema-driven access using model patterns      |
+
+## How to think about the layers
+
+### `$fetch`
+
+Use `$fetch` when you need a relatively direct HTTP-oriented access path.
+
+### `$api`
+
+Use `$api` when you want business-oriented service access rather than scattering request details across pages and components.
+
+### `Model`
+
+Use model-based patterns when caching, shared remote state, and a more unified usage model matter.
+
+### `OpenAPI SDK`
+
+Use OpenAPI SDK generation when you want backend-generated API contracts to drive frontend calling patterns more directly.
+
+### `$apiSchema` and `$sdk`
+
+Use schema-driven layers when metadata itself needs to participate in higher-level frontend behavior such as validation or automatic rendering.
+
+## Why this matters for Cabloy
+
+This abstraction ladder is one of the key links between Zova and Vona.
+
+Vona emits backend-side metadata and OpenAPI information.
+Zova can consume that information through SDK and schema-driven layers.
+
+That makes server data a core fullstack integration topic, not just a frontend utility topic.
+
+A practical contract-consumption reading is:
+
+- [OpenAPI Guide](/backend/openapi-guide) explains backend contract emission
+- [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk) explains the fullstack contract bridge
+- [OpenAPI SDK Guide](/frontend/openapi-sdk-guide), [API Schema Guide](/frontend/api-schema-guide), and [SDK Guide](/frontend/sdk-guide) explain different frontend consumption layers
+
+## Implementation checks for frontend data-loading changes
+
+When adding frontend data access, avoid jumping straight to ad hoc request logic.
+
+Instead, it should ask:
+
+1. is `$fetch` enough?
+2. should this be a business-oriented `$api` service?
+3. should this become model-managed state?
+4. is there already an OpenAPI or schema-driven route for this integration?
+
+That decision usually produces cleaner, more Cabloy-native code.
+
+When the real backend contract is temporarily unavailable, frontend-side mocks can provide a short-lived bridge for page, API, or model development; see [Mock Guide](/frontend/mock-guide).

package/cabloy-docs/frontend/ssr-client-only.md

@@ -0,0 +1,40 @@
+# SSR ClientOnly
+
+This guide explains when to use `ClientOnly` in Zova SSR within the Cabloy monorepo.
+
+## When to use `ClientOnly`
+
+Some components only make sense on the client side.
+
+When that happens, wrap them in `ClientOnly` so SSR does not try to render behavior that depends on the browser-only environment.
+
+## Representative pattern
+
+```typescript
+import { ClientOnly } from 'zova';
+
+@Render()
+export class RenderTabs {
+  render() {
+    return (
+      <ClientOnly>
+        <div role="tablist" class="tabs tabs-lifted">
+          {domTabs}
+        </div>
+      </ClientOnly>
+    );
+  }
+}
+```
+
+## Why this matters
+
+This is one of the simplest but most important SSR boundary tools.
+
+It makes the server/client split explicit and keeps browser-only behavior from leaking into the server render path.
+
+## Implementation checks for client-only SSR boundaries
+
+When adding or editing SSR-sensitive UI, ask whether the component depends on client-only behavior such as browser APIs, client-only rendering expectations, or interactions that should not appear in the server render.
+
+If yes, `ClientOnly` may be the right boundary.

package/cabloy-docs/frontend/ssr-env.md

@@ -0,0 +1,51 @@
+# SSR Environment Variables
+
+This guide explains SSR-related environment variables in Zova within the Cabloy monorepo.
+
+## Why SSR env configuration matters
+
+SSR behavior often depends on environment variables that do not matter in exactly the same way for purely client-side execution.
+
+Zova exposes SSR-related environment variables so the framework can configure key behaviors directly.
+
+## Representative configurable variables
+
+Representative variables include:
+
+- `SSR_COOKIE`
+- `SSR_COOKIE_THEMEDARK_DEFAULT`
+- `SSR_BODYREADYOBSERVER`
+- `SSR_API_BASE_URL`
+- `SSR_PROD_PORT`
+
+These affect areas such as cookie-driven SSR behavior, theme defaults, body-load observation, server-side API targeting, and SSR production port behavior.
+
+## Dynamic environment variables
+
+The runtime also exposes environment variables that describe the current execution context, such as:
+
+- `SSR`
+- `DEV`
+- `PROD`
+- `CLIENT`
+- `SERVER`
+
+These are important because SSR-aware code often needs to distinguish:
+
+- server versus client behavior
+- development versus production behavior
+- SSR mode versus non-SSR mode
+
+## Implementation checks for SSR environment-sensitive changes
+
+When editing SSR-sensitive code, do not assume one execution environment.
+
+It should explicitly consider whether the code path depends on:
+
+- server versus client execution
+- dev versus prod behavior
+- SSR-specific environment configuration
+
+That is often the difference between code that “works locally once” and code that fits the actual Zova SSR model.
+
+For the broader mode/appMode/flavor and env/config loading model, see [Environment and Config Guide](/frontend/environment-config-guide).

package/cabloy-docs/frontend/ssr-init-data.md

@@ -0,0 +1,46 @@
+# SSR Init Data
+
+This guide explains how SSR init data works in Zova within the Cabloy monorepo.
+
+## Why init data matters
+
+SSR needs data to be ready on the server before the rendered result is sent to the client.
+
+Zova’s SSR model makes this feel natural by letting controllers prepare the needed data in `__init__`, while model-based state handles synchronization and hydration.
+
+## Representative pattern
+
+A representative pattern looks like this:
+
+```typescript
+@Controller()
+export class ControllerPageTodo {
+  @Use()
+  $$modelTodo: ModelTodo;
+
+  protected async __init__() {
+    const queryTodos = this.$$modelTodo.select();
+    await queryTodos.suspense();
+    if (queryTodos.error) throw queryTodos.error;
+  }
+}
+```
+
+## What is happening here
+
+1. a model bean encapsulates the data access path
+2. the controller injects the model
+3. `__init__` prepares the data on the server
+4. model-based SSR support synchronizes that data to the client and completes hydration automatically
+
+## Implementation checks for SSR data-loading changes
+
+When changing SSR pages, avoid inventing parallel data-loading patterns unless there is a real reason.
+
+A better default is:
+
+- use the existing model abstraction
+- prepare data in `__init__`
+- let hydration reuse the server-prepared cache on the client
+
+That keeps SSR code aligned with Zova’s intended flow.

package/cabloy-docs/frontend/ssr-overview.md

@@ -0,0 +1,48 @@
+# SSR Overview
+
+This guide explains the overall SSR model in Zova within the Cabloy monorepo.
+
+## What Zova SSR provides
+
+Zova includes a built-in SSR solution that supports both front-end applications and admin systems.
+
+The important point for the new docs is not the implementation detail alone. It is the developer experience goal:
+
+SSR should feel like a normal part of the application model rather than a separate, awkward mode that forces unrelated coding patterns.
+
+## Key SSR capabilities
+
+### Support for multiple UI-library strategies
+
+Zova SSR can be used together with different UI-library strategies. This matters directly for Cabloy editions because Basic and Start diverge on frontend stack assumptions.
+
+### Theme support
+
+The SSR story includes theme-related behavior, including dark/light patterns and admin-oriented theme behavior.
+
+### Sidebar and client-state integration
+
+For admin systems, SSR still needs to cooperate with client-facing behavior such as sidebar state.
+
+### Initialize data
+
+A central SSR capability is preparing initial data on the server, synchronizing it to the client, and completing hydration naturally.
+
+### SEO meta
+
+SSR also supports flexible SEO metadata handling.
+
+### Env configuration
+
+SSR behavior can depend on environment variables and configuration choices, so SSR docs should be read together with the runtime/flavor model and frontend script model.
+
+## Implementation checks for SSR-sensitive changes
+
+When changing SSR-sensitive code, ask:
+
+1. does this logic run on the server, the client, or both?
+2. does this affect initialization or hydration?
+3. does the active edition change the UI-library assumptions behind the SSR workflow?
+4. does the existing Zova SSR abstraction already cover this case?
+
+That keeps SSR work aligned with the framework instead of drifting into generic frontend patterns.