cabloy 5.1.50 → 5.1.52

package/cabloy-docs/frontend/environment-config-guide.md

@@ -0,0 +1,250 @@
+# Environment and Config Guide
+
+## Why this guide matters
+
+Zova uses a multi-dimensional environment and configuration model so frontend behavior can vary cleanly across runtime scenarios without scattering ad hoc conditionals through the codebase.
+
+That matters because SSR, SPA, edition-specific flavors, and deployment-specific variants all need a shared way to select the right settings.
+
+## The three core dimensions
+
+Zova’s frontend runtime model is built around three dimensions:
+
+- **mode**
+- **appMode**
+- **flavor**
+
+Together they determine which env variables, config files, and script paths should be active.
+
+## Runtime mode
+
+Runtime mode describes whether the app is running in:
+
+- `development`
+- `production`
+
+This affects script behavior, environment loading, and tree-shakeable flags such as `DEV` and `PROD`.
+
+## App mode
+
+App mode describes the application delivery model, such as:
+
+- `ssr`
+- `spa`
+
+This matters because SSR and SPA have different runtime assumptions, build paths, and environment-sensitive code behavior.
+
+## Flavor
+
+Flavor adds a third dimension so the frontend can support different product or UI variants without flattening everything into only one mode axis.
+
+Representative built-in flavors include:
+
+- `admin`
+- `web`
+- `cabloyBasicAdmin`
+- `cabloyStartAdmin`
+- `cabloyStartWeb`
+
+Flavor is especially important in Cabloy because Basic and Start do not always share the same frontend stack or output assumptions.
+
+## Env-file loading model
+
+Zova loads env files from `env/` using the multi-dimensional model.
+
+Representative patterns include:
+
+- `.env`
+- `.env.[meta]`
+- `.env.local`
+- `.env.[meta].local`
+
+This means env loading is layered and conditional rather than single-file only.
+
+## Config-file loading model
+
+Zova also loads frontend config files from `src/front/config/config/` using the same multi-dimensional logic.
+
+Representative patterns include:
+
+- `config.ts`
+- `config.[meta].ts`
+- `config.local.ts`
+- `config.[meta].local.ts`
+
+That keeps env variables and frontend config aligned around the same runtime-selection model.
+
+## Resolution principle
+
+The practical rule is:
+
+- base files always load
+- meta-specific files load when their dimensions match
+- `.local` files override while remaining git-ignored
+
+This lets projects combine shared defaults with scenario-specific and local overrides cleanly.
+
+A representative SSR admin development stack looks like:
+
+```txt
+.env
+.env.ssr
+.env.ssr.admin
+.env.ssr.admin.development
+.env.local
+.env.ssr.local
+.env.ssr.admin.local
+.env.ssr.admin.development.local
+```
+
+The config side follows the same merge pattern with `config.ts`, `config.[meta].ts`, and `.local` variants.
+
+## Scripts and runtime variants
+
+Frontend scripts map directly onto the same runtime dimensions.
+
+Representative commands include variants such as:
+
+- `dev:ssr:admin`
+- `build:ssr:admin`
+- `preview:ssr:admin`
+- `dev:ssr:web`
+- `build:ssr:web`
+- `dev:spa`
+- `dev:ssr:cabloyBasicAdmin`
+- `build:ssr:cabloyBasicWeb`
+
+Representative current-repo script shapes include:
+
+```json
+{
+  "dev": "npm run dev:ssr:admin",
+  "build": "npm run build:ssr:admin",
+  "preview": "npm run preview:ssr:admin",
+  "dev:ssr:admin": "npm run prerun && quasar dev --mode ssr --flavor admin",
+  "dev:ssr:web": "npm run prerun && quasar dev --mode ssr --flavor web",
+  "dev:spa": "npm run prerun && quasar dev --mode spa --flavor admin"
+}
+```
+
+That means scripts are not just convenience aliases. They are the operational surface for selecting mode, appMode, and flavor.
+
+For current monorepo usage, also see [Frontend Scripts](/frontend/scripts).
+
+## Tree-shakeable env flags
+
+Some environment variables are especially important because they support tree-shaking or compile-time branching.
+
+Representative flags include:
+
+- `META_MODE`
+- `META_APP_MODE`
+- `META_FLAVOR`
+- `NODE_ENV`
+- `DEV`
+- `PROD`
+- `SSR`
+- `CLIENT`
+- `SERVER`
+
+This is one of the most important reasons environment access should be done deliberately rather than by inventing custom runtime checks everywhere.
+
+## `process.env` vs `sys.env` vs `sys.config`
+
+Use the right access path for the right kind of value:
+
+- `process.env` for tree-shakeable env-based conditions
+- `sys.env` for runtime env values that are not tree-shaken
+- `sys.config` for the merged frontend config model
+
+Representative patterns:
+
+```typescript
+if (process.env.DEV) {
+  console.log('for development');
+}
+
+const publicPath = this.sys.env.APP_PUBLIC_PATH;
+const apiBaseURL = this.sys.config.api.baseURL;
+const flavor = this.sys.config.meta.flavor;
+```
+
+This distinction is central to writing Zova code that behaves correctly across builds and runtime variants.
+
+## Built-in env variables
+
+Zova exposes built-in variables covering areas such as:
+
+- app identity
+- router mode
+- dev-server settings
+- project-disabled suites/modules
+- build output settings
+- API/proxy configuration
+- SSR-specific values
+- mock configuration
+
+That means many common project-level knobs already exist and should be reused before inventing project-specific patterns.
+
+## Custom flavors
+
+Projects can define custom flavors when built-in variants are not enough.
+
+This usually requires:
+
+- adding scripts that pass the new `--flavor` value
+- using `META_FLAVOR` or `sys.config.meta.flavor` in code
+- optionally augmenting type definitions for better autocomplete
+
+Representative flavor type extension:
+
+```typescript
+declare module '@cabloy/module-info' {
+  export interface ZovaMetaFlavorExtend {
+    customA: never;
+  }
+}
+```
+
+In the VSCode workflow, the `recordflavor` snippet can generate this augmentation skeleton.
+
+## Async config loading
+
+Frontend config files can also load asynchronously when configuration must be derived from a remote or generated source.
+
+Representative pattern:
+
+```typescript
+export default async function (_sys: ZovaSys) {
+  const config: ZovaConfigOptional = {};
+
+  // async load remote config
+
+  return config;
+}
+```
+
+That should be used deliberately, because asynchronous config still participates in the same startup and merge model.
+
+## Relationship to other frontend guides
+
+Read this guide together with:
+
+- [Frontend Scripts](/frontend/scripts)
+- [SSR Environment Variables](/frontend/ssr-env)
+- [Frontend Quickstart](/frontend/quickstart)
+- [App Startup Guide](/frontend/app-startup-guide)
+- [System Startup Guide](/frontend/system-startup-guide)
+
+These guides explain the operational script surface, SSR-specific environment concerns, and the monorepo-first starting path.
+
+## Implementation checks for runtime-sensitive changes
+
+When changing frontend runtime-sensitive code, ask:
+
+1. does this behavior depend on mode, appMode, flavor, or more than one of them?
+2. should this logic read from `process.env`, `sys.env`, or `sys.config`?
+3. is there already a built-in env/config variable for this concern?
+4. does the active edition change which flavor or script family is correct?
+
+That helps AI keep frontend runtime behavior aligned with Zova’s actual configuration model.

