cabloy 5.1.159 → 5.1.161

package/repo-docs/frontend/table-guide.md

@@ -47,7 +47,7 @@ If you only remember one idea, remember this one:
 That leads to three common authoring surfaces:
 
 - `ZTable` — the root table component
-- schema `rest.table` metadata — the default source of visibility, order, and render decisions
+- schema metadata — `ZovaRender.column(...)` supplies table-column layout/capability metadata, while shared/table-scene overlays supply effective visibility, order, and render metadata
 - `tableCell` beans — the main extension surface for reusable cell rendering
 
 ## One running example through this guide: Student list page
@@ -123,17 +123,12 @@ A practical reading takeaway is:
 
 In the default path, `ZTable` reads table-scene metadata from the row schema.
 
-The key table-facing metadata surface is the schema field `rest.table`, especially values such as:
-
-- `order`
-- `visible`
-- `render`
-- `columnProps`
+The table sees the **effective table metadata**, not only one literal source object. It combines shared field `rest` metadata with the table-scene `rest.table` overlay, then orders the resulting properties by effective `rest.order`.
 
 A simplified mental model is:
 
 ```text
-schema row -> load table properties -> sort by order -> filter by visible -> build columns -> render cells
+schema row -> merge table metadata -> sort by order -> filter by visible -> build columns -> render cells
 ```
 
 That means the default list-page question becomes less:
@@ -146,6 +141,58 @@ and more:
 
 This is why table work often belongs in the broader contract loop when the real source of truth is backend field metadata.
 
