cabloy 5.1.59 → 5.1.61

package/cabloy-docs/frontend/router-tabs-route-meta-cookbook.md

@@ -0,0 +1,343 @@
+# Router Tabs Route Meta Cookbook
+
+This guide provides practical route-meta recipes for the router-tabs mechanism in Zova within the Cabloy monorepo.
+
+Read this together with:
+
+- [Router Tabs Introduction](/frontend/router-tabs-introduction)
+- [Page Route Guide](/frontend/page-route-guide)
+- [Router Tabs Overview](/frontend/router-tabs-overview)
+- [Router Tabs Mechanism](/frontend/router-tabs-mechanism)
+
+## Why this cookbook exists
+
+The router-tabs mechanism is flexible, but the most important authoring choices are usually concentrated in route metadata.
+
+In practice, contributors often need a quick answer to questions such as:
+
+- when should several pages share one level-1 workspace?
+- when should several route visits reuse one page instance?
+- when should different records remain open in parallel?
+- when should a routed page be excluded from keep-alive?
+
+This cookbook answers those questions with focused examples.
+
+## The relevant route-meta surface
+
+Representative route-meta fields for router tabs include:
+
+- `tabKey`
+- `componentKey`
+- `componentKeyMode`
+- `keepAlive`
+
+Representative source definition:
+
+- `zova/src/suite-vendor/a-zova/modules/a-router/src/types/router.ts`
+
+## Mental model before choosing a recipe
+
+Use this decision split first:
+
+- `tabKey` answers: which level-1 workspace should this route belong to?
+- `componentKey` answers: should this route visit reuse an existing page instance or remain separately open?
+
+If you keep that split clear, most router-tabs authoring decisions become straightforward.
+
+## Recipe 1: use the default behavior for a simple page
+
+Use the default behavior when a page does not need special grouping or custom instance control.
+
+```typescript
+export const routes: IModuleRoute[] = [
+  {
+    path: 'dashboard',
+    component: ZPageDashboard,
+  },
+];
+```
+
+What this means in practice:
+
+- the route can still participate in router tabs
+- the effective `tabKey` falls back to the effective `componentKey`
+- the page behaves like its own workspace by default
+
+Use this when the page is simple and does not need to share a workspace with related pages.
+
+## Recipe 2: group several pages into one stable workspace with `tabKey`
+
+Use a shared `tabKey` when several related routes should stay under one level-1 workspace.
+
+```typescript
+export const routes: IModuleRoute[] = [
+  {
+    path: 'user/list',
+    component: ZPageUserList,
+    meta: {
+      tabKey: '/user/list',
+    },
+  },
+  {
+    path: 'user/create',
+    component: ZPageUserCreate,
+    meta: {
+      tabKey: '/user/list',
+    },
+  },
+  {
+    path: 'user/edit/:id',
+    component: ZPageUserEdit,
+    meta: {
+      tabKey: '/user/list',
+    },
+  },
+];
+```
+
+What this means in practice:
+
+- User List, User Create, and User Edit all belong to one level-1 workspace
+- the top-level workspace remains stable
+- the inner work items can still vary
+
+Use this when the business workspace identity matters more than the specific route identity.
+
+## Recipe 3: reuse one page instance across param changes with `componentKeyMode: 'nameOnly'`
+
+Use `componentKeyMode: 'nameOnly'` when different param values should still reuse one logical page instance.
+
+```typescript
+export const routes: IModuleRoute[] = [
+  {
+    name: 'reportDetail',
+    path: 'report/:id?',
+    component: ZPageReportDetail,
+    meta: {
+      componentKeyMode: 'nameOnly',
+    },
+  },
+];
+```
+
+What this means in practice:
+
+- the route name becomes the effective page-instance identity
+- visiting different param values can still reuse one page instance
+- this is useful when the page behaves like one reusable tool surface
+
+Representative source example:
+
+- `zova/src/suite/a-demo/modules/demo-basic/src/routes.ts` lines 20-28
+
+## Recipe 4: use an explicit `componentKey` when you need full control
+
+Use an explicit `componentKey` when the default path-based behavior is not precise enough.
+
+```typescript
+export const routes: IModuleRoute[] = [
+  {
+    name: 'orderDetail',
+    path: 'order/:id',
+    component: ZPageOrderDetail,
+    meta: {
+      componentKey(route) {
+        return `order:${route.params.id}`;
+      },
+    },
+  },
+];
+```
+
+What this means in practice:
+
+- every order id gets its own page-instance identity
+- several orders can remain open in parallel
+- the page-instance rule is explicit instead of inferred indirectly
+
+Use this when you want independently open task items for different business objects.
+
+## Recipe 5: combine stable `tabKey` with distinct `componentKey`
+
+This is the most common workbench recipe.
+
+Use it when several routes should stay in one workspace, but different records should still remain separately open.
+
+```typescript
+export const routes: IModuleRoute[] = [
+  {
+    name: 'productEdit',
+    path: 'product/edit/:id',
+    component: ZPageProductEdit,
+    meta: {
+      tabKey: '/product/list',
+      componentKey(route) {
+        return `product-edit:${route.params.id}`;
+      },
+    },
+  },
+];
+```
+
+What this means in practice:
+
+- all product-edit work stays under the Product List workspace
+- Product A and Product B can still remain open as separate level-2 work items
+- this preserves both business grouping and parallel record editing
+
+If you need only one recipe to remember, this is often the one.
+
+## Recipe 6: compute `tabKey` dynamically when the workspace identity is derived
+
+Use a function `tabKey` when the workspace grouping depends on route context rather than a fixed string.
+
+```typescript
+export const routes: IModuleRoute[] = [
+  {
+    name: 'contentScene',
+    path: 'content/:scene/:id?',
+    component: ZPageContentScene,
+    meta: {
+      tabKey(route) {
+        return `/content/${route.params.scene}`;
+      },
+    },
+  },
+];
+```
+
+What this means in practice:
+
+- each content scene becomes its own workspace grouping
+- routes in the same scene stay together
+- different scenes remain separated
+
+Use this when the stable business workspace is derived from a route dimension such as scene, category, or module context.
+
+## Recipe 7: exclude a page from keep-alive with `keepAlive: false`
+
+Use `keepAlive: false` when the page should not stay alive in the routed workbench cache.
+
+```typescript
+export const routes: IModuleRoute[] = [
+  {
+    path: 'search/live',
+    component: ZPageSearchLive,
+    meta: {
+      keepAlive: false,
+    },
+  },
+];
+```
+
+What this means in practice:
+
+- the route can still participate in router tabs
+- but its instance is excluded from the keep-alive include list
+- switching away and back may rebuild the page state
+
+Use this only when the page should not preserve the normal keep-alive workbench behavior.
+
+## Recipe 8: pin the workspace identity to the business entry, not to task routes
+
+When choosing `tabKey`, prefer the stable business entry rather than temporary task pages.
+
+Better:
+
+```typescript
+meta: {
+  tabKey: '/invoice/list',
+}
+```
+
+Usually worse:
+
+```typescript
+meta: {
+  tabKey: '/invoice/edit/123',
+}
+```
+
+Why:
+
+- the first form preserves a stable Invoice workspace
+- the second form turns one temporary task into the workspace identity itself
+
+That usually weakens the business meaning of the level-1 surface.
+
+## Recipe 9: decide between `componentKeyMode` and explicit `componentKey`
+
+Use this rule of thumb:
+
+### Prefer `componentKeyMode: 'nameOnly'` when
+
+- one named page should behave as one reusable inner tool
+- params do not need separate open instances
+- the route name is already a good page-instance identity
+
+### Prefer explicit `componentKey` when
+
+- different records should remain separately open
+- the reuse rule depends on route params or query details
+- you want the instance boundary to be obvious in the route definition
+
+In the current implementation, `nameOnly` is the special opt-in mode. Otherwise the router-tabs model falls back to path-based distinction unless an explicit `componentKey` is provided.
+
+## Recipe 10: avoid using `tabKey` and `componentKey` for the same purpose
+
+Avoid these two mistakes:
+
+### Mistake A: using `tabKey` to distinguish separate records
+
+```typescript
+meta: {
+  tabKey(route) {
+    return `/customer/${route.params.id}`;
+  },
+}
+```
+
+This often turns every record into its own top-level workspace and makes the level-1 surface noisy.
+
+### Mistake B: using `componentKey` to simulate business grouping
+
+```typescript
+meta: {
+  componentKey: '/customer/list',
+}
+```
+
+This can collapse different work items into one reused page instance even when users expect parallel open tasks.
+
+The safer rule is:
+
+- use `tabKey` for workspace grouping
+- use `componentKey` for page-instance reuse or separation
+
+## Recommended authoring checklist
+
+Before finalizing route meta for a page, ask:
+
+1. what is the stable business workspace identity?
+2. should this page join an existing workspace or create its own?
+3. should several visits reuse one page instance or open separately?
+4. should this page preserve normal keep-alive behavior?
+5. would the chosen keys still make sense after future route refactors?
+
+If the answers are stable, the route-meta design is usually in good shape.
+
+## Summary
+
+The most useful router-tabs recipes are built from one simple split:
+
+- `tabKey` controls workspace grouping
+- `componentKey` controls page-instance identity
+
+Once that split is clear, route meta becomes a practical and predictable tool for shaping the workbench experience.
+
+## See also
+
+- [Router Tabs Introduction](/frontend/router-tabs-introduction)
+- [Router Tabs Overview](/frontend/router-tabs-overview)
+- [Router Tabs Mechanism](/frontend/router-tabs-mechanism)
+- [Router Tabs Admin and Web Comparison](/frontend/router-tabs-admin-web-comparison)

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

