cabloy 5.1.59 → 5.1.60

package/cabloy-docs/fullstack/tutorial-3-frontend-metadata-sharing.md

@@ -0,0 +1,131 @@
+# Tutorial 3: Frontend Metadata Sharing
+
+<Badge type="info" text="Basic" />
+
+In this tutorial, one prompt lets AI show the reverse direction of Cabloy’s fullstack contract loop: backend field metadata can reference frontend render resources.
+
+You start with the simplest path first: reuse the existing built-in rendering resources for the `level` field.
+
+## Goal
+
+By the end of this tutorial, you will understand:
+
+- why Cabloy fullstack sharing is bidirectional
+- how a backend field can reuse frontend rendering resources through metadata
+- how one `level` field can participate in schema-driven form and table behavior without a custom component yet
+
+## AI Prompt
+
+Give AI a prompt like this:
+
+```text
+Please add a level field to the Student resource. It should be a number field with these enum values:
+
+- 1: beginner
+- 2: intermediate
+- 3: advanced
+```
+
+## Why this step matters
+
+This is the right step because it teaches one very specific Cabloy distinction.
+
+The goal is not to make backend and frontend share arbitrary component code. The goal is to keep the backend field contract in charge while letting that contract reference frontend render resources through metadata.
+
+In other words, this step is about **frontend metadata sharing**: the backend field contract references frontend render resources through metadata.
+
+## CLI commands to inspect/use
+
+This tutorial is mainly a contract-refinement step, so the most important habit is inspection before editing.
+
+Useful discovery commands from the repo root:
+
+```bash
+npm run vona :
+npm run zova :
+npm run zova :create
+```
+
+You usually do **not** need to generate a custom bean in this tutorial.
+
+Instead, inspect the current contract surfaces first:
+
+- `vona/src/module/demo-student/src/entity/student.tsx`
+- `vona/src/module/demo-student/src/dto/studentSelectReq.tsx`
+
+Usage notes:
+
+- keep the backend entity as the main source of truth for the `level` field
+- prefer built-in frontend render resources first
+- delay custom renderer authoring to the next tutorial
+
+## Generated or affected files
+
+The key backend contract anchor is:
+
+- `vona/src/module/demo-student/src/entity/student.tsx`
+
+By the end of this tutorial, the `level` field should follow a built-in path like this:
+
+```typescript
+@Api.field(
+  v.title($locale('Level')),
+  v.required(),
+  ZovaRender.order(3),
+  ZovaRender.field('basic-select:formFieldSelect', {
+    items: levelItems,
+    placeholder: $locale('LevelPlaceholder'),
+  }),
+  ZovaRender.cell('basic-select:select', { items: levelItems }),
+  levelSchema,
+)
+level: number;
+```
+
+A related DTO anchor is:
+
+- `vona/src/module/demo-student/src/dto/studentSelectReq.tsx`
+
+That DTO already shows how filter-side field metadata can also participate in schema-driven UI.
+
+## What those files mean in the business thread
+
+This tutorial teaches one core mental model:
+
+- the backend still owns the business field contract
+- the frontend still owns the render resources
+- metadata is the bridge between them
+
+Concretely:
+
+- `entity/student.tsx` defines `level` as a real business field
+- `levelItems` gives that field a stable set of business options
+- `ZovaRender.field('basic-select:formFieldSelect', ...)` makes the form side schema-aware
+- `ZovaRender.cell('basic-select:select', ...)` makes the table side schema-aware
+- `dto/studentSelectReq.tsx` reminds you that filter-side metadata is also part of the same contract story
+
+At this stage, you do not need a custom frontend component to understand the reverse-sharing model.
+
+## Verification
+
+1. make sure the local dev workflow is running:
+
+```bash
+npm run dev
+```
+
+2. open `http://localhost:7102/admin/`
+3. enter the **Student** list page from the **Student** menu
+4. verify that the `level` field appears with select-style behavior in the relevant schema-driven surfaces
+5. inspect `vona/src/module/demo-student/src/entity/student.tsx` and confirm that the backend field contract now points to built-in frontend render resources instead of page-local hard-coded UI logic
+
+## Read more
+
+- [Frontend Metadata Back to Backend](/fullstack/frontend-metadata-to-backend)
+- [API Schema Guide](/frontend/api-schema-guide)
+- [Server Data](/frontend/server-data)
+- [Frontend CLI](/frontend/cli)
+
+## Next step
+
+Continue to [Tutorial 4: Custom Form/Table Renderers for Level](/fullstack/tutorial-4-custom-level-renderers).

