cabloy 5.1.96 → 5.1.98

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

@@ -0,0 +1,512 @@
+# Image Guide
+
+This guide explains how to use **Zova image** in Cabloy Basic with a practical, contract-first path.
+
+Zova image is not only a file input. It is a frontend image layer built around:
+
+- the built-in form-field renderer `basic-image:formFieldImage`
+- the built-in table-cell renderer `basic-image:image`
+- resolved relation fields such as `image` and `sceneImages`
+- upload-token based upload through the generated image API
+- optional crop and resize behavior in the browser
+- shared preview dialogs for form and table usage
+
+Use this page together with:
+
+- [Form Guide](/frontend/form-guide)
+- [Table Guide](/frontend/table-guide)
+- [TableCell Authoring Cookbook](/frontend/table-cell-cookbook)
+- [API Schema Guide](/frontend/api-schema-guide)
+- [SSR ClientOnly](/frontend/ssr-client-only)
+- [Backend Image Guide](/backend/image-guide)
+
+> [!TIP]
+> **Image docs path**
+>
+> - **[Frontend Image Guide](/frontend/image-guide)** — learn `basic-image:formFieldImage`, `basic-image:image`, relation previews, and client-side image-field behavior
+> - **[Backend Image Guide](/backend/image-guide)** — learn image scenes, providers, serializer transforms, delivery policy, and backend lifecycle behavior
+>
+> Use the frontend guide when the question is about forms, tables, previews, or client-side upload UX. Use the backend guide when the question is about image scenes, providers, serializer transforms, signed delivery, or upload policy enforcement.
+
+Read this page first when your next question is:
+
+- how to wire `basic-image:formFieldImage` into a form
+- how to show image thumbnails in a table with `basic-image:image`
+- why an image field has IDs on one side and resolved relation fields on the other
+
+## What you should learn first
+
+If you only remember one idea, remember this one:
+
+> In Zova, an image field usually stores image ID data, while resolved relation fields provide the `DtoImageView` objects that the built-in image renderers use for previews, dialogs, and richer display.
+
+That leads to two closely related data surfaces:
+
+- persisted value such as `imageId` or `sceneImageIds`
+- resolved relation field such as `image` or `sceneImages`
+
+The built-in image resources work best when both surfaces are present and named consistently.
+
+## What `basic-image` provides on the frontend
+
+The `basic-image` module exposes two main public rendering resources.
+
+### `basic-image:formFieldImage`
+
+Use this as the standard image field renderer for forms.
+
+It supports:
+
+- single-image and multi-image fields
+- upload-token based upload
+- frontend file validation
+- optional crop
+- optional resize and re-encode before upload
+- readonly image cards
+- relation-backed preview refresh after upload
+
+### `basic-image:image`
+
+Use this as the standard image table-cell renderer.
+
+It supports:
+
+- thumbnail rendering
+- relation-first preview lookup
+- fallback URL preview behavior
+- multi-image count badges
+- shared preview dialog opening from the table cell
+
+### Shared preview behavior
+
+Both resources use the same preview conventions:
+
+- preview URLs are normalized against `sys.config.api.baseURL` when needed
+- preview titles use the field title when available
+- multi-image preview supports keyboard left/right navigation
+
+## Minimum backend/frontend contract
+
+The frontend image resources depend on a small but important backend contract.
+
+A practical minimum is:
+
+1. the backend field stores image ID data such as `imageId` or `sceneImageIds`
+2. the backend field metadata points to the built-in render resources
+3. the backend DTO exposes resolved relation fields such as `image?: DtoImageView` or `sceneImages?: DtoImageView[]`
+4. the backend image scene defines the authoritative upload policy
+
+Representative contract pattern:
+
+```typescript
+ZovaRender.field('basic-image:formFieldImage', {
+  imageScene: 'training-student:studentImage',
+  relationName: 'image',
+});
+
+ZovaRender.cell('basic-image:image', {
+  relationName: 'image',
+});
+```
+
+And on the DTO side:
+
+```typescript
+v.serializerTransform('a-image:resolveView', {
+  fieldName: 'imageId',
+  imageScene: 'training-student:studentImage',
+});
+```
+
+A practical rule is:
+
+- frontend validation, crop, and resize improve UX
+- backend image scenes and backend upload-token verification remain the true policy boundary
+
+For the backend side of that contract, read [Backend Image Guide](/backend/image-guide), especially the sections on image scenes, upload-token flow, and DTO-side image view resolution.
+
+## One running example through this guide: Student image
+
+To keep the guide concrete, the first example uses the Student resource.
+
+The Student entity stores one image field:
+
+```typescript
+@Api.field(
+  v.title($locale('StudentImage')),
+  v.optional(),
+  ZovaRender.field('basic-image:formFieldImage', {
+    imageScene: 'training-student:studentImage',
+    accept: ['image/png', 'image/jpeg', 'image/webp'],
+    maxSize: 2 * 1024 * 1024,
+    enableCrop: true,
+    cropAspectRatio: 1,
+    relationName: 'image',
+    resize: {
+      width: 512,
+      height: 512,
+      fit: 'cover',
+      format: 'jpeg',
+      quality: 90,
+    },
+  }),
+  ZovaRender.cell('basic-image:image', { relationName: 'image' }),
+  v.tableIdentity(),
+)
+imageId?: TableIdentity;
+```
+
+And the DTO exposes a resolved relation field:
+
+```typescript
+@Api.field(
+  ZovaRender.visible(false),
+  v.optional(),
+  v.serializerTransform('a-image:resolveView', {
+    fieldName: 'imageId',
+    imageScene: 'training-student:studentImage',
+  }),
+  v.object(DtoImageView),
+)
+image?: DtoImageView;
+```
+
+This gives the frontend a clean split:
+
+- `imageId` is the submitted field value
+- `image` is the resolved relation field
+
+The backend explanation for that pairing lives in [Backend Image Guide](/backend/image-guide), where the same example is described from the scene and serializer-transform perspective.
+
+## Step 1: Choose the right image field style
+
+Before writing code, choose which of these styles matches your field.
+
+### Style A: built-in image resources
+
+Use this when:
+
+- standard upload, preview, and thumbnail behavior is enough
+- the field should stay schema-driven
+- you want the shortest path to a working CRUD field
+
+This is the preferred default.
+
+### Style B: built-in image field plus custom backend contract
+
+Use this when:
+
+- the frontend UX can stay standard
+- but the backend scene, DTO, or relation structure is business-specific
+- the field still fits the `basic-image` mental model
+
+### Style C: custom image renderer
+
+Use this when:
+
+- the form interaction is business-specific
+- the table thumbnail behavior must be custom
+- built-in crop, preview, or value flow is not enough
+
+A practical rule is:
+
+- start with the built-in image resources first
+- add custom renderers only when the business UI really needs module-owned image behavior
+
+## Step 2: Understand relation naming and `relationName`
+
+The built-in image resources infer relation names from the stored field name.
+
+Current inference rules are:
+
+- `imageId` -> `image`
+- `sceneImageIds` -> `sceneImages`
+
+That is why the Student example can naturally pair:
+
+- `imageId`
+- `image`
+
+and the Record example can naturally pair:
+
+- `sceneImageIds`
+- `sceneImages`
+
+Use explicit `relationName` when:
+
+- the field name does not follow the `...Id` or `...Ids` pattern
+- you want the contract to be more obvious in examples and maintenance
+- nested or details flows should avoid any ambiguity
+
+Even when inference would work, setting `relationName` explicitly is often a good public-doc choice because it makes the pairing obvious.
+
+## Step 3: Understand `basic-image:formFieldImage`
+
+`basic-image:formFieldImage` is the main form-side image renderer.
+
+### Default behavior
+
+The current defaults include:
+
+- `accept: ['image/png', 'image/jpeg', 'image/webp']`
+- `maxCount: 1`
+- `enableCrop: true`
+- `cropAspectRatio: 1`
+- `cropShape: 'rect'`
+- `resize: { width: 512, height: 512, fit: 'cover', format: 'jpeg', quality: 90 }`
+
+These defaults are helpful, but they are not a replacement for explicit business intent.
+
+### Important options
+
+#### Required in practice
+
+- `imageScene`
+
+Although the option shape is optional at the type level, upload currently throws if no image scene is provided.
+
+#### Value-shape options
+
+- `multiple`
+- `maxCount`
+
+These control whether the field behaves like one image ID or an array of image IDs.
+
+#### File-selection and validation options
+
+- `accept`
+- `mimeTypes`
+- `extensions`
+- `maxSize`
+- `minSize`
+- `placeholder`
+
+These affect frontend input behavior and frontend validation messaging.
+
+#### Crop options
+
+- `enableCrop`
+- `cropAspectRatio`
+- `cropShape`
+
+These control the optional crop dialog.
+
+#### Resize options
+
+- `resize.width`
+- `resize.height`
+- `resize.fit`
+- `resize.background`
+- `resize.quality`
+- `resize.format`
+
+These control browser-side preprocessing before upload.
+
+#### Relation option
+
+- `relationName`
+
+Use this to pair the stored field with its resolved relation field explicitly.
+
+## Step 4: Understand the upload lifecycle
+
+The built-in form field follows a consistent frontend flow.
+
+1. the user selects a file or files
+2. the frontend validates the file type and size
+3. if enabled, the crop dialog opens
+4. if configured, the browser resizes and re-encodes the image
+5. the frontend calls `scope.api.image.createUploadToken(...)`
+6. the frontend uploads multipart data with `token` and `image`
+7. the stored field value is updated to the uploaded image ID or image ID array
+8. the resolved relation field is synchronized so the form can preview the uploaded image immediately
+
+That last step is easy to miss, but it is one of the most important behaviors in the current implementation.
+
+The field value stores IDs.
+
+The resolved relation field stores preview-ready image objects.
+
+## Step 5: Readonly and preview behavior
+
+The built-in form field keeps image previews useful even outside edit mode.
+
+### Editable mode
+
+In editable mode, the field shows:
+
+- select/add/replace button
+- upload spinner
+- validation or upload error message
+- preview cards for current images
+- preview button per image
+- remove button per image
+
+### Readonly mode
+
+In readonly mode, the field still renders preview cards.
+
+If no images are available, it shows a lightweight empty-state message instead of a file input.
+
+### Preview dialog
+
+When an image preview is available, the field opens a shared preview dialog that supports:
+
+- large lead image preview
+- filename display
+- multi-image thumbnail selection
+- `1 / N` style counters
+- left/right keyboard navigation
+
+## Step 6: Use the multi-image pattern when the business field is plural
+
+The Record example shows the multi-image case.
+
+Entity pattern:
+
+```typescript
+@Api.field(
+  v.title($locale('ScenePhotos')),
+  v.optional(),
+  ZovaRender.field('basic-image:formFieldImage', {
+    imageScene: 'training-record:sceneImage',
+    multiple: true,
+    maxCount: 9,
+    relationName: 'sceneImages',
+    accept: ['image/png', 'image/jpeg', 'image/webp'],
+    maxSize: 2 * 1024 * 1024,
+    enableCrop: false,
+    resize: {
+      width: 1280,
+      height: 1280,
+      fit: 'contain',
+      format: 'jpeg',
+      quality: 90,
+    },
+  }),
+  ZovaRender.cell('basic-image:image', { relationName: 'sceneImages' }),
+  v.array(v.tableIdentity()),
+)
+sceneImageIds?: TableIdentity[];
+```
+
+DTO pattern:
+
+```typescript
+@Api.field(
+  ZovaRender.visible(false),
+  v.optional(),
+  v.serializerTransform('a-image:resolveViews', {
+    fieldName: 'sceneImageIds',
+    imageScene: 'training-record:sceneImage',
+  }),
+  v.array(DtoImageView),
+)
+sceneImages?: DtoImageView[];
+```
+
+This is the cleanest pattern when the business field should store many image IDs while the UI needs many preview-ready image objects.
+
+## Step 7: Understand `basic-image:image` in tables
+
+`basic-image:image` is the standard image table-cell renderer.
+
+### Public options
+
+- `size` — defaults to `40`
+- `fit` — defaults to `cover`
+- `relationName`
+
+### Runtime behavior
+
+The cell renderer:
+
+- reads the normal table cell value through `next()`
+- tries resolved relation field data first
+- falls back to treating the cell value as URL or URL array data
+- renders a thumbnail
+- adds a `+N` badge when multiple images exist
+- opens the shared preview dialog on click
+- stops row-click propagation while opening the preview
+
+A practical rule is:
+
+- if the table should show reliable image thumbnails from ID-backed fields, make sure the row data includes the matching resolved relation field
+
+## Step 8: Keep details and nested forms relation-aware
+
+There is an important special case in the details flow.
+
+The `basic-details` service currently special-cases `basic-image:formFieldImage` so submitted detail items keep the resolved relation field data.
+
+That matters because nested or detail-based image editing should preserve:
+
+- the stored image ID data
+- the resolved relation field data
+
+If your image field appears in details or nested form flows, make sure:
+
+- the matching resolved relation field exists
+- the field name follows the expected naming rule, or `relationName` is set explicitly
+
+Without that relation pairing, image IDs may still save correctly while preview behavior becomes weaker or incomplete in the detail UI.
+
+## Step 9: Remember the SSR and client-only boundary
+
+Crop and resize are browser-side behaviors.
+
+The current implementation relies on:
+
+- `ClientOnly`
+- browser `File`
+- browser `Image`
+- browser `canvas`
+- object URLs
+
+That means:
+
+- existing preview data can still render in SSR-safe flows
+- crop and resize behavior only happens on the client
+- the guide should not describe crop or resize as SSR features
+
+For the general boundary, read [SSR ClientOnly](/frontend/ssr-client-only).
+
+## Common mistakes to avoid
+
+When image fields misbehave, these are the first mistakes to check.
+
+1. **Forgetting `imageScene`**
+   - the field may render, but upload cannot work correctly
+2. **Treating frontend validation as the security boundary**
+   - backend image scene policy is still authoritative
+3. **Storing only image IDs without exposing resolved relation fields**
+   - previews, cards, and table thumbnails become weaker
+4. **Relying on inferred relation names when the field name is nonstandard**
+   - set `relationName` explicitly instead
+5. **Forgetting `multiple: true` for array-backed fields**
+   - the UI and data shape will drift apart
+6. **Describing crop or resize as backend processing**
+   - current crop and resize are frontend preprocessing steps before upload
+7. **Ignoring details/nested-form relation behavior**
+   - saved data may be correct while preview state becomes fragile
+
+## Verification checklist
+
+When writing or changing frontend image docs, verify in this order.
+
+1. confirm the form-field resource is still `basic-image:formFieldImage`
+2. confirm the table-cell resource is still `basic-image:image`
+3. confirm option names still match the current controller and table-cell source
+4. confirm relation-name inference still matches:
+   - `imageId -> image`
+   - `...Ids -> ...s`
+5. confirm the Student example still shows the single-image pattern
+6. confirm the Record example still shows the multi-image pattern
+7. confirm the details service still preserves image relation data specially
+8. run the docs build and confirm the page appears in navigation
+
+A good final question is:
+
+- does this explanation stay frontend-first and contract-aware, or has it drifted into a backend image internals article?
+
+If it stays centered on image fields, relation previews, table thumbnails, upload lifecycle, and client-side behavior, it matches how Zova image currently works.

