TableCell Authoring Cookbook

This cookbook explains how to author tableCell resources in Zova for the most common business table patterns.

Use this page when the public table runtime already makes sense to you and your next question is practical:

how should I write a custom tableCell bean?
when should I use next() directly?
how should I format values, wrap them with styles, or trigger commands?
when should I use the tableActionRow boilerplate instead of a normal tableCell?

Use this page together with:

What a `tableCell` bean is for

A tableCell bean is the main reusable extension surface for one table cell in Zova.

It is a good fit when:

the same cell behavior should be reused across pages
a schema field should point to a named frontend render resource
a row action should be represented as one reusable render unit
the table runtime should continue owning scope, visibility, and render orchestration

It is not the first choice when:

the change is only one page-local layout tweak with no reuse value
the page should instead add or remove whole columns through getColumns(...)
the business truth really belongs in backend schema metadata and no custom frontend behavior is needed yet

A practical rule is:

use schema metadata first
use built-in table-cell resources second
add a custom tableCell bean only when the UI behavior becomes business-specific or reusable

The smallest correct mental model

If you only remember one idea, remember this one:

A tableCell bean does not own the whole table. The table controller owns the table runtime, and your tableCell bean receives a prepared render context plus next() for the current cell.

That is why tableCell authoring usually feels small and focused.

Your bean normally decides only one of these things:

format the current value
wrap the current value with extra markup
trigger a command or action
orchestrate several nested row actions

Step 1: Start from the CLI scaffold

Inspect the CLI surface first:

bash

npm run zova :create:bean --help

Create a normal table-cell bean:

bash

npm run zova :create:bean tableCell level -- --module=training-student

Create a row-action variant:

bash

npm run zova :create:bean tableCell actionOperationsRow -- --module=training-student --boilerplate=tableActionRow

Create a details-row-action variant:

bash

npm run zova :create:bean tableCell actionDelete -- --module=training-student --boilerplate=detailsActionRow

Use tableActionRow when one table cell should compose several table-row actions together. Use detailsActionRow when the render resource belongs to the details-row action contract under IResourceDetailsActionRowRecord.

The default scaffold shape is intentionally small:

tsx

@TableCell<ITableCellOptionsLevel>()
export class TableCellLevel extends BeanBase implements ITableCellRender {
  render(
    _options: ITableCellOptionsLevel,
    _renderContext: IJsxRenderContextTableCell,
    next: NextTableCellRender,
  ) {
    return next();
  }
}

That is already the correct architectural starting point because:

the bean is registered in the tableCell scene
the options type is local to your resource identity
the render context is already prepared by the table controller
next() already represents the cell’s current value or downstream content path

Step 2: Understand the three parameters you receive

The render(...) method usually receives:

options — the final merged options for this cell resource
renderContext — the current table/cell runtime context
next — the function that gives you the downstream cell content

`options`

Use options for things such as:

class
formatting presets
display items
command options
action lists for row-action cells

These options may come from more than one layer, including:

decorator defaults on @TableCell(...)
schema rest.table.columnProps
action metadata options

`renderContext`

Use renderContext when you need access to:

$host — the host controller utilities such as $performCommand(...)
$$table — the current table controller
cellContext — the TanStack cell context
$celScope — the current cell scope

`next()`

Use next() when your cell should build on top of the current value rather than replace the whole rendering path.

A practical rule is:

if the cell is basically a formatter or wrapper, start from next()
if the cell is a command button or link, you may ignore next() and render your own content

Pattern 1: Minimal pass-through cell

Use this pattern when you only want a reusable placeholder bean or a very thin wrapper.

Representative shape:

tsx

@TableCell<ITableCellOptionsLevel>()
export class TableCellLevel extends BeanBase implements ITableCellRender {
  render(
    _options: ITableCellOptionsLevel,
    _renderContext: IJsxRenderContextTableCell,
    next: NextTableCellRender,
  ) {
    return next();
  }
}

Use this when:

the backend already points to a custom cell resource but the UI behavior is still small
you want the resource identity to exist before you add richer logic
you want a stable extension point for future customization

This is the right starting point for many business-specific fields.

Pattern 2: Format a value and optionally wrap it with a class

Use this pattern when the cell is still “show the field value,” but the value needs formatting.

Representative built-in examples are:

basic-date:date
basic-currency:currency
basic-select:select
basic-text:text

The common pattern is:

call next()
transform the value
if options.class exists, wrap the result with a container

