cabloy 5.1.50 → 5.1.52

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

@@ -0,0 +1,105 @@
+# Component Guide
+
+This guide explains how components work in Zova within the Cabloy monorepo.
+
+## What a component means in Zova
+
+A Zova component is not only a reusable render unit. It is also part of the controller-oriented architecture that gives Zova its specific coding style.
+
+That means component design is closely tied to:
+
+- controller-based logic organization
+- TSX rendering
+- IOC-friendly instance access
+- async-friendly module loading
+- CSS-in-JS styling through the same controller-oriented architecture
+
+For the practical styling decision map around local `$style`, dedicated style beans, shared/global styles, and token/theme surfaces, also see [CSS-in-JS Guide](/frontend/css-in-js-guide).
+
+## Create a component
+
+Example: create a component named `card` in module `demo-student`.
+
+```bash
+npm run zova :create:component card -- --module=demo-student
+```
+
+## Controller definition
+
+Representative component controller shape:
+
+```typescript
+@Controller()
+class ControllerCard extends BeanControllerBase {
+  protected render() {
+    return null;
+  }
+}
+```
+
+## Component wrapper
+
+Zova automatically creates a wrapper component for each component.
+
+Representative example:
+
+- component: `card`
+- wrapper: `ZCard`
+
+The `Z` prefix is useful because it makes framework components easy to identify quickly inside TSX.
+
+## Use a component
+
+Representative usage pattern:
+
+```typescript
+import { ZCard } from 'zova-module-demo-student';
+
+class RenderPageCounter {
+  render() {
+    return <ZCard />;
+  }
+}
+```
+
+## Async loading behavior
+
+Component wrappers can also participate in asynchronous loading behavior automatically.
+
+This matters because the wrapper is not just a naming convenience. It is part of how Zova turns modular code into practical runtime behavior.
+
+## Reference the component instance
+
+Instead of relying on template refs in the usual Vue style, Zova prefers direct access to the component controller instance.
+
+Representative pattern:
+
+```typescript
+import type { ControllerCard } from 'zova-module-demo-student';
+import { ZCard } from 'zova-module-demo-student';
+
+class RenderPageCounter {
+  cardRef: ControllerCard;
+
+  render() {
+    return (
+      <ZCard
+        controllerRef={ref => {
+          this.cardRef = ref;
+        }}
+      />
+    );
+  }
+}
+```
+
+## Practical implications for component implementation
+
+When working on Zova components, do not automatically fall back to generic Vue component habits.
+
+A better default is:
+
+1. use the component generator
+2. preserve the wrapper-based usage model
+3. treat controller access as the primary instance-reference pattern
+4. remember that wrapper behavior and async loading are part of the framework design

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

@@ -0,0 +1,97 @@
+# Component Props Guide
+
+This guide explains how component props work in Zova within the Cabloy monorepo.
+
+## Why Zova props feel different
+
+In Zova, component design does not force a hard separation between `Props`, `Emits`, and `Slots` in the same way many Vue codebases do.
+
+Zova uses a more unified approach centered on component props, which makes the programming model more concise and TypeScript-friendly.
+
+## Add props support
+
+Example: add props support to component `card`.
+
+```bash
+npm run zova :refactor:componentProps card -- --module=demo-student
+```
+
+## Define props
+
+Representative pattern:
+
+```typescript
+import { ISlot } from 'zova';
+
+export interface ControllerCardProps {
+  content?: string;
+  onReset?: () => void;
+  slotHeader?: ISlot;
+  slotDefault?: (name: string) => VNode;
+}
+```
+
+This is important because the props contract can describe ordinary values, callbacks, and slot-like behavior in one consistent shape.
+
+## Default values
+
+Representative pattern:
+
+```typescript
+class ControllerCard {
+  static $propsDefault = {
+    content: 'no content',
+  };
+}
+```
+
+## Use props in the controller
+
+Zova injects `$props` into the controller base class.
+
+Representative pattern:
+
+```typescript
+class ControllerCard {
+  render() {
+    return (
+      <div>
+        <div>{this.$props.slotHeader?.()}</div>
+        <div>{this.$slotDefault?.('tom')}</div>
+        <div>{this.$props.content}</div>
+        <button onClick={() => this.$props.onReset?.()}>Reset</button>
+      </div>
+    );
+  }
+}
+```
+
+## Pass props to child components
+
+Representative pattern:
+
+```typescript
+<ZCard
+  content="custom content"
+  onReset={() => {
+    console.log('onReset is invoked');
+  }}
+  slotHeader={() => {
+    return <div>custom header</div>;
+  }}
+  slotDefault={name => {
+    return <div>{name}</div>;
+  }}
+/>
+```
+
+## Practical implications for component API design
+
+When creating or refactoring Zova components, do not automatically impose a generic Vue component API style.
+
+A better default is:
+
+1. use the Zova refactor command to add the props skeleton
+2. keep the props contract explicit and typed
+3. treat props as the main contract surface for values, callbacks, and slot-like behavior
+4. preserve the controller-oriented way of consuming props inside the component

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