cabloy 5.1.49 → 5.1.51

package/cabloy-docs/frontend/icon-engine-guide.md

@@ -0,0 +1,88 @@
+# Icon Engine Guide
+
+This guide explains how the icon engine works in Zova within the Cabloy monorepo.
+
+## Why the icon engine exists
+
+In large systems, no fixed built-in icon set is ever enough.
+
+Zova’s icon engine solves that problem by treating icons as a modular, asynchronous, UI-library-independent resource system.
+
+## Core advantages
+
+Several important advantages stand out:
+
+- easy icon maintenance
+- performance-conscious loading behavior
+- asynchronous loading on demand
+- UI-library independence
+
+This is especially important for Cabloy because the same icon strategy should work across Basic and Start even when their UI libraries differ.
+
+## Basic concepts
+
+The icon engine is organized around two ideas:
+
+### Icon group
+
+A group combines multiple SVG icons into one asynchronously loaded unit.
+
+### Icon module
+
+An icon module can contain multiple groups, and a system can contain multiple icon modules.
+
+## Naming convention
+
+The naming convention is:
+
+```text
+{moduleName}:{groupName}:{iconName}
+```
+
+Representative example:
+
+- full name: `home-icon:default:add`
+
+There are also shorthand rules, such as:
+
+- `::add`
+- `:auth:github`
+- `test-othericon::icon`
+
+This matters because icon use is part of the framework’s typed, discoverable resource model.
+
+## Access helpers
+
+Two important helpers are:
+
+- `icon` for typed icon-name access and completion
+- `iconh` for directly generating the icon vnode
+
+## UI-library independence
+
+The icon engine exposes a unified interface that can be used from multiple UI libraries.
+
+This is one of the clearest places where Zova’s architecture deliberately protects higher-level app code from UI-library churn.
+
+## Create and build icons
+
+A simple process looks like this:
+
+1. initialize the icon skeleton
+2. place SVG icons into the module/group directory
+3. regenerate metadata
+
+The metadata generation step matters because icons are part of the framework’s typed resource graph.
+
+## Implementation checks for icon-related changes
+
+When adding icons, do not hardcode one-off icon usage patterns too quickly.
+
+A better default is to ask:
+
+1. should the icon belong in an existing icon module or a new one?
+2. what group should own it?
+3. should metadata be regenerated after adding the icon?
+4. is the chosen icon usage path still UI-library-independent?
+
+That keeps icon work maintainable and consistent across editions.

package/cabloy-docs/frontend/introduction.md

@@ -0,0 +1,32 @@
+# Frontend (Zova)
+
+This page is the frontend hub for contributors who are documenting, designing, or extending frontend work in the Cabloy repository.
+
+Zova is the frontend half of the Cabloy fullstack architecture.
+
+## What Zova is responsible for
+
+- page and component architecture
+- SSR, SPA, Web, and Admin rendering flows
+- data access patterns such as `$fetch`, `$api`, and generated SDKs
+- UI library integration
+- route, icon, and component type generation
+- frontend-side refactors and code generation through the Zova CLI
+
+## How to approach frontend work
+
+For contributor and automation workflows in this repository, prefer this order:
+
+1. inspect the root `package.json` and `npm run zova` entrypoint
+2. inspect Zova CLI command families such as `create:*`, `init:*`, `refactor:*`, `tools:*`, and `openapi:*`
+3. inspect the active edition before assuming a UI stack
+4. document shared concepts once, then isolate edition-specific notes where the module set or UI library differs
+
+## Edition impact
+
+Frontend work is where Cabloy Basic and Cabloy Start differ most clearly.
+
+- **Cabloy Basic** uses a frontend stack centered on DaisyUI and TailwindCSS in the current docs and examples.
+- **Cabloy Start** uses Vuetify and ships different frontend modules as a private value-add project.
+
+Because of this, automation and docs should always detect the active edition before recommending page-level, component-level, or UI-library-specific work.

package/cabloy-docs/frontend/ioc-and-beans.md

