cabloy 5.1.108 → 5.1.110

package/cabloy-docs/frontend/table-resource-crud-cookbook.md

@@ -162,8 +162,8 @@ This block uses `ZForm` with:
 
 - `schema={$$page.schemaFilter}`
 - `schemaScene="filter"`
-- inline layout
 - page-owned filter data
+- field-level `formFieldLayout.inline: true` by default
 
 Its job is not to duplicate the list query logic.
 
@@ -178,6 +178,38 @@ A practical rule is:
 - if you need to refine which filter fields exist, start from backend filter-side metadata and schema
 - if you need to refine how filter submission affects the list, inspect `blockFilter` and `blockPage.onFilter(...)`
 
+### Use blocks for a structural filter layout
+
+A bare `basic-page:blockFilter` keeps the default schema field rendering and adds Search/Reset controls automatically. For a structured filter, compose the existing form layout block with the filter-specific action block:
+
+```tsx
+ZovaRender.block('basic-page:blockFilter', {
+  formFieldLayout: { inline: true },
+  blocks: [
+    ZovaRender.block('basic-form:blockFormLayout', {
+      formLayout: {
+        children: [
+          {
+            type: 'section',
+            layout: 'flow',
+            children: [
+              { type: 'field', name: 'name' },
+              { type: 'field', name: 'level' },
+              { type: 'field', name: 'createdAt' },
+            ],
+          },
+        ],
+      },
+    }),
+    ZovaRender.block('basic-page:blockFilterActions'),
+  ],
+});
+```
+
+`basic-form:blockFormLayout` only places schema fields. `basic-page:blockFilterActions` owns Search/Reset placement and invokes the filter command surface supplied through the form scope, so it preserves filter normalization and page-query behavior. A nonempty `blocks` list replaces the automatic body and footer; include the action block explicitly to make the filter operable.
+
+`ZForm.inline` is no longer a form API. Use `formFieldLayout.inline` for field-level compact layout, or use blocks plus `basic-form:blockFormLayout` for structural layout. The flow section above keeps compact filters left-packed and wrapping; use the default Grid section when fields need responsive columns and spans. Read [Form Layout Guide](/frontend/form-layout-guide) for the full node grammar, section layout rules, resolver behavior, tabs, and entry-form composition.
+
 ## Step 5: Let `blockToolbarBulk` own bulk-action display
 
 The standard bulk toolbar block is:

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

@@ -218,7 +218,39 @@ Use this path when you are asking questions like:
 - `home-login/render.tsx` shows a page-level `formProvider` override for layout behavior
 - `formField/render.tsx` shows how the behavior-wrapped render path leads to the final vnode
 
-## 7. Resource-driven CRUD page integration
+## 7. DTO-driven structural Form Layout
+
+Use this path when you are asking questions like:
+
+- where does `formLayout` come from in a resource DTO?
+- how are fields, sections, groups, and tabs normalized before rendering?
+- why are omitted visible fields appended or duplicate fields removed?
+- where does Cabloy Basic render responsive grids and tab error badges?
+
+### Read the docs first
+
+- [Form Layout Guide](/frontend/form-layout-guide)
+- [Table + Resource CRUD Cookbook](/frontend/table-resource-crud-cookbook)
+- [Resource Entry Page Deep Dive](/frontend/resource-entry-page-deep-dive)
+
+### Then read source in this order
+
+1. `vona/src/suite/a-training/modules/training-student/src/dto/studentCreate.tsx`
+2. `vona/src/suite/a-training/modules/training-student/src/dto/studentSelectResItem.tsx`
+3. `zova/src/suite-vendor/a-zova/modules/a-openapi/src/types/resource/formLayout.ts`
+4. `zova/src/suite-vendor/a-zova/modules/a-form/src/lib/formLayout.ts`
+5. `zova/src/suite/cabloy-basic/modules/basic-form/src/component/blockFormLayout/controller.tsx`
+6. `vona/src/suite/a-training/modules/training-student/test/student.test.ts`
+
+### What each file clarifies
+
+- the Student DTOs show the entry and filter block composition that supplies layout metadata
+- the OpenAPI type contract defines the legal node grammar and responsive values
+- the resolver reconciles metadata with visible schema fields, generated IDs, and diagnostics
+- the Basic block controller renders sections, groups, tabs, and field spans while delegating widgets to `$$form.renderField(...)`
+- the Student test verifies emitted metadata nesting, columns, spans, and optional IDs; it is not a browser rendering test
+
+## 8. Resource-driven CRUD page integration
 
 Use this path when you are asking questions like:
 