package/cabloy-docs/frontend/foundation.md

@@ -0,0 +1,58 @@
+# Frontend Foundation
+
+This guide explains the core architectural role of Zova in the Cabloy monorepo.
+
+## What Zova is in Cabloy
+
+Zova is the frontend half of the Cabloy fullstack architecture.
+
+It is an intuitive frontend framework that combines strengths associated with Vue3 reactivity, React-style TSX rendering, and Angular-style IOC.
+
+## Why that matters in practice
+
+The point of this combination is not branding. The point is to make large business systems feel more natural to write and maintain.
+
+Three enduring ideas define this design:
+
+- intuitive reactive code
+- elegant structure for complex systems
+- strong extensibility through IOC and AOP patterns
+
+## UI-library flexibility
+
+One point still matters throughout the monorepo docs:
+
+Zova is not tied to one UI library.
+
+That flexibility matters directly for Cabloy’s edition model:
+
+- **Shared frontend engineering layer**: both editions follow the same Zova-centered frontend direction, with Vue, Vite, Quasar tooling, and related libraries
+- **Cabloy Basic UI layer**: current public docs and examples align with DaisyUI + Tailwind CSS
+- **Cabloy Start UI layer**: the private commercial edition aligns with Vuetify-oriented frontend modules, workflows, and SSR site baselines
+
+So docs and skills must separate shared Zova principles from edition-specific UI assumptions.
+
+## Enduring frontend capabilities
+
+The highest-value Zova capabilities to preserve in the unified docs are:
+
+- SSR support across `SSR`, `SPA`, `Web`, and `Admin` flows
+- dual-layer tabs navigation
+- CRUD-oriented rendering patterns
+- model-based unified state management
+- CSS-in-JS and theme support
+- IOC + AOP extensibility
+- compatibility with multiple UI-library strategies
+
+For the deeper architectural concepts behind IoC, module boundaries, and scope-based resources, see [IoC and Beans](/frontend/ioc-and-beans), [Modules and Suites](/frontend/modules-and-suites), and [Module Scope](/frontend/module-scope). For the runtime-variant and startup model, see [Environment and Config Guide](/frontend/environment-config-guide), [App Startup Guide](/frontend/app-startup-guide), and [System Startup Guide](/frontend/system-startup-guide).
+
+## Why this matters for AI development
+
+AI systems should not treat Zova as generic Vue with a few utilities.
+
+Instead, they should:
+
+- preserve Zova’s model, IOC, and AOP conventions
+- detect the active edition before assuming a UI-library workflow
+- prefer the Zova CLI for scaffolding and refactor work
+- verify that the generated or edited code still matches Zova’s actual architecture

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