@@ -0,0 +1,211 @@
+# IoC and Beans
+
+## Why IoC matters in Zova
+
+Zova uses IoC as a unifying frontend architecture rather than treating it as a small dependency-injection helper.
+
+That matters because state sharing, resource access, lifecycle behavior, and cross-module composition all need to stay structured as the system grows.
+
+## The four state-sharing scopes
+
+A key Zova idea is that several common sharing scopes can be handled through one IoC-centered model:
+
+- component-internal
+- between-components
+- app-global
+- system-level
+
+This replaces the need to switch constantly between unrelated mechanisms for each sharing scope.
+
+## The three container types
+
+Zova uses three main IoC containers:
+
+- **sys container** for system-wide singleton-style beans
+- **app container** for request-scoped or app-scoped beans
+- **ctx container** for component-instance-local beans
+
+This is one of the main reasons Zova can support both SSR-aware behavior and strongly structured frontend logic.
+
+## Bean classes
+
+Zova’s IoC model is built around bean classes provided by modules.
+
+All beans inherit from `BeanBase`, which exposes common framework capabilities and gives each bean a structured place inside the broader frontend architecture.
+
+## `BeanBase`
+
+`BeanBase` provides built-in members and is also a host for extended members injected by modules and adapters.
+
+Representative members include:
+
+- `sys`
+- `app`
+- `ctx`
+- `bean`
+- `scope`
+- `$el`
+- `$event`
+- `$ssr`
+- `$useMeta`
+
+Page and component beans also get frontend-specific members such as:
+
+- `$params`
+- `$query`
+- `$props`
+
+Module and UI adapters can further extend the base surface.
+
+## Injection methods
+
+Zova supports two main styles:
+
+- **dependency injection** through `@Use`
+- **dependency lookup** through the container and scope model
+
+A key Zova preference is to keep the code concise by favoring dependency lookup where it leads to clearer business code.
+
+## Resolution rules
+
+A bean can be resolved by:
+
+- bean class
+- bean identifier
+- registration name
+- variable name
+
+The most important design point is that cross-module access should prefer bean identifiers over hardwired file-path coupling.
+
+### Representative `@Use` patterns
+
+Same-module injection can stay class-oriented and concise:
+
+```typescript
+import { ModelTodo } from '../../bean/model.todo.js';
+
+class ControllerTodo {
+  @Use()
+  $$modelTodo: ModelTodo;
+}
+```
+
+Cross-module injection should usually prefer a bean identifier so the consuming module does not depend on the provider’s internal file path layout:
+
+```typescript
+import type { ModelTabs } from 'zova-module-a-routertabs';
+
+class ControllerLayout {
+  @Use('a-routertabs.model.tabs')
+  $$modelTabs: ModelTabs;
+}
+```
+
+In practice, Zova can still preserve the ergonomic class-based development experience while compiling cross-module usage back toward bean-identifier-based resolution.
+
+### Hierarchical injection patterns
+
+Hierarchical injection replaces many cases where a generic Vue app would fall back to `provide/inject`.
+
+Representative child lookup pattern:
+
+```typescript
+import type { ModelTabs } from 'zova-module-a-routertabs';
+
+class Child {
+  @Use({ injectionScope: 'host' })
+  $$modelTabs: ModelTabs;
+}
+```
+
+That keeps parent/child sharing aligned with the same IoC model instead of introducing a separate state-sharing mechanism.
+
+## Injection scopes
+
+Zova supports several injection scopes:
+
+- `sys`
+- `app`
+- `ctx`
+- `new`
+- `host`
+- `skipSelf`
+
+This allows code to be explicit about whether a bean should be shared globally, per request, per component instance, or created fresh.
+
+## Hierarchical injection
+
+The `host` and `skipSelf` scopes provide hierarchical lookup behavior.
+
+This replaces much of the conventional Vue `provide/inject` style with an IoC-native rule set.
+
+That means parent/child sharing can stay aligned with the same overall bean model instead of becoming a separate architectural subsystem.
+
+## Lifecycle
+
+All beans can define two lifecycle methods:
+
+- `__init__`
+- `__dispose__`
+
+These lifecycle hooks are important because they give beans a structured place for initialization and cleanup logic.
+
+Representative uses include:
+
+- computed setup
+- watchers
+- derived state wiring
+- resource cleanup
+
+Representative initialization pattern:
+
+```typescript
+export class Counter {
+  count: number = 0;
+  count2: string;
+
+  protected async __init__() {
+    this.count2 = this.$computed(() => {
+      return `=== ${this.count} ===`;
+    });
+
+    this.$watch(
+      () => this.count,
+      () => {
+        console.log('changed: ', this.count);
+      },
+    );
+  }
+}
+```
+
+That gives a bean one consistent place to wire reactive behavior instead of scattering setup logic through unrelated hooks.
+
+## Bean identifiers and loose coupling
+
+Bean identifiers are a key part of Zova’s modular architecture.
+
+They make cross-module access more stable and decoupled than always relying on direct file-path imports.
+
+This matters especially in large systems, where business modules should remain reusable and composable.
+
+## Relationship to other frontend guides
+
+Read this together with:
+
+- [Modules and Suites](/frontend/modules-and-suites)
+- [Module Scope](/frontend/module-scope)
+- [Frontend Design Principles](/frontend/design-principles)
+
+Those pages explain how beans fit into module boundaries, scope-based resources, and the broader Zova architectural model.
+
+## Implementation checks for frontend bean-architecture changes
+
+When editing Zova frontend code, ask:
+
+1. should this behavior live in a bean instead of a framework-neutral helper?
+2. is the right sharing scope `ctx`, `app`, or `sys`?
+3. should dependency injection or dependency lookup be preferred here?
+4. does this component or page already rely on lifecycle hooks, hierarchical injection, or bean identifiers that should be preserved?
+
+That helps AI keep frontend changes aligned with Zova’s real architectural model instead of drifting toward generic Vue patterns.

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