+## Step 4: Configure physical columns with `ZovaRender.column(...)`
+
+`ZovaRender.column(...)` is a shared Cabloy/Zova schema-metadata API available in both Cabloy Basic and Cabloy Start. It returns a schema transformer that writes column options under `rest.table`; it does **not** register a frontend column or render a cell by itself.
+
+```ts
+@Api.field(
+  v.title($locale('Name')),
+  ZovaRender.column({
+    align: 'left',
+    width: 240,
+    fixed: 'left',
+    enableSorting: true,
+    sortDescFirst: true,
+  }),
+  v.string(),
+)
+name: string;
+```
+
+The current options are:
+
+| Option          | Meaning in the table runtime                                                                                                   |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `order`         | Orders this property among the effective table properties. For shared field order, `ZovaRender.order(...)` is usually clearer. |
+| `align`         | Applies `left`, `center`, or `right` text alignment to the header and cells.                                                   |
+| `width`         | Supplies the TanStack column size and current renderers apply it as pixel width and minimum width.                             |
+| `fixed`         | Pins the column to the `left` or `right`; the table runtime calculates pinning and renderers apply sticky offsets.             |
+| `enableSorting` | Requests a sortable header, subject to the order-schema capability described below.                                            |
+| `sortDescFirst` | Makes the first header toggle descend; it does not change backend order syntax.                                                |
+
+`ZovaRender.column(...)` configures the physical column. `ZovaRender.cell(...)` independently selects the cell renderer and its options. For example, a virtual Operations field can be right-pinned and centered while its content comes from a reusable `tableCell` resource:
+
+```ts
+@Api.field(
+  v.title($locale('Operations')),
+  ZovaRender.order(1, 'max'),
+  ZovaRender.column({ align: 'center', width: 360, fixed: 'right' }),
+  ZovaRender.cell('basic-table:actionOperationsRow', { actions }),
+)
+_operationsRow?: unknown;
+```
+
+The `basic-table:*` renderer key in this example is Cabloy Basic-specific. The `ZovaRender.column(...)` contract itself is shared; use the active edition's renderer keys when selecting a cell resource.
+
+### Enable server-backed sorting
+
+`enableSorting: true` is necessary but not sufficient. The same field, canonical key, or schema alias must also exist in `schemaOrder`; otherwise the table deliberately creates a non-sortable column.
+
+A direct `ZTable` consumer owns and passes `schemaOrder`, controlled `sorting`, and `onSortingChange`. In the standard Cabloy Basic resource-page path, `basic-page:blockTable` passes those values from `basic-page:blockPage`; the page translates one manual table sort into backend `orders` and reloads the resource query. The loaded page is not client-side sorted by TanStack.
+
+For relation-order rewriting, see [Existing Resource Field Update](/backend/resource-field-update#filter-and-sort-a-relation-by-its-display-field). For the resource-page bridge, see [Table + Resource CRUD Cookbook](/frontend/table-resource-crud-cookbook).
+
 A practical expression example is a schema-driven cell display that formats the current row value through CEL:
 
 ```text
@@ -156,7 +203,7 @@ In the shared table CEL scope, `getValue(name)` reads the current row value and
 
 For the schema side of that contract, also see [API Schema Guide](/frontend/api-schema-guide).
 
-## Step 4: Use built-in or custom `tableCell` render resources
+## Step 5: Use built-in or custom `tableCell` render resources
 
 A column render is usually chosen through schema metadata such as:
 
@@ -184,7 +231,7 @@ A practical rule is:
 - use built-in `tableCell` resources first
 - add a custom `tableCell` bean only when the business UI really needs module-owned rendering behavior
 
-## Step 5: Create a custom `tableCell` bean
+## Step 6: Create a custom `tableCell` bean
 
 When a built-in renderer is not enough, use the existing CLI-backed scene workflow.
 
@@ -230,7 +277,7 @@ That scaffold is useful because it starts from the correct Zova scene contract:
 
 For the broader scene system behind this decorator, see [Bean Scene Authoring](/frontend/bean-scene-authoring).
 
-## Step 6: Add page-local custom columns with `getColumns(...)`
+## Step 7: Add page-local custom columns with `getColumns(...)`
 
 When most columns should stay schema-driven but one column should be page-local, use `getColumns(...)`.
 
@@ -275,7 +322,7 @@ A practical caveat is:
 
 So a mixed table does **not** mean bypassing Zova. It means extending the existing runtime through its own hooks.
 
-## Step 7: Use resource-driven page blocks for CRUD list pages
+## Step 8: Use resource-driven page blocks for CRUD list pages
 
 For standard resource pages, the more common public surface is not direct `ZTable` usage. It is the block-based page runtime:
 
@@ -299,7 +346,7 @@ This gives you a cohesive CRUD path where:
 
 For the resource ownership side of that page shape, see [Model Resource Owner Pattern](/frontend/model-resource-owner-pattern).
 
-## Step 8: Know when to use `BeanControllerPageTableBase`
+## Step 9: Know when to use `BeanControllerPageTableBase`
 
 If your table belongs directly to a page controller rather than a reusable component controller, the page-oriented base class already exists:
 
@@ -322,15 +369,19 @@ TanStack Table is still important, but the business-facing runtime is controller
 
 For many resource pages, the faster path is to let `rest.table` metadata describe the default columns first.
 
-### Mistake 3: Bypassing `tableCell` beans for reusable cell behavior
+### Mistake 3: Treating `ZovaRender.column(...)` as a cell renderer
+
+`ZovaRender.column(...)` supplies column layout and sorting metadata. Use `ZovaRender.cell(...)` to name the cell render target, and use a `tableCell` bean when that reusable renderer needs module-owned behavior.
+
+### Mistake 4: Bypassing `tableCell` beans for reusable cell behavior
 
 If a renderer should be shared across pages or modules, prefer a `tableCell` resource over repeated page-local callbacks.
 
-### Mistake 4: Treating `controllerRef` like a generic Vue DOM ref
+### Mistake 5: Treating `controllerRef` like a generic Vue DOM ref
 
 `controllerRef` gives you the table controller instance, not a plain DOM element.
 
-### Mistake 5: Rebuilding CRUD list wiring manually when `basic-page` already owns it
+### Mistake 6: Rebuilding CRUD list wiring manually when `basic-page` already owns it
 
 For standard resource pages, prefer the existing block/page runtime before hand-building a custom table flow.
 
@@ -340,12 +391,12 @@ If you want the shortest accurate path to a real business table, use this order:
 
 1. make sure the backend row schema is already the right contract truth
 2. start with a resource page or direct `ZTable`
-3. let schema metadata drive the default columns
-4. reuse built-in `tableCell` renderers first
+3. let schema metadata drive the default columns; add `ZovaRender.column(...)` only where layout, pinning, or sorting metadata is needed
+4. use `ZovaRender.cell(...)` and built-in `tableCell` renderers for cell content first
 5. add page-local `getColumns(...)` only where needed
 6. create custom `tableCell` beans only where the UI becomes business-specific
 7. continue with [TableCell Authoring Cookbook](/frontend/table-cell-cookbook) when you want concrete patterns for custom cell beans and row actions
-8. continue with [Table + Resource CRUD Cookbook](/frontend/table-resource-crud-cookbook) when you want the standard resource-page integration path for filter, bulk actions, table, and pager
+8. continue with [Table + Resource CRUD Cookbook](/frontend/table-resource-crud-cookbook) when you want the standard resource-page integration path for filter, bulk actions, table, pager, and server sorting
 9. continue with [Zova Table Under the Hood](/frontend/zova-table-under-the-hood) when you want the runtime explanation behind the public authoring surface
 10. continue with [Zova Table Source Reading Map](/frontend/zova-table-source-reading-map) when you need framework-level source details and targeted file-order guidance
 
@@ -359,9 +410,11 @@ When documenting or changing a table workflow, verify in this order:
    npm run zova :create:bean --help
    ```
 
-2. confirm the `tableCell` scene metadata still exists in the current `a-table` module
-3. confirm the runtime claims against the current `a-table`, `basic-table`, and `basic-page` source
-4. if you changed docs, build the docs site:
+2. confirm the `ZovaRender.column(...)` option contract and table-scene metadata merge still match current source
+3. confirm the `tableCell` scene metadata still exists in the current `a-table` module
+4. for sortable resource columns, verify header state, fixed-column layout/overflow where relevant, and the backend `orders` request
+5. confirm the runtime claims against the current `a-table`, `basic-table`, and `basic-page` source
+6. if you changed docs, build the docs site:
 
    ```bash
    npm run docs:build

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

@@ -269,6 +269,8 @@ Its bridge role is very clear:
 - render `ZTable`
 - pass page data into `data`
 - pass row schema into `schema`
+- pass the resource order schema into `schemaOrder`
+- pass controlled `sorting` and `onSortingChange`
 - pass page CEL scope into `tableScope`
 - capture the table controller through `controllerRef`
 
@@ -329,10 +331,13 @@ _operationsRow?: unknown;
 
 This is the practical reverse-sharing model:
 
-- the backend row contract chooses the table cell resource identity
+- `ZovaRender.column(...)` configures physical-column behavior such as alignment, width, pinning, and sorting eligibility
+- `ZovaRender.cell(...)` chooses the table-cell resource identity and its options
 - the frontend table runtime resolves that resource
 - the page block and table block do not need page-local hard-coded row-action wiring
 
+For example, an Operations field can add `ZovaRender.column({ align: 'center', width: 360, fixed: 'right' })` beside the existing `ZovaRender.cell(...)`. `ZovaRender.column(...)` is a shared Basic/Start capability; the `basic-table:*` cell key remains a Cabloy Basic choice.
+
 For the built-in metadata-sharing teaching path, see [Tutorial 3: Frontend Metadata Sharing](/fullstack/tutorial-3-frontend-metadata-sharing).
 
 For the forward-chain row-action teaching path, see [Tutorial 5: Backend Contract Sharing](/fullstack/tutorial-5-backend-contract-sharing).
@@ -346,10 +351,24 @@ For standard CRUD list pages, most customization should happen in one of these p
 Use this when:
 
 - a field should change order
+- a column should change alignment, width, or left/right pinning
+- a server-authorized field should expose a sortable header
 - a column should be visible or hidden
 - a field should use a different built-in or custom `tableCell`
 
-This is usually the first and best extension point.
+This is usually the first and best extension point. Use `ZovaRender.column(...)` for the column metadata and `ZovaRender.cell(...)` for the cell renderer; do not treat either helper as a replacement for the other.
+
+### Enable standard resource-page sorting
+
+For a normal Cabloy Basic resource list, backend field metadata can request a sortable column with:
+
+```ts
+ZovaRender.column({ enableSorting: true });
+```
+
+The field must also be present in the resource `schemaOrder`; that order schema remains the authority for whether the header is actually sortable. `blockTable` forwards the order schema plus controlled sorting state into `ZTable`, and `blockPage` turns one header selection into backend `orders` before reloading the resource query. This is server sorting, not local reordering of the current page.
+
+For the full shared `ZovaRender.column(...)` contract, see [Table Guide](/frontend/table-guide#configure-physical-columns-with-zovarendercolumn). For relation-backed order rewriting, see [Existing Resource Field Update](/backend/resource-field-update#filter-and-sort-a-relation-by-its-display-field).
 
 ### Extension point B: backend block composition metadata
 
@@ -505,8 +524,8 @@ If you want the shortest path to a real CRUD list page, use this order:
 1. generate or confirm the backend CRUD contract thread
 2. confirm the resource-owner model already exposes the required schemas and permissions
 3. keep the standard `blockPage -> blockFilter -> blockToolbarBulk -> blockTable -> blockPager` chain
-4. refine backend row metadata for visible columns and row actions
-5. reuse built-in `tableCell` resources first
+4. refine backend row metadata for visible columns, layout/pinning/sort capability through `ZovaRender.column(...)`, and row actions
+5. reuse `ZovaRender.cell(...)` with built-in `tableCell` resources first
 6. add custom `tableCell` resources only where the UI becomes business-specific
 7. change block controllers only when the existing runtime is structurally insufficient
 8. continue with [Table Guide](/frontend/table-guide) for the public `ZTable` surface
@@ -533,6 +552,8 @@ When authoring or documenting a resource CRUD list page, verify in this order:
    - filter works
    - bulk actions render correctly
    - table columns and row actions match metadata
+   - fixed columns, widths, and overflow behave as intended when configured
+   - sortable headers expose the expected state and reload with the intended backend `orders`
    - pager updates the list correctly
 7. if you changed docs, build the docs site:
 

package/repo-docs/frontend/zova-table-source-reading-map.md

@@ -120,7 +120,8 @@ Use this path when you are asking questions like:
 Use this path when you are asking questions like:
 
 - how does a row schema become visible columns?
-- where do `visible`, `order`, `render`, and `columnProps` come from?
+- where do `order`, `align`, `width`, `fixed`, `enableSorting`, and `sortDescFirst` come from?
+- where do `visible`, `render`, and `columnProps` come from?
 - how does the table scene differ from form or filter scenes?
 
 ### Read the docs first
@@ -130,17 +131,51 @@ Use this path when you are asking questions like:
 
 ### Then read source in this order
 
+1. `zova/packages-cli/cli-set-front/cli/templates/rest/rest.ts`
+2. `zova/src/suite-vendor/a-zova/modules/a-openapi/src/types/rest.ts`
+3. `zova/src/suite-vendor/a-zova/modules/a-openapi/src/lib/schema.ts`
+4. `zova/src/suite-vendor/a-zova/modules/a-table/src/component/table/controller.tsx`
+5. `zova/src/suite-vendor/a-zova/modules/a-table/src/component/table/render.tsx`
+
+### What each file clarifies
+
+- `cli/templates/rest/rest.ts` shows that `ZovaRender.column(...)` writes `ITableColumnOptions` under `rest.table`
+- `types/rest.ts` defines `order`, `align`, `width`, `fixed`, `enableSorting`, and `sortDescFirst`
+- `schema.ts` shows `loadSchemaProperties(...)`, `$ref` resolution, and the merge of shared `rest` metadata with table-scene overlays
+- `controller.tsx` shows `_createProperties()`, `_createTableMeta()`, `_createColumnsMiddle()`, order-schema sorting eligibility, and pinning
+- `render.tsx` shows how effective metadata becomes alignment, dimensions, fixed-column styles, and sortable header DOM
+
+## 4. Column metadata, sortable headers, and resource orders
+
+Use this path when you are asking questions like:
+
+- why did `ZovaRender.column({ enableSorting: true })` not make a header sortable?
+- how do fixed columns become sticky left/right columns?
+- how does one header click become a resource request `orders` value?
+
+### Read the docs first
+
+- [Table Guide](/frontend/table-guide)
+- [Table + Resource CRUD Cookbook](/frontend/table-resource-crud-cookbook)
+- [Existing Resource Field Update](/backend/resource-field-update#filter-and-sort-a-relation-by-its-display-field)
+
+### Then read source in this order
+
 1. `zova/src/suite-vendor/a-zova/modules/a-table/src/component/table/controller.tsx`
-2. `zova/src/suite-vendor/a-zova/modules/a-openapi/src/lib/schema.ts`
-3. `zova/src/suite-vendor/a-zova/modules/a-openapi/src/types/rest.ts`
+2. `zova/src/suite-vendor/a-zova/modules/a-table/src/component/table/render.tsx`
+3. `zova/src/suite/cabloy-basic/modules/basic-page/src/component/blockTable/controller.tsx`
+4. `zova/src/suite/cabloy-basic/modules/basic-page/src/component/blockPage/controller.tsx`
 
 ### What each file clarifies
 
-- `controller.tsx` shows `_createProperties()`, `_createTableMeta()`, and `_createColumnsMiddle()`
-- `schema.ts` shows `loadSchemaProperties(...)`, `$ref` resolution, and scene-specific `rest` overlays
-- `rest.ts` shows the schema extension contract, including `rest.table` and table-related render types
+- `controller.tsx` shows that `enableSorting` also requires the property key or aliases to exist in `schemaOrder`, and shows left/right pinning construction
+- `render.tsx` shows the header toggle, `aria-sort`, indicators, and sticky styles
+- `blockTable/controller.tsx` shows the handoff of `schemaOrder`, controlled sorting, and `onSortingChange`
+- `blockPage/controller.tsx` shows conversion of the single current sort into backend `orders` and query reload
+
+The result is a controlled, manual server-sorting path: the standard resource page does not client-side sort rows that have already been fetched. The `basic-page` files are Cabloy Basic specimens; the metadata API and base Zova Table behavior are shared with Cabloy Start, whose page module paths must be resolved in that edition.
 
-## 4. `tableCell` bean-scene contract and decorator surface
+## 5. `tableCell` bean-scene contract and decorator surface
 
 Use this path when you are asking questions like:
 
@@ -168,7 +203,7 @@ Use this path when you are asking questions like:
 - `package.json` shows `zovaModule.onions.tableCell` and boilerplate metadata
 - the boilerplate files show the intended scaffold shape for normal cells and row-action cells
 
-## 5. Cell render pipeline and CEL/JSX scope
+## 6. Cell render pipeline and CEL/JSX scope
 
 Use this path when you are asking questions like:
 
@@ -193,7 +228,7 @@ Use this path when you are asking questions like:
 - `tableColumn.ts` shows column scope, cell scope, and table column render types
 - `tableCell.ts` shows the render-context contract received by a `tableCell` bean
 
-## 6. Representative built-in cell renderers
+## 7. Representative built-in cell renderers
 
 Use this path when you are asking questions like:
 
@@ -220,7 +255,7 @@ Use this path when you are asking questions like:
 - `tableCell.select.tsx` shows value-to-item mapping
 - `actionOperationsRow.tsx` shows advanced visibility checks, nested action rendering, and permission-aware orchestration
 
-## 7. Custom columns through `getColumns(...)`
+## 8. Custom columns through `getColumns(...)`
 
 Use this path when you are asking questions like:
 
@@ -243,15 +278,15 @@ Use this path when you are asking questions like:
 
 - `types/table.ts` shows `TypeTableGetColumns` and `TypeTableCreateColumnRender`
 - `controller.tsx` shows how custom columns are given `next(...)`, `createColumnRender(...)`, and the table controller itself
-- `basic-table/render.tsx` shows a module-level consumer wrapping `ZTable` rather than replacing its runtime
+- `basic-table/render.tsx` is a Cabloy Basic forwarding wrapper around `ZTable`; it preserves the custom-column hook rather than serving as an executable custom-column specimen
 
-## 8. Resource-page integration
+## 9. Resource-page integration
 
 Use this path when you are asking questions like:
 
 - how does a resource list page feed schema and data into `ZTable`?
-- where do `data`, `schemaRow`, and `tableScope` come from?
-- where should permission-sensitive table refresh be debugged?
+- where do `data`, `schemaRow`, `schemaOrder`, and `tableScope` come from?
+- where should permission-sensitive table refresh or resource sorting be debugged?
 
 ### Read the docs first
 
@@ -266,11 +301,11 @@ Use this path when you are asking questions like:
 
 ### What each file clarifies
 
-- `blockPage/controller.tsx` shows resource ownership, query state, page CEL scope, permissions, and table refresh integration
-- `blockTable/controller.tsx` shows the direct bridge from page block to `ZTable`
+- `blockPage/controller.tsx` shows resource ownership, query state, page CEL scope, permissions, table refresh integration, and `orders` mapping
+- `blockTable/controller.tsx` shows the direct bridge from page block to `ZTable`, including order schema and controlled sorting props
 - the Vona DTO specimen shows the block-based page composition consumed from backend-owned metadata
 
-## 9. Representative specimens to read before editing the framework
+## 10. Representative specimens to read before editing the framework
 
 Use this section when you want one small example before reading framework internals.
 
@@ -288,7 +323,7 @@ Use this section when you want one small example before reading framework intern
 
 Together they give you the public integration, the advanced cell path, and the minimal cell path before you descend into the whole table runtime.
 
-## 10. A compact reading strategy
+## 11. A compact reading strategy
 
 When in doubt, use this order:
 
@@ -301,7 +336,7 @@ When in doubt, use this order:
 
 That order usually gets you to the answer faster than starting from the deepest runtime files first.
 
-## 11. Final takeaway
+## 12. Final takeaway
 
 The fastest way to read Zova Table accurately is not to memorize every file in `a-table`.
 

package/repo-docs/frontend/zova-table-under-the-hood.md

@@ -58,13 +58,14 @@ This page is that bridge.
 
 For a typical Zova table, the shortest accurate model is:
 
-1. the `ZTable` wrapper creates a table controller bean through the normal Zova controller path
-2. the table controller loads table-scene schema properties from the row schema
-3. the controller builds table metadata with visible properties and per-column render functions
-4. the controller creates TanStack table options through Zova’s `$useTable(...)` wrapper
-5. each cell render resolves either to text fallback, a general JSX render target, or a `tableCell` bean
-6. the cell runtime evaluates JSX/CEL props with table-aware column and cell scope
-7. resource pages feed schema, data, permissions, and page scope into the same table runtime through `basic-page:blockTable`
+1. backend schema helpers such as `ZovaRender.column(...)` attach table-column metadata to the field contract
+2. the `ZTable` wrapper creates a table controller bean through the normal Zova controller path
+3. the table controller loads effective table-scene schema properties from the row schema
+4. the controller builds table metadata with visible properties and per-column render functions
+5. the controller creates TanStack table options through Zova’s `$useTable(...)` wrapper
+6. each cell render resolves either to text fallback, a general JSX render target, or a `tableCell` bean
+7. the cell runtime evaluates JSX/CEL props with table-aware column and cell scope
+8. resource pages feed schema, data, permissions, and page scope into the same table runtime through `basic-page:blockTable`
 
 That is why Zova Table is not only a thin wrapper around TanStack Table. The business-facing runtime surface is still Zova-native.
 
@@ -98,25 +99,27 @@ These three files already show the core architecture:
 
 When you want to trace the full mechanism, read these files in order:
 
-1. `zova/src/suite-vendor/a-zova/modules/a-table/src/.metadata/component/table.ts`
-2. `zova/src/suite-vendor/a-zova/modules/a-table/src/component/table/controller.tsx`
-3. `zova/src/suite-vendor/a-zova/modules/a-table/src/lib/beanControllerTableBase.ts`
-4. `zova/src/suite-vendor/a-zova/modules/a-table/src/component/table/render.tsx`
-5. `zova/src/suite-vendor/a-zova/modules/a-openapi/src/lib/schema.ts`
-6. `zova/src/suite-vendor/a-zova/modules/a-table/src/types/tableCell.ts`
-7. `zova/src/suite/cabloy-basic/modules/basic-page/src/component/blockTable/controller.tsx`
-8. `zova/src/suite/cabloy-basic/modules/basic-page/src/component/blockPage/controller.tsx`
+1. `zova/packages-cli/cli-set-front/cli/templates/rest/rest.ts`
+2. `zova/src/suite-vendor/a-zova/modules/a-table/src/.metadata/component/table.ts`
+3. `zova/src/suite-vendor/a-zova/modules/a-table/src/component/table/controller.tsx`
+4. `zova/src/suite-vendor/a-zova/modules/a-table/src/lib/beanControllerTableBase.ts`
+5. `zova/src/suite-vendor/a-zova/modules/a-table/src/component/table/render.tsx`
+6. `zova/src/suite-vendor/a-zova/modules/a-openapi/src/lib/schema.ts`
+7. `zova/src/suite-vendor/a-zova/modules/a-table/src/types/tableCell.ts`
+8. `zova/src/suite/cabloy-basic/modules/basic-page/src/component/blockTable/controller.tsx`
+9. `zova/src/suite/cabloy-basic/modules/basic-page/src/component/blockPage/controller.tsx`
 
 A compact role map is:
 
+- `cli/templates/rest/rest.ts` shows that `ZovaRender.column(...)` stores its options under `rest.table`
 - `table.ts` shows how the public wrapper enters `useController(...)`
-- `component/table/controller.tsx` owns schema properties, metadata refresh, TanStack bridge, and cell rendering
+- `component/table/controller.tsx` owns schema properties, metadata refresh, TanStack bridge, pinning, sorting eligibility, and cell rendering
 - `beanControllerTableBase.ts` shows the Zova wrapper around `useVueTable(...)`
-- `component/table/render.tsx` shows the default table DOM render path through `FlexRender`
-- `schema.ts` shows how table-scene schema properties are loaded and ordered
+- `component/table/render.tsx` shows the default table DOM render path, layout metadata, sortable headers, and `FlexRender`
+- `schema.ts` shows how top-level and table-scene metadata are merged and ordered
 - `types/tableCell.ts` shows the `tableCell` scene contract
-- `blockTable/controller.tsx` shows how page blocks feed `data`, `schema`, and `tableScope` into `ZTable`
-- `blockPage/controller.tsx` shows where resource data, permissions, and page scope come from
+- `blockTable/controller.tsx` shows how Basic page blocks feed data, schemas, scope, and sorting state into `ZTable`
+- `blockPage/controller.tsx` shows where resource data, permissions, page scope, and backend `orders` mapping come from
 
 ## Step-by-step runtime path
 
@@ -205,16 +208,19 @@ zova/src/suite-vendor/a-zova/modules/a-openapi/src/lib/schema.ts
 
 The important runtime path is:
 
-1. the table receives `schema`
-2. `_createProperties()` computes `this.$sdk.loadSchemaProperties(this.schema, 'table')`
-3. `loadSchemaProperties(...)` resolves `$ref`, applies `rest.table` overlays, and sorts by `rest.order`
-4. `_createTableMeta()` iterates those properties and decides visibility and render behavior
-5. `_createColumnsMiddle()` converts the surviving properties into TanStack column definitions
+1. `ZovaRender.column(options)` stores the field's column options under `rest.table`
+2. the table receives `schema`
+3. `_createProperties()` computes `this.$sdk.loadSchemaProperties(this.schema, 'table')`
+4. `loadSchemaProperties(...)` resolves `$ref`, merges shared `rest` metadata with the `rest.table` overlay, and sorts by effective `rest.order`
+5. `_createTableMeta()` iterates those properties and decides visibility and render behavior
+6. `_createColumnsMiddle()` converts the surviving properties into TanStack column definitions
+
+`ZovaRender.column(...)` is a shared Zova API available in both Cabloy Basic and Cabloy Start. It supplies metadata only; it neither registers a frontend column nor selects a cell renderer. `ZovaRender.cell(...)` supplies the render target, and `tableCell` beans implement reusable cell behavior.
 
 A practical reading takeaway is:
 
 - **schema is not only validation truth**
-- **schema also drives table order, visibility, and cell render metadata**
+- **schema also drives table order, physical-column behavior, visibility, and cell render metadata**
 
 ## 5. How table metadata is built
 
@@ -257,6 +263,21 @@ A practical reading takeaway is:
 - **TanStack owns the row-model mechanics**
 - **the controller still owns which data and columns TanStack sees**
 
+### Column metadata becomes TanStack and DOM behavior
+
+When `_createColumnsMiddle()` creates each surviving property column, it maps effective table metadata as follows:
+
+| Metadata             | Controller and render behavior                                                                       |
+| -------------------- | ---------------------------------------------------------------------------------------------------- |
+| `rest.order`         | Orders properties during schema-property loading.                                                    |
+| `rest.width`         | Becomes the TanStack `size`; render beans apply pixel `width` and `min-width`.                       |
+| `rest.align`         | Remains in column metadata; render beans apply header/cell text alignment.                           |
+| `rest.fixed`         | Builds left/right TanStack pinning arrays; render beans use sticky positions and calculated offsets. |
+| `rest.enableSorting` | Enables sorting only when the field's key or aliases are also present in `schemaOrder`.              |
+| `rest.sortDescFirst` | Becomes TanStack's first-toggle direction.                                                           |
+
+The sorting gate is intentional: metadata can request sorting, but the order schema remains the contract that authorizes the field. The standard resource-page table is controlled and `manualSorting`; it does not locally reorder the fetched data.
+
 ## 7. Column and cell render context are explicitly separated
 
 The controller creates two related but distinct runtime contexts.
@@ -392,12 +413,12 @@ That contract defines:
 The decorator itself is:
 
 ```typescript
-createBeanDecorator('tableCell', 'sys', true, options);
+createBeanDecorator('tableCell', 'app', true, options);
 ```
 
-That means `tableCell` is not only a naming convention. It is a frontend bean scene with:
+That means `tableCell` is not only a naming convention. It is an app-scoped frontend bean scene with:
 
-- system-scoped resolution behavior
+- app-scoped reusable bean resolution
 - scene-level typing
 - CLI boilerplate support
 - metadata-driven resource identity
@@ -437,9 +458,12 @@ The default render bean lives in:
 zova/src/suite-vendor/a-zova/modules/a-table/src/component/table/render.tsx
 ```
 
-It does two important jobs:
+It does more than delegate vnode creation:
 
 - render the outer table markup with `<table class="table">`
+- apply effective column alignment, pixel width/minimum width, and fixed-column sticky positioning
+- calculate and apply left/right pinned-column offsets
+- render accessible sortable header buttons, `aria-sort`, and sort-state indicators when the controller exposes a sortable column
 - delegate header and cell vnode creation to TanStack `FlexRender`
 
 If `slotDefault` is supplied, the render bean yields to that slot instead of the built-in table DOM.
@@ -470,7 +494,8 @@ zova/src/suite/cabloy-basic/modules/basic-page/src/component/blockTable/controll
 - loads `ModelResource`
 - creates page-level JSX/CEL environment
 - computes resource query state
-- exposes `data`, `schemaRow`, and `permissions`
+- exposes `data`, `schemaRow`, `schemaOrder`, and `permissions`
+- owns controlled table sorting and converts its single current sorting entry into backend `orders`
 - refreshes table metadata when permissions change
 
 ### Table block path
@@ -480,6 +505,8 @@ zova/src/suite/cabloy-basic/modules/basic-page/src/component/blockTable/controll
 - renders `ZTable`
 - passes `data={$$page.data}`
 - passes `schema={$$page.schemaRow}`
+- passes `schemaOrder={$$page.schemaOrder}`
+- passes controlled `sorting` and `onSortingChange`
 - passes `tableScope={$$page.jsxCelScope}`
 - captures `controllerRef` and stores `tableRef` back onto the page controller
 
@@ -487,18 +514,22 @@ This is one of the most important integration facts about the module.
 
 The resource page does not manually rebuild the table runtime. It feeds page-owned resource state into the same reusable table controller.
 
+This section uses Cabloy Basic `basic-page` paths as the concrete resource-page specimen. The core `ZovaRender.column(...)` metadata contract and the base Zova Table controller behavior are shared by Cabloy Basic and Cabloy Start; resolve Start-specific page modules and renderer keys from the active Start repository.
+
 ## 14. Compact call-flow sketch
 
 When in doubt, use this short call flow:
 
-1. `ZTable` wrapper enters the normal Zova controller path
-2. `ControllerTable.__init__()` creates CEL/JSX support and schema-driven properties
-3. `refreshMeta()` computes visible table properties and per-column render functions
-4. `_createTable()` creates the TanStack bridge through `$useTable(...)`
-5. `RenderTable` renders headers and rows through `FlexRender`
-6. each cell render resolves to text fallback, a general render target, or a `tableCell` bean
-7. `tableCell` beans receive controller-prepared options, scope, and `next()`
-8. resource pages prepare `data`, `schemaRow`, `permissions`, and `tableScope` before entering the same runtime
+1. `ZovaRender.column(...)` contributes `rest.table` metadata to the backend/OpenAPI field contract
+2. `ZTable` wrapper enters the normal Zova controller path
+3. `ControllerTable.__init__()` creates CEL/JSX support and schema-driven properties
+4. `refreshMeta()` computes visible table properties, column pinning, and per-column render functions
+5. `_createTable()` creates the TanStack bridge through `$useTable(...)`
+6. `RenderTable` applies column metadata and renders headers and rows through `FlexRender`
+7. each cell render resolves to text fallback, a general render target, or a `tableCell` bean
+8. `tableCell` beans receive controller-prepared options, scope, and `next()`
+9. resource pages prepare `data`, `schemaRow`, `schemaOrder`, sorting state, permissions, and `tableScope` before entering the same runtime
+10. a resource-page sort becomes backend `orders`; TanStack does not locally sort the fetched page
 
 That is the shortest end-to-end explanation of how the module cooperates.