package/cabloy-docs/fullstack/tutorial-4-custom-level-renderers.md

@@ -0,0 +1,119 @@
+# Tutorial 4: Custom Form/Table Renderers for Level
+
+<Badge type="info" text="Basic" />
+
+In this tutorial, one prompt lets AI upgrade the `level` field from built-in render resources to custom frontend renderers owned by the `demo-student` module.
+
+## Goal
+
+By the end of this tutorial, you will understand:
+
+- when built-in render metadata is enough and when a custom renderer is worth adding
+- how a frontend table cell bean and a frontend form-field component can both serve the same backend field
+- how backend metadata points to module-owned frontend render resources
+
+## AI Prompt
+
+Give AI a prompt like this:
+
+```text
+Please make the level UI more business-specific in the Student list page and form.
+```
+
+## Why this step matters
+
+This is the right follow-up step because built-in render resources are a good starting point, but some business fields eventually need module-specific behavior.
+
+The `level` field is a good teaching example because this step deepens the UI in two concrete ways:
+
+- a custom table cell that renders a more business-specific badge style
+- a custom form field that adds helper text, readonly behavior, or module-specific select styling
+
+This is where Cabloy’s contract model becomes more practical: the backend field still owns the business contract, while the frontend module progressively deepens the UI behavior behind that contract.
+
+## CLI commands to inspect/use
+
+Inspect the Zova create surface first:
+
+```bash
+npm run zova :create
+npm run zova :create:bean --help
+npm run zova :create:component --help
+```
+
+Representative generation commands for this tutorial:
+
+```bash
+npm run zova :create:bean tableCell level -- --module=demo-student
+npm run zova :create:component formFieldLevel -- --module=demo-student
+```
+
+Usage notes:
+
+- use `:create:bean` when you need a table-cell render resource under the bean scene
+- use `:create:component` when you need a custom frontend component/controller surface
+- generation gives you the structural starting point, but this tutorial still expects manual refinement so the result matches the `demo-student` teaching implementation
+- after frontend resources exist, return to the backend entity and point `ZovaRender.field(...)` and `ZovaRender.cell(...)` at the custom module resources
+
+## Generated or affected files
+
+By the end of this tutorial, your module should provide these teaching anchors:
+
+- custom table cell bean:
+  - `zova/src/module/demo-student/src/bean/tableCell.level.tsx`
+- custom form-field controller:
+  - `zova/src/module/demo-student/src/component/formFieldLevel/controller.tsx`
+- form-field metadata wrapper:
+  - `zova/src/module/demo-student/src/.metadata/component/formFieldLevel.ts`
+- backend field contract to update:
+  - `vona/src/module/demo-student/src/entity/student.tsx`
+
+Representative custom metadata targets are:
+
+```typescript
+ZovaRender.field('demo-student:formFieldLevel', {
+  items: levelItems,
+  helper: $locale('LevelPlaceholder'),
+})
+```
+
+and:
+
+```typescript
+ZovaRender.cell('demo-student:level', { items: levelItems })
+```
+
+## What those files mean in the business thread
+
+This tutorial makes the split of responsibilities explicit:
+
+- `tableCell.level.tsx` owns the custom table-cell rendering behavior for `level`
+- `component/formFieldLevel/controller.tsx` owns the custom form-field behavior for `level`
+- `.metadata/component/formFieldLevel.ts` exposes that component through the module registration surface
+- `entity/student.tsx` remains the backend-owned business contract that chooses which frontend resources should render the field
+
+That means the backend still defines the business field, validation, and metadata entry point, while the frontend module owns the implementation details of the richer UI behavior.
+
+## Verification
+
+1. make sure the local dev workflow is running:
+
+```bash
+npm run dev
+```
+
+2. open `http://localhost:7102/admin/`
+3. enter the **Student** list page and verify that the `level` column now uses the custom table-cell presentation
+4. open a Student create, update, or view form and verify that the `level` field now uses the custom form-field behavior
+5. inspect `vona/src/module/demo-student/src/entity/student.tsx` and confirm that the backend metadata now points to `demo-student:formFieldLevel` and `demo-student:level`
+
+## Read more
+
+- [Frontend Metadata Back to Backend](/fullstack/frontend-metadata-to-backend)
+- [Frontend CLI](/frontend/cli)
+- [Component Guide](/frontend/component-guide)
+- [Bean Scene Boilerplate Variants](/reference/bean-scene-boilerplates)
+
+## Next step
+
+Continue to [Tutorial 5: Backend Contract Sharing](/fullstack/tutorial-5-backend-contract-sharing).