@@ -0,0 +1,109 @@
+# Mock Guide
+
+## Why mock matters in Zova
+
+Zova provides an out-of-the-box mock mechanism so frontend development can continue even when a real backend integration path is incomplete or intentionally decoupled.
+
+That matters because page, API, and server-data workflows often need stable response shapes before the final backend contract is available.
+
+## Core mock model
+
+The Zova mock mechanism is based on `vite-plugin-fake-server` and is integrated into the frontend development workflow.
+
+A mock route is typically defined in a `.fake.ts` file inside the relevant module.
+
+## Mock file structure
+
+Representative example:
+
+```typescript
+import { defineFakeRoute } from 'vite-plugin-fake-server-turbo/client';
+
+export default defineFakeRoute([
+  {
+    url: '/home/layout/menu/select',
+    method: 'get',
+    response: () => {
+      return {
+        code: 0,
+        message: 'Success',
+        data: [],
+      };
+    },
+  },
+]);
+```
+
+Key points:
+
+- mock files use the `.fake.ts` extension
+- `defineFakeRoute(...)` provides the route definition shape
+- each mock route describes the request path, method, and response
+
+## Where mock files belong
+
+Mocks belong near the frontend module that consumes or defines the route shape.
+
+Representative example:
+
+- `src/suite/a-home/modules/home-layout/mock/menu.fake.ts`
+
+This keeps mock behavior close to the page, API, or business module that depends on it.
+
+## Relationship to frontend APIs and server data
+
+Mocking fits naturally with:
+
+- [API Guide](/frontend/api-guide)
+- [Server Data](/frontend/server-data)
+- [Page Guide](/frontend/page-guide)
+
+A common workflow is:
+
+1. define or update the frontend page or API contract
+2. provide a mock route with the expected response shape
+3. build page, component, or model behavior against that mock response
+4. later replace the mock-backed path with the real backend contract when ready
+
+## Configuration
+
+Mock behavior is configured through environment variables such as:
+
+- `MOCK_ENABLED`
+- `MOCK_LOGGER`
+- `MOCK_BASE_NAME`
+- `MOCK_BUILD`
+- `MOCK_BUILD_PORT`
+- `MOCK_BUILD_OUTPUT`
+- `MOCK_BUILD_CORS`
+
+These settings control whether mocks are enabled, whether a standalone fake server should be built, and how the mock server behaves.
+
+## Development and production behavior
+
+By default, production builds do not generate the fake server.
+
+If a standalone fake server should be generated during build, `MOCK_BUILD` must be enabled.
+
+That means mock support can be used in development only, or intentionally packaged for separate deployment when needed.
+
+## When to use mock
+
+Use mock when:
+
+- frontend page or API work needs stable response data before the backend is ready
+- you want to prototype UI behavior against an expected contract
+- you want repeatable local demo or development behavior without a live backend dependency
+
+Do not treat mock as the final source of truth for the contract when a real backend/OpenAPI path already exists.
+
+## Implementation checks for mock-versus-contract decisions
+
+When editing frontend integration paths, ask:
+
+1. is the real backend contract available yet?
+2. should this flow use a temporary mock route or a real `$api`/OpenAPI path?
+3. does the mock response shape match the intended page, API, or model contract?
+4. should mock be enabled only for development, or is a standalone fake server also needed?
+
+That helps AI keep frontend development moving without confusing temporary mock behavior with final backend truth.

package/cabloy-docs/frontend/model-architecture.md

