document-tabular-section

Files (1)

• SKILL.md

SKILL.md (first lines)

# Document Tabular Section Skill

Use this skill when:
- creating or refactoring the табличну частину of a `document` model
- a control inside a table cell still shows its own frame, rounded corners or gaps instead of merging with the grid
- rows look taller than the controls inside them
- adding decimal columns (quantity, price, amount) with live line/document totals
- a focus ring inside a cell does not line up with the cell borders

The CSS contract lives in the framework theme (`@client/styles/theme.css`, section
«Табличні частини документів») and ships with `@altera/client` — the application
never redefines those classes, it only uses them.

## Default path: the TabularSection primitive

Do NOT hand-write the table markup and row mechanics — use the primitive
(`@client/ui-kit/tabular/`). The form declares a typed section (columns, where
rows live, how a new row looks) and places two INDEPENDENT view components —
either can be replaced with custom markup, all actions are public on the section:

```ts
private lines = new TabularSection<InvoiceLine>(this, {
  rows: () => this.$root.item.lines,
  setRows: (lines) => { this.$root.item = { ...this.$root.item, lines }; },
  createLine: () => ({ id: null, lineNo: 0, bankId: "", bank: null, qty: "0.000", price: "0.00" }),
  columns: [
    { kind: "picker",  key: "bankId", refKey: "bank", title: "invoice.bank", url: "catalog/bank" },
    { kind: "decimal", key: "qty",   title: "invoice.qty",   precision: 3, width: "7rem" },
    { kind: "decimal", key: "price", title: "invoice.price", precision: 2, width: "7rem" },
    { kind: "computed", title: "invoice.amount", width: "7rem", total: true,
      value: (l) => dec(l.qty).mul(dec(l.price)).toFixed(2) },
  ],
});
// render():
//   <ui-tabular-toolbar .section=${this.lines}></ui-tabular-toolbar>
//   <ui-tabular-table   .section=${this.lines}></ui-tabular-table>
```

What the primitive provides: add / copy (id is stripped — the save merge would
otherwise overwrite the original) / delete / move up-down with automatic
`lineNo` renumbering, current-row highlight, live totals in `<tfoot>`
(`total: true`), empty state, canonical decimal values on the way in and
`section.normalizedRows()` for the way out (see below), and keyboard
entry: Enter walks editable cells and appends a row at the end, ↑/↓ move
between rows, Insert adds, Ctrl+Delete removes. At the very last editable cell
Enter is two-step: if that Enter committed a typed value (the control fired
`value-changed` while handling it) it only finishes the edit; the next Enter
appends the row and puts the focus into its first cell. A `custom` cell gets the
same behaviour only if its control reports commits through `value-changed`.
Esc in a just-added row nobody has typed into removes that row and returns to
the last cell of the previous one (`section.discardNewLine()`); a row with any
value in it is never removed by Esc. A control that needs Esc itself (an open
list or calendar, reverting typed text) stops it, so one Esc does one thing. Column kinds: `text`,
`decimal`, `picker`, `date`, `checkbox`, `computed`, and the escape hatch
`custom` (`render(line, index)` returns the `<td>` CONTENT — never the `<td>`
itself). Conditional columns: `visible: () => boolean` (see currency columns
in `manualEntryEdit.ts`). Two-level headers: ADJACENT columns sharing the same
`group: "key"` get one spanning header cell above their own titles («Дебет»
over «Рахунок» + «Субконто»); columns without `group` span both rows.
Multi-row records (1С style): a column with `row: 2` renders as a SECOND `<tr>`
of the same record, laid left-to-right under the row-1 grid; `span: N` says how
many grid columns its cell covers (default 1, remainder is padded). The `#` and
delete cells rowspan the whole record; a sub-row header line appears only if a
`row: 2` column has a `title`; `total` on sub-row columns is ignored. The typical use
is subconto printed under its account in a manual journal entry. Dynamic per-line
controls (subconto pickers whose model depends on the line's account) stay in
`custom` cells.

The CSS knowledge below still applies to `custom` cells and to fully
hand-written tables (which remain legal — the primitive is a default, not a
requirement).

## Something of your own in the toolbar: `toolbarExtra`

A barcode scan field or a «Fill» button belongs in the section's toolbar, next to
«Add» — not above the tabs. Declare it on the section, not on the tab:

```ts
private readonly scanStatus = signal("");   // state of the extra lives in a signal

private goods = new TabularSection<Line>(this, {
  …,
  toolbarExtra: () => scanField({
    disabled: this.goods.readonly,
    status: this.scanStatus.get(),
    onScan: (code) => this.scan(code),
  }),
});
```

The toolbar draws it to the right of its buttons, wherever the section is shown —
inside `<ui-form-tabs>` as well, so the tab keeps its row count and error mark.
Three things the toolbar does NOT do for you:

- **disable it on a read-only form** — read `section.readonly` in your template;
- **redraw on the form's `@state`** — the toolbar redraws on section changes and on
  signals it reads, and the form's re-render hands it the same section object; a
  scan that finds nothing changes no row, so its message must sit in a signal;
- **swallow `Enter`** — a native input there is a form field for «Enter moves on»;
  handle `Enter` on `keydown` and call `preventDefault()`.

## Rows are REPLACED, never edited in place

The table caches what it has already drawn and redraws only the records that
changed — that is what keeps a thousand-line inventory sheet typable (a
keystroke costs 23 ms instead of 78 ms; measured). It tells a changed record
from the rest by **object identity**, and every action of the section already
gives it one: `patch`, `addLine`, `copyLine`, `removeLine` and `move` all put a
NEW object in the row's place.

So one thing is now forbidden that merely "worked" before:

```ts
this.$root.item.lines[0].qty = "5";     // ✗ таблиця цього не побачить
this.lines.patch(0, { qty: "5" });      // ✓
```

Reactivity itself is untouched — the component still redraws on every change of
`$root`; what it no longer does is re-evaluate rows nobody touched.

From IgorAIvanov/altera03, MIT.

More from IgorAIvanov/altera03