package/cabloy-docs/fullstack/tutorial-5-backend-contract-sharing.md

@@ -0,0 +1,144 @@
+# Tutorial 5: Backend Contract Sharing
+
+<Badge type="info" text="Basic" />
+
+In this tutorial, one prompt lets AI show the forward direction of Cabloy’s fullstack contract loop: backend API contracts that generate and refresh the frontend consumption surface.
+
+The teaching thread in this page is the pair of Student actions:
+
+- `summary/:id`
+- `deleteForce/:id`
+
+## Goal
+
+By the end of this tutorial, you will understand:
+
+- how a backend controller and DTO change becomes frontend generated API output
+- how backend row-action metadata can drive frontend table actions
+- how generated API, frontend model helpers, and row-action beans fit into one contract-sharing workflow
+
+## AI Prompt
+
+Give AI a prompt like this:
+
+```text
+Please add two custom actions to the Student list:
+
+- Summary: return or display a student summary for the selected row
+- Force Delete: permanently delete the selected student through a dedicated row action
+
+Make both actions work end to end, from the backend contract to the Student list page.
+```
+
+## Why this step matters
+
+This is the right step because it reduces duplicated type work across backend and frontend.
+
+Instead of manually synchronizing request and response shapes in two places, this workflow keeps the backend as the source of truth and regenerates the frontend artifacts from that contract.
+
+This step also shows that contract sharing is not only about API methods. It also affects how backend row-action metadata becomes frontend table behavior.
+
+## CLI commands to inspect/use
+
+Inspect the relevant command surfaces first:
+
+```bash
+npm run zova :openapi
+npm run zova :openapi:config demo-student
+npm run zova :openapi:generate demo-student
+```
+
+If your workflow also needs refreshed rest-contract output for Cabloy Basic, the related build commands are:
+
+```bash
+cd zova && npm run build:rest:cabloyBasicAdmin
+cd zova && npm run build:rest:cabloyBasicWeb
+```
+
+Usage notes:
+
+- use the backend controller and DTOs as the starting point
+- inspect the module OpenAPI config before generation
+- prefer regeneration over hand-written duplicate API layers when the module already owns an OpenAPI contract surface
+
+## Generated or affected files
+
+The backend contract anchors are:
+
+- `vona/src/module/demo-student/src/controller/student.ts`
+- `vona/src/module/demo-student/src/dto/studentSummary.tsx`
+- `vona/src/module/demo-student/src/dto/studentSelectResItem.tsx`
+
+By the end of this tutorial, your `demo-student` controller should expose:
+
+```typescript
+@Web.get('summary/:id')
+async summary(...) { ... }
+
+@Web.delete('deleteForce/:id')
+async deleteForce(...) { ... }
+```
+
+The frontend contract and consumption anchors are:
+
+- OpenAPI config:
+  - `zova/src/module/demo-student/cli/openapi.config.ts`
+- generated frontend API:
+  - `zova/src/module/demo-student/src/api/demoStudent.ts`
+- frontend model wrapper:
+  - `zova/src/module/demo-student/src/model/student.ts`
+- custom row-action cells:
+  - `zova/src/module/demo-student/src/bean/tableCell.actionSummary.tsx`
+  - `zova/src/module/demo-student/src/bean/tableCell.actionDeleteForce.tsx`
+
+After regeneration, `src/api/demoStudent.ts` should contain generated methods such as:
+
+- `summary(...)`
+- `deleteForce(...)`
+
+## What those files mean in the business thread
+
+This tutorial is easiest to understand as one contract chain:
+
+1. `controller/student.ts` defines the backend action endpoints
+2. `dto/studentSummary.tsx` defines the response contract for the summary action
+3. `dto/studentSelectResItem.tsx` defines the row-action metadata that exposes those actions in the Student list page
+4. `cli/openapi.config.ts` tells the frontend module which backend operations it owns
+5. `src/api/demoStudent.ts` is the generated typed API surface created from that backend contract
+6. `src/model/student.ts` wraps the generated API in frontend business-facing helper methods
+7. `tableCell.actionSummary.tsx` and `tableCell.actionDeleteForce.tsx` turn those model methods into visible row actions
+
+That is the practical contract-sharing loop: backend controller and DTO truth flows into generated frontend API output, then into frontend model helpers, and finally into visible table actions.
+
+## Verification
+
+1. make sure the local dev workflow is running:
+
+```bash
+npm run dev
+```
+
+2. open `http://localhost:7102/admin/`
+3. enter the **Student** list page
+4. trigger the **Summary** row action and verify that it uses the regenerated frontend API and returns the expected Student summary data
+5. trigger the **Force Delete** row action and verify that it reaches the custom backend deleteForce contract path
+6. inspect the source chain and confirm that each layer is present:
+   - `controller/student.ts`
+   - `dto/studentSummary.tsx`
+   - `dto/studentSelectResItem.tsx`
+   - `src/api/demoStudent.ts`
+   - `src/model/student.ts`
+   - `tableCell.actionSummary.tsx`
+   - `tableCell.actionDeleteForce.tsx`
+
+## Read more
+
+- [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk)
+- [OpenAPI Guide](/backend/openapi-guide)
+- [OpenAPI SDK Guide](/frontend/openapi-sdk-guide)
+- [SDK Guide](/frontend/sdk-guide)
+- [Server Data](/frontend/server-data)
+
+## Next step
+
+Continue to [Tutorial 6: One Contract Surface, Four Uses](/fullstack/tutorial-6-one-contract-four-uses).