package/cabloy-docs/frontend/introduction.md

@@ -41,6 +41,7 @@ Recommended starting set:
 - [Quickstart](/frontend/quickstart)
 - [Foundation](/frontend/foundation)
 - [Reading Zova for Vue Developers](/frontend/reading-zova-for-vue-developers)
+- [State Architecture for Vue Developers](/frontend/state-architecture-for-vue-developers)
 - [Frontend Source Reading Roadmap](/frontend/frontend-source-reading-roadmap)
 - [Zova Source Reading Map](/frontend/zova-source-reading-map)
 - [IoC and Beans](/frontend/ioc-and-beans)
@@ -79,6 +80,7 @@ Use this path when the task is about UI composition, component contracts, form o
 
 - [Component Guide](/frontend/component-guide)
 - [Form Guide](/frontend/form-guide)
+- [Image Guide](/frontend/image-guide)
 - [Zova Form Under the Hood](/frontend/zova-form-under-the-hood)
 - [Zova Form Source Reading Map](/frontend/zova-form-source-reading-map)
 - [Table Guide](/frontend/table-guide)

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

@@ -8,14 +8,45 @@ That matters because state sharing, resource access, lifecycle behavior, and cro
 
 ## The four state-sharing scopes
 
-A key Zova idea is that several common sharing scopes can be handled through one IoC-centered model:
+A key Zova idea is that several common sharing scopes can be handled through one IoC-centered model.
+
+In many Vue 3 codebases, developers combine local reactive state, composables, `provide/inject`, and store layers depending on where sharing must happen. Zova asks a different first question: which bean owns this state or behavior, and which container scope should own that bean?
 
 - component-internal
 - between-components
 - app-global
 - system-level
 