@@ -0,0 +1,87 @@
+# Model Architecture
+
+This guide explains the overall model architecture in Zova within the Cabloy monorepo.
+
+## Why Zova models matter
+
+Zova uses a unified `Model` mechanism to manage several kinds of data that other frontend stacks often split across unrelated tools.
+
+This is one of the most important architectural ideas in Zova.
+
+## Four kinds of global state
+
+The model architecture can be understood through four common data categories:
+
+- asynchronous data, usually from the server
+- local storage data
+- cookie data
+- in-memory data
+
+In Zova, these can all participate in one broader model-centered system instead of forcing developers to switch between unrelated mental models.
+
+## Relationship to TanStack Query
+
+One key point is explicit: the base of Zova Model is TanStack Query.
+
+That matters because Zova is not discarding the strengths of TanStack Query. It is building a more unified and framework-friendly usage model on top of it.
+
+## Key model capabilities
+
+Several important capabilities remain central in the unified docs:
+
+### 1. Support for async and sync data
+
+The model system is not limited to server data. It also extends the same broader mechanism to synchronous data categories.
+
+### 2. Automatic caching
+
+Remote data can be cached locally, while local-storage or cookie-backed data can be accessed through unified model patterns.
+
+### 3. Automatic update behavior
+
+The model system supports data freshness and update behavior instead of treating state as static snapshots.
+
+### 4. Reduced duplicate requests
+
+When multiple parts of the app need the same data, the framework avoids unnecessary repeated requests.
+
+### 5. Memory optimization
+
+Model-managed data does not need to occupy memory forever. Cache lifecycle and release behavior matter, especially for large long-running applications.
+
+### 6. Persistence
+
+Model-managed data can participate in persistence strategies so refreshes do not always mean starting from nothing.
+
+### 7. SSR support
+
+The model system helps smooth out SSR differences across data categories and makes hydration more natural.
+
+### 8. Namespace isolation
+
+Because data is managed through model beans, the bean identity itself helps provide namespace isolation and reduces collision risk.
+
+## Create a model bean
+
+Representative pattern:
+
+```typescript
+import { Model } from 'zova';
+import { BeanModelBase } from 'zova-module-a-model';
+
+@Model()
+export class ModelTodo extends BeanModelBase {}
+```
+
+## Practical implications for frontend state design
+
+When asked to add frontend state, do not immediately assume a generic Vue/Pinia-style answer.
+
+A better default is to ask:
+
+1. is this state already a good fit for a Zova model?
+2. is the data async or sync, and does that distinction matter to the model choice?
+3. does SSR or persistence make the model layer especially valuable here?
+4. is there already a model bean that should own this state instead of adding a new ad hoc state container?
+
+That keeps the code aligned with Zova’s actual architecture.

package/cabloy-docs/frontend/model-state-guide.md

@@ -0,0 +1,70 @@
+# Model State Guide
+
+This guide explains how model-based server-data state works in Zova within the Cabloy monorepo.
+
+## Why the model layer exists
+
+Zova uses model-based state management on top of API access so remote data can participate in a more unified caching and usage model.
+
+This improves runtime performance and developer experience by building on top of TanStack Query rather than exposing only raw request flows.
+
+## Create a model
+
+Example: create a model named `menu` in module `demo-student`.
+
+```bash
+npm run zova :create:bean model menu -- --module=demo-student
+```
+
+## Model definition
+
+Representative pattern:
+
+```typescript
+@Model()
+export class ModelMenu {
+  retrieveMenus() {
+    return this.$useStateData({
+      queryKey: ['retrieveMenus'],
+      queryFn: async () => {
+        return await this.$api.homeBaseMenu.retrieveMenus({
+          params: { publicPath: '' },
+        });
+      },
+    });
+  }
+}
+```
+
+This pattern is important because it shows that model logic is not just local state. It is also the place where cached remote data becomes a reusable abstraction.
+
+## Using a model
+
+Representative pattern:
+
+```typescript
+@Use()
+$$modelMenu: ModelMenu;
+
+protected render() {
+  const { data, error } = this.$$modelMenu.retrieveMenus();
+  if (error) return <div>{error.message}</div>;
+  return <div>{data}</div>;
+}
+```
+
+## Relationship to the server-data ladder
+
+In the new docs, think about the layers like this:
+
+- `$fetch` → direct request access
+- `$api` → business-oriented service methods
+- `Model` → cached, reusable, UI-friendly remote state
+
+That makes the model layer one of the most important bridges between backend contracts and frontend rendering.
+
+## Implementation checks for model-based state changes
+
+When you see repeated frontend data usage, caching concerns, or UI state that depends on remote data, ask whether the right abstraction is a model instead of a direct API call in the page.
+
+That usually leads to cleaner SSR behavior, cleaner reuse, and a more Cabloy-native structure.