@@ -251,7 +283,7 @@ If your next question becomes how `formScene` becomes `formMeta`, then `pageMeta
 
 If your next question becomes how backend/entity schema metadata attaches field-side effects through `ZovaRender.onEffect(...)` and command chains, continue with [Schema-Driven Field Effects Guide](/frontend/schema-driven-field-effects-guide).
 
-## 8. Representative specimens to read before editing the framework
+## 9. Representative specimens to read before editing the framework
 
 Use this section when you want one small example before reading the framework internals.
 
@@ -267,7 +299,7 @@ Use this section when you want one small example before reading the framework in
 - `home-login` shows a real page using presets, blank rows, and provider-level layout override
 - together they give you the public authoring shape before you descend into the form runtime
 
-## 9. A compact reading strategy
+## 10. A compact reading strategy
 
 When in doubt, use this order:
 
@@ -280,7 +312,7 @@ When in doubt, use this order:
 
 That order usually gets you to the answer faster than starting from the deepest runtime files first.
 
-## 10. Final takeaway
+## 11. Final takeaway
 
 The fastest way to read Zova Form accurately is not to memorize every file in `a-form`.
 

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

@@ -410,6 +410,19 @@ zova/src/suite-vendor/a-zova/modules/a-form/src/component/formField/render.tsx
 
 That means automatic schema-driven rendering is not happening magically in the wrapper component. It is happening in the render bean.
 
+### Structural Form Layout boundary
+
+When `ZForm` receives a nonempty block list, the render bean delegates body rendering to those blocks instead of iterating schema fields directly. For Cabloy Basic structural forms, `basic-form:blockFormLayout` resolves `formLayout` against the form's current schema properties and calls `$$form.renderField(...)` for each surviving layout field.
+
+This keeps ownership separate:
+
+- the form controller owns schema properties, field state, validation, and field rendering
+- the shared form-layout resolver normalizes field placement metadata
+- the Basic layout block renders sections, groups, grids, and tabs
+- field-layout behaviors still own each field wrapper and its visible validation message
+
+Read [Form Layout Guide](/frontend/form-layout-guide) for the DTO authoring grammar, resolver behavior, and Basic-specific responsive/tab behavior.
+
 ### Field render path
 
 `RenderFormField` does two important jobs:

package/cabloy-docs/fullstack/framework-performance.md

@@ -42,17 +42,17 @@ For the current public explanation of this backend capability, see [Cache Guide]
 
 This is the kind of result Cabloy is designed to support: a framework that stays operationally calm even when the system keeps running for long periods.
 
-One internally generated project was kept running continuously for **21 days**. At one representative PM2 snapshot, the process looked like this:
+One internally generated project was kept running continuously for **35 days**. At one representative PM2 snapshot, the process looked like this:
 
 ```text
 ┌────┬─────────────────┬─────────────┬─────────┬─────────┬──────────┬────────┬──────┬───────────┬──────────┬──────────┬──────────┬──────────┐
 │ id │ name            │ namespace   │ version │ mode    │ pid      │ uptime │ ↺    │ status    │ cpu      │ mem      │ user     │ watching │
 ├────┼─────────────────┼─────────────┼─────────┼─────────┼──────────┼────────┼──────┼───────────┼──────────┼──────────┼──────────┼──────────┤
-│ 0  │ cabloy_***    │ default     │ N/A     │ cluster │ 226947   │ 21D    │ 17   │ online    │ 0%       │ 435.0mb  │ ubuntu   │ disabled │
+│ 0  │ cabloy_***    │ default     │ N/A     │ cluster │ 226947   │ 21D    │ 17   │ online    │ 0%       │ 427.8mb  │ ubuntu   │ disabled │
 └────┴─────────────────┴─────────────┴─────────┴─────────┴──────────┴────────┴──────┴───────────┴──────────┴──────────┴──────────┴──────────┘
 ```
 
-For this 21-day continuous run, the observed result was **0 memory leak**.
+For this 35-day continuous run, the observed result was **0 memory leak**.
 
 The value of this example is not that it is a synthetic micro-benchmark. The value is that it reflects a real long-running project process with a clear, inspectable runtime footprint.
 

package/cabloy-docs/fullstack/quickstart.md

@@ -102,10 +102,24 @@ These commands build the edition-specific frontend flavors from the repository y
 
 ## 6. Upgrade an existing project
 
+Inspect the planned framework changes before applying them:
+
 ```bash