-This replaces the need to switch constantly between unrelated mechanisms for each sharing scope.
+| Sharing scope      | Common Vue 3 pattern                                       | Zova implementation shape                                                          |
+| ------------------ | ---------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| component-internal | local component state or component-local composables       | `ctx`-scoped controller or bean ownership                                          |
+| between-components | props/emits, parent-owned composables, or `provide/inject` | hierarchical injection through the same IoC model, often with `host` or `skipSelf` |
+| app-global         | app-level stores or app-wide provided state                | `app` container beans shared at app or request scope                               |
+| system-level       | module-level singletons or long-lived imported state       | `sys` container beans and system-level startup/lifecycle                           |
+
+The most important SSR distinction is between `app-global` and `system-level`: app-global behavior can be tied to an individual app instance or request, while system-level behavior is not request-scoped and can outlive individual SSR requests. For more on that lifecycle boundary, see [System Startup Guide](/frontend/system-startup-guide).
+
+The point is not that Vue patterns are wrong. The point is that Zova can keep more of these sharing cases inside one bean-and-container architecture instead of switching between unrelated mechanisms. If you want the broader architectural comparison, read [Zova vs Vue 3 Comparison](/frontend/zova-vs-vue3-comparison). If your main question is how ownership, scope, persistence, cache semantics, and SSR behavior fit together as one large-project state system, continue with [State Architecture for Vue Developers](/frontend/state-architecture-for-vue-developers).
+
+A compact mental model looks like this:
+
+```typescript
+class ControllerPage {
+  @Use()
+  $$localCounterState: CounterState;
+
+  @Use({ injectionScope: 'host' })
+  $$hostCounterState: CounterState;
+
+  @Use({ injectionScope: 'app' })
+  $$appCounterState: CounterState;
+
+  @Use({ injectionScope: 'sys' })
+  $$sysCounterState: CounterState;
+}
+```
+
+This top-level example is intentionally compact. The injection, hierarchical lookup, and scope sections below explain these patterns in more detail.
 
 ## The three container types
 