@@ -0,0 +1,35 @@
+# Generic Component Guide
+
+This guide explains how generic components work in Zova within the Cabloy monorepo.
+
+## Why generic components matter
+
+Zova supports generic components so strongly typed reusable components can preserve richer type information across usage sites.
+
+This matters in large TypeScript-heavy systems because generic components help keep abstraction reusable without giving up strong typing.
+
+## Convert a component to a generic component
+
+Example: convert component `card` into a generic component.
+
+```bash
+npm run zova :refactor:componentGeneric card -- --module=demo-student
+```
+
+## Why the CLI matters here
+
+This topic is intentionally short, but the implication is important: generic-component conversion is not treated as an ad hoc manual rewrite. It is part of the framework’s supported refactor surface.
+
+That means the safest default is to let the Zova refactor command establish the skeleton first, then refine the typing and behavior.
+
+## Implementation checks for reusable component design
+
+When you see a component that is reused across multiple typed data shapes, ask whether the right answer is a generic component instead of copying the component into several near-duplicate variants.
+
+A better default is:
+
+1. inspect whether the component really needs generic typing
+2. use the Zova generic-component refactor command
+3. refine the resulting type surface instead of inventing a framework-foreign pattern
+
+That keeps generic typing aligned with Zova’s supported refactor workflow.

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,33 @@
+# Frontend (Zova)
+
+This page is the frontend hub for Cabloy users, contributors, and AI vibe coding workflows that need the frontend side of the framework.
+
+Zova is the frontend half of Cabloy’s one-framework-system 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.
+
+- **Shared frontend engineering layer**: both editions follow the same Zova-centered frontend direction, with Vue, Vite, Quasar tooling, and related libraries.
+- **Cabloy Basic UI layer**: current public docs and examples align with DaisyUI + Tailwind CSS.
+- **Cabloy Start UI layer**: the private commercial edition aligns with Vuetify and ships different frontend modules, SSR site baselines, and project assets.
+
+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.