@@ -27,6 +27,8 @@ These layers define the server-data abstraction ladder:
 
 Use `$fetch` when you need a relatively direct HTTP-oriented access path.
 
+When the transport concern itself needs framework-level handling such as auth headers, response-envelope normalization, SSR short-circuiting, or mock fallback, read [Fetch Interceptor Guide](/frontend/fetch-interceptor-guide) together with this page.
+
 ### `$api`
 
 Use `$api` when you want business-oriented service access rather than scattering request details across pages and components.

package/cabloy-docs/frontend/ssr-architecture-overview.md

@@ -0,0 +1,211 @@
+# SSR Architecture Overview
+
+This guide explains the public SSR architecture model in Zova within the Cabloy monorepo.
+
+## Why this page exists
+
+The other SSR pages explain focused topics such as init data, client-only boundaries, SEO meta, and env behavior.
+
+This page explains the larger mental model:
+
+- where SSR starts
+- how Vona and Zova cooperate
+- what the generated frontend bundle contributes
+- how server render hands off to client hydration
+
+That model helps contributors and AI workflows place SSR changes in the correct layer instead of treating SSR as a single opaque step.
+
+## The shortest accurate SSR model
+
+Cabloy SSR is a coordinated fullstack flow:
+
+1. **Vona** receives the request and decides whether the request should be handled as SSR
+2. **Vona SSR integration** loads the built frontend SSR bundle for the matching site
+3. **Zova SSR runtime** resolves the page route and renders HTML on the server
+4. **Zova SSR state/meta logic** injects the data needed for hydration
+5. **the browser** hydrates the page and continues as a normal client application
+
+The important point is that SSR is not frontend-only and not backend-only.
+
+It is one connected request flow across both sides of the framework.
+
+## The four practical layers
+
+In these docs, **frontend build output** includes the SSR bundle entry plus the client assets used after render.
+
+### 1. Vona SSR orchestration
+
+This layer owns the outer request lifecycle.
+
+Its responsibilities include:
+
+- receiving the HTTP request
+- matching the request to the correct SSR site
+- deciding between dev proxy, built static asset, or SSR render
+- loading the built SSR entry for the site
+- writing the final HTML response
+
+A practical way to think about this layer is:
+
+- **Vona decides whether SSR should happen and which site should handle it**
+
+### 2. Generated frontend SSR bundle
+
+Each SSR site produces a built bundle that the backend can load.
+
+This bundle contributes:
+
+- the SSR entry used by the backend
+- the client assets used after render
+- the manifest/preload information needed by the SSR runtime
+
+A practical way to think about this layer is:
+
+- **the frontend build produces the server-renderable application package**
+
+### 3. Zova server-side SSR runtime
+
+This layer owns the actual server render of the frontend application.
+
+Its responsibilities include:
+
+- resolving the target route inside the frontend application
+- creating the SSR context
+- rendering the application to HTML
+- collecting preload information for used modules/assets
+- returning the final HTML shell
+
+A practical way to think about this layer is:
+
+- **Zova turns the built frontend application into server-rendered HTML**
+
+### 4. Zova hydration handoff
+
+After server render, the framework still needs to transfer state into the browser correctly.
+
+This layer owns:
+
+- injecting initial SSR state into the HTML
+- injecting SSR-aware meta output
+- preserving data needed for hydration
+- resuming on the client without redoing the whole first-screen work unnecessarily
+
+A practical way to think about this layer is:
+
+- **SSR finishes only when hydration has a clean handoff path**
+
+## End-to-end request flow
+
+A useful high-level sequence is:
+
+```text
+browser request
+  -> Vona receives the URL
+  -> Vona matches the SSR site
+  -> Vona chooses dev proxy, static asset, or SSR render
+  -> Vona loads the built frontend SSR entry
+  -> Zova resolves the frontend route
+  -> Zova renders HTML on the server
+  -> Zova injects state/meta/preload output
+  -> Vona returns the HTML response
+  -> browser hydrates the page
+```
+
+This sequence is the durable contract even if specific internal implementation details evolve.
+
+## What each side owns
+
+### Vona mainly owns
+
+- request entry
+- SSR site matching
+- HTTP response lifecycle
+- SSR site-level environment assembly
+- backend-side integration with the built frontend bundle
+
+### Zova mainly owns
+
+- frontend route resolution during SSR
+- server rendering of the frontend application
+- SSR state and meta injection
+- hydration-aware frontend runtime behavior
+
+### The built bundle mainly owns
+
+- the page/component tree itself
+- the emitted SSR entry
+- the client assets used after render
+
+## Why this split matters
+
+This split helps avoid common mistakes.
+
+### Mistake 1: treating SSR as frontend-only
+
+That misses the fact that Vona decides when SSR runs and how the frontend bundle is entered.
+
+### Mistake 2: treating SSR as backend-only
+
+That misses the fact that route resolution, HTML render, state injection, and hydration behavior are frontend runtime responsibilities.
+
+### Mistake 3: debugging the wrong layer
+
+For example:
+
+- if the request never reaches the intended SSR site, start from the Vona side
+- if the page route or rendered HTML is wrong after the frontend bundle is entered, continue on the Zova side
+- if hydration or SSR-transferred state is wrong, focus on the SSR state/meta layer rather than only the outer request layer
+
+## How to reason about SSR changes
+
+When editing SSR-sensitive code, ask these questions first:
+
+1. does this change affect **request routing** or **frontend rendering**?
+2. does it affect the **server render result** or only the **client hydration result**?
+3. does it belong to **site integration**, **frontend runtime**, or **page-level application code**?
+4. does the active edition change only the UI layer, or does it change the SSR workflow itself?
+
+That framing usually tells you where the change belongs before you start coding.
+
+## Edition impact
+
+For Cabloy Basic and Cabloy Start, the SSR architecture contract is shared at the framework level.
+
+That means the same high-level model still applies:
+
+- backend request entry
+- frontend SSR bundle
+- server render
+- hydration handoff
+
+What can differ by edition is usually:
+
+- UI library assumptions
+- site baselines
+- frontend flavor names
+- project assets and generated output paths
+
+So the architecture model is shared, while some concrete frontend examples remain edition-sensitive.
+
+## Recommended reading order
+
+Use this order when you need the shortest path from mental model to implementation detail:
+
+1. this page for the architecture overview
+2. [SSR Overview](/frontend/ssr-overview)
+3. [SSR Init Data](/frontend/ssr-init-data)
+4. [SSR ClientOnly](/frontend/ssr-client-only)
+5. [SSR SEO Meta](/frontend/ssr-seo-meta)
+6. [SSR Env](/frontend/ssr-env)
+7. [Fullstack Vona + Zova Integration](/fullstack/vona-zova-integration)
+
+## Implementation checks for architecture-sensitive SSR changes
+
+Before finalizing an SSR-related change, ask:
+
+1. does the request still enter the correct SSR site?
+2. does the server render still produce the intended HTML?
+3. does the client reuse the server-provided state during hydration?
+4. does the change assume a UI or theme behavior that is actually edition-specific?
+
+That keeps SSR work aligned with the Cabloy fullstack model rather than drifting into generic frontend-only or backend-only assumptions.