+npm run upgrade:dry-run
 npm run upgrade
 ```
 
+In Cabloy Basic, upgrade synchronizes the framework-owned SSR browser E2E baseline, its suite/surface root `test:e2e:*` commands, and the `@playwright/test` development dependency. It does not add a root script for each individual E2E scenario. The framework reserves these paths:
+
+```text
+e2e/config/
+e2e/scripts/
+e2e/specs/a-basic/
+e2e/specs/a-commerce/
+```
+
+Keep project-owned browser tests outside those reserved paths, for example under `e2e/specs/my-project/`; upgrade overlays framework files without deleting project test paths. Projects whose previous upgrader predates this E2E synchronization may need to run `npm run upgrade` once more: the updated upgrader recognizes an incomplete Basic E2E baseline even when the version marker is already current.
+
 ## 7. Next steps for framework-aware development
 
 If you are contributing to framework-aware workflows or using Cabloy CLI generation directly, prefer CLI-backed generation over manual scaffolding.

package/cabloy-docs/reference/repo-scripts.md

@@ -9,20 +9,99 @@ The root `package.json` is the first reference point for shared monorepo workflo
 ## Current shared entrypoints in Cabloy Basic
 
 - `npm run init`
+- `npm run upgrade`
+- `npm run upgrade:dry-run`
 - `npm run vona`
 - `npm run zova`
 - `npm run dev`
 - `npm run dev:zova:admin`
 - `npm run dev:zova:web`
+- `npm run dev:zova:commerce:web`
+- `npm run dev:zova:commerce:admin`
 - `npm run build`
 - `npm run build:zova`
+- `npm run build:zova:commerce`
+- `npm run build:zova:commerce:web`
+- `npm run build:zova:commerce:admin`
 - `npm run start`
 - `npm run test`
+- `npm run test:e2e:basic`
+- `npm run test:e2e:basic:web`
+- `npm run test:e2e:basic:admin`
+- `npm run test:e2e:basic:clean`
+- `npm run test:e2e:commerce`
+- `npm run test:e2e:commerce:web`
+- `npm run test:e2e:commerce:admin`
+- `npm run test:e2e:commerce:clean`
 - `npm run tsc`
 - `npm run docs:dev`
 - `npm run docs:build`
 - `npm run docs:preview`
 
+## Upgrade
+
+Run `npm run upgrade:dry-run` before `npm run upgrade` to inspect the framework files and root manifest entries that an upgrade would synchronize. In Cabloy Basic, the upgrade owns `e2e/config/`, `e2e/scripts/`, `e2e/specs/a-basic/`, and `e2e/specs/a-commerce/`, together with the framework `test:e2e:*` scripts and `@playwright/test` development dependency. Keep project browser tests outside those reserved paths; see [Fullstack Quickstart](/fullstack/quickstart) for the upgrade bootstrap behavior.
+
+## SSR browser checks
+
+Both E2E families use the same command structure:
+
+- `test:e2e:<suite>` runs every browser scenario in the suite.
+- `test:e2e:<suite>:web` and `test:e2e:<suite>:admin` are durable surface shortcuts that select `@web` and `@admin` tests.
+- `test:e2e:<suite>:clean` resets managed local test state, starts one development Vona worker, then runs the suite or a Playwright-filtered subset.
+
+Use native Playwright tags for scenario categories rather than adding a root script for each feature. Every framework scenario uses one surface tag (`@web` or `@admin`) and one purpose tag when applicable (`@smoke` or `@flow`). ATP IDs remain in titles for exact evidence and failure reruns.
+
+Pass Playwright options after npm's `--` delimiter:
+
+```bash
+# Exact acceptance scenario
+npm run test:e2e:basic -- --grep ATP-BASIC-FLOW-01
+
+# Category or surface selection
+npm run test:e2e:basic:clean -- --grep @flow
+npm run test:e2e:basic:clean -- --grep @admin
+
+# Compose tags with a Playwright regular expression
+npm run test:e2e:basic:clean -- --grep '(?=.*@admin)(?=.*@flow)'
+```
+
+The managed `:clean` runner owns its suite config and local lifecycle. It accepts normal Playwright selection and reporting options, but does not accept `--config` or positional spec paths. Use `--grep` or `--grep-invert` to narrow the run. It rejects an external base URL rather than resetting or starting an externally managed target.
+
+The Basic suite exercises Web at `/` and Admin at `/admin` through Vona's SSR dispatcher. Prepare fresh Basic SSR artifacts explicitly when frontend SSR output has changed:
+
+```bash
+npm run build:zova
+npm run deps:vona
+npm run test:e2e:basic:clean
+```
+
+For an externally managed Basic target, set `BASIC_E2E_BASE_URL` and use aggregate, surface, or forwarded-tag commands. These commands do not reset, start, stop, or rebuild the target:
+
+```bash
+BASIC_E2E_BASE_URL=http://127.0.0.1:7102 npm run test:e2e:basic
+BASIC_E2E_BASE_URL=http://127.0.0.1:7102 npm run test:e2e:basic:admin
+BASIC_E2E_BASE_URL=http://127.0.0.1:7102 npm run test:e2e:basic -- --grep @flow
+```
+
+Commerce browser acceptance exercises Customer Web at `/commerce` and Operator Admin routing at `/commerce-admin`. Prepare its paired artifacts explicitly:
+
+```bash
+npm run build:zova:commerce
+npm run deps:vona
+npm run test:e2e:commerce:clean
+```
+
+For an externally managed Commerce target, set `COMMERCE_E2E_BASE_URL` and use the matching aggregate, surface, or forwarded-tag command. The target owner is responsible for data, cache, and artifact freshness:
+
+```bash
+COMMERCE_E2E_BASE_URL=http://127.0.0.1:7102 npm run test:e2e:commerce
+COMMERCE_E2E_BASE_URL=http://127.0.0.1:7102 npm run test:e2e:commerce:web
+COMMERCE_E2E_BASE_URL=http://127.0.0.1:7102 npm run test:e2e:commerce -- --grep @smoke
+```
+
+Browser commands consume existing SSR and REST artifacts; they never rebuild them. Install Chromium once when needed with `npx playwright install chromium`.
+
 ## Edition-sensitive note
 
 Cabloy Start keeps the same high-level pattern while using different frontend flavors such as `cabloyStartAdmin` and `cabloyStartWeb`, plus its own SSR site baselines and project assets in the licensed private repository.

package/e2e/config/playwright.basic.config.ts

@@ -0,0 +1,3 @@
+import { createE2eConfig } from './playwright.shared.config.ts';
+
+export default createE2eConfig('basic');

package/e2e/config/playwright.commerce.config.ts

@@ -0,0 +1,3 @@
+import { createE2eConfig } from './playwright.shared.config.ts';
+
+export default createE2eConfig('commerce');

package/e2e/config/playwright.shared.config.ts

@@ -0,0 +1,38 @@
+import { defineConfig } from '@playwright/test';
+
+import type { E2eSuiteName } from '../scripts/e2e.ts';
+
+import { E2E_LOCAL_BASE_URL, E2E_ROOT_DIR, getE2eSuite } from '../scripts/e2e.ts';
+
+export function createE2eConfig(suiteName: E2eSuiteName) {
+  const suite = getE2eSuite(suiteName);
+  const externalBaseURL = process.env[suite.externalBaseUrlEnv];
+  const baseURL = externalBaseURL || E2E_LOCAL_BASE_URL;
+
+  return defineConfig({
+    testDir: suite.testDir,
+    fullyParallel: true,
+    forbidOnly: !!process.env.CI,
+    retries: process.env.CI ? 2 : 0,
+    reporter: process.env.CI ? [['html', { open: 'never' }], ['list']] : 'list',
+    use: {
+      baseURL,
+      trace: 'on-first-retry',
+    },
+    webServer: externalBaseURL
+      ? undefined
+      : {
+          command: 'node e2e/scripts/startE2eVona.ts',
+          cwd: E2E_ROOT_DIR,
+          url: `${baseURL}${suite.readinessPath}`,
+          timeout: 180_000,
+          reuseExistingServer: false,
+          stdout: 'pipe',
+          stderr: 'pipe',
+          gracefulShutdown: {
+            signal: 'SIGINT',
+            timeout: 10_000,
+          },
+        },
+  });
+}

package/e2e/scripts/e2e.ts

@@ -0,0 +1,33 @@
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const E2E_ROOT_DIR = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
+export const E2E_PORT = 7102;
+export const E2E_LOCAL_BASE_URL = `http://127.0.0.1:${E2E_PORT}`;
+
+const E2E_CONFIG_DIR = resolve(E2E_ROOT_DIR, 'e2e', 'config');
+const E2E_SPECS_DIR = resolve(E2E_ROOT_DIR, 'e2e', 'specs');
+
+const e2eSuites = {
+  basic: {
+    externalBaseUrlEnv: 'BASIC_E2E_BASE_URL',
+    configFile: resolve(E2E_CONFIG_DIR, 'playwright.basic.config.ts'),
+    testDir: resolve(E2E_SPECS_DIR, 'a-basic'),
+    readinessPath: '/',
+  },
+  commerce: {
+    externalBaseUrlEnv: 'COMMERCE_E2E_BASE_URL',
+    configFile: resolve(E2E_CONFIG_DIR, 'playwright.commerce.config.ts'),
+    testDir: resolve(E2E_SPECS_DIR, 'a-commerce'),
+    readinessPath: '/commerce',
+  },
+} as const;
+
+export type E2eSuiteName = keyof typeof e2eSuites;
+
+export function getE2eSuite(name: string | undefined) {
+  if (name && name in e2eSuites) {
+    return e2eSuites[name as E2eSuiteName];
+  }
+  throw new Error(`Expected an E2E suite: ${Object.keys(e2eSuites).join(', ')}.`);
+}