package/cabloy-docs/fullstack/tutorial-6-one-contract-four-uses.md

@@ -0,0 +1,168 @@
+# Tutorial 6: One Contract Surface, Four Uses
+
+<Badge type="info" text="Basic" />
+
+In this tutorial, one prompt lets AI close the series by showing Cabloy’s core fullstack idea: one field-oriented contract surface can drive several behaviors across backend and frontend.
+
+This time the main teaching field is `mobile`, while `level` stays as the supporting example for table and form rendering.
+
+## Goal
+
+By the end of this tutorial, you will understand how one business field thread can participate in:
+
+1. validation
+2. OpenAPI generation
+3. table and form rendering
+4. serialization or desensitization
+
+## AI Prompt
+
+Give AI a prompt like this:
+
+```text
+Please add a mobile field to the Student resource. It should be required, be at least 11 characters long, and show the middle 4 digits as asterisks in returned data.
+```
+
+## Why this step matters
+
+This is the right capstone step because many frameworks force the same field knowledge to be repeated in many places:
+
+- validation rules
+- backend DTOs
+- API documentation
+- frontend forms
+- frontend tables
+- response masking logic
+
+Cabloy tries to reduce that duplication through a field-oriented contract and metadata model, and this tutorial lets you inspect that reduction through one concrete field story.
+
+## CLI commands to inspect/use
+
+This tutorial is mainly a source-inspection and verification capstone.
+
+Useful commands include:
+
+```bash
+npm run zova :openapi:generate demo-student
+npm run dev
+```
+
+Usage notes:
+
+- regenerate the frontend contract if your backend field changes affect the generated output
+- treat the backend entity and DTO surfaces as the first place to inspect
+- use the admin UI to confirm both the visible rendering result and the exposed mobile behavior
+
+## Generated or affected files
+
+The key backend field contract anchor is:
+
+- `vona/src/module/demo-student/src/entity/student.tsx`
+
+By the end of this tutorial, the `mobile` field should show the main capstone pattern:
+
+```typescript
+@Api.field(
+  v.title($locale('Mobile')),
+  v.required(),
+  v.min(11),
+  studentMobileSerializer(),
+  ZovaRender.order(4),
+)
+mobile: string;
+```
+
+The serializer helper lives in:
+
+- `vona/src/module/demo-student/src/lib/studentMobile.ts`
+
+The summary DTO also participates in the same thread:
+
+- `vona/src/module/demo-student/src/dto/studentSummary.tsx`
+
+The supporting render example remains:
+
+- `vona/src/module/demo-student/src/entity/student.tsx`
+  - `ZovaRender.field(...)` for `level`
+  - `ZovaRender.cell(...)` for `level`
+
+## What those files mean in the business thread
+
+This tutorial works best when you read `mobile` as one continuous contract thread.
+
+That is why `mobile` is the main capstone field, while `level` remains the supporting rendering field.
+
+### Use 1: Validation
+
+In `entity/student.tsx`, `mobile` already carries validation decisions such as:
+
+- `v.required()`
+- `v.min(11)`
+
+That means the field definition is part of the request-contract story, not only a persistence concern.
+
+### Use 2: OpenAPI generation
+
+The same field contract participates in DTO and controller flows, which then feed machine-readable API output.
+
+That is why backend field and DTO changes can later affect what frontend regeneration sees.
+
+### Use 3: Table and form rendering
+
+The main rendering example in this series remains `level`, not `mobile`.
+
+That is intentional.
+
+`level` shows how the same field-oriented contract can carry:
+
+- `ZovaRender.field(...)`
+- `ZovaRender.cell(...)`
+- built-in or custom frontend render resources
+
+This keeps the “four uses” explanation complete without forcing `mobile` to act like the best rendering example.
+
+### Use 4: Serialization and desensitization
+
+The most practical `mobile` lesson is response exposure policy.
+
+In `studentMobile.ts`, the helper:
+
+- defines the masking pattern
+- returns `v.serializerReplace(...)`
+
+That keeps the masking rule close to the field contract ecosystem instead of scattering it into ad hoc controller or service post-processing.
+
+## Verification
+
+1. make sure the local dev workflow is running:
+
+```bash
+npm run dev
+```
+
+2. open `http://localhost:7102/admin/`
+3. enter the relevant **Student** page
+4. verify that `level` still shows the expected render-driven behavior
+5. verify that `mobile` follows the validation and serialization policy you defined
+6. inspect these anchors and confirm that the four-use story is concrete rather than abstract:
+   - `vona/src/module/demo-student/src/entity/student.tsx`
+   - `vona/src/module/demo-student/src/lib/studentMobile.ts`
+   - `vona/src/module/demo-student/src/dto/studentSummary.tsx`
+
+## Read more
+
+- [Validation Guide](/backend/validation-guide)
+- [OpenAPI Guide](/backend/openapi-guide)
+- [API Schema Guide](/frontend/api-schema-guide)
+- [Server Data](/frontend/server-data)
+- [Serialization Guide](/backend/serialization-guide)
+- [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk)
+- [Frontend Metadata Back to Backend](/fullstack/frontend-metadata-to-backend)
+
+## Next step
+
+After finishing this series, choose the next path based on your current task:
+
+- if you want deeper backend contract detail, continue with [Entity Guide](/backend/entity-guide) and [DTO Guide](/backend/dto-guide)
+- if you want deeper frontend contract consumption, continue with [OpenAPI SDK Guide](/frontend/openapi-sdk-guide) and [API Schema Guide](/frontend/api-schema-guide)
+- if you want more CLI-oriented workflow depth, continue with [CLI Reference](/reference/cli-reference)