cabloy 5.1.49 → 5.1.51

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

@@ -0,0 +1,110 @@
+# Component v-model Guide
+
+This guide explains how component `v-model` works in Zova within the Cabloy monorepo.
+
+## Why Zova `v-model` matters
+
+Zova makes it convenient to add two-way binding behavior to a component while keeping the binding logic visible inside the controller model.
+
+That is important because the framework treats model binding as part of the controller-oriented component architecture, not just as template sugar.
+
+## Add the basic `modelValue` skeleton
+
+Example: add `modelValue` to component `card`.
+
+```bash
+npm run zova :refactor:componentModel card modelValue -- --module=demo-student
+```
+
+## Representative generated shape
+
+```typescript
+export interface ControllerCardModels {
+  vModel?: number;
+}
+
+@Controller()
+export class ControllerCard extends BeanControllerBase {
+  static $propsDefault = {
+    modelValue: 0,
+  };
+
+  modelValue: number;
+
+  protected async __init__() {
+    this.modelValue = this.$useModel('modelValue');
+  }
+}
+```
+
+## Use `v-model` inside the component
+
+Representative pattern:
+
+```typescript
+class ControllerCard {
+  render() {
+    return (
+      <div>
+        <div>{this.modelValue}</div>
+        <button
+          onClick={() => {
+            this.modelValue++;
+          }}
+        >
+          Change
+        </button>
+      </div>
+    );
+  }
+}
+```
+
+The key idea is that changing `this.modelValue` updates the bound parent-side value through the framework binding model.
+
+## Pass `v-model` from the parent
+
+Representative pattern:
+
+```typescript
+class ControllerOther {
+  count: number;
+
+  render() {
+    return <ZCard vModel={this.count} />;
+  }
+}
+```
+
+## Named `v-model` parameters
+
+`modelValue` is only the default binding name. Other binding names can be added, for example `title`.
+
+Representative generation command:
+
+```bash
+npm run zova :refactor:componentModel card title -- --module=demo-student
+```
+
+Representative usage pattern:
+
+```typescript
+<ZCard vModel:title={this.title} />
+```
+
+## Modifiers
+
+Zova also supports modifiers through the same broader binding model.
+
+One representative example uses a custom `capitalize` modifier, implemented by passing a setter transformation into `$useModel`.
+
+That is useful because it shows `v-model` behavior in Zova is programmable and explicit, not just a fixed syntax feature.
+
+## Implementation checks for component binding changes
+
+When adding two-way binding to a Zova component:
+
+1. use the Zova refactor command to create the skeleton
+2. keep the binding visible through `Controller*Models` and `$useModel`
+3. choose between default and named model parameters deliberately
+4. use modifiers through the framework pattern instead of inventing parallel custom binding logic

package/cabloy-docs/frontend/css-in-js-guide.md

