cabloy 5.1.134 → 5.1.136

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

@@ -0,0 +1,258 @@
+# Markdown Guide
+
+This guide explains how Markdown works across the Cabloy Basic frontend and backend. The practical contract is deliberately split into two values:
+
+- **Markdown** is the editable source value.
+- **HTML** is a server-generated presentation projection.
+
+The Zova frontend provides the editor and the trusted-HTML display component. The Vona backend owns Markdown parsing, HTML rendering, and sanitization.
+
+Use this page together with:
+
+- [Form Guide](/frontend/form-guide)
+- [Component Guide](/frontend/component-guide)
+- [SSR ClientOnly](/frontend/ssr-client-only)
+- [Backend Markdown Guide](/backend/markdown-guide)
+
+> [!TIP]
+> **Choose the component by data contract**
+>
+> - Use `basic-markdown:formFieldMarkdown` or `ZFormFieldMarkdown` to edit a Markdown string in a schema-driven form.
+> - Use `basic-markdown:markdownHtml` or `ZMarkdownHtml` to display HTML that was generated and sanitized by the server.
+> - Do not pass arbitrary user HTML, browser-generated HTML, or HTML from an unknown pipeline to `ZMarkdownHtml`.
+
+## The Markdown data contract
+
+A typical business resource keeps the authoring value and the rendered value separate:
+
+| Surface               | Owner                             | Purpose                        | Public use                                       |
+| --------------------- | --------------------------------- | ------------------------------ | ------------------------------------------------ |
+| `descriptionMarkdown` | Form and backend business service | Editable source text           | Returned to an authorized editor                 |
+| `descriptionHtml`     | Backend business service          | Server-derived HTML projection | Returned to a public read model when appropriate |
+| `ZMarkdownHtml`       | Zova presentation layer           | Displays the HTML projection   | Receives trusted HTML only                       |
+
+The frontend editor never needs to submit HTML. On every relevant write path, the backend should derive HTML again from the submitted Markdown. This prevents a caller from choosing a different HTML representation than the server's rendering and sanitization policy.
+
+The Commerce Catalog product content flow is the reference implementation:
+
+```text
+Admin Markdown field
+  → descriptionMarkdown
+  → Vona service calls bean.markdown.renderHtml(...)
+  → descriptionMarkdown + descriptionHtml are persisted
+  → public detail exposes descriptionHtml
+  → ZMarkdownHtml displays the server projection
+```
+
+The backend companion page documents the rendering and sanitizer contract in detail: [Backend Markdown Guide](/backend/markdown-guide).
+
+## Configure the Markdown form field
+
+The schema-driven renderer is selected with `ZovaRender.field`:
+
+```typescript
+import { Api, v } from 'vona-module-a-openapiutils';
+import { ZovaRender } from 'zova-rest-cabloy-basic-admin';
+
+export class EntityArticleContent {
+  @Api.field(v.optional(), ZovaRender.field('basic-markdown:formFieldMarkdown'))
+  bodyMarkdown?: string;
+}
+```
+
+The current resource options type does not add business-specific options. The renderer identifier is the important part of the contract:
+
+```typescript
+ZovaRender.field('basic-markdown:formFieldMarkdown');
+```
+
+The field value remains Markdown. It is not the editor's HTML output, and it should not be replaced with `innerHTML` or a browser DOM serialization.
+
+A field can keep the derived HTML hidden from the editor-facing form while still exposing it in a separate public DTO. The Commerce Catalog entity follows this shape:
+
+```typescript
+@Api.field(
+  v.optional(),
+  ZovaRender.field('basic-markdown:formFieldMarkdown'),
+)
+descriptionMarkdown?: string;
+
+@Api.field(v.optional(), ZovaRender.visible(false))
+descriptionHtml?: string;
+```
+
+The exact persistence and DTO design belongs to the business module. Markdown does not require a paired HTML column, but a persisted projection can avoid repeating rendering work for public reads.
+
+## What `ZFormFieldMarkdown` does
+
+`ZFormFieldMarkdown` is a Zova component with the normal Controller/Render/Style split.
+
+| Zova role  | Responsibility in this component                                                            |
+| ---------- | ------------------------------------------------------------------------------------------- |
+| Controller | Owns the TipTap `Editor`, Markdown `value`, `readonly` state, form callbacks, and lifecycle |
+| Render     | Composes the standard `ZFormField`, field shell, `ClientOnly`, and `EditorContent`          |
+| Style      | Creates the shared rich-text CSS class used by the editor and HTML display component        |
+
+This is a Markdown editor integrated with `ZFormField`; it is not a generic HTML editor API.
+
+### Editor initialization
+
+The Controller creates the browser-dependent TipTap editor in `$controllerMounted`. Its extension set includes:
+
+- Markdown
+- StarterKit
+- nested `TaskList` and `TaskItem`
+- Image
+- TableKit
+- Highlight
+
+The initial value is interpreted as Markdown through:
+
+```typescript
+content: this.value,
+contentType: 'markdown',
+editable: !this.readonly,
+```
+
+The editor DOM receives the current component style class and a minimum-height/padding class. The outer field shell uses Cabloy Basic's DaisyUI-oriented classes and adds an error border when the host form field is invalid.
+
+### Editor-to-form flow
+
+When TipTap emits an update, the controller calls:
+
+```typescript
+editor.getMarkdown();
+```
+
+and forwards the Markdown string to the host form field's `setValue()` method. When the editor loses focus, the controller forwards the event to the host form field's `handleBlur()` method, so the normal form validation and touched-state path remains in control.
+
+There are no component-specific Vue `emit()` events. The effective interaction boundary is the standard form-field contract plus the editor's update and blur callbacks.
+
+### Form-to-editor flow
+
+The render bean binds the current `propsBucket.value` and `propsBucket.readonly` values from `ZFormField`. If the form value changes externally, the controller updates the editor with:
+
+```typescript
+this.editor.commands.setContent(value, { contentType: 'markdown' });
+```
+
+A private syncing flag prevents that programmatic update from immediately writing the same value back to the form. When `readonly` changes, the controller calls `editor.setEditable(!readonly)`.
+
+When the component is disposed, the controller calls `editor.destroy()` so TipTap's DOM and event resources are released.
+
+### SSR and `ClientOnly`
+
+TipTap's `EditorContent` is browser-dependent. The editor is therefore inside Zova's `ClientOnly` component:
+
+- SSR renders a minimum-height placeholder;
+- the browser creates the editor after mounting;
+- the editor should not be described as an SSR-rendered interactive control.
+
+The read-only HTML display path is different: it does not need TipTap or `ClientOnly` because it receives already-generated HTML.
+
+## Display server-generated HTML with `ZMarkdownHtml`
+
+Use `ZMarkdownHtml` when a page has an HTML projection from a trusted backend rendering path:
+
+```tsx
+import { ZMarkdownHtml } from 'zova-module-basic-markdown';
+
+export class ControllerArticlePage {
+  public render() {
+    const html = this.article?.bodyHtml;
+    if (!html) return null;
+
+    return <ZMarkdownHtml class="article-content" html={html} />;
+  }
+}
+```
+
+`ZMarkdownHtml` accepts `class?: string` and `html?: string`. Its render bean produces one `div`, applies the shared rich-text class, and assigns the `html` prop through `innerHTML`.
+
+> [!WARNING]
+> `ZMarkdownHtml` does **not** sanitize its input. It does not parse Markdown. Its caller is responsible for providing HTML generated by `bean.markdown.renderHtml(...)` or by an equivalent, explicitly trusted sanitizer pipeline. Treating this component as a general-purpose safe HTML sink is incorrect.
+
+The shared rich-text style covers headings, paragraphs, ordered and unordered lists, nested task-list structure, blockquotes, inline and block code, highlight classes, links, images, horizontal rules, and tables. The style is a presentation layer; it does not change the sanitizer or URL policy.
+
+A public product page uses this boundary:
+
+```text
+publicProduct.descriptionHtml
+  → product page controller
+  → <ZMarkdownHtml html={descriptionHtml} />
+```
+
+The public response should not expose the editable Markdown unless that is an intentional access-controlled contract.
+
+## Supported Markdown features
+
+The current frontend and backend extension sets are aligned around these features:
+
+- StarterKit document basics: headings, paragraphs, emphasis, strong text, strike-through, blockquotes, horizontal rules, lists, and code;
+- GitHub-flavored Markdown parsing on the backend;
+- nested task lists;
+- images;
+- tables;
+- highlight support in the TipTap document/rendering extensions.
+
+The backend Markdown manager is configured with two-space indentation. Treat this as the current parser/serializer convention, not as a reason to reject every inbound document that uses another indentation style.
+
+A representative input is:
+
+````markdown
+# Product details
+
+This is **durable** content.
+
+- [ ] Draft the description
+  - [x] Review the link
+
+| Field  | Value |
+| ------ | ----- |
+| Status | Ready |
+
+```ts
+const ready = true;
+```
+
+[Project home](https://example.com)
+
+![Product image](https://example.com/product.png)
+````
+
+The exact HTML output is governed by the backend renderer and sanitizer. Do not infer support for arbitrary raw HTML, iframe embeds, inline styles, `data:` URLs, or custom classes from the presence of a TipTap extension.
+
+## Common mistakes
+
+1. **Storing editor HTML as the form value**
+   - Keep the form value as Markdown. The editor uses `getMarkdown()` and `setContent(..., { contentType: 'markdown' })` for that reason.
+
+2. **Trusting a client-supplied HTML field**
+   - Ignore or overwrite submitted HTML. Rebuild it on the server from Markdown.
+
+3. **Passing unknown HTML to `ZMarkdownHtml`**
+   - The component uses `innerHTML` and has no frontend sanitizer.
+
+4. **Expecting task checkboxes to be interactive**
+   - The backend transforms rendered task inputs into disabled checkboxes for display.
+
+5. **Expecting a toolbar or upload workflow from this module**
+   - The module supplies an editor surface, not a toolbar specification, image upload service, remote image importer, or configurable plugin registry.
+
+6. **Treating browser validation or presentation CSS as security**
+   - The backend renderer/sanitizer is the relevant content boundary. External image availability, privacy, CSP, and application authorization remain separate concerns.
+
+## Frontend checklist
+
+Before integrating Markdown into a Zova feature, verify:
+
+1. The editable field is a string containing Markdown.
+2. The field metadata uses `basic-markdown:formFieldMarkdown`.
+3. The form value is updated through the editor's Markdown API, not HTML.
+4. Blur and readonly behavior still pass through the standard `ZFormField` contract.
+5. The interactive editor is inside the expected `ClientOnly` boundary.
+6. Public display uses `ZMarkdownHtml` only with server-derived sanitized HTML.
+7. Public DTOs do not expose editable Markdown unless that is intentional.
+8. The backend write path regenerates the HTML projection for every create, update, import, or backfill path that can change Markdown.
+
+For the backend API and security details, continue with [Backend Markdown Guide](/backend/markdown-guide).

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

@@ -164,6 +164,54 @@ class StylePageCounter extends BeanStyleBase {
 }
 ```
 
+### Companion-member access in a split page
+
+The three files have distinct primary ownership:
+
+- **Controller** owns state, actions, and lifecycle work.
+- **Render** owns TSX composition.
+- **Style** owns scoped CSS-in-JS setup.
+
+Within one split page or component, ordinary access to a companion member uses `this.member`; it does not require `@Use()` or a container lookup. Runtime lookup proceeds in this order:
+
+| Current bean | Direct member lookup order          |
+| ------------ | ----------------------------------- |
+| Controller   | Controller only                     |
+| Style        | Style, then Controller              |
+| Render       | Render, then Controller, then Style |
+
+A member declared on the current bean shadows the next fallback surface. Keep names distinct when a Style class name and a Controller state/action could otherwise collide.
+
+For example, the Render bean can read Controller state and actions directly, while it receives the generated Style class through the same direct access surface:
+
+```typescript
+@Render()
+class RenderPageCounter extends BeanRenderBase {
+  public render() {
+    return <div class={this.cTextCenter}>count: {this.count}</div>;
+  }
+}
+```
+
+The Style bean can likewise read Controller state while owning the generated class name:
+
+```typescript
+@Style()
+class StylePageCounter extends BeanStyleBase {
+  cTextCenter: string;
+
+  protected async __init__() {
+    this.cTextCenter = this.$style({
+      opacity: this.count > 0 ? 1 : 0.6,
+    });
+  }
+}
+```
+
+Use explicit `@Use()` or bean/container lookup when the task needs a specific named instance, selector or scope boundary, identity passing, lifecycle control, or other interop. Those mechanisms are not the default for same-component companion access.
+
+For the generated typing and runtime evidence behind this rule, see [Zova Source Reading Map](/frontend/zova-source-reading-map#3-split-controller-render-and-style-companion-access).
+
 ### More-file growth
 
 When the page continues to grow, you can keep splitting responsibilities instead of forcing one large controller or render bean to absorb everything.

package/cabloy-docs/frontend/page-params-guide.md

@@ -30,7 +30,9 @@ Because route params arrive as strings at the URL level, the schema is also wher
 
 ## Route record requirements
 
-One important rule is that if a page supports params, the route should expose the proper route structure and route name.
+A page route that declares or consumes dynamic params **must** define `route.name`. Do not use an unnamed route with params.
+
+The route name is required because Zova uses the named route identity to generate and resolve the page's typed `params` schema at runtime. This initializes the controller's `$params` surface during SSR and client navigation. A params schema declaration alone does not make `$params` available if the route is unnamed.
 
 Representative route idea:
 
@@ -82,6 +84,6 @@ this.$router.push(url);
 When adding or editing param-driven page behavior:
 
 1. use the Zova refactor command when possible
-2. update the route record and route name deliberately
+2. define `route.name` whenever the route has dynamic params
 3. regenerate metadata when route typing depends on it
 4. use `this.$params` and typed router helpers instead of manual parsing

package/cabloy-docs/frontend/page-route-guide.md

@@ -42,7 +42,7 @@ This matters because path generation is modular by default.
 
 ## `name`
 
-If a page uses params, the route name becomes especially important because typed param-aware routing depends on it.
+A route with dynamic params must define `name`. Typed param-aware routing uses the named route identity to generate and resolve the page's runtime params schema; an unnamed parameterized route does not provide the required `$params` contract.
 
 ## `component`
 
@@ -145,7 +145,7 @@ When editing page routing, do not only change the URL string.
 
 It should also check whether the route change affects:
 
-- params typing
+- params typing and the required `route.name` for dynamic params
 - auth behavior
 - layout behavior
 - whether `meta.locale` should participate in URL-locale behavior

package/cabloy-docs/frontend/zova-router-under-the-hood.md

@@ -417,6 +417,8 @@ When `_initControllerRoute(...)` updates a page controller, it resolves the rout
 - `pageNameSchemas` for named routes
 - `pagePathSchemas` for path-keyed routes
 
+For page routes with dynamic params, define `route.name` and use the named-route metadata path. Do not rely on an unnamed parameterized route: the generated path-keyed record does not establish the typed controller `$params` contract.
+
 Those schema records are generated into module metadata.
 
 Representative generator source:

package/cabloy-docs/frontend/zova-source-reading-map.md

@@ -107,7 +107,51 @@ Use this path when you are asking questions like:
 - `component.ts` shows how render is patched toward controller/render beans
 - the concrete component controller shows the public authoring pattern for the case you care about
 
-## 3. Bean lifecycle, instance scope, and helper APIs
+## 3. Split Controller, Render, and Style companion access
+
+Use this path when you are asking questions like:
+
+- why can a Render Bean read Controller state with `this.member`?
+- why can a Style Bean read Controller state, or a Render Bean read a generated Style class?
+- does generated type augmentation create the runtime fallback behavior?
+- when is `@Use()` or an explicit bean lookup actually needed?
+
+### Read the docs first
+
+- [Page Guide](/frontend/page-guide#companion-member-access-in-a-split-page)
+- [Component Guide](/frontend/component-guide#controllerref-and-internal-companion-access)
+- [CSS-in-JS Guide](/frontend/css-in-js-guide#style-beans-in-a-split-controllerrenderstyle-component)
+
+### Then read source in this order
+
+1. `zova/src/suite/a-home/modules/home-layoutadmin/src/.metadata/component/layoutAdmin.ts`
+2. `zova/packages-zova/zova-core/src/composables/useController.ts`
+3. `zova/packages-zova/zova-core/src/bean/beanStyleBase.ts`
+4. `zova/packages-zova/zova-core/src/bean/beanControllerLike.ts`
+5. `zova/packages-zova/zova-core/src/bean/beanRenderLike.ts`
+6. `zova/packages-zova/zova-core/src/bean/beanContainer.ts`
+7. `zova/packages-zova/zova-core/src/core/context/component.ts`
+
+### What each file clarifies
+
+- `layoutAdmin.ts` shows generated type augmentation: Style extends Controller and Render extends Style, so TypeScript exposes the companion members.
+- `useController.ts` creates the Controller first, then Style, then Render in one component context.
+- `beanStyleBase.ts` and `beanControllerLike.ts` show Style's runtime fallback from Style to Controller.
+- `beanRenderLike.ts` extends that fallback so Render resolves Render, then Controller, then Style.
+- `beanContainer.ts` shows that proxy handling keeps locally declared members local and asks `__get__`/`__set__` only for a missing member; this produces own-member shadowing.
+- `component.ts` shows that the runtime uses the Controller's render when it has one and otherwise selects the Render Bean.
+
+The source-confirmed direct lookup order is:
+
+| Current bean | Direct member lookup order          |
+| ------------ | ----------------------------------- |
+| Controller   | Controller only                     |
+| Style        | Style, then Controller              |
+| Render       | Render, then Controller, then Style |
+
+Use `this.member` for normal same-component access. Use explicit `@Use()` or a bean/container lookup only when you need a named or specific instance, selector or scope boundary, identity passing, lifecycle control, or other interop. Generated type augmentation makes this authoring surface type-safe; the proxy fallback is the separate runtime mechanism that supplies missing companion members.
+
+## 4. Bean lifecycle, instance scope, and helper APIs
 
 Use this path when you are asking questions like:
 
@@ -134,7 +178,7 @@ Use this path when you are asking questions like:
 - `beanContainer.ts` shows init, inject, and dispose flow
 - `context/util.ts` shows how instance scope is applied around framework operations
 
-## 4. Page routing, params, query, and layout-oriented route behavior
+## 5. Page routing, params, query, and layout-oriented route behavior
 
 Use this path when you are asking questions like:
 
@@ -180,9 +224,9 @@ If your next question becomes any of these:
 then continue immediately with:
 
 - [Router View Hosts Guide](/frontend/router-view-hosts-guide)
-- section 5 on this page for the compact source-reading path
+- section 6 on this page for the compact source-reading path
 
-## 5. Router-view hosts, routertabs, and routerstack
+## 6. Router-view hosts, routertabs, and routerstack
 
 Use this path when you are asking questions like:
 
@@ -225,7 +269,7 @@ If your next question becomes specifically about task-level title, dirty state,
 - `model/stack.ts` shows the fullPath-based stack identity model and recency-based pruning
 - active layout consumers show how the current shell turns host state into visible Admin or Web behavior
 
-## 6. Model state, cache-oriented state, and broader data ownership
+## 7. Model state, cache-oriented state, and broader data ownership
 
 Use this path when you are asking questions like:
 
@@ -253,7 +297,7 @@ Use this path when you are asking questions like:
 - built-in model beans show how the architecture is used in nontrivial cases
 - consuming code shows whether the state really belongs in the model or only uses the model result
 
-## 7. Command scene and command-bean invocation
+## 8. Command scene and command-bean invocation
 
 Use this path when you are asking questions like:
 
@@ -318,7 +362,7 @@ Use this path when you are asking questions like:
 - `controller.tsx` shows app-level meta setup, behavior-holder initialization, and behavior-wrapped `RouterView` render
 - `config.ts` shows the root behavior injection point through `scope.config.behaviors`
 
-## 8. Behavior scene and render-time interception
+## 9. Behavior scene and render-time interception
 
 Use this path when you are asking questions like:
 
@@ -345,7 +389,7 @@ Use this path when you are asking questions like:
 - composer/service files show how behavior chains are normalized and executed
 - host dependencies show why host-scoped injection is part of the behavior design
 
-## 9. SSR runtime and hydration handoff
+## 10. SSR runtime and hydration handoff
 
 Use this path when you are asking questions like:
 
@@ -374,7 +418,7 @@ Use this path when you are asking questions like:
 - page/controller/model files show whether the bug is actually page-level logic
 - the Vona side shows whether the problem happens before the Zova runtime is even entered
 
-## 10. Modules, suites, and architectural placement
+## 11. Modules, suites, and architectural placement
 
 Use this path when you are asking questions like: