pgkiln 0.41.0 → 0.43.0

package/db/migrations/098_app_activity.sql

@@ -0,0 +1,37 @@
+-- =====================================================================
+-- 098: activity reporting for an application's administrators (sprint 73;
+-- APEX: the Activity Reporting feature of the Create Application wizard)
+--
+-- meta.app_activity(days): the page views, sign-ins and errors of the
+-- current application (meta.app_id()) in the last days (1 to 366), newest
+-- first, at most 10,000 rows. Only for a signed-in user with the admin role
+-- whose session belongs to that application; anyone else gets an error.
+-- The client's IP address and the error details are left out.
+--
+-- The wizard's Activity page (page 9010, authorization ADMIN) reads it:
+--   select * from meta.app_activity(30)
+-- =====================================================================
+create function meta.app_activity(p_days int default 30)
+returns table (at timestamptz, username text, event text, page_no int, elapsed_ms int)
+language plpgsql stable security definer set search_path = meta, pg_catalog as $$
+declare
+  v_app     int := meta.app_id();
+  v_session uuid := nullif(current_setting('pgkiln.session_id', true), '')::uuid;
+begin
+  if v_app is null or v_session is null
+     or not exists (select 1 from meta.session s where s.id = v_session and s.app_id = v_app)
+     or not meta.has_role('admin') then
+    raise exception 'the activity of this application is for its administrators' using errcode = '42501';
+  end if;
+  return query
+    select l.at, l.username, l.event, l.page_no, l.elapsed_ms
+      from meta.activity_log l
+     where l.app_id = v_app
+       and l.at > now() - make_interval(days => least(greatest(coalesce(p_days, 30), 1), 366))
+     order by l.at desc
+     limit 10000;
+end
+$$;
+revoke all on function meta.app_activity(int) from public;
+grant execute on function meta.app_activity(int) to public;
+comment on function meta.app_activity(int) is 'The current application''s activity (page views, sign-ins, errors) for its administrators (098).';

package/db/migrations/099_layout_positions.sql

