feat(layout): Forms geometry as native APEX components, with a mapping report (1.1.0)

One resolved layout model (apexlayout) feeds the exporter and the preview:
canvases, frames and tab pages become regions, sub-regions and tab pages on
the 12-column grid; rows come from the Forms geometry with a unit tolerance,
column spans from each item's share of its parent, the label keeps its own
share of the row, and items beside or below a frame keep their vertical
order in derived row regions.

Multi-record blocks on a table become interactiveGrid regions with one
column per item in Forms order (headings, native types, primary key, widths,
required, hidden columns, saved report); editing stays off until the block's
DML is confirmed. Native item types carry their Forms properties: datePicker
and numberField with format masks, textarea with width and height, checkbox
values, radioGroup columns without the empty choice, selectList on a shared
static LOV, readOnly, textCase, help text. Template options are native
properties; stacked canvases and secondary windows become inline dialogs.

Every export writes a per-element layout mapping report in the manifest
(source identity, geometry, target, grid placement, rule, preserved
properties, approximations, unsupported, missing metadata, status with
explicit denominators). Button ids and grid column names come from one place
so the page file, the manifest and the report agree.

Verified on APEX 26.1.0: validate, import into a dedicated dev app, dictionary
checks, and the page rendered through ORDS as a temporary end user
(examples/verify/apex_render_check.py; no page made public). Docs: the
mapping matrix with before/after, and the verification runbook rewritten.

Tests: tests/test_apexlayout_fidelity.py (895 passed, 1 skipped in the full
suite).

Author: gevianajr

CHANGELOG.md

@@ -7,8 +7,72 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.1.0] — 2026-09-05
+
+The layout release: a Forms screen becomes native APEX components that keep
+its structure — regions, sub-regions, tab pages, Interactive Grids, native
+item types, Universal Theme template options — with a per-element mapping
+report in every export and a login-based render check that never makes a
+page public.
+
+### Added
+
+- Layout model (`apexlayout.py`, one resolved layout shared by the exporter
+  and the preview): rows detected with a tolerance in Forms units, column
+  spans per parent width, the label's share of the row kept apart from the
+  item's, nested frames as sub-regions, items drawn beside or below a frame
+  in derived row regions that keep the vertical order of the screen.
+- Multi-record blocks on a table become `interactiveGrid` regions: one
+  column per item in the order Forms draws the record, headings from the
+  prompts, native column types, `primaryKey`, widths in characters,
+  required and max length, hidden database items as hidden columns,
+  non-database items with `source { type: none }`, a primary saved report.
+  Editing stays off until the block's DML is confirmed, and no table is
+  invented for a block without a query data source.
+- Native item types with their Forms properties: `datePicker` and
+  `numberField` with `formatMask` (and `numberAlignment: end`), `textarea`
+  with `width` / `height` from the item box, `checkbox` with the item's
+  checked and unchecked values, `radioGroup` with `noOfCols` and no empty
+  choice, `selectList` on a shared static LOV, `readOnly` for disabled
+  items, `textCase`, help text from hint and tooltip.
+- Universal Theme template options as native properties:
+  `t-Form--stretchInputs` on form regions and `t-IRR-region--hideHeader`
+  on a grid that sits inside a captioned frame.
+- Stacked canvases and secondary windows as `inline-dialog` regions;
+  toolbar canvases as blank regions with their controls in flow;
+  boilerplate text and rectangles as static regions; a frame whose only
+  content is a multi-record block hands its caption to the grid.
+- Per-element layout mapping report in `apexlang-manifest.json`
+  (`layout.mapping_report`): source identity, canvas, geometry, target
+  component and grid placement, the rule applied, preserved properties,
+  approximations, unsupported mappings, missing metadata, and a
+  `faithful` / `approximation` / `unsupported` status with explicit
+  denominators — never a score.
+- Preview: the planned APEX layout is drawn from the same resolved model
+  the export writes — Interactive Grids with their columns, date and
+  number shapes, a fidelity badge per control, Faithful / Approximated /
+  Unsupported / Grid columns counters.
+- `examples/verify/apex_render_check.py`: renders an imported page through
+  ORDS as a temporary workspace end user that the script creates and
+  removes (password never on the command line), then inspects the HTML.
+- `docs/layout-mapping-matrix.md`: the mapping matrix (source element,
+  native target, properties preserved, verified support, fallback, known
+  differences), the geometry-to-grid rules, the showcase denominators, the
+  before/after of the rendered page and the commands that reproduce it.
+- `tests/test_apexlayout_fidelity.py`: every visible control placed exactly
+  once, label spans always smaller than item spans
+  (`LABEL_COLUMN_SPAN_TOO_BIG`), grid columns and button identifiers
+  traceable from the report to the page file, unsupported item types
+  reported as such, no custom JavaScript or CSS in the page.
+
 ### Changed
 