@@ -104,7 +135,7 @@ In practice, Zova can still preserve the ergonomic class-based development exper
 
 ### Hierarchical injection patterns
 
-Hierarchical injection replaces many cases where a generic Vue app would fall back to `provide/inject`.
+Hierarchical injection replaces many common cases where a generic Vue app would fall back to `provide/inject`.
 
 Representative child lookup pattern:
 

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

@@ -42,6 +42,8 @@ In practice, a model often sits above `$api` and below page rendering:
 
 Read together with [Server Data](/frontend/server-data) when deciding which abstraction layer a feature should use.
 
+If you want the larger docs-style overview of how ownership, scope, persistence, cache semantics, and SSR behavior connect in big Vue applications, read [State Architecture for Vue Developers](/frontend/state-architecture-for-vue-developers) before diving deeper into model internals.
+
 If your next question is how the generic lower-level model runtime works beneath these abstractions, continue with [A-Model Under the Hood](/frontend/a-model-under-the-hood).
 
 ## Relationship to TanStack Query

package/cabloy-docs/frontend/model-resource-owner-pattern.md

@@ -8,6 +8,8 @@ It uses the current `rest-resource` model as the main source specimen:
 
 Read [Model Architecture](/frontend/model-architecture) and [Model State Guide](/frontend/model-state-guide) first if you want the broader Model runtime and helper surface.
 