Representative shape:

tsx

@TableCell<ITableCellOptionsCurrency>()
export class TableCellCurrency extends BeanBase implements ITableCellRender {
  render(
    options: ITableCellOptionsCurrency,
    _renderContext: IJsxRenderContextTableCell,
    next: NextTableCellRender,
  ) {
    const value = currencyFormat(next(), options);
    if (!options.class) return value;
    return <div class={options.class}>{value}</div>;
  }
}

This is a good fit when:

the field is still conceptually one value
formatting logic should be shared across multiple pages
schema metadata should be able to point to one stable frontend renderer

A practical rule is:

prefer formatting around next() for date, currency, enum-label, or badge-like display
do not re-fetch row data manually if the current cell value is already enough

Pattern 3: Map a raw value to an item label

Use this pattern when the raw stored value is not the final display value.

Representative built-in example:

basic-select:select

Representative shape:

tsx

@TableCell<ITableCellOptionsSelect>({
  itemValue: 'value',
  itemTitle: 'title',
})
export class TableCellSelect extends BeanBase implements ITableCellRender {
  render(
    options: ITableCellOptionsSelect,
    _renderContext: IJsxRenderContextTableCell,
    next: NextTableCellRender,
  ) {
    const value = next();
    const item = options.items?.find(
      item => String(item[String(options.itemValue)]) === String(value),
    );
    const value2 = item?.[String(options.itemTitle)];
    if (!options.class) return value2;
    return <div class={options.class}>{value2}</div>;
  }
}

This is a good fit when:

the stored value is a code, enum, or id-like value
the visible table should show a label instead
the same mapping should be reused in several places

Pattern 4: Turn the cell into a command link or button

Use this pattern when the cell should trigger a user action.

Representative built-in examples are:

basic-table:actionView
basic-table:actionDelete

A command-link pattern looks like this:

tsx

@TableCell<ITableCellOptionsActionView>({
  class: 'hover:text-blue-500',
})
export class TableCellActionView extends BeanBase implements ITableCellRender {
  render(
    options: ITableCellOptionsActionView,
    renderContext: IJsxRenderContextTableCell,
    next: NextTableCellRender,
  ) {
    const { $host } = renderContext;
    const value = next();
    return (
      <a
        class={options.class}
        href="#"
        onClick={async e => {
          e.preventDefault();
          e.stopPropagation();
          await $host.$performCommand('basic-commands:view', options, renderContext);
        }}
      >
        {value}
      </a>
    );
  }
}

A command-button pattern looks like this:

tsx

@TableCell<ITableCellOptionsActionDelete>({
  class: 'btn btn-outline btn-error join-item',
})
export class TableCellActionDelete extends BeanBase implements ITableCellRender {
  render(
    options: ITableCellOptionsActionDelete,
    renderContext: IJsxRenderContextTableCell,
    _next: NextTableCellRender,
  ) {
    const { $host } = renderContext;
    return (
      <button
        class={options.class}
        type="button"
        onClick={async () => {
          const confirmed = await $host.$performCommand('basic-commands:confirm', {
            text: this.scope.locale.DeleteConfirm(),
          });
          if (!confirmed) return;
          await $host.$performCommand('basic-commands:delete', options, renderContext);
        }}
      >
        Delete
      </button>
    );
  }
}

This is a good fit when:

the cell is really an action, not only formatted display
the same action should be reusable across resource pages
command-scene infrastructure should remain the action execution path

A practical rule is:

let the cell resource own the render interaction
let the command bean or model layer own the actual action semantics

Collect input for a business row action in a dialog

When a row action needs additional business input, such as shipment details or a stock-adjustment reason, prefer a compact button in the cell and collect the input in a focused dialog. Keep deliberate inline-editing workflows inline; this is not a requirement to put every table action in a dialog.

Use the following interaction boundaries:

Open from the target row. Keep the cell responsible for the trigger and row context. For caller-owned content, use the ordinary this.$appModal.dialog(...) with slotDefault and slotActions; use a routed dialog only when the workflow needs routed pages. See Routed Dialog Guide.
Collect operation-specific input. Prefer the operation's generated $apiSchema or the owning ModelResource schema with automatic ZForm rendering when the contract already describes the fields. Keep localized schema access reactive, and do not copy backend field metadata into the controller. Use manual or mixed fields only for a concrete interaction need, such as UI-only confirmation. See API Schema Guide and Form Guide.
Submit through the existing action owner. Keep the draft local to the interaction, but reuse the existing command or semantic model facade for business execution. For an action on the same resource, retain its existing ModelResource mutation and cache owner rather than adding dialog-local fetch/cache state or manual list refreshes. See Resource Model Cookbook.
Keep one complete submission lifecycle. Validate and normalize input as required by the operation, and prevent duplicate submission at the boundary that owns all submit paths. Return or await the whole action through ZButton.onPerform for a button-only action; use form submission state and error handling when ZForm owns submission. Reflect broader mutation pending state only when it is needed beyond that button's own lifecycle. Choose one error presentation owner, not competing alerts. See Behavior Guide.
Close only after success. Await the mutation before calling the dialog's close(). On failure, keep the dialog and entered values available for correction or retry; do not close in finally. Cancel or dismissal must not initiate a mutation, but closing the dialog does not cancel an already submitted request. Choose confirmation, draft reset/recovery, and dismissal behavior from the business workflow rather than copying one example's checkbox, width, or reset policy.

For a schema-driven form, keep its submit controls in ZForm.slotFooter when appropriate so that validation and native-form submission remain one path. The dialog's slotActions is not a reason to introduce a second submission owner.

Apply these schema-driven form details where they fit the operation:

Submit same-shaped data directly. When the validated form data has the same shape as the operation's request DTO, pass data.value directly to the existing mutation, for example await mutation.mutateAsync(data.value). Build a separate payload only when the operation needs a real projection, conversion, or removal of UI-only fields. Do not enumerate fields or duplicate normalization merely to reconstruct the same request; when the backend already owns normalization, leave it there. Schema validation does not imply that every operation trims its input.
Await business confirmation inside onSubmitData. If the operation requires a confirmation prompt, await it after form validation and before the mutation in the same returned or awaited submit handler. Button submission and Enter then share validation, confirmation, pending state, and error handling. A declined confirmation should return without mutating or closing the form, preserving the draft. Do not put confirmation only in the submit button's click handler or introduce a confirmation checkbox unless the business workflow calls for one.
Prepare lazy schemas at the opening boundary when appropriate. For a low-frequency dialog, opening can await $QueryEnsureLoaded(() => this.apiSchemasShip.sdk) before rendering the form. Resolve apiSchemasShip through a getter for the current runtime and derive requestBody reactively, such as with $computed. Ensure the current locale's SDK on every opening, even if the reactive derivation was installed earlier; do not retain a facade or schema snapshot from a previous locale. If preparation is extracted into a helper, await SDK readiness on every call and use if (!this.schema) only to create the computed derivation once. Do not place if (this.schema) return before the SDK check: an existing computed does not prove that the current locale's SDK is loaded. Extracting a helper is optional; the important boundary is repeated readiness checks versus one-time derivation setup. This is an optional loading boundary, not a requirement to defer every form's schema until interaction.

The Cabloy Basic shipment example is zova/src/suite/a-commerce/modules/commerce-trade/src/component/tableCellActionShip/controller.tsx: _openDialog() calls _ensureSchema() to prepare the current schema, ZForm renders the contract fields automatically, and _submit() awaits confirmation and mutateAsync(data.value) before closing. Its dialog width, draft-reset policy, and backend normalization are operation-specific choices, not additional form rules.

Extend an existing critical-flow E2E scenario rather than creating a separate harness:

locate the trigger within the intended order or resource row, then locate fields and submit controls within the opened dialog
check that the cell no longer exposes the dialog's input fields, and that invalid input cannot submit
check cancellation and the chosen reopen/draft policy
check successful submission, dialog closure, and the refreshed resource state
when covering a submission failure, assert that the dialog retains the draft, presents the intended error, and allows retry after pending state clears

In Cabloy Basic, the ordinary dialog can be located with getByRole('dialog'); assert its visible heading rather than assuming the title also supplies its accessible name. Verify the active edition's modal adapter before reusing UI-specific selectors.

Pattern 5: Row-action composition with `tableActionRow`

Use this pattern when one cell should show several row actions together.

Representative built-in example:

basic-table:actionOperationsRow

This pattern is different from a normal single-action cell because the bean often needs to:

inspect an actions array
filter actions by permission
preload nested renders
render several child action cells in one wrapper

That is why the tableActionRow boilerplate exists.

By contrast, the newer detailsActionRow boilerplate is for one detail-row action resource at a time. Its scaffold declaration-merges into IResourceDetailsActionRowRecord and types the options through IResourceDetailsActionRowOptionsBase, so it fits the details-table action path instead of the standard table-operations composition path.

Representative runtime shape:

tsx

@TableCell<ITableCellOptionsActionOperationsRow>({
  class: 'join',
})
export class TableCellActionOperationsRow extends BeanBase implements ITableCellRender {
  async checkVisible(
    options: ITableCellOptionsActionOperationsRow,
    renderContext: IJsxRenderContextTableColumn,
  ): Promise<boolean> {
    const { $celScope, $host, $$table } = renderContext;
    const permissions = $celScope.permissions;
    const actions = options.actions;
    if (!actions || actions.length === 0) return false;
    const renders: TypeTableCellRenderComponent[] = [];
    for (const action of actions) {
      const actionName = action.name;
      const actionRender = action.render;
      const permissionHint = action.options?.permission;
      if ($host.$passport.checkPermission(permissions, actionName, permissionHint)) {
        if (!actionRender) throw new Error(`should specify action render: ${actionName}`);
        renders.push(actionRender);
      }
    }
    await $$table.cellRenderPrepare(renders);
    return renders.length > 0;
  }
}

And the render step usually reuses the table runtime again:

tsx

render(options, renderContext) {
  const { $celScope, $host, $$table } = renderContext;
  const permissions = $celScope.permissions;
  const actions = options.actions;
  if (!actions || actions.length === 0) return;
  const domActions = [];
  actions.forEach((action, index) => {
    const actionName = action.name;
    const permissionHint = action.options?.permission;
    if (!$host.$passport.checkPermission(permissions, actionName, permissionHint)) return;
    const options2 = Object.assign({ key: index }, action.options);
    domActions.push($$table.cellRender(action.render!, options2, renderContext));
  });
  return <div class={options.class}>{domActions}</div>;
}

This is a good fit when:

one Operations column should contain several reusable child actions
permission filtering belongs in the table action layer
nested action cells should still reuse the same table-cell pipeline

A practical rule is:

use the normal scaffold for one render resource
use --boilerplate=tableActionRow when the cell is really a row-action container

Pattern 6: Business-specific badge or label cell

Use this pattern when a field such as level, status, or state should have module-owned presentation.

A typical workflow is:

create a module-local table cell bean
move the presentation logic into that bean
point backend metadata to the bean resource name

Representative CLI command:

bash

npm run zova :create:bean tableCell level -- --module=training-student

Representative backend-facing metadata target:

typescript

ZovaRender.cell('training-student:level', { items: levelItems });

This is the right fit when:

the field now has business-specific UI meaning
built-in renderers are a good start but no longer enough
the backend contract should still choose the frontend resource identity

For the full walkthrough around level, see Tutorial 4: Custom Form/Table Renderers for Level.

Pattern 7: Backend contract to frontend cell handoff

Many table-cell workflows are easiest to understand as a contract chain.

A common chain is:

backend row DTO owns the field metadata or row-action metadata
frontend tableCell bean provides the render resource implementation
the table controller resolves that render resource at runtime
the visible table page reuses the same table runtime with no page-local duplication

For row actions, the chain often continues further:

backend action contract exists
frontend generated API exists
frontend model wraps the generated API thinly
tableCell.actionXxx.tsx triggers that action through command or model logic

That is why custom table cells often belong to the contract loop rather than to isolated page-only UI work.

For the forward-chain row-action example, see Tutorial 5: Backend Contract Sharing.

How to choose between the common patterns

Use this quick rule set:

Choose a minimal pass-through cell when:

you only need a stable module-owned resource identity
you expect richer logic later

Choose a formatting cell when:

the cell still represents one value
the business behavior is formatting or display mapping

Choose a command cell when:

the cell is an action trigger
the action should be reusable and command-oriented

Choose a row-action cell when:

one column should contain several child actions
permission-sensitive action composition is needed

Stay with schema metadata only when:

built-in render resources already solve the problem
no module-owned frontend logic is needed yet

Common mistakes to avoid

Mistake 1: Rebuilding row access manually

The table controller already prepares cellContext, scope, and render context. Use next() and renderContext first.

Mistake 2: Using a custom `tableCell` bean for a one-off page-local column shape

If the behavior is not reusable, consider getColumns(...) or page-local rendering first.

Mistake 3: Putting business action semantics directly into ad hoc click handlers everywhere