+- Button identifiers and grid column names come from one place
+  (`apexlayout.button_id`, `apexlayout.column_name`), so the page file,
+  the manifest and the mapping report name every component the same way.
+- `docs/apex-import-verification.md`: the render-time check logs in as a
+  temporary end user instead of making the page public, and reads the
+  APEX dictionary before the HTML.
 - README: screenshots refreshed from the 1.0 workbench on the showcase
   module — review and CLI conversion, Doc (overview, block, triggers),
   Preview (Forms canvas next to the APEX page), Diff, the export dialog
@@ -761,7 +825,8 @@ build yet -- the roadmap item in `README.md` stays unchecked until it has.
   CLI providers (Claude Code, Codex), offline Echo mode, APEXlang 26.1
   export ZIP, Windows desktop app (Tauri) with MSI and NSIS installers.
 
-[Unreleased]: https://github.com/B2DEV-TECH/FormsLang/compare/v0.1.8...HEAD
+[Unreleased]: https://github.com/B2DEV-TECH/FormsLang/compare/v1.1.0...HEAD
+[1.1.0]: https://github.com/B2DEV-TECH/FormsLang/compare/v1.0.0...v1.1.0
 [0.1.6]: https://github.com/B2DEV-TECH/FormsLang/compare/v0.1.5...v0.1.6
 [0.1.5]: https://github.com/B2DEV-TECH/FormsLang/compare/v0.1.4...v0.1.5
 [0.1.4]: https://github.com/B2DEV-TECH/FormsLang/compare/v0.1.3...v0.1.4

README.md

@@ -744,12 +744,16 @@ after every export.
 The ZIP is deliberately separate from the audit artifacts. Only approved
 proposals are included, and they are emitted as disabled page-process
 candidates until their execution point and condition are confirmed in Page
-Designer. Regions and page items are a migration scaffold — every Forms
-item lands on the page's 12-column grid at its canvas position, `MultiLine`
-text items become `textarea`, display-only items become `displayOnly`,
-Date and Number items deliberately stay `textField` until the richer
-keywords have been through a live validate — and schema binding, LOVs,
-validations and application navigation still require functional review.
+Designer. Regions and page items are native components on the page's
+12-column grid: canvases, frames and tab pages become regions, sub-regions
+and tab pages; single-record blocks become page items of the native type
+(`textarea`, `displayOnly`, `datePicker`, `numberField`, `checkbox`,
+`radioGroup`, `selectList`); multi-record blocks on a table become
+Interactive Grids with their columns in Forms order; and every export
+carries a per-element mapping report — see
+[docs/layout-mapping-matrix.md](docs/layout-mapping-matrix.md). Schema
+binding, LOVs, validations and application navigation still require
+functional review.
 
 ### Validate and import
 
@@ -785,8 +789,10 @@ apex import   -input orders.apex.zip
 
 `validate` proves the package compiles; it cannot see a defect that only
 appears when a page is rendered. The repeatable procedure for that last
-mile — import, make the page public, fetch it through ORDS, read the HTML —
-is in [docs/apex-import-verification.md](docs/apex-import-verification.md).
+mile — import, log in as a temporary end user, fetch the page through ORDS,
+read the HTML, remove the user — is in
+[docs/apex-import-verification.md](docs/apex-import-verification.md), and
+`examples/verify/apex_render_check.py` does exactly that.
 
 ### What lands in APEX
 
@@ -820,13 +826,16 @@ is in [docs/apex-import-verification.md](docs/apex-import-verification.md).
   the required marks Forms declared.</sub>
 </p>
 