@@ -0,0 +1,151 @@
+# CSS-in-JS Guide
+
+This guide explains the role of CSS-in-JS in Zova within the Cabloy monorepo.
+
+## Why CSS-in-JS matters in Zova
+
+Zova uses a built-in CSS-in-JS approach so styling can stay close to component and page logic without collapsing into uncontrolled global CSS.
+
+This is often explained through TypeStyle, but the main point is not novelty. The goal is a styling system that stays flexible, scoped, and framework-friendly in larger applications.
+
+## Core benefits
+
+Several enduring benefits stand out:
+
+- scoped styles that reduce conflicts
+- dynamic style generation from reactive state
+- token support independent of UI libraries
+- theme support independent of UI libraries
+- easier debugging through development-friendly class naming
+- built-in template support for multiple UI-library strategies
+
+## Choose the right styling mechanism
+
+A practical decision map is:
+
+| Use this                                  | When it fits best                                                                       |
+| ----------------------------------------- | --------------------------------------------------------------------------------------- |
+| `this.$style(...)`                        | local scoped styles near one controller, render bean, or style bean                     |
+| dedicated style bean with `BeanStyleBase` | the page or component has enough styling logic to deserve its own file or boundary      |
+| `@Css()` and `$cssBase`                   | shared/global style vocabulary should be reused across many pages or components         |
+| `$token`                                  | style values should come from theme-defined design values instead of hardcoded literals |
+| `$theme`                                  | runtime behavior needs to read or switch the active theme or dark-mode state            |
+
+The important point is that these are not competing styling systems. They are connected surfaces inside one Zova styling architecture.
+
+## Local scoped styles with `this.$style(...)`
+
+`this.$style(...)` is the normal entrypoint for local scoped class generation.
+
+Use it when the style belongs to one page, component, or style bean and should stay close to the current controller-oriented logic.
+
+This is a good default for:
+
+- one-off local classes
+- styles driven by local runtime state
+- styles that should remain scoped instead of becoming app-wide vocabulary
+
+## Dedicated style beans with `BeanStyleBase`
+
+When styling grows beyond a small local block, split it into a dedicated style bean instead of forcing everything to remain inline.
+
+A practical rule is:
+
+- use local `this.$style(...)` first when the styling is still small
+- move into a dedicated style bean when the page or component needs a clearer styling boundary
+
+This is an organizational split, not a different styling engine. Zova still uses the same CSS-in-JS model; it simply gives larger pages and components a better place to hold their style concerns.
+
+## Shared/global styles with `@Css()` and `$cssBase`
+
+Not every style should stay local.
+
+Use shared/global styles when the application needs reusable style vocabulary that should be available across multiple pages or components.
+
+A practical distinction is:
+
+- use local scoped classes when the style belongs to one page or component
+- use `@Css()` and `$cssBase` when the style should be shared as part of broader app-level styling vocabulary
+
+That is the practical global-style story in Zova: shared styles still live inside the framework model instead of falling back to uncontrolled ad hoc global CSS.
+
+## How styles consume tokens
+
+When a value represents design meaning rather than a one-off literal, prefer `$token` over hardcoded values.
+
+That is especially useful for:
+
+- colors
+  n- spacing or sizing conventions owned by the theme
+- component-surface values that should change with dark mode or brand theme
+
+This keeps style logic flexible across themes and editions without changing the underlying styling architecture.
+
+## Style -> token -> theme flow
+
+A useful mental model is:
+
+1. `this.$style(...)` generates scoped classes
+2. those classes can consume `this.$token`
+3. token values come from the active theme
+4. theme beans provide the concrete token values
+5. runtime theme switching changes the active token set
+
+That means CSS-in-JS, tokens, and themes are not separate ideas. They are one connected frontend styling flow.
+
+For the token and theme lifecycle itself, also see [Theme Guide](/frontend/theme-guide).
+
+## Debugging generated class names
+
+CSS-in-JS class names are framework-generated for scoping, but they still remain debuggable during development.
+
+A practical rule is:
+
+- treat generated class names as framework output rather than as a hand-authored public CSS API
+- use the development-friendly naming help to trace where a style came from when debugging
+
+## Why UI-library independence matters
+
+This is especially important in Cabloy because the two editions diverge in frontend stack choices:
+
+- **Cabloy Basic** aligns with DaisyUI + TailwindCSS oriented examples
+- **Cabloy Start** aligns with Vuetify-oriented modules
+
+A UI-library-independent styling layer makes it easier for the same architectural ideas to survive across both editions.
+
+## Styling in the controller-oriented model
+
+In Zova, styling is not an unrelated afterthought. It fits into the same controller-oriented architecture as state and render logic.
+
+That is why examples often use style generation directly from a controller or style-oriented bean rather than splitting everything into a separate CSS asset by default.
+
+## What stays shared across editions
+
+Across Cabloy Basic and Cabloy Start, the styling architecture itself stays shared:
+
+- CSS-in-JS remains the primary styling model
+- local scoped styles still use `$style`
+- larger styling concerns can still move into dedicated style beans
+- shared/global styling can still use `@Css()` and `$cssBase`
+- token and theme behavior still form the same architecture
+- runtime theme switching still belongs to the same `$theme` model
+
+What may still vary by edition or UI library is:
+
+- token shape details
+- concrete token values
+- theme-handler integration details
+- surrounding utility-class or component-library conventions
+
+That means edition differences usually change the surrounding UI stack, not the core styling architecture.
+
+## Implementation checks for frontend styling changes
+
+When changing frontend styling in Zova, ask:
+
+1. should this use the built-in CSS-in-JS path instead of ad hoc external CSS?
+2. does the style depend on reactive or runtime state?
+3. does the active edition affect only the UI library, while the styling architecture remains shared?
+4. should token or theme mechanisms be used instead of hardcoded values?
+
+That keeps style work aligned with Zova’s actual design.

package/cabloy-docs/frontend/design-principles.md

@@ -0,0 +1,55 @@
+# Frontend Design Principles
+
+This guide explains the core design principles behind Zova in the Cabloy monorepo.
+
+## Intuitive reactivity
+
+Zova keeps Vue3’s reactive strengths, but aims for a code style that feels closer to native variable usage than traditional `ref/reactive`-heavy code.
+
+The practical design goal is not just shorter syntax. It is to keep business code understandable even as the system grows.
+
+## Unified model-based state
+
+A major Zova idea is that multiple state categories can be handled through one model-centered mental model instead of unrelated mechanisms.
+
+Four common categories help explain this model:
+
+- asynchronous server-side data
+- local storage data
+- cookie data
+- in-memory data
+
+In Zova, these are intentionally brought under a more unified `Model` abstraction so SSR support, usage patterns, and maintenance expectations stay more consistent.
+
+## IOC as the sharing model
+
+State and behavior sharing across several scopes can be expressed through IOC rather than a pile of unrelated patterns.
+
+Representative scopes include:
+
+- component-internal sharing
+- between-components sharing
+- app-global sharing
+- system-level sharing
+
+This is one of the clearest reasons Zova code can look different from conventional Vue code while staying structured for large systems.
+
+## IOC + AOP for extensibility
+
+Zova does not treat IOC as only a dependency injection mechanism. It also layers AOP-oriented extensibility on top of IOC so the system can grow without forcing every concern into the same class body.
+
+That is especially valuable for:
+
+- logging
+- cross-cutting behavior
+- internal and external extension points
+- large-scale maintainability
+
+## Practical implications for implementation
+
+These design principles should influence how code is extended in Zova. For the deeper structural model behind these principles, see [IoC and Beans](/frontend/ioc-and-beans), [Modules and Suites](/frontend/modules-and-suites), and [Module Scope](/frontend/module-scope).
+
+- do not rewrite Zova code toward generic Vue habits automatically
+- do not assume `ref.value`-style patterns are the desired end state
+- prefer existing model, IOC, and AOP conventions when extending code
+- verify whether an existing Zova abstraction already solves the problem before introducing a framework-neutral pattern

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,57 @@
+# 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:
+
+- **Cabloy Basic** currently aligns with DaisyUI + TailwindCSS oriented examples
+- **Cabloy Start** aligns with Vuetify-oriented frontend modules and workflows
+
+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.