@@ -0,0 +1,29 @@
+-- =====================================================================
+-- 099: display positions, button positions and side-column page templates
+-- (sprint 77; APEX: a region's Layout → Position, a button's Layout →
+-- Button Position, the Left / Right Side Column page templates)
+--
+-- meta.region.position: where the region shows on the page: banner (above
+-- everything), breadcrumb (the bar under the title), left or right (the side
+-- column of a side-column page template; on other pages in the body, in
+-- sequence), body (the default) or footer (after the body). Null is body.
+-- meta.button.slot: where a region's button shows: create, edit, change,
+-- copy, help or up (the region's top bar), previous, close or delete (the
+-- bottom bar, on the left), next (the bottom bar, on the right) or region
+-- (with the region's other buttons, as before). Null is region.
+-- meta.page.page_template: left_side_column and right_side_column too.
+--
+-- The columns are nullable (older exports and imports leave them null) and
+-- travel with an application's export like its other columns.
+-- =====================================================================
+alter table meta.region add column position text
+  check (position in ('banner', 'breadcrumb', 'left', 'body', 'right', 'footer'));
+comment on column meta.region.position is 'Where the region shows (099): banner, breadcrumb, left, body (null), right or footer.';
+
+alter table meta.button add column slot text
+  check (slot in ('create', 'edit', 'change', 'copy', 'help', 'up', 'previous', 'close', 'delete', 'next', 'region'));
+comment on column meta.button.slot is 'Where a region''s button shows (099): the top bar (create, edit, change, copy, help, up), the bottom bar (previous, close, delete; next on the right) or with the other buttons (region, null).';
+
+alter table meta.page drop constraint page_page_template_check;
+alter table meta.page add constraint page_page_template_check
+  check (page_template in ('standard', 'minimal', 'left_side_column', 'right_side_column'));

package/docs/apex-feature-parity.md

@@ -7,7 +7,7 @@ open item and open an issue or pull request; see [CONTRIBUTING.md](../CONTRIBUTI
 Legend: ✅ available · 🟡 partial (see notes) · ❌ not yet · ➖ not planned (a deliberate choice,
 or better served by the PostgreSQL ecosystem; see the notes and [extensions](guide/15-extensions.md))
 
-Last reviewed: 2026-10-14 (sprint 70: treemap, sunburst and timeline charts; sprint 69: dragging tasks on a Gantt chart; sprint 68: the Data Reporter's welcome page, Find my workspace; sprint 67: REST source catalogs from OpenAPI documents, a workspace's export and import (two rows added); sprint 66: a blueprint from an existing application; sprint 65: facet charts; sprint 64: approval vacation rules and expiration policies; sprint 63: range, box plot and stock charts; sprint 62: workspace preferences (SQL Workshop and RESTful services per workspace), extension links, Manage backups across applications, SQL Workshop utilities with object reports, About Database and a database monitor; sprint 61: the builder's screens compared with APEX 26.1: the workspace sign-in page, the Administration menu with workspace message, environment banner and utilization, the SQL Workshop home, the App Gallery, application groups and cross application reports (four rows added); sprint 60: isolated workspaces with their own database logins, row-level security on pgkiln's tables and workspace database roles, workspace administrators; sprint 59: the Page Designer's help pane, Quick edit from the developer toolbar; sprint 58: page groups; sprint 57: region templates hero, title bar, buttons container, inline dialog and drawer, wizard with wizard progress, the carousel; sprint 56: Generate DDL and Schema Comparison in the SQL Workshop, `pgkiln ddl` and `pgkiln compare`; sprint 55: an editable login page with a Login region and the Minimal page template, Forgot password through the application's mail service; sprint 54: interactive grid views, the single row view, group by and chart; sprint 53: application settings, user preferences and items kept per user, dynamic translations, `meta.data_export` and data export downloads, display image and geocoded address items; sprint 52: every dynamic action event and action, Ajax callbacks, an error handling function, the session timeout warning; sprint 51: checked imports, application backups, availability and Run only, feedback, type-specific attribute help; sprint 50: lost update detection, warn on unsaved changes, the URL and search regions with search configurations, the developer toolbar with a session state viewer, and e-mail through SMTP with OAuth2, Microsoft Graph, Amazon SES and HTTP APIs; import checks, application availability, property help and e-mail compared again; 2026-10-06: pgkiln 0.31.0, in progress: static application files and the Execute JavaScript dynamic action; region, item, dynamic action and process plug-ins; conditional and dynamic theme styles; XML and Excel in `meta.parse_data`, zips in SQL, `meta.v_boolean`; file items in S3-compatible object storage; map layers by the visible area and as vector tiles; a graphical query builder; tenants for workflows and tasks; application files as YAML and region static IDs; Lucide icons and icon modifiers; PWA push notifications; 0.30.0: 136 icons and an icon picker; an axe-core accessibility audit; cropping pictures; session sharing between applications; twenty-two built-in languages; 0.29.0: workspaces; the Iris base style; drawers; built-in template components including the metric card; Theme Roller dark-mode colours, live preview and template options on items and report columns; report selection across pages; instance settings; fourteen built-in languages; 0.28.0: AI with Claude and OpenAI; 0.27.0: Data Reporter; sample data generator; create application from several sheets, pasted data or existing tables; 0.26.0: working copies with a three-way merge; theme, library and boilerplate applications with subscriptions; 0.25.0: Gantt, pyramid and polar charts; map layers, clustering and server-side spatial filters; REST data sources that write back from forms and grids and synchronise into tables, OAuth2 password and refresh-token grants; debug messages per request and an install/upgrade log; `meta.web_request()` and `meta.parse_data()`; Theme Roller style variants and template options; 0.24.0: automations with several actions, error handling per row and runs from SQL; invoke-API workflow steps; Unload Data in the Data Workshop; create page wizards for cards, calendar, chart, map, faceted search, form and master-detail; create an application from a file; 0.23.0: interactive grid aggregates, frozen/moved/resized columns, layouts and saved grid reports, master-detail, row actions and copy/paste; download processes, execution chains in the background, workflow processes, branches to a function's URL or another app, the Dialog Closed event; number format masks, automatic time zone, runtime messages in German, French and Spanish; SQL scripts, Quick SQL, a query builder, XML loading and data load definitions; custom authentication, lists, page and application locks with developer comments, supporting objects; 0.22.0: keyset paging, report PDFs and REST collections streamed from a cursor, database-account authentication; 0.21.0: HTTP-header authentication behind a reverse proxy; 0.20.0: a popup list of values with server-side search; 0.19.0: row-range pagination, maximum row counts and row limits, lazy loading and caching of regions, streamed CSV/Excel downloads; 0.18.0: calendar week/day/list views with drag and drop, bubble/gauge/funnel/radar charts and drill-down, smart filters, a region display selector and more facet types, computations, conditional branches, build options, menu buttons, REST data sources and web credentials, rich text/Markdown, rating, combobox, date range and QR code items; 0.17.0: an App Builder home, workspace dashboard and utilities like APEX's; 0.16.0: a Page Designer with drag-and-drop layout, a code editor with autocomplete, template components and plug-ins, parallel branches and versions of workflows, the `pgkiln` command line with one file per component; 0.15.0: drop and paste files, heat maps, filtering a report by the map area; 0.14.0: stacked, combo, scatter and pie charts, several files per upload item; 0.13.0: map and tree regions; 0.12.0: REST modules in the builder; 0.11.0: workflows and Progressive Web Apps; 0.10.0: LDAP, SAML, "Keep me signed in", document templates, JSON loading, approvals and the task list; pgkiln installs no application, HR is an example).
+Last reviewed: 2026-10-14 (sprint 77: the Page Designer's layout and tree by display position, button positions, the tree's context menu with Duplicate and Copy to other page, Show Common / Show All, Go to group and the Template Options dialog; display positions, button positions and side-column page templates at runtime; sprint 76: the interactive report's menus and pagination, date items in the date format; sprint 75: the SQL Workshop's Object Browser and tabs; sprint 74: the builder's information architecture: Shared Components grid, Settings tabs, application home search and tasks; sprint 73: the Create Application wizard on one page with page types and features; sprint 72: the runtime chrome compared with APEX 26.2's: the developer toolbar, the Iris look, the navigation bar's Help menu and Install button; sprint 71: generated applications compared with APEX 26.2's: labels, foreign key names in reports, file columns, format masks, the Home page and the dashboard; sprint 70: treemap, sunburst and timeline charts; sprint 69: dragging tasks on a Gantt chart; sprint 68: the Data Reporter's welcome page, Find my workspace; sprint 67: REST source catalogs from OpenAPI documents, a workspace's export and import (two rows added); sprint 66: a blueprint from an existing application; sprint 65: facet charts; sprint 64: approval vacation rules and expiration policies; sprint 63: range, box plot and stock charts; sprint 62: workspace preferences (SQL Workshop and RESTful services per workspace), extension links, Manage backups across applications, SQL Workshop utilities with object reports, About Database and a database monitor; sprint 61: the builder's screens compared with APEX 26.1: the workspace sign-in page, the Administration menu with workspace message, environment banner and utilization, the SQL Workshop home, the App Gallery, application groups and cross application reports (four rows added); sprint 60: isolated workspaces with their own database logins, row-level security on pgkiln's tables and workspace database roles, workspace administrators; sprint 59: the Page Designer's help pane, Quick edit from the developer toolbar; sprint 58: page groups; sprint 57: region templates hero, title bar, buttons container, inline dialog and drawer, wizard with wizard progress, the carousel; sprint 56: Generate DDL and Schema Comparison in the SQL Workshop, `pgkiln ddl` and `pgkiln compare`; sprint 55: an editable login page with a Login region and the Minimal page template, Forgot password through the application's mail service; sprint 54: interactive grid views, the single row view, group by and chart; sprint 53: application settings, user preferences and items kept per user, dynamic translations, `meta.data_export` and data export downloads, display image and geocoded address items; sprint 52: every dynamic action event and action, Ajax callbacks, an error handling function, the session timeout warning; sprint 51: checked imports, application backups, availability and Run only, feedback, type-specific attribute help; sprint 50: lost update detection, warn on unsaved changes, the URL and search regions with search configurations, the developer toolbar with a session state viewer, and e-mail through SMTP with OAuth2, Microsoft Graph, Amazon SES and HTTP APIs; import checks, application availability, property help and e-mail compared again; 2026-10-06: pgkiln 0.31.0, in progress: static application files and the Execute JavaScript dynamic action; region, item, dynamic action and process plug-ins; conditional and dynamic theme styles; XML and Excel in `meta.parse_data`, zips in SQL, `meta.v_boolean`; file items in S3-compatible object storage; map layers by the visible area and as vector tiles; a graphical query builder; tenants for workflows and tasks; application files as YAML and region static IDs; Lucide icons and icon modifiers; PWA push notifications; 0.30.0: 136 icons and an icon picker; an axe-core accessibility audit; cropping pictures; session sharing between applications; twenty-two built-in languages; 0.29.0: workspaces; the Iris base style; drawers; built-in template components including the metric card; Theme Roller dark-mode colours, live preview and template options on items and report columns; report selection across pages; instance settings; fourteen built-in languages; 0.28.0: AI with Claude and OpenAI; 0.27.0: Data Reporter; sample data generator; create application from several sheets, pasted data or existing tables; 0.26.0: working copies with a three-way merge; theme, library and boilerplate applications with subscriptions; 0.25.0: Gantt, pyramid and polar charts; map layers, clustering and server-side spatial filters; REST data sources that write back from forms and grids and synchronise into tables, OAuth2 password and refresh-token grants; debug messages per request and an install/upgrade log; `meta.web_request()` and `meta.parse_data()`; Theme Roller style variants and template options; 0.24.0: automations with several actions, error handling per row and runs from SQL; invoke-API workflow steps; Unload Data in the Data Workshop; create page wizards for cards, calendar, chart, map, faceted search, form and master-detail; create an application from a file; 0.23.0: interactive grid aggregates, frozen/moved/resized columns, layouts and saved grid reports, master-detail, row actions and copy/paste; download processes, execution chains in the background, workflow processes, branches to a function's URL or another app, the Dialog Closed event; number format masks, automatic time zone, runtime messages in German, French and Spanish; SQL scripts, Quick SQL, a query builder, XML loading and data load definitions; custom authentication, lists, page and application locks with developer comments, supporting objects; 0.22.0: keyset paging, report PDFs and REST collections streamed from a cursor, database-account authentication; 0.21.0: HTTP-header authentication behind a reverse proxy; 0.20.0: a popup list of values with server-side search; 0.19.0: row-range pagination, maximum row counts and row limits, lazy loading and caching of regions, streamed CSV/Excel downloads; 0.18.0: calendar week/day/list views with drag and drop, bubble/gauge/funnel/radar charts and drill-down, smart filters, a region display selector and more facet types, computations, conditional branches, build options, menu buttons, REST data sources and web credentials, rich text/Markdown, rating, combobox, date range and QR code items; 0.17.0: an App Builder home, workspace dashboard and utilities like APEX's; 0.16.0: a Page Designer with drag-and-drop layout, a code editor with autocomplete, template components and plug-ins, parallel branches and versions of workflows, the `pgkiln` command line with one file per component; 0.15.0: drop and paste files, heat maps, filtering a report by the map area; 0.14.0: stacked, combo, scatter and pie charts, several files per upload item; 0.13.0: map and tree regions; 0.12.0: REST modules in the builder; 0.11.0: workflows and Progressive Web Apps; 0.10.0: LDAP, SAML, "Keep me signed in", document templates, JSON loading, approvals and the task list; pgkiln installs no application, HR is an example).
 
 ## At a glance
 
@@ -36,10 +36,10 @@ two, REST source catalogs and the workspace export, with their features.)
 | APEX | pgkiln | Notes |
 |---|---|---|
 | App Builder: create, edit, delete, run apps | ✅ | Builder at `/builder` |
-| Create application wizard | ✅ | Blank app with its own database role and schema, started from a **boilerplate application** if wanted; **from a file**: CSV/TSV/XLSX/JSON/XML, where an Excel workbook with several sheets (or JSON with several arrays) becomes several tables, with a preview to include or leave out each sheet, edit table/column names, types and primary keys, and **foreign keys proposed** from matching columns; **from pasted data** (CSV/TSV text); **from existing tables** (pick the tables and views of a schema). Each gives a report and form per table, navigation and an optional dashboard (a chart per table), plus an optional faceted search for a single table, all created in one transaction. **Missing:** blueprints (26.1) |
+| Create application wizard | ✅ | Blank app with its own database role and schema, started from a **boilerplate application** if wanted; **from a file**: CSV/TSV/XLSX/JSON/XML, where an Excel workbook with several sheets (or JSON with several arrays) becomes several tables, with a preview to include or leave out each sheet, edit table/column names, types and primary keys, and **foreign keys proposed** from matching columns; **from pasted data** (CSV/TSV text); **from existing tables** (pick the tables and views of a schema). Each gives a report and form per table, navigation and an optional dashboard (a chart per table), plus an optional faceted search for a single table, all created in one transaction. (sprint 73) **One page like APEX's**: name, icon and description, appearance (theme style, side or top menu, accent), a **page type per table** (interactive report with form, faceted search, cards, calendar, master detail, interactive grid, report, none; large tables proposed as a grid), **features** (About page, access control roles, activity reporting, feedback, theme style selection, PWA, push), settings (alias, authentication, first user, language) and a boilerplate under Advanced; a progress message, then straight to the new application. (sprint 71) The generated pages read like APEX's: human labels (abbreviations, run-together words, column and table comments), plural page and menu names with singular form titles, foreign keys shown by the parent's name in reports, `bytea` columns as one file item with their name/mime/size/updated columns, number format masks, a pencil per report row, the Dashboard after Home with *(none)* and top-N charts, and a Home page with a hero and a card per page. **Missing:** blueprints (26.1) |
 | Create page wizards | ✅ | Report and form, interactive grid, form, cards, calendar, chart, map, faceted search and master-detail (stacked grids) from any table or view, with defaults from the catalog (columns, key, dates, positions, foreign keys), an optional modal form page and a navigation entry; also from SQL (`meta.generate_page`). No side-by-side or drill-down master-detail, no wizard for smart filters or trees |
-| Page Designer | ✅ | IDE-style window (dark or light): component tree, a layout canvas with drag and drop (with keyboard and button alternatives) and a gallery of regions, items and buttons, a filterable property editor; undo/redo; panes become tabs on phones. Settings forms for report, grid, chart, cards, calendar, faceted search, smart filters, display selector, map, tree and template component regions. A code editor for SQL, PL/pgSQL, JSON and HTML with highlighting and autocomplete of tables, columns and `:ITEM` binds (no extra libraries). Drag and drop needs a mouse; on touch screens the Arrange buttons move components |
-| Shared components | ✅ | Navigation menu, **lists** (static entries with nesting, badges, conditions, authorization and build options, or a query; for list regions, the navigation menu and the navigation bar), authorization schemes, build options, lists of values, application items and processes, access control, globalization, template components and plug-ins, web credentials, REST data sources, data load definitions, supporting objects |
+| Page Designer | ✅ | IDE-style window (dark or light): component tree, a layout canvas with drag and drop (with keyboard and button alternatives) and a gallery of regions, items and buttons, a filterable property editor; undo/redo; panes become tabs on phones. Settings forms for report, grid, chart, cards, calendar, faceted search, smart filters, display selector, map, tree and template component regions. A code editor for SQL, PL/pgSQL, JSON and HTML with highlighting and autocomplete of tables, columns and `:ITEM` binds (no extra libraries). Drag and drop needs a mouse; on touch screens the Arrange buttons move components. (sprint 77) The layout draws the page template's display positions (banner, breadcrumb bar, left/right column, body, footer) as drop zones and a region's button positions; the rendering tree groups by position and has a context menu (create in or below, Duplicate, Copy to other page, expand/collapse all, delete); the property editor has Common / All, Go to group and a Template Options dialog; a page number in the toolbar. No nested regions (APEX's sub regions) and no Comment Out |
+| Shared components | ✅ | (sprint 74) A grid of ten groups with counts like APEX's, a searchable, sortable list per type with Create, and Settings-backed types linking to their Settings tab ([mapping below](#shared-components-apex-links-and-pgkiln)). Navigation menu, **lists** (static entries with nesting, badges, conditions, authorization and build options, or a query; for list regions, the navigation menu and the navigation bar), authorization schemes, build options, lists of values, application items and processes, access control, globalization, template components and plug-ins, web credentials, REST data sources, data load definitions, supporting objects |
 | Export / import | ✅ | `meta.export_app()` / `meta.import_app()`: portable JSON, also in the builder (new applications; `pgkiln import --replace` and the MCP `import_app` update one in place, live for every user at the commit). (sprint 51) **Checked imports**: `pgkiln import --check` (`--dry-run`, `--force`), the MCP import (by default) and the builder's import run the Advisor inside the import's transaction (SQL planned as the application's role: missing tables, columns, functions, types, grants; references) and refuse on errors, so nothing changes; APEX doesn't check. The version an import replaces is [backed up](guide/03-builder.md#backups) first ([chapter 18](guide/18-cli.md#checking-before-an-import)) |
 | APEXlang: human-readable, diffable app files; static IDs (26.1) | ✅ | `pgkiln export --format dir`: one JSON file per component with sorted keys, SQL and HTML in sibling files, references by static id instead of database ids; `pgkiln import --replace` updates an app in place, `pgkiln diff` compares ([chapter 18](guide/18-cli.md)). (0.31) **`--format text`**: the same files as YAML (a strict subset any YAML tool reads) with the SQL and templates inline, read back losslessly ([text files](guide/18-cli.md#text-files-apexlang)); regions have a stored **Static ID** (exported as their key, rendered as `data-static-id`), other components are named by their stored names. The syntax is YAML rather than APEXlang's own, so APEXlang files don't import |
 | Working copies, merge, team development | ✅ | **Working copies** of an application ([chapter 3](guide/03-builder.md#working-copies)): a second app on the same schema and data, compared three ways per component (settings, each shared component, page, region, item, …) with the main app as it was when copied; changes on one side merge, conflicts are chosen per component with a line diff; merge into the main app or refresh the copy, keeping users, sessions, saved reports, secrets and automation switches; locks respected. Conflicts are resolved per component, not per property |
@@ -61,11 +61,11 @@ two, REST source catalogs and the workspace export, with their features.)
 | APEX | pgkiln | Notes |
 |---|---|---|
 | Classic report | ✅ | `report` with `interactive: false` |
-| Interactive report | ✅ | Search, column filters, sort, rows per page, control break, aggregates (with subtotals), highlight, saved private and public reports, computed columns, group by, pivot, chart view, row selection into a page item, CSV, Excel (typed cells) and PDF download, print, reset, reflow on phones. a maximum row count (`max_rows`), natural-language control (*Ask in your own words*, 26.1) and row selection that stays across pages. Not possible: flashback queries (PostgreSQL has none; use an audit or temporal table) |
+| Interactive report | ✅ | (sprint 76) An Actions menu of nine entries with dialogs, a column heading menu (sort, hide, control break, the column's values to filter by), a search in one column, hidden columns, pagination with the range, first/last and rows per page. Search, column filters, sort, rows per page, control break, aggregates (with subtotals), highlight, saved private and public reports, computed columns, group by, pivot, chart view, row selection into a page item, CSV, Excel (typed cells) and PDF download, print, reset, reflow on phones. a maximum row count (`max_rows`), natural-language control (*Ask in your own words*, 26.1) and row selection that stays across pages. Not possible: flashback queries (PostgreSQL has none; use an audit or temporal table) |
 | Interactive grid | ✅ | Inline edit, add and delete rows, lists of values, required columns, per-row errors, all-or-nothing save, signed row keys, search and paging; **aggregates** over the whole result (developer and user defined), **frozen columns**, column **reorder/resize/hide** (Actions → Columns, or drag and drop), per-user layouts and **saved grid reports** (private and public), **master-detail** (signed row selection, details refreshed in place), a **row actions menu** (edit, duplicate, delete, links) and **copy/paste** of cell ranges (tab-separated, spreadsheet compatible) ([chapter 4](guide/04-pages-and-regions.md)) |
 | Interactive grid views: single row view, chart view, group by | ✅ | (sprint 54) **Single row view**: one row of the search as a form with first/previous/next/last and *Add row*, from the Actions or row actions menu, saved by the grid's own process with the same checks; **group by** and **chart** set up in the Actions menu over every row of the search, as for the interactive report; `views` limits them; Save comes back to the same search, page and view ([chapter 4](guide/04-pages-and-regions.md#grid-interactive-grid)). No pivot view on grids (the interactive report has one), no editing in the single row view of columns the grid doesn't show |
 | Form (automatic row processing) | ✅ | Fetch, insert, update, delete, in a page or a modal dialog. Detects rows deleted meanwhile. (sprint 50) **Lost update detection** (APEX: *Prevent Lost Updates* and *Lock Row*): the page carries a checksum of the row's form columns (`meta.row_version`, independent of time zone and date format, as the app's role); *Save* and *Delete* lock the row and refuse when it changed meanwhile; off per form with `{"lost_update": false}` ([chapter 4](guide/04-pages-and-regions.md#form)) |
-| Charts | ✅ | Bar, column, stacked, line, area, combination (columns + lines), scatter, bubble, donut, pie, gauge, funnel, radar, **Gantt** (start/end, progress, milestones, dependencies, a today line, a time axis from hours to years), **pyramid** (area-proportional segments, or two series back to back) and **polar** (polar area); (sprint 63) **range** (floating columns from low to high), **box plot** (from one value per row or five statistics) and **stock** (candlesticks from open, high, low and close); multi-series, tooltips, data table, palette checked for colour-vision deficiency; drill-down links on chart marks (checksummed, only to pages the user may open). Drawn on the server as SVG without inline styles. (sprint 69) **Gantt editing**: drag a task or its end, or the arrow keys, runs the region's SQL as the app's role. (sprint 70) **treemap** (squarified, two levels shown), **sunburst** (up to four rings) from `node_id` / `parent_id` columns, and **timeline** (lanes by a `series` column, points and periods, overlaps in rows). **Missing:** other Oracle JET types (e.g. picto, NBox, Sankey) |
+| Charts | ✅ | Bar, column, stacked, line, area, combination (columns + lines), scatter, bubble, donut, pie, gauge, funnel, radar, **Gantt** (start/end, progress, milestones, dependencies, a today line, a time axis from hours to years), **pyramid** (area-proportional segments, or two series back to back) and **polar** (polar area); (sprint 63) **range** (floating columns from low to high), **box plot** (from one value per row or five statistics) and **stock** (candlesticks from open, high, low and close); multi-series, tooltips, data table, (sprint 71) a value axis with gridlines on horizontal bars and top-N with an *Other* bar (`"top": 10`), palette checked for colour-vision deficiency; drill-down links on chart marks (checksummed, only to pages the user may open). Drawn on the server as SVG without inline styles. (sprint 69) **Gantt editing**: drag a task or its end, or the arrow keys, runs the region's SQL as the app's role. (sprint 70) **treemap** (squarified, two levels shown), **sunburst** (up to four rings) from `node_id` / `parent_id` columns, and **timeline** (lanes by a `series` column, points and periods, overlaps in rows). **Missing:** other Oracle JET types (e.g. picto, NBox, Sankey) |
 | Cards and metric cards (26.1 metric card template) | ✅ | Cards from SQL, with a KPI "metric" style |
 | Calendar | ✅ | Month, week, day and list views (agenda list on phones); create on click (a checksummed link with the slot); drag and drop to move events through the developer's move SQL, run as the app's role (CSRF, a *who may drag* authorization, only events the user sees). Works without JavaScript; dragging adds on top ([chapter 4](guide/04-pages-and-regions.md#calendar)) |
 | Faceted search | ✅ | Checkbox, range (predefined, or a custom from/to on numbers and dates), star rating and search facets with live counts that honour the other facets; exclude on checkbox facets (26.1). Values travel as query parameters, never as SQL text. (sprint 65) **Facet charts**: a bar or pie chart of a facet's counts, each mark filtering on its value |
@@ -156,7 +156,7 @@ two, REST source catalogs and the workspace export, with their features.)
 
 | APEX | pgkiln | Notes |
 |---|---|---|
-| Universal Theme look and layout | ✅ | Header, side/top navigation, breadcrumbs, 12-column grid, region templates |
+| Universal Theme look and layout | ✅ | Header, side/top navigation, breadcrumbs, 12-column grid, region templates. (sprint 77) Region display positions (banner, breadcrumb bar, left and right column, body, footer), the Left / Right Side Column page templates and button positions (create, edit, change, copy, help, up, previous, close, delete, next) ([chapter 4](guide/04-pages-and-regions.md#side-columns-and-display-positions)) |
 | Region templates (Carousel, Hero, Inline Dialog/Popup/Drawer, Wizard Container, Title Bar, Buttons Container, Login) | ✅ | Standard, plain and collapsible; (sprint 57) **hero**, **title bar**, **buttons container**, **inline dialog** and **inline drawer** (opened by the dynamic action *Open region* or a link to `#R<id>`), **wizard** with the list template **wizard progress**, and the **carousel** style of the display selector; dialog and drawer **pages**; the login page's **Login** region (sprint 55) ([chapter 4](guide/04-pages-and-regions.md#layout)). An inline popup (anchored to a button) is an inline dialog |
 | Warn on unsaved changes | ✅ | (sprint 50) A page attribute: the browser asks before the user leaves the page (links, redirect buttons, other forms, closing a dialog, closing or reloading the tab) while an item differs from the value it was shown with, also after a submit that failed; submitting doesn't ask; items opt out with `{"warn_unsaved": false}`; `pgkiln.isChanged()` (APEX: `apex.page.isChanged()`); on for the form pages the wizards make. The interactive grid keeps its own check ([chapter 4](guide/04-pages-and-regions.md#warn-on-unsaved-changes)). No per-button "do not check" |
 | Responsive: phone, tablet, desktop | ✅ | Tested at 390, 768, 1024 and 1440px on every change (`npm run test:e2e`) |
@@ -166,7 +166,7 @@ two, REST source catalogs and the workspace export, with their features.)
 | Icons (Font APEX 2.5) | ✅ | 136 line icons of pgkiln's own and (0.31) the **Lucide** set of about 1,600 more in the same line style, each served on its own; **modifiers** like Font APEX's (sizes, spin, rotate, flip, colours) and Font APEX names (`fa-users fa-lg`) where Lucide has the icon; a visual picker in the builder that searches all of them by name and search word ([chapter 9](guide/09-reference.md#icons)). Font APEX's own drawings are Oracle's, so icons look different and a few Font APEX names have no match |
 | Accessibility | ✅ | Labels, keyboard, focus rings, reduced motion, table alternatives for charts, scrolling tables reachable from the keyboard; an automated WCAG 2.1 A/AA audit (axe-core) of every example page in light, dark and Iris and of the builder's main pages runs in CI with no violations allowed. Not a manual expert audit |
 | Drawers, top/bottom dialogs (26.1) | ✅ | Modal pages open as a centred dialog or as a drawer from the left, right, top or bottom edge, in three sizes, sliding in (without animation for reduced motion); on phones full screen ([chapter 4](guide/04-pages-and-regions.md#dialogs-and-drawers)). Not yet: a footer slot for inline drawers |
-| New "Iris" default style (26.1) | ✅ | Base style **Iris** (indigo accent, larger corners, softer shadows, light and dark palettes checked for WCAG AA contrast), the default for new applications; existing ones keep *Standard* until switched in Settings → Theme ([chapter 14](guide/14-globalization.md#base-styles-iris-and-standard)) |
+| New "Iris" default style (26.1) | ✅ | Base style **Iris**, the default for new applications, light by default with the user's choice of dark: (sprint 72) like APEX 26's: a white body, a dark warm-grey header with an accent strip and a dark menu, 4 px corners, region headers with a rule, a dark primary button, a large page title; light and dark palettes checked for WCAG AA contrast. The earlier look stays as **Lavender** ([chapter 14](guide/14-globalization.md#base-styles-iris-lavender-and-standard)) |
 | Progressive Web App (push notifications: 23.1) | ✅ | Per app: installable (manifest, icon, standalone), service worker, offline pages (opt-in, wiped at sign-in/out), **forms sent offline queued on the device and sent later** (files included, once only, under the same user), location, camera and barcode items. (0.31) **Push notifications**: users turn them on per device (My account, or the dynamic action `push_subscribe`); `meta.send_push(user, title, body, page, items)` and a `send_push` process queue them, sent after the commit, encrypted for the device (RFC 8291) and signed with the application's own VAPID key (RFC 8292, stored encrypted, never exported); links signed for the recipient; devices end at sign-out, a new password, deactivation or removed access ([chapter 17](guide/17-mobile.md#push-notifications)). No images or action buttons in notifications |
 
 ## Globalization
@@ -176,7 +176,7 @@ two, REST source catalogs and the workspace export, with their features.)
 | Translated applications (26.1: text-message-based translation of one app) | ✅ | One app with translations, like 26.1; XLIFF 1.2 and CSV export/import, coverage per language |
 | Text messages (`APEX_LANG.MESSAGE`, `&APP_TEXT$…`) | ✅ | `meta.message()`, `&APP_TEXT$NAME.`, fallback to the base and primary language |
 | Language from browser, preference or session | ✅ | Browser, user preference or primary; `?lang=`; right-to-left languages |
-| Date and timestamp format masks | ✅ | Per app or per language |
+| Date and timestamp format masks | ✅ | Per app or per language; (sprint 76) date items show and read the application's date format (or their own) with a calendar button |
 | Dynamic translations (`APEX_LANG.LANG`: translated data values, e.g. list of values entries) | ✅ | (sprint 53) Shared Components → Dynamic translations; `meta.lang(text)` in a query returns the value in the session's language (base language fallback); exported with the application |
 | Number format masks, automatic time zone | ✅ | Oracle-style number masks (`999G999G990D00`, `FML…`, `0000`, `%`, `S`/`MI`/`PR`, `EEEE`, `X`, `RN`) on report, grid and cards columns, charts and number/display items, in the language's separators with the app's currency; Automatic Time Zone (browser, My account, app or database), `timestamptz` shown in it ([chapter 14](guide/14-globalization.md)) |
 
@@ -184,7 +184,7 @@ two, REST source catalogs and the workspace export, with their features.)
 
 | APEX | pgkiln | Notes |
 |---|---|---|
-| SQL Workshop: SQL commands, object browser | ✅ | (sprint 61) A **home page** like APEX's: tiles, recently created tables, your recent SQL commands and the workspace's recent scripts, and the session's **default schema** (first in the search path of SQL Commands and Scripts). The object browser shows columns, RLS policies, grants, data and function source. (sprint 62) **Utilities** like APEX's: the tools on one page, **Object Reports** (tables without a primary key, unindexed foreign keys, row-level security without policies or not enabled, PUBLIC grants, unused indexes, largest tables, missing comments), **About Database** and a **Database Monitor** of sessions and blocked queries for administrators. **Missing:** a recycle bin (PostgreSQL has none), user interface defaults (pgkiln's wizards read the catalog and comments) |
+| SQL Workshop: SQL commands, object browser | ✅ | (sprint 61) A **home page** like APEX's: tiles, recently created tables, your recent SQL commands and the workspace's recent scripts, and the session's **default schema** (first in the search path of SQL Commands and Scripts). (sprint 75) The **Object Browser** like APEX's: a schema in the header, a tree by object type (tables, views, materialized views, indexes, sequences, types, functions, procedures, triggers) with a filter and a Create menu, system and extension objects hidden unless asked, and a table in tabs (columns with Add/Rename/Drop column writing the ALTER TABLE to review, data in pages, indexes, constraints, triggers, grants, row level security, dependencies, statistics, DDL); the tools as main tabs and a More menu. (sprint 62) **Utilities** like APEX's: the tools on one page, **Object Reports** (tables without a primary key, unindexed foreign keys, row-level security without policies or not enabled, PUBLIC grants, unused indexes, largest tables, missing comments), **About Database** and a **Database Monitor** of sessions and blocked queries for administrators. **Missing:** a recycle bin (PostgreSQL has none), user interface defaults (pgkiln's wizards read the catalog and comments) |
 | RESTful services (ORDS) | ✅ | [PostgREST](https://postgrest.org) next to pgkiln: `api` schema, the same RLS as the UI, per-app API role, tokens in the builder, a pre-request check, and **OAuth clients** (client credentials, like ORDS `oauth.create_client`) so tokens renew themselves |
 | REST handler editor, REST-enabled SQL | ✅ | **REST modules** in the builder: handlers (method, path with parameters, SQL as collection, item or statements, roles, public) served by pgkiln with bearer tokens and an OpenAPI description; plus PostgREST for schema-wide APIs. **Missing:** REST-enabled SQL (rarely desirable) |
 | SQL scripts, query builder, Quick SQL | ✅ | **SQL Scripts**: saved, upload/download, a result per statement, stop or continue on errors, optionally one transaction, run history. **Quick SQL** (a subset: tables, child tables, types, the main column directives, `/auditcols`, settings, views). A graphical **query builder**: tables as boxes on a canvas (dragged, placed where left), joins along foreign keys or drawn from column to column (inner or left), column functions with automatic `group by`, conditions, sort, open in SQL Commands; without JavaScript the same as forms ([chapter 3](guide/03-builder.md#sql-workshop)) |
@@ -219,7 +219,7 @@ two, REST source catalogs and the workspace export, with their features.)
 | Workspace message, environment banner, workspace utilization, preferences and extension links (Manage Service) | ✅ | (sprint 61) An **Administration** menu in the icon rail; administrators and workspace administrators set a **workspace message** (on the App Builder home) and an **environment banner** (a coloured label on every builder page of the workspace), and see **workspace utilization** (applications, pages, page views, users, static files, schema storage) ([chapter 3](guide/03-builder.md#workspace-message-and-environment-banner)). (sprint 62) **Workspace preferences**: the SQL Workshop and the applications' RESTful services (REST modules) on or off per workspace; **extension links** in an Extensions menu of the rail ([chapter 3](guide/03-builder.md#workspace-preferences)). **Missing:** the account login controls of APEX's preferences (pgkiln's password policy and sign-in throttling are installation-wide) |
 | Instance administration, install/upgrade logs (26.1) | ✅ | Versioned migrations (`npm run db:migrate`), every run logged; Workspace utilities → **Installation** (administrators): server version, install and upgrade runs with errors, applied migrations, and warnings for migrations the database misses or the server doesn't know ([chapter 3](guide/03-builder.md)). Workspace utilities → **Instance settings**: session length and sign-in throttling (stored in the database, over the environment variables) and an overview of the server's configuration without secrets; a server whose database lacks migrations says so (503) or applies them (`MIGRATE_ON_START`). Other settings stay environment variables |
 | Debug messages | ✅ | Debug levels 1–9 per app; `meta.debug(level, text)` and `meta.debug_enabled(level)` from application SQL (APEX_DEBUG); timed entries per request (page steps, regions, processes, branches, errors, SQL notices); Activity → **Debug messages** viewer per page view with filters and the slowest step highlighted; retention 1–90 days; password item values are never recorded ([chapter 6](guide/06-processing.md)). (sprint 50) Debug for **one session** from the developer toolbar, the application staying out of debug. **Missing:** debug entries for background jobs and REST requests |
-| Developer toolbar, session state viewer | ✅ | (sprint 50) Developers signed in to the builder see a toolbar on the pages of their applications in the same browser: App Builder, the application, **Edit page** (Page Designer), **Session** (the session state viewer: user, roles, session, language, time zone, debug level, this page's items, application items and other pages' items; passwords never shown; clear the page's items) **Quick edit** (sprint 59: click a region, item or button to open it in the Page Designer) and **Debug** for this session only. A separate random token (cookie path `/a`, HttpOnly) of a live builder session of a developer of the application's workspace ([chapter 3](guide/03-builder.md#developer-toolbar)). **Missing:** Theme Roller from the page |
+| Developer toolbar, session state viewer | ✅ | (sprint 50) Developers signed in to the builder see a toolbar on the pages of their applications in the same browser: App Builder, the application, **Edit page** (Page Designer), **Session** (the session state viewer: user, roles, session, language, time zone, debug level, this page's items, application items and other pages' items; passwords never shown; clear the page's items) **Quick edit** (sprint 59: click a region, item or button to open it in the Page Designer) and **Debug** for this session only. A separate random token (cookie path `/a`, HttpOnly) of a live builder session of a developer of the application's workspace ([chapter 3](guide/03-builder.md#developer-toolbar)). (sprint 72) A compact bar of icons with tooltips like APEX's, centred at the bottom, **Customize** (the Theme Roller) and **Info**, hidden to a slim tab when not used, docked at the bottom, top, left or right; the page keeps room for it |
 | Feedback (users send feedback from a page, developers answer) | ✅ | (sprint 51) With *Users can send feedback* on, the navigation bar's **Feedback** link opens a page for a comment, idea or problem about the page (optional rating), with the user's earlier feedback and the developers' answers; developers read, filter, set a status and answer under Application → Feedback ([chapter 3](guide/03-builder.md#feedback)). No screenshots, no e-mail to developers |
 | Automatic application backups, page groups | ✅ | (sprint 51) **Backups**: before every import that replaces an application (CLI, MCP, working copy merge, restore), daily when it changed, and by hand; the newest 25 (configurable) are kept; download and restore from the builder ([chapter 3](guide/03-builder.md#backups)); (sprint 62) Workspace utilities → **Manage backups** across the workspace's applications, with a backup of all of them at once. (sprint 58) **Page groups**: Shared Components → Page groups, a page's *Page group*, the page list by group with a filter ([chapter 3](guide/03-builder.md#page-groups)) |
 | Application availability (Available, Developers only, Restricted access, Unavailable; build status *Run only*) | ✅ | (sprint 51) Available, available to developers only (a builder session in the same browser), restricted to named users, or unavailable with a message, for pages, file downloads, REST modules and PostgREST; build status **Run only** refuses builder changes as if the application were locked, while `pgkiln import --replace` still deploys. Installation settings: not exported, kept by an import ([chapter 3](guide/03-builder.md#availability-and-build-status)) |
@@ -304,3 +304,30 @@ report filters, App Builder AI and blueprints.
 Sources: [APEX 26.1 new features](https://docs.oracle.com/en/database/oracle/apex/26.1/htmrn/new-features.html),
 [What's new in APEX 24.2](https://apex.oracle.com/en/platform/features/whats-new-242/),
 [APEX_MAIL (APEX API reference)](https://docs.oracle.com/en/database/oracle/apex/24.2/aeapi/APEX_MAIL.html).
+
+## Shared Components: APEX links and pgkiln
+
+(sprint 74) Every link of APEX 26.2's Shared Components page and where it is in pgkiln.
+
+| APEX | pgkiln |
+|---|---|
+| Application Definition, Application Items, Application Processes, Application Settings, Build Options | The same names (Application Logic) |
+| Application Computations | ➖ Not planned: an application process *before every page* or an item's computation does it |
+| Authentication Schemes | Settings → Security: one authentication per application (its type and fields); several schemes to switch between are ➖ not planned |
+| Authorization Schemes, Access Control | The same names (Security) |
+| Security Attributes, Session State Protection | Settings → Security and Sign-in; session state protection is per page (Page Designer → *Protection*) |
+| Lists of Values, Lists, Email Templates, Supporting Objects, Subscriptions | The same names (Other Components) |
+| Navigation Menu, Navigation Bar List, Breadcrumbs, Search Configurations | The same names (Navigation and Search); breadcrumbs follow each page's breadcrumb parent |
+| Shortcuts | ➖ Not planned: application items and substitutions (`&ITEM.`) |
+| Themes, Templates, User Interface Attributes, Theme Roller | Themes and Theme Roller, Template Components, Settings → User Interface; page and region templates are a fixed list (➖ no template editor) |
+| Plug-ins, Component Settings | Plug-ins; component settings ➖ not planned |
+| Component Groups | Page Groups (pages); groups of other components ➖ not planned |
+| Progressive Web App | Settings → Progressive Web App |
+| Static Application Files, Static Workspace Files | Static Application Files; workspace files ➖ not planned |
+| Report Layouts, Report Queries | Report Layouts and Document Templates (a template with its own queries) |
+| REST Data Sources, Web Credentials, REST Enabled SQL, Data Load Definitions | The same names (Data Sources); REST Enabled SQL ➖ not planned (one database) |
+| Workflows, Task Definitions, Automations | The same names |
+| Text Messages, Translate, Dynamic Translations, Globalization Attributes | Translations and Text Messages, Dynamic Translations, Settings → Globalization |
+| Map Backgrounds | The installation's map tile server (`MAP_TILE_URL`) |
+| AI Attributes, AI Services, AI Agents | AI Services; AI agents ➖ not planned |
+

package/docs/guide/03-builder.md

@@ -246,23 +246,33 @@ The list is `examples/gallery/gallery.json`; add your own starters there as blue
 
 ### Creating an application
 
-**Create** (a tile, or `/builder/create`):
+**Create** (a tile, or `/builder/create`) is one page, like APEX's Create Application wizard. Links at the top
+start from a file, pasted data, a blueprint or the App Gallery instead. Then:
 
-| Field | Meaning |
-|---|---|
-| Name | Display name, shown in the header |
-| Alias | Lowercase URL name: `inventory` gives `/a/inventory` |
-| Parsing schema | The database schema the app works with. Choose an existing schema, or leave it on "new schema" to create one named after the alias |
-| Authentication | *App users* (a login page and a user list), *HTTP header* (a trusted reverse proxy names the user, see [chapter 8](08-security.md#http-header-authentication-reverse-proxy)), *Database accounts* (PostgreSQL login roles and their passwords, see [chapter 8](08-security.md#database-accounts-postgresql-roles)), *Custom* (your own PL/pgSQL function, see [chapter 8](08-security.md#custom-authentication-a-plpgsql-function)) or *None* (a public app) |
-| First user / Password | The first user; they get the `admin` role. An existing account is reused (its password isn't changed) |
-| Start from | Shown when there are **boilerplate** applications (Settings → Application type): their pages, shared components and settings are copied into the new application, which keeps its own name, alias, role and authentication ([application types](#application-types-and-subscriptions)) |
+| Section | Field | Meaning |
+|---|---|---|
+| Data | Pages on the tables of | The parsing schema: an existing schema (*Show its tables* lists them under Pages), or a new, empty one named after the alias |
+| Application | Name | Display name, shown in the header. Proposed from the schema and selected when you click it, so typing replaces it |
+| | Description, Icon | Shown on the home page's hero and the About page |
+| Appearance | Theme style, Navigation, Accent colour | Iris, Lavender or Standard; a side or top menu; an own accent colour |
+| Pages | a page type per table | *Interactive report with form*, *Faceted search*, *Cards*, *Calendar* (a table with a date column), *Master detail* (a table another table refers to), *Interactive grid*, *Report* or *No page*. Tables with a single-column primary key get a modal form with their report, faceted search, cards and calendar; views and tables without such a key can't have a form or a grid. Proposed: a report with form, an interactive grid for a table of more than 100,000 rows, a report for a view. *Dashboard*: a chart per table |
+| Features | | *About page* (in a Help menu), *Access control* (authorization schemes `CONTRIBUTOR` and `READER` next to `ADMIN`, for the roles admin, contributor and reader), *Activity reporting* (page 9010 for administrators: page views per day and the latest activity, from `meta.app_activity`), *Feedback*, *Theme style selection* (users may choose light or dark), *Install as an app* (PWA) and *Push notifications* (needs `PGKILN_SECRET_KEY`) |
+| Settings | Alias | Lowercase URL name: `inventory` gives `/a/inventory` |
+| | Authentication | *App users* (a login page and a user list), *HTTP header* (a trusted reverse proxy names the user, see [chapter 8](08-security.md#http-header-authentication-reverse-proxy)), *Database accounts* (PostgreSQL login roles and their passwords, see [chapter 8](08-security.md#database-accounts-postgresql-roles)), *Custom* (your own PL/pgSQL function, see [chapter 8](08-security.md#custom-authentication-a-plpgsql-function)) or *None* (a public app) |
+| | First user / Password | The first user; they get the `admin` role. An existing account is reused (its password isn't changed) |
+| | Language | The application's primary language |
+| Advanced | Start from | Shown when there are **boilerplate** applications (Settings → Application type): their pages, shared components and settings are copied into the new application, which keeps its own name, alias, role and authentication ([application types](#application-types-and-subscriptions)) |
 
 Creating the app also:
 
 - creates the database role `app_<alias>` with `SELECT/INSERT/UPDATE/DELETE` on all tables,
   `USAGE` on sequences and `EXECUTE` on functions in the schema, plus **default privileges**,
   so tables you create later (as the owner, e.g. in the SQL Workshop) are usable by the app straight away;
-- creates page 1 *Home*, a navigation entry, and an authorization scheme `ADMIN` (role `admin`).
+- creates page 1 *Home*, a navigation entry, and an authorization scheme `ADMIN` (role `admin`);
+- shows a progress message while it works and then opens the new application's page in the builder,
+  with what was created (and anything left out) as a message.
+
+Everything is created in one transaction: when a page can't be made, nothing is.
 
 The parsing schema can't be `meta`, `information_schema` or a `pg_*` schema.
 
@@ -334,18 +344,50 @@ most 4 MB of text; upload larger data as a file.
 
 ### Creating an application from existing tables
 
-**Create → From existing tables** (`/builder/create/tables`): choose a schema (pgkiln's `meta`,
-`information_schema` and the `pg_*` schemas aren't offered), then tick its tables and views (tables
-are ticked by default). The application gets that schema as its parsing schema and a role
+**Create**, then a schema under *Data* (`/builder/create?schema=…`; pgkiln's `meta`,
+`information_schema` and the `pg_*` schemas aren't offered): each table and view gets a page type
+under *Pages* (above), or *No page*. The application gets that schema as its parsing schema and a role
 `app_<alias>` with the grants of a blank application on the schema (so **all** tables of the schema,
-not only the ticked ones). For each ticked table with a single-column primary key, an interactive
-report with a modal form (`meta.generate_page` *report_form*); for views and tables without such a
-key, a report page; a navigation entry each; and optionally a dashboard (a chart per table, as above;
+not only the ones with pages). The pages are made with `meta.generate_page`, with a navigation entry
+each; and optionally a dashboard (a chart per table, as above;
 for existing tables the repeating values come from the planner statistics, so `ANALYZE` a table that
 was never analyzed). Everything is created in one transaction. Foreign keys to tables in another
 schema show in forms as select lists that the app's role may not be allowed to read: grant it, or
 pick a schema that holds them all.
 
+#### What the generated pages look like
+
+The wizards (every *Create application* flow and the page wizards) make pages that read like APEX's:
+
+- **Labels**: names become words. `snake_case` and `camelCase` are split, run-together words are
+  recognised (`hiredate` → *Hire Date*, `deptno` → *Department Number*) and common abbreviations are
+  expanded (`emp` → *Employee*, `dept` → *Department*, `sal` → *Salary*, `comm` → *Commission*, `mgr` →
+  *Manager*, `qty` → *Quantity*, `desc` → *Description*, `pct` → *Percent*, `crm` → *CRM*, `id` → *ID*).
+  A foreign key column drops its `_id`/`no` suffix (`deptno` → *Department*), and a column named after
+  the table's first letter drops it (`emp.ename` → *Name*). A short `COMMENT ON COLUMN` (one line, at
+  most 60 characters, no full stop) is the label; a longer one becomes the item's help text. A short
+  `COMMENT ON TABLE` names the pages.
+- **Plural and singular**: report pages, cards and the navigation menu use the plural (*Employees*),
+  forms and dialog titles the singular (*Employee*).
+- **Reports** show a foreign key's parent by its display column (a name, title or label, else its first
+  text column): *Manager* shows KING, *Department* shows SALES. The key itself stays in the query,
+  hidden, so filters can use it. A row starts with a pencil that opens the form.
+- **Files**: a `bytea` column becomes one file upload item that also fills the columns that go with it
+  (`<col>_name`/`_filename`, `<col>_mime`/`_mime_type`, `<col>_size`, `<col>_updated`; or `filename`
+  and `mime_type` next to the only `bytea` column). Reports leave these columns out. Columns named like
+  *photo*, *image* or *logo* accept pictures only.
+- **Numbers** get a format mask with group separators (and the scale's decimals for `numeric(p,s)`),
+  in reports and forms alike, in the application's language (*2,850.00*); keys get none.
+- The **Dashboard** comes right after *Home* in the menu; its charts are titled *Employees by Manager*,
+  rows without a value are labelled *(none)*, and bar charts show the ten largest values (the rest is
+  one *Other* bar). Tables with row-level security are left out (the application's role may see none of
+  their rows); the result page says which.
+- The **Home** page has a hero with the application's icon and name, and a card per page of the menu
+  (a list `HOME_PAGES`, Shared Components → Lists). A blank application gets the hero only.
+- An **About** page (page 9000: the application's description, or the pages of its menu) in a **Help**
+  menu of the header's navigation bar (a list `NAVBAR`, the application's navigation bar list).
+- New applications use the **Iris** base style in the **light** theme; users may switch to dark.
+
 ### Creating an application from a blueprint
 
 **Create → From a blueprint** (`/builder/blueprints`; APEX 26.1: *Blueprints*, spec-driven
@@ -420,6 +462,14 @@ they are **not** run until you choose to.
 
 ## App dashboard
 
+(sprint 74) Above the pages: a **search** by page name or number (the rows filter while you type),
+**Report** and **Icons** views, and **Create page** (the page wizards below). **Tasks** on the right: run the
+application, create pages (also with AI), Shared Components, page groups, export, backups, supporting
+objects, lock or delete the application.
+
+The **default-password** warning shows on the App Builder home (and Developers) only; dismiss it with × until the
+next sign-in. The avatar keeps a red dot until the password is changed.
+
 Open an application to see its pages, with region/item/dynamic-action/process counts,
 authorization and protection. The tabs under its name lead to **Shared Components**, **Activity**,
 **REST API**, **Settings**, **Search** and **Advisor**; **Export** and **Run** are on the right.
@@ -490,8 +540,11 @@ choosing a component opens the Properties tab.
 
 - **Left: the component tree**, with four tabs:
   - **Rendering**: the page, *Pre-Rendering* (branches, computations and processes that run
-    before the page is shown), the
-    **Regions** with their items and buttons, and page-level items and buttons;
+    before the page is shown), the regions by
+    [display position](04-pages-and-regions.md#side-columns-and-display-positions) (Banner, Breadcrumb bar,
+    Left column, Body, Right column, Footer: the page template's positions and any other that has regions)
+    with their items and buttons (by [button position](04-pages-and-regions.md#button-positions): *Buttons*,
+    *Buttons: Next*, …), and page-level items and buttons;
   - **Dynamic actions**, grouped by event (change, click, page load);
   - **Processing**: computations after submit, validations, processes and the branches (the
     [branch components](06-processing.md#branches) in sequence, then the buttons that go to
@@ -499,22 +552,36 @@ choosing a component opens the Properties tab.
   - **Shared components** the page can use (lists of values, authorization schemes, navigation,
     application items), linking to Shared Components.
 
-  Icons show which components have an authorization scheme, a condition or a build option. Folders open and close
+  Icons show which components have an authorization scheme, a condition or a build option; type icons are coloured
+  by kind (regions, items, buttons, dynamic actions, processes). Folders open and close
   with a click; with the keyboard, the arrow keys walk the tree (Left / Right close and open a
   folder), Enter opens a component.
-- **Middle: the Layout**: the page's regions on the 12-column grid, each with its items and
-  buttons, as they will be placed on the page; under it a **gallery** of region types, item types
+
+  **Right-click** a region, item or button in the Rendering tree (or press <kbd>Shift</kbd>+<kbd>F10</kbd> or the
+  menu key) for its menu (APEX: the tree's context menu): *Create page item*, *Create button* (in the region),
+  *Create dynamic action*, *Create region below*, **Duplicate** (a copy right after it; a region comes with its
+  items and buttons, names get `_2`), **Copy to other page…** (to the end of a page of the same application; items
+  named `P<n>_` get that page's number, a region's buttons and items come along, references in SQL are not changed),
+  *Expand all below*, *Collapse all below* and *Delete*. The arrow keys move through the menu, Escape closes it.
+  APEX's *Create Sub Region* (pgkiln has no nested regions) and *Comment Out* (use a build option) are not there.
+- **Middle: the Layout**: the page template's display positions as labelled zones (Banner, Breadcrumb bar,
+  the side column of a side-column template beside the Body, Footer), each with its regions on the 12-column
+  grid, each region with its items and its buttons in their button positions, as they will be placed on the page; under it a **gallery** of region types, item types
   and button actions. The middle pane also has a **Page search** tab (searches the application)
   a **Lock and comments** tab ([below](#page-locks-and-comments)) and a **Help** tab (layout keys and the substitution cheat sheet). Zoom in, zoom out and
   maximize (hides the side panes) are above the layout.
 - **Right: the property editor** for the selected component, grouped (Identification, Source,
   Layout, Security, …) with help text for each property. Type in **Filter** to show only the
   properties whose name contains the text (Escape clears it); click a group's name to fold it
-  (remembered on this device). Under the properties, the **Help** pane (APEX: the Help tab) shows the
+  (remembered on this device). **Common** / **All** (APEX: Show Common / Show All) shows only the properties
+  most often set for regions, items and buttons, or all of them (remembered); **Go to group** jumps to a group
+  (opening the Attributes tab when the group is there). **Template options** open in a dialog from a button that
+  counts the chosen ones; they are saved with the other properties. Under the properties, the **Help** pane (APEX: the Help tab) shows the
   property that has the focus (or the pointer): its help, the name it is stored under in exports and
   application files, and a link to the guide section of the component's type.
 
-The toolbar has the page switcher (previous, a list of all pages, next), **Undo** / **Redo** of
+The toolbar has the page switcher (previous, the page number: type or step to one and press Enter, a list of
+all pages, next), **Undo** / **Redo** of
 layout changes, the **Create** menu (region, item, button, dynamic action, computation, validation,
 process, branch, or a new page), a **Utilities** menu (Advisor, search, shared components, all pages, export),
 **Save** (saves the property editor; it is highlighted when there are unsaved changes) and **Run**
@@ -544,7 +611,11 @@ region that no longer fits starts a new row.
 
 - **Drag a region** by its header to another place, or drag its right edge to make it wider or
   narrower.
-- **Drag an item or button** to another place in its region, to another region, or to *Page level*.
+- **Drag a region into another position** (zone) to set its display position: e.g. a faceted search into
+  the *Left column* of a page with the Left side column template.
+- **Drag an item or button** to another place in its region, to another region, or to *Page level*. While a
+  button is dragged, a region's empty [button positions](04-pages-and-regions.md#button-positions) (Create, Edit,
+  …, Previous, Next) show as drop targets; dropping it there sets its position.
 - **Drag an entry of the gallery** onto the layout to create that component there, with a working
   starting point (a sample query for reports, charts and cards; a name like `P5_NEW` for items);
   then set its properties on the right. Clicking a gallery entry instead opens the create form
@@ -555,7 +626,8 @@ region that no longer fits starts a new row.
   (move up, move down, narrower, wider, or move an item or button to another region); on phones and
   tablets this is the way to arrange things.
 - **Undo** and **Redo** in the toolbar take back the last 20 layout changes on this page (moving
-  and resizing; creating a component starts a new history).
+  and resizing, display and button positions too; creating, duplicating or copying a component starts a new
+  history).
 
 Without JavaScript the panes are shown one under the other, every component is a link and the
 Arrange buttons still work.
@@ -635,8 +707,12 @@ Chapters 4–7 describe every component type and property.
 ## Developer toolbar
 
 While you are signed in to the builder, the pages of your applications show the **developer
-toolbar** at the bottom left when you run them in the same browser (APEX: the Runtime Developer
-Toolbar). It isn't shown to anyone else, nor inside dialogs, and it can be folded away. It has:
+toolbar** when you run them in the same browser (APEX: the Runtime Developer Toolbar): a compact bar
+of icons, centred at the bottom, each with a tooltip. It isn't shown to anyone else, nor inside
+dialogs. The page keeps room for it, so it never covers the menu's last entry or a report's pager.
+After a few seconds without use it shrinks to a slim tab at the edge; point at it or Tab to it to
+bring it back. **Settings** (the last icon) docks it at the bottom, top, left or right and turns the
+hiding off (kept in your browser). It has:
 
 | Entry | Does |
 |---|---|
@@ -645,6 +721,8 @@ Toolbar). It isn't shown to anyone else, nor inside dialogs, and it can be folde
 | **Edit page *n*** | This page in the Page Designer |
 | **Quick edit** | (with JavaScript) Point at a region, item or button of the page (it is outlined) and click it: it opens selected in the Page Designer, in the builder's tab (APEX: Quick Edit). Click the button again or press Esc to stop |
 | **Session** | The **session state viewer**: the user, roles, session id, language, time zone and debug level; the values of this page's items, the application items and the items of other pages in the session. A password item's value is never shown. *Clear the items of page n* empties this page's items in the session (APEX: Clear Cache) |
+| **Customize** | The application's Theme Roller in the builder |
+| **Info** | The application, the page, the user and the developer |
 | **Debug** | Records [debug messages](06-processing.md#debug-messages) for **this session only**, at the chosen level, while the application itself stays out of debug (*Application (n)* when the application has a level of its own). *View debug* opens the recorded requests |
 
 How it knows you: signing in to the builder gives the browser a second, separate random token for
@@ -765,7 +843,14 @@ exported.
 
 ## Shared components
 
-Components used by the whole application:
+Components used by the whole application. **Shared Components** opens on a grid like APEX's: ten groups
+(Application Logic, Security, Other Components, Navigation and Search, User Interface, Files and Reports,
+Data Sources, Workflows and Automations, Globalization, Generative AI) with a link and a count per component
+type. A type opens its list (`?type=…`): search by name (the rows filter while you type), sort by name,
+**Create**, and a row opens its editor. The types pgkiln keeps in the application's Settings (authentication,
+security attributes, navigation bar list, user interface attributes, PWA, globalization attributes) open the
+right Settings tab. **Breadcrumbs** shows the pages by their breadcrumb parent. **Tree view** (`?view=tree`)
+is the earlier page: every component in one rail, with **Access control** next to it.
 
 | Component | Purpose |
 |---|---|
@@ -881,6 +966,12 @@ register at the provider, and has a *Test discovery* button. See
 
 ## Settings
 
+Settings has tabs (APEX: Edit Application Definition and Security Attributes): **Definition**, **Security**,
+**Sign-in**, **User Interface**, **Globalization**, **Errors and Sessions** and **Progressive Web App**. It opens
+on Definition (`?tab=…` opens another). *Save settings* saves the first five together and comes back to the tab
+you were on. The Security tab shows only the fields of the chosen authentication type (HTTP header, database
+accounts or custom).
+
 - **Application**: name, alias, home page.
 - **Security**: authentication (*App users*, *HTTP header*, *Database accounts*, *Custom* or
   *None*), the database role, and **debug mode** (shows full database errors to users; development
@@ -1104,13 +1195,24 @@ Commands; other developers' are never shown) and the workspace's **recent SQL sc
 session's **schema** (APEX: the default schema): it goes first in the search path of SQL Commands and SQL Scripts until
 you sign out. Tasks link to Quick SQL, blueprints, table descriptions, sample data and Generate DDL.
 
+(sprint 75) The tools are tabs: Home, Object Browser, SQL Commands, SQL Scripts and Utilities; **More** opens the
+others (Quick SQL, Query Builder, Load and Unload Data, Sample Data, DDL, Compare, AI), and the open one is a tab too.
+
 - **SQL Commands** (`/builder/sql/commands`): run any SQL as the **owner connection**, not as an application role. Multiple
   statements are allowed; the result of the last one is shown (up to 500 rows). Press
   **Ctrl/Cmd + Enter** to run. The [code editor](#the-code-editor) suggests every schema, table,
   column and function the owner sees.
-- **Object Browser**: tables, views and functions per schema. For a table you see columns, types
-  and defaults, **row level security policies**, **grants** and the first 25 rows; for a
-  function, its source.
+- **Object Browser** (APEX's): the **schema** in the header (the session's schema by default) and a tree with a
+  folder per object type (tables, views, materialized views, indexes, sequences, types, functions, procedures,
+  triggers) and a **filter** by name. pgkiln's own schemas (`meta`, `pgkiln_plugins`) and objects that belong to an
+  extension show only with **Show system objects**. **Create** (and the tiles shown when nothing is selected) opens
+  SQL Commands with a CREATE TABLE, VIEW, FUNCTION, SEQUENCE or INDEX statement to fill in. A table opens in tabs:
+  **Columns** (with comments; *Add*, *Rename* and *Drop column* write the ALTER TABLE statement into SQL Commands to
+  review and run: nothing changes until you press Run), **Data** (25 rows a page), **Indexes**, **Constraints**
+  (primary key, foreign keys with the table they refer to, unique, check), **Triggers**, **Grants**, **Row level
+  security** (on or off, the policies), **Dependencies** (views and foreign keys that use it, and what it uses),
+  **Statistics** (rows, sizes, analyze and vacuum times) and **DDL**. A view has the same tabs where they apply; a
+  function or procedure shows its source, a trigger, index, sequence or type its definition.
 - **SQL Scripts**: saved scripts, shared by the developers of the workspace. Create one in the editor, upload a
   `.sql` file (UTF-8, up to 5 MB) or save one from Quick SQL; download it again as `.sql`. **Run**
   splits the script into statements at semicolons (outside strings, comments, quoted identifiers,

package/docs/guide/04-pages-and-regions.md

@@ -40,6 +40,41 @@ template of the same name) shows the page without the header, the navigation men
 navigation bar: the title and the regions only, centred. The application's
 [login page](08-security.md#the-login-page) uses it and gets the sign-in page's backdrop.
 
+### Side columns and display positions
+
+Like APEX's Universal Theme, a page has **display positions** and a region chooses one with its
+**Position** (Page Designer → region → Layout; `position` in the files; APEX: Layout → Position):
+
+| `position` | Where the region shows |
+|---|---|
+| `banner` | At the top of the page content, above everything else |
+| `breadcrumb` | In the bar under the title (the place of APEX's Breadcrumb Bar) |
+| `left`, `right` | In the side column of a page with page template *Left side column* or *Right side column* |
+| `body` (or empty) | The page body, on the 12-column grid (the default) |
+| `footer` | After the body |
+
+The page templates **Left side column** and **Right side column** (Page Designer → Page → Appearance;
+`page_template` `left_side_column` / `right_side_column`) put the regions of that position in a column
+beside the body (14–18rem wide; under the body's start on screens under 900px). On a page without that
+side column, `left` and `right` regions show in the body, in sequence. Regions keep their sequence within
+a position, and a region its condition leaves out leaves no empty position behind. A faceted search in
+the left column next to its report is the typical use.
+
+### Button positions
+
+A region's button has a **Button position** (Page Designer → button → Layout; `slot` in the files; APEX:
+Button Position):
+
+| `slot` | Where the button shows |
+|---|---|
+| `create`, `edit`, `change`, `copy`, `help`, `up` | In the region's header, after the title |
+| `previous`, `close`, `delete` | At the left end of the region's bottom bar |
+| `next` | At the right end of the bottom bar |
+| `region` (or empty) | With the region's other buttons, as before: the header of reports and charts, the bottom of forms and static content |
+
+Positions apply to the `standard`, `collapsible` and `plain` templates; the other templates place every
+button where they always do. Page-level buttons have no position.
+
 ### Dialogs and drawers
 
 A modal page (Page Designer → Page → Appearance: *Page mode* Modal dialog) opens over the page that linked to it.
@@ -187,9 +222,17 @@ select e.empno, e.ename, e.job, d.dname as department, e.sal
 
 Features for end users:
 
-- **Search** across all columns.
-- **Sort** by clicking a column heading (again for descending), or from the Actions menu.
-- **Actions menu**:
+- **Search** across all columns, or in one column chosen in the list at the start of the search field
+  (Enter searches; *Go* too).
+- **Column heading menu** (sprint 76; with JavaScript): clicking a heading opens a menu with *Sort ascending*,
+  *Sort descending*, *Hide column*, *Control break* and the column's **values** with their counts (with the current
+  search and filters; at most 200), with a box to narrow them; choosing a value filters the report on it. The sort
+  arrow of the sorted column sorts at once. Without JavaScript a heading sorts (again for descending).
+- **Hidden columns**: hidden from the heading menu or *Actions → Columns*, shown as chips to bring them back.
+- **Pagination**: *1–15 of 107*, first, previous, next and last page, and the **rows per page** list.
+- **Actions menu** (sprint 76: a short menu like APEX's; each entry opens a dialog, or unfolds in place without
+  JavaScript): *Columns*, *Filter*, *Data* (sort, aggregate, compute, control break), *Format* (highlight, rows per
+  page), *Chart*, *Group by*, *Pivot*, *Report* (saved reports, reset) and *Download* (CSV, Excel, PDF, print):
   - **column filters** (`=`, `≠`, contains, does not contain, `>`, `≥`, `<`, `≤`, is empty, is
     not empty) and **sort**;
   - **control break**: group the rows by a column, with a heading row per group;