+If you want the larger docs-style overview of how ownership, scope, unified model state, and resource boundaries fit together in large Vue systems, read [State Architecture for Vue Developers](/frontend/state-architecture-for-vue-developers) first.
+
 If your next question is how `ModelResource` itself works internally at the source level, continue with [ModelResource Internals Deep Dive](/frontend/model-resource-internals-deep-dive).
 
 If your next question is how the generic lower-level model runtime works beneath `ModelResource`, continue with [Model Runtime Under the Hood](/frontend/a-model-under-the-hood).

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

@@ -4,6 +4,8 @@ This guide explains how to author and consume model-managed state in Zova within
 
 Read [Model Architecture](/frontend/model-architecture) first if you want the broader architectural role of Model.
 
+If your main question is how Model fits into the larger ownership/scope/persistence picture for big Vue applications, read [State Architecture for Vue Developers](/frontend/state-architecture-for-vue-developers) before going deeper into helper families.
+
 If you specifically want the scalable resource-facade pattern, continue with [Model Resource Owner Pattern](/frontend/model-resource-owner-pattern).
 
 If you want the generic lower-level model runtime beneath these helper families, continue with [A-Model Under the Hood](/frontend/a-model-under-the-hood).

package/cabloy-docs/frontend/reading-zova-for-vue-developers.md