Prefer one reusable command or model path, and let the tableCell bean stay the render-facing adapter.

Mistake 4: Using the normal scaffold when the cell is really a row-action container

If the cell will host several actions, prefer --boilerplate=tableActionRow.

Mistake 5: Treating a `tableCell` bean like a full table replacement

It only owns one cell render resource. The table controller still owns the table runtime.

A practical authoring order

If you want the shortest path to a correct custom table cell, use this order:

confirm whether built-in renderers already solve the problem
confirm whether the truth should live in backend schema or row-action metadata
generate the correct tableCell scaffold
start from next() when the cell is still value-centric
use renderContext.$host when the cell needs commands or host services
use tableActionRow only for multi-action composition
point backend metadata to the new frontend cell resource when the contract is ready
continue with Table + Resource CRUD Cookbook if the cell belongs inside a standard resource list page
continue with Backend Metadata to Frontend Table Actions if the cell is part of a larger contract-loop action chain
continue with Zova Table Under the Hood if you need the controller-level runtime explanation
continue with Zova Table Source Reading Map if you need the exact next files to read

Verification checklist

When authoring or documenting a custom tableCell, verify in this order:

confirm the CLI command shape still exists:
bash
```
npm run zova :create:bean --help
```
1

confirm the scene variant still exists before recommending it:

bash

npm run zova :create:bean tableCell test -- --module=training-student --boilerplate=tableActionRow

confirm your bean follows the current ITableCellRender contract
confirm the target backend metadata points to the intended resource name
run the docs build if you changed docs:
bash
```
npm run docs:build
```
1

Final takeaway

A good tableCell bean is usually small.

It does not replace the table runtime. It plugs into it.

That is why the best tableCell authoring style is usually:

small bean
clear options type
minimal render responsibility
stable contract-facing resource identity

TableCell Authoring Cookbook ​

What a tableCell bean is for ​

The smallest correct mental model ​

Step 1: Start from the CLI scaffold ​

Step 2: Understand the three parameters you receive ​

options ​

renderContext ​

next() ​

Pattern 1: Minimal pass-through cell ​

Pattern 2: Format a value and optionally wrap it with a class ​

Pattern 3: Map a raw value to an item label ​

Pattern 4: Turn the cell into a command link or button ​

Collect input for a business row action in a dialog ​

Pattern 5: Row-action composition with tableActionRow ​

Pattern 6: Business-specific badge or label cell ​

Pattern 7: Backend contract to frontend cell handoff ​

How to choose between the common patterns ​

Choose a minimal pass-through cell when: ​

Choose a formatting cell when: ​

Choose a command cell when: ​

Choose a row-action cell when: ​

Stay with schema metadata only when: ​

Common mistakes to avoid ​

Mistake 1: Rebuilding row access manually ​

Mistake 2: Using a custom tableCell bean for a one-off page-local column shape ​

Mistake 3: Putting business action semantics directly into ad hoc click handlers everywhere ​

Mistake 4: Using the normal scaffold when the cell is really a row-action container ​

Mistake 5: Treating a tableCell bean like a full table replacement ​

A practical authoring order ​

Verification checklist ​

Final takeaway ​

TableCell Authoring Cookbook

What a `tableCell` bean is for

The smallest correct mental model

Step 1: Start from the CLI scaffold

Step 2: Understand the three parameters you receive

`options`

`renderContext`

`next()`

Pattern 1: Minimal pass-through cell

Pattern 2: Format a value and optionally wrap it with a class

Pattern 3: Map a raw value to an item label

Pattern 4: Turn the cell into a command link or button

Collect input for a business row action in a dialog

Pattern 5: Row-action composition with `tableActionRow`

Pattern 6: Business-specific badge or label cell

Pattern 7: Backend contract to frontend cell handoff

How to choose between the common patterns

Choose a minimal pass-through cell when:

Choose a formatting cell when:

Choose a command cell when:

Choose a row-action cell when:

Stay with schema metadata only when:

Common mistakes to avoid

Mistake 1: Rebuilding row access manually

Mistake 2: Using a custom `tableCell` bean for a one-off page-local column shape

Mistake 3: Putting business action semantics directly into ad hoc click handlers everywhere

Mistake 4: Using the normal scaffold when the cell is really a row-action container

Mistake 5: Treating a `tableCell` bean like a full table replacement

A practical authoring order

Verification checklist

Final takeaway