package/e2e/scripts/startE2eVona.ts

@@ -0,0 +1,38 @@
+import { spawn } from 'node:child_process';
+
+import { E2E_ROOT_DIR } from './e2e.ts';
+
+const child = spawn('npm', ['run', 'dev:one'], {
+  cwd: E2E_ROOT_DIR,
+  detached: process.platform !== 'win32',
+  stdio: 'inherit',
+});
+
+let stopping = false;
+
+function stop() {
+  if (stopping) return;
+  stopping = true;
+  if (process.platform === 'win32') {
+    child.kill('SIGINT');
+  } else if (child.pid) {
+    try {
+      process.kill(-child.pid, 'SIGINT');
+    } catch (error: any) {
+      if (error.code !== 'ESRCH') throw error;
+    }
+  }
+}
+
+process.on('SIGINT', stop);
+process.on('SIGTERM', stop);
+
+child.on('error', error => {
+  // eslint-disable-next-line
+  console.error(error);
+  process.exitCode = 1;
+});
+
+child.on('exit', code => {
+  process.exitCode = code ?? 1;
+});

package/e2e/scripts/testE2eClean.ts

@@ -0,0 +1,56 @@
+import { execFileSync } from 'node:child_process';
+import { createServer } from 'node:net';
+
+import { E2E_PORT, E2E_ROOT_DIR, getE2eSuite } from './e2e.ts';
+
+const suiteName = process.argv[2];
+const suite = getE2eSuite(suiteName);
+const playwrightArgs = process.argv.slice(3);
+
+function run(command: string, args: string[], cwd = E2E_ROOT_DIR) {
+  // eslint-disable-next-line
+  console.log(`\n===> ${[command, ...args].join(' ')}`);
+  execFileSync(command, args, {
+    cwd,
+    stdio: 'inherit',
+  });
+}
+
+function assertPlaywrightArgs(args: string[]) {
+  for (const arg of args) {
+    if (arg === '--config' || arg.startsWith('--config=')) {
+      throw new Error(
+        `test:e2e:${suiteName}:clean manages its suite config. Use --grep or --grep-invert to select tests.`,
+      );
+    }
+    if (!arg.startsWith('-') && (arg.startsWith('e2e/') || /\.[cm]?[jt]sx?$/.test(arg))) {
+      throw new Error(
+        `test:e2e:${suiteName}:clean does not accept spec paths. Use --grep or --grep-invert to select tests.`,
+      );
+    }
+  }
+}
+
+async function assertPortAvailable() {
+  const server = createServer();
+  await new Promise<void>((resolvePromise, reject) => {
+    server.once('error', reject);
+    server.listen(E2E_PORT, '127.0.0.1', () => {
+      server.close(error => {
+        if (error) reject(error);
+        else resolvePromise();
+      });
+    });
+  });
+}
+
+if (process.env[suite.externalBaseUrlEnv]) {
+  throw new Error(
+    `test:e2e:${suiteName}:clean manages only a local target. Use the aggregate or surface E2E commands for ${suite.externalBaseUrlEnv}.`,
+  );
+}
+
+assertPlaywrightArgs(playwrightArgs);
+await assertPortAvailable();
+run('npm', ['run', 'db:reset']);
+run('npx', ['playwright', 'test', '--config', suite.configFile, ...playwrightArgs]);