@@ -29,14 +29,14 @@ That is why Zova code often reads more like controller-oriented application code
 
 ## Quick translation table
 
-| If you usually think in Vue terms | Read Zova like this instead |
-| --- | --- |
-| `setup()` is the main wiring point | `__init__` and bean lifecycle are major wiring points |
-| `ref` / `reactive` are the visible state hosts | controller and bean instances are the visible state hosts |
-| `computed()` creates local derived refs | `$computed()` usually creates instance-level derived state |
-| `useRoute()` pulls route state into the component | page controllers expose `$route`, `$params`, and `$query` as part of the controller surface |
-| `provide/inject`, composables, props, and stores are separate sharing tools | bean scopes and IoC are used to unify more sharing patterns under one model |
-| template or component render is the obvious center | controller-oriented architecture is the center; render can stay in the controller or move into render beans |
+| If you usually think in Vue terms                                           | Read Zova like this instead                                                                                 |
+| --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `setup()` is the main wiring point                                          | `__init__` and bean lifecycle are major wiring points                                                       |
+| `ref` / `reactive` are the visible state hosts                              | controller and bean instances are the visible state hosts                                                   |
+| `computed()` creates local derived refs                                     | `$computed()` usually creates instance-level derived state                                                  |
+| `useRoute()` pulls route state into the component                           | page controllers expose `$route`, `$params`, and `$query` as part of the controller surface                 |
+| `provide/inject`, composables, props, and stores are separate sharing tools | bean scopes and IoC are used to unify more sharing patterns under one model                                 |
+| template or component render is the obvious center                          | controller-oriented architecture is the center; render can stay in the controller or move into render beans |
 
 ## Start from the right assumptions
 
@@ -226,6 +226,8 @@ Use this order when:
 - you want to read Zova source code accurately
 - you want to avoid rewriting framework-specific code back toward generic Vue habits
 
+If your main question is specifically about large-project state organization rather than source-reading posture first, continue next with [State Architecture for Vue Developers](/frontend/state-architecture-for-vue-developers).
+
 ## Common mistakes to avoid
 
 ### Mistake 1: "This should become a normal Vue SFC"

package/cabloy-docs/frontend/server-data.md

@@ -45,6 +45,8 @@ Use OpenAPI SDK generation when you want backend-generated API contracts to driv
 
 Use schema-driven layers when metadata itself needs to participate in higher-level frontend behavior such as validation or automatic rendering.
 
+If your main question is not only which data-access layer to choose, but how data ownership, sharing boundaries, persistence, and SSR semantics fit together in large Vue systems, read [State Architecture for Vue Developers](/frontend/state-architecture-for-vue-developers) together with this page.
+
 ## Why this matters for Cabloy
 
 This abstraction ladder is one of the key links between Zova and Vona.