-> **Note — the layout of the converted application is being improved.** What
-> you see above is the scaffold 1.0 exports today: correct placement, correct
-> item types, correct required flags, but item widths, label alignment and
-> region packing still read as a migration scaffold rather than a finished
-> page. Tightening that layout is the current work on the exporter. Schema
-> binding, LOVs, validations and navigation remain the functional review
-> described above.
+> **Note — the screenshots above show the 1.0 layout.** Since 1.1 the
+> exporter turns the Forms geometry into native components with their own
+> widths, label placement and region packing — frames as sub-regions,
+> multi-record blocks as Interactive Grids, dates and numbers as Date
+> Pickers and Number Fields, Universal Theme template options — and each
+> export ships a per-element mapping report with explicit denominators.
+> [docs/layout-mapping-matrix.md](docs/layout-mapping-matrix.md) has the
+> mapping matrix and the before/after of the showcase page at the same
+> viewport. Schema binding, LOVs, validations and navigation remain the
+> functional review described above.
 
 ## Versioning Forms and APEXlang in git
 
@@ -952,13 +961,13 @@ formslang/
 ├── report.py       # self-contained HTML + JSON
 ├── formdoc.py      # `doc`: the module's technical reference
 ├── formdiff.py     # `diff`: structural diff between two revisions
-├── formui.py       # `preview`: canvases next to the APEX items they become
+├── formui.py       # `preview`: Forms canvases next to the planned APEX layout (same model as the export)
 ├── ai.py           # provider layer (urllib only) + CLI providers + offline stub
 ├── config.py       # the settings file the in-app Settings screen writes
 ├── secrets.py      # the OS credential store: Credential Manager / Keychain / libsecret
 ├── convert.py      # conversion tasks, the doctrine prompt, answer parsing
 ├── store.py        # SQLite session: proposals, decisions, settings, audit trail
-├── apexlayout.py   # Forms canvas geometry -> the APEX 12-column grid
+├── apexlayout.py   # the shared layout model: geometry -> regions, grid rows, Interactive Grids, mapping report
 ├── apexlang.py     # APEXlang 26.1 project + deterministic import ZIP
 ├── apeximport.py   # SQLcl driver: validate / import, password on stdin only
 ├── authstore.py    # organizations, users, roles, sessions, MFA (auth.db)
@@ -969,6 +978,7 @@ formslang/
 desktop/            # Tauri 2 shell: native window, engine sidecar, MSI/NSIS
 packaging/          # PyInstaller entry: freezes the engine into one .exe
 examples/ci/        # the GitHub Actions workflow to copy
+examples/verify/    # render an imported page through ORDS as a temporary end user and inspect it
 docs/               # SPEC, risk model, CI/CD contract, import verification, auth design
 assets/brand/       # the FormsLang brand kit (SVG)
 ```
@@ -1028,6 +1038,11 @@ CI runs the suite on Linux and Windows across Python 3.10–3.13, runs
 - [x] Proof that a generated export imports on a real Oracle APEX 26.1
       instance, and the repeatable render-time check
       ([`docs/apex-import-verification.md`](docs/apex-import-verification.md))
+- [x] High-fidelity layout: the Forms geometry as native APEX components —
+      regions, sub-regions, tab pages, Interactive Grids for multi-record
+      blocks, native item types, template options — with a per-element
+      mapping report and the before/after of the showcase
+      ([`docs/layout-mapping-matrix.md`](docs/layout-mapping-matrix.md))
 - [x] Windows desktop app (bundled engine, MSI / NSIS installers)
 - [x] Secure multi-user workspaces: RBAC, MFA/TOTP, per-organization
       isolation — switched on from Settings or `FORMSLANG_AUTH`, the first

desktop/package.json

@@ -1,7 +1,7 @@
 {
   "name": "formslang-desktop",
   "private": true,
-  "version": "1.0.0",
+  "version": "1.1.0",
   "scripts": {
     "tauri": "tauri",
     "icon:render": "node scripts/render-icon.mjs",

desktop/src-tauri/Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "formslang-desktop"
-version = "1.0.0"
+version = "1.1.0"
 description = "FormsLang desktop shell (B2DEV TECH)"
 edition = "2021"
 license = "Apache-2.0"

desktop/src-tauri/Cargo.toml

@@ -1,7 +1,7 @@
 {
   "$schema": "https://schema.tauri.app/config/2",
   "productName": "FormsLang",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "identifier": "tech.b2dev.formslang",
   "build": {
     "frontendDist": "../ui-shell"