pgkiln 0.82.0 → 0.83.0

package/db/migrations/153_component_events.sql

@@ -0,0 +1,21 @@
+-- Sprint 161 (CD-3, part 2; APEX: component events of Interactive Grid, Calendar, Map and Tree).
+--
+-- Events (trigger: the component's region id or static id):
+--   grid_row_init         a row was added to an editable grid (Add row, Duplicate) (APEX: Row Initialization)
+--   grid_save             a grid's changes were saved; runs on the page that comes back (APEX: Save)
+--   calendar_date_select  an empty day or hour of a calendar was chosen; the condition sees the date
+--                         (YYYY-MM-DD or YYYY-MM-DDTHH:MM); a cancel_event keeps the Create link closed
+--                         (APEX: Date Select)
+--   calendar_view_change  a calendar showed another view or period; the condition sees the view
+--                         (month, week, day, list) (APEX: View Change)
+--   map_object_click      a marker or shape of a map was clicked; the condition sees its id column (else its
+--                         title) (APEX: Map Object Clicked)
+--   map_change            a map was moved or zoomed; the condition sees the zoom level (APEX: Map Changed)
+--   tree_selection_change a node of a tree was chosen; the condition sees its id; a cancel_event keeps its link
+--                         closed (APEX: Selection Change [Tree])
+
+alter table meta.dynamic_action drop constraint dynamic_action_event_check;
+alter table meta.dynamic_action add constraint dynamic_action_event_check check (event in (
+  'change', 'click', 'load', 'dialog_closed', 'after_refresh', 'selection_change', 'focus', 'blur', 'key_release', 'before_submit', 'custom', 'menu_entry',
+  'double_click', 'key_down', 'key_press', 'mouse_enter', 'mouse_leave', 'select', 'resize', 'scroll', 'page_unload', 'before_refresh', 'facets_change',
+  'grid_row_init', 'grid_save', 'calendar_date_select', 'calendar_view_change', 'map_object_click', 'map_change', 'tree_selection_change'));

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-11-05 against **APEX 26.2** (sprint 160: the Workflow Diagram region, an instance's steps with the reached, current and failed ones marked (CD-7); sprint 159: map layers Lines, Polygons and Extruded Polygons with fill and line styles per layer or per row (CD-6); sprint 158: the item types Image Upload, Text Field with autocomplete, Percent Graph and Display Map (CD-5); sprint 157: the process types Close Dialog, Clear Session State, Reset Pagination, User Preferences, Server Side Geocoding, Print Report, Human Task – Create / – Manage and Form – Initialization (CD-4); sprint 156: dynamic action events double click, key down / press, mouse enter / leave, select, resize, scroll, page unload, before refresh and facets change, greater / less and not-in-list conditions, and the actions Cancel Event, Set Style, Collapse / Expand Tree, Show AI Assistant, Trigger Geocoding and Open report dialog (CD-3); sprint 155: APEX's validation types, with an authorization scheme, Always execute and the error's display location (CD-1); sprint 154: one catalogue of server-side condition types for every component, shown in words in the Page Designer (CD-2); sprint 153: Database users in the eleven builder languages (WS-7 leftover); sprint 152: Workspace utilities, the dashboard, Mail queue, Network access, Instance settings and LDAP directories in the eleven builder languages (WS-7 leftover); sprint 151: vector providers with a model in the database, PostgresML (APEX's ONNX models, AP-1 leftover); sprint 150: remote databases, another PostgreSQL database's tables as foreign tables the applications query (REST Enabled SQL, AP-7 leftover); sprint 149: running workflow instances inside parallel branches migrate to a newer version (WS-6 leftover); sprint 148: the AI assistant streams its answers as the model writes them (WS-4 leftover); sprint 147: `pgkiln advise --offline` checks an export's files without a database (AP-10 leftover); sprint 146: the Advisor checks JSON sources' views against their data profile (AP-8 leftover); sprint 145: the texts that offered AI with "Claude or OpenAI" name all four providers: Claude, OpenAI, Gemini and OpenAI-compatible services (AP-11); sprint 144: `pgkiln advise` for CI with text, JSON and SARIF output (APEXlang static analysis / SQLcl CodeScan), security checks in the Advisor, and working copies and locks from the command line and MCP (the Working Copy APIs) (AP-10); sprint 143: the interactive report's 26.2 dialogs: *is one of* / *is not one of* filters with the column's values and counts, *is between* two values (dates with the date picker in the application's format), relative periods on date columns, and the column order by drag and drop or arrow buttons, followed by downloads and the PDF (AP-9); sprint 142: JSON sources with a data profile and updatable views whose arrays are rows, document views of a table with its children (APEX's duality views), JSON path columns in reports (AP-8); sprint 141: static workspace files (`#WORKSPACE_FILES#`), remote servers for REST data sources, catalogs and AI services (an environment variable per environment), and workspace-level web credentials (AP-7); sprint 140: the items Shuttle (ordered), Select One and Select Many, the regions Classic Report (report templates, pagination types), Breadcrumb and Help Text with a page help text, and a [mapping of every APEX item and region type](#item-and-region-types-one-by-one) (AP-4); sprint 139: OpenTelemetry, traces with a span per SQL statement, web call, AI request and tool call, logs, metrics and `/metrics` for Prometheus, browser spans relayed by pgkiln, per workspace off or its own collector (AP-6); sprint 138: an application's Utilities tab with a dashboard, database object dependencies, change history per component, Upgrade application, UI defaults (APEX's Attribute Dictionary), application and page checksums and an icon browser (AP-5); sprint 137: Create page as a grid of page types with previews, the page types interactive report, smart filters, search page, data loading, tree, timeline, media list, content row, comments, dashboard, wizard, unified task list and workflow console, a Feature tab with nine features that install once, and Create page as copy with shared components mapped or copied (AP-3); sprint 136: vector providers (an AI service with an embedding model or a SQL function), `meta.embed`, *Add vector column* in Table Properties with an HNSW index and a queue that keeps embeddings current, search types vector and hybrid (reciprocal rank fusion with full-text) and a Retrieve (RAG) tool for AI agents, all as the app's role through RLS, on pgvector (AP-1); sprint 135: full-text search configurations, APEX's Oracle Text search type on PostgreSQL full-text search with stemming, ranking, highlights, *Did you mean* and *Add full-text search* in Table Properties (AP-2); sprint 134: the builder also in Italiano, 中文 (简体), 中文 (繁體), 日本語 and 한국어, APEX's ten builder languages plus Nederlands (SEC-5); sprints 121, 123–125: the builder in Deutsch, English, Español, Français, Nederlands and Português, step by step: the frame, sign-in, Workspace home, App Builder, Page Designer menus, the SQL Workshop's home, SQL Worksheet, Object Browser and Table Properties, Shared Components, application settings, users, identity providers, developers and workspaces (WS-7); sprint 122: *Ask in your own words* sets faceted search and smart filter facets, smart filters read a typed phrase (WS-5), and Sample Maps, Sample Approvals, Sample Data Loading and Sample Files in the App Gallery (WS-8); sprint 120: the App Gallery's single-topic sample apps (charts, cards, calendar, interactive grids, dynamic actions, reporting), the UX Pattern Catalog and a Utility Apps tab with Lookup Lists, Release Notes and Announcements (WS-8); sprint 119: data security per table, a roles × columns matrix and masked values per application role in a masking view, the same identity for pages, AI tools, REST, AutoREST and MCP (WS-13); sprint 118: Administration → Mail queue with delivery per hour and per workspace, the slowest provider calls and failures with Retry and Purge, a workspace's own mail service, and workspace network access lists that narrow the installation's allow-list (WS-9); sprint 117: Pillar Light and Pillar Dark navigation appearances with a header strip, clearer navigation tree states, subtle colour utilities, RTL; sprint 116: the comparison moved from 26.1 to 26.2, with a section for the 26.2 workspace items WS-1 … WS-13 and OCI managed identities; the App Builder list with Updated by, working copies and the lock; `pgkiln import --only`, a file-level import; stale rows on facet menus and blueprints fixed; sprint 115: popup LOVs that load on scroll, Wait Popup dynamic actions and dynamic actions on menu entries; sprint 114: Workflow 26.2 with custom task outcomes, task events and notifications, Send E-Mail and draft steps, migrating running instances and the diagram as SVG / PNG; sprint 113: Team Development with issues, labels, milestones, templates, a board and a set-up wizard; sprint 112: AI interactive reports with chips, Undo, computed columns and a phrase parser that needs no AI service; sprint 111: AI Agents with tools as a shared component, a Navigate tool with checksummed URLs, Gemini and OpenAI-compatible services; sprint 110: Data Reporter as a workspace tool with datasets, reporting applications, editors and viewers, published reports with stable URLs and pins; sprint 109: the Workspace home above the App Builder and SQL Workshop, with a summary, top applications, users and developers, and an optional release check; sprint 108: the code editor's syntax colours in the builder's light and dark themes, read-only SQL highlighted, the Data Modeler in dark mode; sprint 107: a transaction mode in the SQL Worksheet with Commit and Rollback; DA-18: JavaScript (MLE) not planned, plv8 where installed; sprint 106: the change log of DDL change sets with Flyway, Liquibase and SQL downloads; sprint 104: RESTful Services modules, templates and handlers with PL/pgSQL and media handlers, privileges, OpenAPI and Try it; sprint 103: Schema Export / Import with pg_dump and pg_restore; sprint 102: the SQL Monitor with live sessions, Top SQL and a statement's plan; sprint 101: Scheduling of pg_cron jobs with a schedule builder, run now and run history; sprint 100: RESTful Services, tables and views published as REST endpoints with paging, filters, keys and OpenAPI; sprint 99: Administration → Database Users for PostgreSQL roles; sprint 98: the Data Modeler with relational diagrams, DDL and a data dictionary; sprint 97: charts of a query in the worksheet, saved charts and their dashboard; sprint 96: the SQL Workshop's Launchpad with pins and tool groups, the builder's search with Ctrl+K; sprint 95: Table Properties: create, edit or copy a table in a form with a DDL preview and Apply in one transaction; sprint 94: an object's menu with Open in a panel, Quick DDL, Add index / trigger / policy and Drop with dependents; sprint 93: worksheets saved as SQL Scripts with tabs and a Files list, Format, Convert case, find and replace, bind and substitution variables; sprint 92: the worksheet's Query Result with sort, value dialog, copy and downloads, plans as a tree with the slowest step and misestimates, SQL History with status, search and run again; sprint 91: the SQL Worksheet like Database Actions' SQL: navigator, Run Statement at the cursor and Run Script with a log per statement, Explain Plan, Autotrace, notices, history, Run as an application role; sprint 90: Comment Out in the page designer, gallery labels in title case; sprint 89: the Object Browser's schema, one row of tabs, blank NULLs, Modify column; sprint 88: home cards with colour bands and round icons, the hero on the page background, a page footer with the version and Back to top; sprint 87: the Create Application wizard reloads the page list for a schema, RLS badges, the alias from the name; sprint 86: the page designer by page number, HTML error pages in the builder; sprint 85: the Form Designer, beyond APEX; sprint 84: the date picker, facet menus; sprint 83: Component Settings and Component Groups; sprint 82: Report Queries; sprint 81: Application Computations and Shortcuts in Shared Components; sprint 80: the master grid's first row selected when the page opens and after a search; grid cells as text with their format mask until edited, with cell navigation by arrow keys, Enter, F2 and Escape; sprint 79: generated dashboards with sums, donuts and lines, leaving out charts that say nothing; applications open in their own light or dark mode until the user chooses, per application; a user menu with Appearance and Sign in when signed out; the developer toolbar's App and Page texts and debug state; the report search's column scope in the magnifier; sprint 78: generated faceted search reports with one column per foreign key, the faceted search's total row count, Show all and Yes/No values, one search field, friendly headings and number formats in generated grids and master-detail pages, friendly names in the Create Application wizard's page list; 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).
+Last reviewed: 2026-11-06 against **APEX 26.2** (sprint 162: the SQL Workshop tools and the region and report settings in the eleven builder languages (CD-8); sprint 161: component events of grids, calendars, maps and trees (CD-3); sprint 160: the Workflow Diagram region, an instance's steps with the reached, current and failed ones marked (CD-7); sprint 159: map layers Lines, Polygons and Extruded Polygons with fill and line styles per layer or per row (CD-6); sprint 158: the item types Image Upload, Text Field with autocomplete, Percent Graph and Display Map (CD-5); sprint 157: the process types Close Dialog, Clear Session State, Reset Pagination, User Preferences, Server Side Geocoding, Print Report, Human Task – Create / – Manage and Form – Initialization (CD-4); sprint 156: dynamic action events double click, key down / press, mouse enter / leave, select, resize, scroll, page unload, before refresh and facets change, greater / less and not-in-list conditions, and the actions Cancel Event, Set Style, Collapse / Expand Tree, Show AI Assistant, Trigger Geocoding and Open report dialog (CD-3); sprint 155: APEX's validation types, with an authorization scheme, Always execute and the error's display location (CD-1); sprint 154: one catalogue of server-side condition types for every component, shown in words in the Page Designer (CD-2); sprint 153: Database users in the eleven builder languages (WS-7 leftover); sprint 152: Workspace utilities, the dashboard, Mail queue, Network access, Instance settings and LDAP directories in the eleven builder languages (WS-7 leftover); sprint 151: vector providers with a model in the database, PostgresML (APEX's ONNX models, AP-1 leftover); sprint 150: remote databases, another PostgreSQL database's tables as foreign tables the applications query (REST Enabled SQL, AP-7 leftover); sprint 149: running workflow instances inside parallel branches migrate to a newer version (WS-6 leftover); sprint 148: the AI assistant streams its answers as the model writes them (WS-4 leftover); sprint 147: `pgkiln advise --offline` checks an export's files without a database (AP-10 leftover); sprint 146: the Advisor checks JSON sources' views against their data profile (AP-8 leftover); sprint 145: the texts that offered AI with "Claude or OpenAI" name all four providers: Claude, OpenAI, Gemini and OpenAI-compatible services (AP-11); sprint 144: `pgkiln advise` for CI with text, JSON and SARIF output (APEXlang static analysis / SQLcl CodeScan), security checks in the Advisor, and working copies and locks from the command line and MCP (the Working Copy APIs) (AP-10); sprint 143: the interactive report's 26.2 dialogs: *is one of* / *is not one of* filters with the column's values and counts, *is between* two values (dates with the date picker in the application's format), relative periods on date columns, and the column order by drag and drop or arrow buttons, followed by downloads and the PDF (AP-9); sprint 142: JSON sources with a data profile and updatable views whose arrays are rows, document views of a table with its children (APEX's duality views), JSON path columns in reports (AP-8); sprint 141: static workspace files (`#WORKSPACE_FILES#`), remote servers for REST data sources, catalogs and AI services (an environment variable per environment), and workspace-level web credentials (AP-7); sprint 140: the items Shuttle (ordered), Select One and Select Many, the regions Classic Report (report templates, pagination types), Breadcrumb and Help Text with a page help text, and a [mapping of every APEX item and region type](#item-and-region-types-one-by-one) (AP-4); sprint 139: OpenTelemetry, traces with a span per SQL statement, web call, AI request and tool call, logs, metrics and `/metrics` for Prometheus, browser spans relayed by pgkiln, per workspace off or its own collector (AP-6); sprint 138: an application's Utilities tab with a dashboard, database object dependencies, change history per component, Upgrade application, UI defaults (APEX's Attribute Dictionary), application and page checksums and an icon browser (AP-5); sprint 137: Create page as a grid of page types with previews, the page types interactive report, smart filters, search page, data loading, tree, timeline, media list, content row, comments, dashboard, wizard, unified task list and workflow console, a Feature tab with nine features that install once, and Create page as copy with shared components mapped or copied (AP-3); sprint 136: vector providers (an AI service with an embedding model or a SQL function), `meta.embed`, *Add vector column* in Table Properties with an HNSW index and a queue that keeps embeddings current, search types vector and hybrid (reciprocal rank fusion with full-text) and a Retrieve (RAG) tool for AI agents, all as the app's role through RLS, on pgvector (AP-1); sprint 135: full-text search configurations, APEX's Oracle Text search type on PostgreSQL full-text search with stemming, ranking, highlights, *Did you mean* and *Add full-text search* in Table Properties (AP-2); sprint 134: the builder also in Italiano, 中文 (简体), 中文 (繁體), 日本語 and 한국어, APEX's ten builder languages plus Nederlands (SEC-5); sprints 121, 123–125: the builder in Deutsch, English, Español, Français, Nederlands and Português, step by step: the frame, sign-in, Workspace home, App Builder, Page Designer menus, the SQL Workshop's home, SQL Worksheet, Object Browser and Table Properties, Shared Components, application settings, users, identity providers, developers and workspaces (WS-7); sprint 122: *Ask in your own words* sets faceted search and smart filter facets, smart filters read a typed phrase (WS-5), and Sample Maps, Sample Approvals, Sample Data Loading and Sample Files in the App Gallery (WS-8); sprint 120: the App Gallery's single-topic sample apps (charts, cards, calendar, interactive grids, dynamic actions, reporting), the UX Pattern Catalog and a Utility Apps tab with Lookup Lists, Release Notes and Announcements (WS-8); sprint 119: data security per table, a roles × columns matrix and masked values per application role in a masking view, the same identity for pages, AI tools, REST, AutoREST and MCP (WS-13); sprint 118: Administration → Mail queue with delivery per hour and per workspace, the slowest provider calls and failures with Retry and Purge, a workspace's own mail service, and workspace network access lists that narrow the installation's allow-list (WS-9); sprint 117: Pillar Light and Pillar Dark navigation appearances with a header strip, clearer navigation tree states, subtle colour utilities, RTL; sprint 116: the comparison moved from 26.1 to 26.2, with a section for the 26.2 workspace items WS-1 … WS-13 and OCI managed identities; the App Builder list with Updated by, working copies and the lock; `pgkiln import --only`, a file-level import; stale rows on facet menus and blueprints fixed; sprint 115: popup LOVs that load on scroll, Wait Popup dynamic actions and dynamic actions on menu entries; sprint 114: Workflow 26.2 with custom task outcomes, task events and notifications, Send E-Mail and draft steps, migrating running instances and the diagram as SVG / PNG; sprint 113: Team Development with issues, labels, milestones, templates, a board and a set-up wizard; sprint 112: AI interactive reports with chips, Undo, computed columns and a phrase parser that needs no AI service; sprint 111: AI Agents with tools as a shared component, a Navigate tool with checksummed URLs, Gemini and OpenAI-compatible services; sprint 110: Data Reporter as a workspace tool with datasets, reporting applications, editors and viewers, published reports with stable URLs and pins; sprint 109: the Workspace home above the App Builder and SQL Workshop, with a summary, top applications, users and developers, and an optional release check; sprint 108: the code editor's syntax colours in the builder's light and dark themes, read-only SQL highlighted, the Data Modeler in dark mode; sprint 107: a transaction mode in the SQL Worksheet with Commit and Rollback; DA-18: JavaScript (MLE) not planned, plv8 where installed; sprint 106: the change log of DDL change sets with Flyway, Liquibase and SQL downloads; sprint 104: RESTful Services modules, templates and handlers with PL/pgSQL and media handlers, privileges, OpenAPI and Try it; sprint 103: Schema Export / Import with pg_dump and pg_restore; sprint 102: the SQL Monitor with live sessions, Top SQL and a statement's plan; sprint 101: Scheduling of pg_cron jobs with a schedule builder, run now and run history; sprint 100: RESTful Services, tables and views published as REST endpoints with paging, filters, keys and OpenAPI; sprint 99: Administration → Database Users for PostgreSQL roles; sprint 98: the Data Modeler with relational diagrams, DDL and a data dictionary; sprint 97: charts of a query in the worksheet, saved charts and their dashboard; sprint 96: the SQL Workshop's Launchpad with pins and tool groups, the builder's search with Ctrl+K; sprint 95: Table Properties: create, edit or copy a table in a form with a DDL preview and Apply in one transaction; sprint 94: an object's menu with Open in a panel, Quick DDL, Add index / trigger / policy and Drop with dependents; sprint 93: worksheets saved as SQL Scripts with tabs and a Files list, Format, Convert case, find and replace, bind and substitution variables; sprint 92: the worksheet's Query Result with sort, value dialog, copy and downloads, plans as a tree with the slowest step and misestimates, SQL History with status, search and run again; sprint 91: the SQL Worksheet like Database Actions' SQL: navigator, Run Statement at the cursor and Run Script with a log per statement, Explain Plan, Autotrace, notices, history, Run as an application role; sprint 90: Comment Out in the page designer, gallery labels in title case; sprint 89: the Object Browser's schema, one row of tabs, blank NULLs, Modify column; sprint 88: home cards with colour bands and round icons, the hero on the page background, a page footer with the version and Back to top; sprint 87: the Create Application wizard reloads the page list for a schema, RLS badges, the alias from the name; sprint 86: the page designer by page number, HTML error pages in the builder; sprint 85: the Form Designer, beyond APEX; sprint 84: the date picker, facet menus; sprint 83: Component Settings and Component Groups; sprint 82: Report Queries; sprint 81: Application Computations and Shortcuts in Shared Components; sprint 80: the master grid's first row selected when the page opens and after a search; grid cells as text with their format mask until edited, with cell navigation by arrow keys, Enter, F2 and Escape; sprint 79: generated dashboards with sums, donuts and lines, leaving out charts that say nothing; applications open in their own light or dark mode until the user chooses, per application; a user menu with Appearance and Sign in when signed out; the developer toolbar's App and Page texts and debug state; the report search's column scope in the magnifier; sprint 78: generated faceted search reports with one column per foreign key, the faceted search's total row count, Show all and Yes/No values, one search field, friendly headings and number formats in generated grids and master-detail pages, friendly names in the Create Application wizard's page list; 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
 
@@ -200,7 +200,7 @@ review is a diff. Not counted in [At a glance](#at-a-glance): the rows above com
 | Computations | ✅ | Static, item, SQL query, SQL expression and PL/pgSQL function body; before header and after submit; with a condition, authorization and build option ([chapter 6](guide/06-processing.md#computations)); **application computations** (sprint 81) for every page: after authentication, before header, after submit ([chapter 6](guide/06-processing.md#application-computations)) |
 | Page processes | ✅ | SQL / PL/pgSQL, form DML, grid DML, data loading (`data_load`), **invoke API** (a REST data source or URL, response values into items), **download** (a file from a query; several rows become one zip; on submit or on load), **execution chains** (child processes with their own conditions, nested, optionally run in the background with a status view), **workflow** (start, terminate, retry), **Generate text with AI** (text or structured output into items); (sprint 157) **Close Dialog** with items to return, **Clear Session State**, **Reset Pagination**, **User Preferences**, **Server Side Geocoding**, **Print Report**, **Human Task – Create / – Manage**, **Form – Initialization** ([chapter 6](guide/06-processing.md#declarative-process-types)) |
 | Branches | ✅ | Before header and after processing, to a page (with items) or a URL inside the app, *When button pressed*, server-side conditions (the shared catalogue, sprint 154); the button's target page stays the fallback ([chapter 6](guide/06-processing.md#branches)); a PL/pgSQL function returning a path in the app, and a page of another application (with signed items) |
-| Dynamic actions | ✅ | Show, hide, enable, disable, set value (SQL), execute SQL, refresh region or item, alert, submit, set focus, add/remove class, show success/error message and clear errors (26.1); the **Dialog Closed** event (per dialog page, with the dialog's message). **Execute JavaScript**: calls a function a static application file registered with `pgkiln.actions.register` (no inline code: the CSP stays strict) ([chapter 7](guide/07-dynamic-actions.md#execute-javascript)); dynamic action plug-ins ; (sprint 156) events double click, key down / press, mouse enter / leave, select, resize, scroll, page unload, before refresh, facets change; conditions greater / less (or equal), not in list; Cancel Event, Set Style, Collapse / Expand Tree, Show AI Assistant, Trigger Geocoding, Open report dialog. Not yet: grid, calendar, map and tree component events |
+| Dynamic actions | ✅ | Show, hide, enable, disable, set value (SQL), execute SQL, refresh region or item, alert, submit, set focus, add/remove class, show success/error message and clear errors (26.1); the **Dialog Closed** event (per dialog page, with the dialog's message). **Execute JavaScript**: calls a function a static application file registered with `pgkiln.actions.register` (no inline code: the CSP stays strict) ([chapter 7](guide/07-dynamic-actions.md#execute-javascript)); dynamic action plug-ins ; (sprint 156) events double click, key down / press, mouse enter / leave, select, resize, scroll, page unload, before refresh, facets change; conditions greater / less (or equal), not in list; Cancel Event, Set Style, Collapse / Expand Tree, Show AI Assistant, Trigger Geocoding, Open report dialog; component events (sprint 161) Row Initialization and Save of a grid, Date Select and View Change of a calendar, Map Object Clicked and Map Changed, Selection Change of a tree, each with its value for the condition and a Set Value without SQL |
 | Dynamic action events | ✅ | Change, click, page load, Dialog Closed and (sprint 52) Get/Lose Focus, Key Release, After Refresh (a refreshed, lazy or master-detail region), Selection Change (report row selection, a grid's master row), Before Page Submit and custom events (`pgkiln.trigger(name, value)`); the actions of one event run in sequence order ([chapter 7](guide/07-dynamic-actions.md#events)) |
 | Dynamic action actions: confirm, close/cancel dialog, clear, open/close region, download, print, current position, share | ✅ | (sprint 52) Confirm (No stops the actions after it, and a submit), Close and Cancel Dialog, Clear, Open/Close Region, Download (a download process of the page), Print, Get Current Position, Share (the share sheet, or the link copied) ([chapter 7](guide/07-dynamic-actions.md#actions)) |
 | Ajax callbacks (On Demand processes, `apex.server.process`) | ✅ | (sprint 52) Page and application processes with point *ajax*, called with `pgkiln.server.process(name, {items, x01 … x10})`: SQL as the app's role with its authorization and condition, JSON rows back, items it sets set on the page ([chapter 7](guide/07-dynamic-actions.md#ajax-callbacks)) |
@@ -335,7 +335,7 @@ row above where there is one.
 | WS-4 AI Agents with tools | ✅ | (sprint 111) AI Agents and AI Tools as shared components, a Navigate tool, Gemini and OpenAI-compatible services ([Workflow, automation and AI](#workflow-automation-and-ai)) |
 | WS-5 AI interactive reports: chips, computed columns | ✅ | (sprint 112) *Ask in your own words* with chips, Undo and computed columns; a phrase parser that needs no AI service; (sprint 122) phrases set faceted search and smart filter facets |
 | WS-6 Workflow 26.2: outcomes, migrating running instances, drafts, diagram export | ✅ | (sprint 114) Custom task outcomes, task events, Send E-Mail and draft steps, migrating running instances, the diagram as SVG / PNG ([Workflow, automation and AI](#workflow-automation-and-ai)) |
-| WS-7 The builder in more languages | ✅ | (sprint 121) The builder in Deutsch, English, Español, Français, Nederlands and Português, and (sprint 134, SEC-5) Italiano, 中文 (简体), 中文 (繁體), 日本語 and 한국어 with CJK font stacks: links on the sign-in page, a language menu in the status bar, the choice stored per developer (migration 127); builder texts are keyed message files with a coverage check in CI, also for the builder's own JavaScript (sprint 123). Translated (sprints 121, 123–125): the builder's frame, sign-in page, Workspace home, App Builder home, an application's home and tabs, the Page Designer's toolbar, menus, tree and gallery, the SQL Workshop's home and tabs, the SQL Worksheet, Object Browser and Table Properties, Shared Components, an application's settings, Users, identity providers, Developers and Workspaces ([chapter 3](guide/03-builder.md#choosing-the-builder-language)). (sprint 152) Workspace utilities, the dashboard, Mail queue, Network access, Instance settings and LDAP directories; (sprint 153) Database users. Still English: the other SQL Workshop tools and the region and report settings, until they move over; by design the property editor's and component forms' field names and help |
+| WS-7 The builder in more languages | ✅ | (sprint 121) The builder in Deutsch, English, Español, Français, Nederlands and Português, and (sprint 134, SEC-5) Italiano, 中文 (简体), 中文 (繁體), 日本語 and 한국어 with CJK font stacks: links on the sign-in page, a language menu in the status bar, the choice stored per developer (migration 127); builder texts are keyed message files with a coverage check in CI, also for the builder's own JavaScript (sprint 123). Translated (sprints 121, 123–125): the builder's frame, sign-in page, Workspace home, App Builder home, an application's home and tabs, the Page Designer's toolbar, menus, tree and gallery, the SQL Workshop's home and tabs, the SQL Worksheet, Object Browser and Table Properties, Shared Components, an application's settings, Users, identity providers, Developers and Workspaces ([chapter 3](guide/03-builder.md#choosing-the-builder-language)). (sprint 152) Workspace utilities, the dashboard, Mail queue, Network access, Instance settings and LDAP directories; (sprint 153) Database users; (sprint 162, CD-8) every SQL Workshop tool (SQL Monitor, Top SQL, Quick SQL, SQL Scripts, Generate DDL, Schema Comparison, Change Log, Charts, Load / Unload Data, Sample Data, Query Builder, Data Modeler, Utilities, Object Reports, AI, Schema Export / Import, Scheduling with schedules in words, RESTful Services, data security, document views) and the region and report settings. Still English: some App Builder screens (Team Development, mail, datasets, JSON sources, blueprints and a few more) until they move over; messages of checks shared with the command line; by design the property editor's and component forms' field names and help |
 | WS-8 App Gallery: more sample apps, Utility Apps | ✅ | (sprint 120) Four tabs with counts and a search that also works without JavaScript ([chapter 3](guide/03-builder.md#app-gallery)). *Sample Apps*: HR Demo, Tasks, ten single-topic apps (Sample Charts, Sample Cards, Sample Calendar, Sample Interactive Grids, Sample Dynamic Actions, Sample Reporting; sprint 122: Sample Maps, Sample Approvals, Sample Data Loading, Sample Files) and the **UX Pattern Catalog**, each with its own schema, data, demo account and explanatory texts, installed by administrators from one SQL file in one transaction; *Utility Apps*: Lookup Lists, Release Notes and Announcements as blueprints any developer installs into the workspace. APEX's 27 sample apps include topics pgkiln shows in HR Demo instead (REST, trees, collections); no remote catalogue |
 | WS-9 Mail queue reporting, workspace SMTP, workspace network ACLs | ✅ | (sprint 118) Administration → Mail queue (per hour and per workspace / application, the slowest provider calls, failures with the provider's answer, Retry and Purge), a workspace's own mail service, and a workspace's network access list that narrows the installation's allow-list for every outgoing call ([Administration](#administration)) |
 | WS-10 Universal Theme 26.2: Pillar appearances, navigation polish | ✅ | (sprint 117) Theme Roller → Navigation appearance Pillar Light / Pillar Dark per application or style, with a header strip colour for light and dark mode; the current page filled, its parents bold with an accent guide line; `u-color-*-subtle` utilities; a lighter processing indicator; RTL mirrored |

package/docs/guide/03-builder.md

@@ -523,7 +523,14 @@ editor frame, access control, breadcrumbs, component settings) and an applicatio
 the administration screens: **Users** (accounts and identity providers), **Developers** and **Workspaces** (with
 utilization), and (sprint 152) **Workspace utilities**, the workspace **Dashboard**, **Mail queue**, **Network
 access**, **Instance settings** (its frame: each setting's own label and help, and the lockout checks' details, stay
-English) and **LDAP directories**, and (sprint 153) **Database users**. Other builder pages are still in English (they move over screen by screen); so are the
+English) and **LDAP directories**, and (sprint 153) **Database users**, and (sprint 162) every **SQL Workshop tool**:
+SQL Monitor, Top SQL, Quick SQL, SQL Scripts, Generate DDL, Schema Comparison, Change Log, Charts, Load and Unload
+Data, Sample Data, Query Builder, Data Modeler, Utilities, Object Reports, the SQL Workshop's AI, Schema Export /
+Import, Scheduling (schedules are described in your language), RESTful Services (modules and AutoREST) and the
+Object Browser's data security and document view, and the Page Designer's **region and report settings** (cards,
+charts, maps, calendars, facets, trees and the other region types, a report's columns). Messages that come from
+the database or from checks shared with the command line (a policy check, a REST handler's validation) stay
+English. Other builder pages are still in English (they move over screen by screen); so are the
 Page Designer's property names and their help (and, the same way, the field names and help of a shared component's
 form), the links to this guide, and any SQL the builder generates.
 

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

@@ -1068,7 +1068,8 @@ excludable job facet, salary ranges with from/to, a hire date range and a star r
 
 **Source**: a SELECT with one row per place. The position comes from `lat` and `lng` (or
 `latitude`/`longitude`), or from a `location` column holding `latitude,longitude` text (what a
-[`location` item](05-items.md) stores). Optional columns: `title` and `body` (the popup), and
+[`location` item](05-items.md) stores). Optional columns: `title` and `body` (the popup), `id` (what a
+[`map_object_click`](07-dynamic-actions.md#component-events) dynamic action sees), and
 `geojson` (a GeoJSON geometry or feature, e.g. PostGIS `st_asgeojson(geom)`) to draw lines and areas;
 a GeoJSON point is a place like a row with `lat`/`lng`. With [PostGIS](#postgis) installed, a
 `geometry` or `geography` column (in WGS 84, SRID 4326) is enough: the server turns it into GeoJSON.

package/docs/guide/07-dynamic-actions.md

@@ -47,6 +47,13 @@ your own from a static application file.
 | `page_unload` | The page is left (APEX: Page Unload); only quick actions in the browser finish | – |
 | `before_refresh` | A region is about to be refreshed by a `refresh_region` action (APEX: Before Refresh); a `cancel_event` or declined `confirm` keeps it as it is | Region ids or static ids |
 | `facets_change` | A faceted search or smart filters region's facets were applied (APEX: Facets Change); runs on the page that comes back with the new filters | The facets region's id or static id |
+| `grid_row_init` | A row was added to an editable grid by Add row or Duplicate (APEX: Row Initialization [Interactive Grid]); the condition sees the row's number among the new rows | The grid's id or static id |
+| `grid_save` | A grid's changes were saved (APEX: Save [Interactive Grid]); runs on the page that comes back | The grid's id or static id |
+| `calendar_date_select` | An empty day or hour of a calendar was clicked (APEX: Date Select); the condition sees `YYYY-MM-DD` or `YYYY-MM-DDTHH:MM`; a `cancel_event` keeps the Create link closed | The calendar's id or static id |
+| `calendar_view_change` | A calendar showed another view or period (APEX: View Change); the condition sees `month`, `week`, `day` or `list` | The calendar's id or static id |
+| `map_object_click` | A marker or shape of a map was clicked (APEX: Map Object Clicked); the condition sees the row's `id` column, else its title | The map's id or static id |
+| `map_change` | A map was moved or zoomed by the user (APEX: Map Changed); the condition sees the zoom level | The map's id or static id |
+| `tree_selection_change` | A tree node was clicked (APEX: Selection Change [Tree]); the condition sees its `id`, the node is marked; a `cancel_event` keeps its link closed | The tree's id or static id |
 
 **The actions of one event and trigger run one after the other, in sequence order** (APEX: the true
 actions of a dynamic action), each waiting for the one before (a server action for its answer). A
@@ -58,6 +65,25 @@ actions of a dynamic action), each waiting for the one before (a server action f
 | 20 | `click` on `DELETE_ALL` | `execute_sql` | `delete from sales.order_line where id = any(string_to_array(:P5_SELECTED, ':')::int[])` |
 | 30 | `click` on `DELETE_ALL` | `refresh_region` | the order lines |
 
+### Component events
+
+The last seven events above belong to a component region (sprint 161): the trigger is that region's
+id or static id. Their value (the date, view, node id, map object id or zoom level) is what the
+client-side condition compares, and an [Execute JavaScript](#execute-javascript) function gets it as
+`value`, with the component's element (the grid row, calendar cell, map or tree node) as `element`.
+Two of them can be cancelled: a `cancel_event` whose condition holds keeps the calendar's Create
+link or the tree node's link closed, wherever it stands in the sequence; like every `cancel_event`
+it also stops the actions after it, so put it last.
+
+A **`set_value` without SQL** on a component event puts the event's value into its affected
+items, in the browser. A tree of departments that filters an employee report, without JavaScript:
+
+| Sequence | Event | Action | Affected / items to submit |
+|---|---|---|---|
+| 10 | `tree_selection_change` on the departments tree | `set_value` (no SQL) | `P5_DEPTNO` |
+| 20 | `tree_selection_change` on the departments tree | `refresh_region` | the employees report; items to submit `P5_DEPTNO` |
+| 30 | `tree_selection_change` on the departments tree | `cancel_event` | – (last, as it stops the actions after it; the node's link stays closed) |
+
 ## Actions
 
 | Action | Runs in | Effect |
@@ -185,6 +211,7 @@ The function gets one argument with the action's context:
 | `elements` | The affected items' fields and the affected region, as DOM elements |
 | `region` | The affected region's element, or `null` |
 | `message` | The action's message |
+| `element` | A [component event](#component-events)'s element (grid row, calendar cell, map, tree node), else `null` |
 
 It may return a promise; an exception is shown as an error message. Besides `actions.register`,
 `window.pgkiln` offers `getValue(item)`, `setValue(item, value)`, `showSuccess(message)`,

package/docs/guide/11-from-apex.md

@@ -39,7 +39,8 @@ What's missing is listed in the [feature parity matrix](../apex-feature-parity.m
 | Page computations (static, item, SQL query, SQL expression, PL/SQL function body) | Computations `before_header` / `after_submit`; function bodies are PL/pgSQL ([chapter 6](06-processing.md#computations)) |
 | Branches (page or URL, *When button pressed*, server-side condition), before header and after processing | Branches with `when_button` and a condition; URLs stay inside the application ([chapter 6](06-processing.md#branches)) |
 | Validation types (Rows returned, Expression, Function Body returning Boolean / Error Text, Item is NOT NULL / numeric / a valid date …, Item = Value, Item in Value, character checks, Regular Expression), Always Execute, Display Location | The same types as `type` (`exists`, `sql`, `function_body`, `function_error`, `not_null`, `numeric`, `valid_date`, `equals`, `in_list`, `chars_only`, `regex` …), `always_execute`, `display_location` ([chapter 6](06-processing.md#validations)). Interactive grid column validations aren't there yet: use a validation on the grid's process or a check constraint |
-| Dynamic action events (Double Click, Key Down / Press, Mouse Enter / Leave, Select, Resize, Scroll, Page Unload, Before Refresh, Facets Change), conditions (greater / less than, not in list) and actions (Cancel Event, Set Style, Collapse / Expand Tree, Show AI Assistant, Trigger Geocoding, Invoke Interactive Report Dialog) | The same events, conditions and actions ([chapter 7](07-dynamic-actions.md)). Not yet: grid, calendar, map and tree component events; JavaScript expression conditions (use a registered function) |
+| Dynamic action events (Double Click, Key Down / Press, Mouse Enter / Leave, Select, Resize, Scroll, Page Unload, Before Refresh, Facets Change), conditions (greater / less than, not in list) and actions (Cancel Event, Set Style, Collapse / Expand Tree, Show AI Assistant, Trigger Geocoding, Invoke Interactive Report Dialog) | The same events, conditions and actions ([chapter 7](07-dynamic-actions.md)). JavaScript expression conditions: use a registered function |
+| Component events: Row Initialization and Save [Interactive Grid], Date Select and View Change [Calendar], Map Object Clicked and Map Changed, Selection Change [Tree] | `grid_row_init`, `grid_save`, `calendar_date_select`, `calendar_view_change`, `map_object_click`, `map_change`, `tree_selection_change`, triggered by the region ([chapter 7](07-dynamic-actions.md#component-events)) |
 | Workflow Diagram region | `workflow_diagram` with `{"instance_item": …}` ([chapter 6](06-processing.md#workflow-diagram-region)) |
 | Map layers Points, Lines, Polygons, Heat Map, Extruded Polygons | `"layer"`: `markers`, `lines`, `polygons`, `heat`, `extruded` (drawn flat, shaded by height), with fill and line colours, width and opacity per layer or per row ([chapter 4](04-pages-and-regions.md#map)) |
 | Items Image Upload, Text Field with autocomplete, Percent Graph, Display Map | `image_upload`, `autocomplete`, `percent_graph`, `display_map` ([chapter 5](05-items.md#item-types)) |

package/docs/guide/12-development.md

@@ -338,7 +338,8 @@ src/
     components.ts          property spec of every component (drives the property editor)
     ui.ts                  IDE shell (icon rail, toolbar, breadcrumb, status bar), builder theme, form helpers, CSRF check, app tabs
     i18n.ts                (sprint 121) the builder's own texts: BUILDER_LANGUAGES, tr(s) / translatorFor(lang) → tx(key, params),
-                           tx.rich (markup in a sentence), tx.dyn (keys made at run time), tx.label (known breadcrumb labels)
+                           tx.rich (markup in a sentence), tx.dyn (keys made at run time), tx.label (known breadcrumb labels),
+                           (sprint 162) tx.code (`backticks` become <code>), withTranslator / scopedTx (a request-scoped translator)
     i18n/                  en.ts defines the builder's keys; de, es, fr, it, nl, pt, zh-cn, zh-tw, ja, ko (sprint 134) are Records of the same keys
     language.ts            (migration 127) the status bar's language menu (POST /builder/language), the sign-in page's
                            language links (?lang=, a cookie), meta.developer.language
@@ -704,8 +705,15 @@ const tx = tr(s);                                  // the developer's language (
 html`<h2>${tx('wh.summary')}</h2><p>${tx('ab.count', { n: 3 })}</p>`;   // plain text: html`` escapes it
 tx.rich('ab.none_yet', { create: html`<a href="…">${tx('ab.create_one')}</a>` });   // markup inside a sentence
 tx.dyn(`gallery.region.${type}`, REGION_LABELS[type][0]);              // a key made at run time, with a fallback
+tx.code('cr.schedule_help');                     // (sprint 162) `backticked` parts become <code>: syntax help
 ```
 
+(sprint 162) A long form built by many helpers (the region and report settings, RESTful Services' pages) doesn't
+pass `tx` to each of them: its entry point runs inside `withTranslator(tr(s), () => …)`, and the helpers import
+`scopedTx as tx`, which takes the translator of the request being rendered from an `AsyncLocalStorage` (so two
+requests in different languages never mix; `test/builder-i18n.test.ts` renders German and French concurrently).
+Outside `withTranslator` it is English.
+
 A missing text falls back to English, never to the raw key. Shared helpers that render chrome take the session as
 an optional last argument (`appHeader(a, 'pages', s)`, `workshopTabs('sql', s)`); `shell()` translates known English
 breadcrumb labels (`tx.label`) so pages that aren't moved yet still get a translated trail.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pgkiln",
-  "version": "0.82.0",
+  "version": "0.83.0",
   "description": "Open source low-code, SQL-driven application builder for PostgreSQL, inspired by Oracle APEX",
   "keywords": [
     "postgresql",

package/public/app.css

@@ -1468,6 +1468,8 @@ path.map-near { stroke: #1f2733; stroke-dasharray: 6 4; fill: #1f2733; fill-opac
 .tree-view a, .tree-view summary > span, .tree-leaf > span { display: inline-flex; align-items: center; gap: 0.35rem; }
 .tree-leaf { padding-left: 1rem; }
 .tree-count { font-size: 0.75rem; color: var(--muted); }
+/* (161) the node a tree_selection_change dynamic action chose */
+.tree-view li.tree-selected > :is(a, span:not(.tree-count), .tree-row), .tree-view li.tree-selected > details > summary > span { background: var(--accent-soft); border-radius: 3px; outline: 1px solid var(--accent); outline-offset: 1px; }
 /* a linked branch: the disclosure triangle sits in front of the link's row */
 .tree-branch { position: relative; }
 .tree-branch > .tree-row { display: inline-flex; align-items: center; gap: 0.35rem; }

package/public/app.js

@@ -507,6 +507,8 @@ const pgkilnUnsaved = (() => {
 
   /** (085) what runDa returns to stop the actions after it (a declined confirm) */
   const STOP = Symbol('stop');
+  /** (161) the element of a component event (a grid row, calendar cell, map, tree node): execute_javascript's `element` */
+  let componentElement = null;
   /** (156) does a Cancel Event in these actions hold its condition (decided at once, so the event's effect can be stopped)? */
   const cancels = (list) => list.some((da) => da.action === 'cancel_event' && conditionHolds(da));
   const text = (k) => (meta.texts && meta.texts[k]) || k;
@@ -634,6 +636,11 @@ const pgkilnUnsaved = (() => {
       case 'clear':
         for (const n of da.items) setItemValue(n, '');
         return;
+      // (161) set_value without SQL on a component event: the event's value, set in the browser
+      case 'set_value':
+        if (!da.eventValue) break;
+        for (const n of da.items) setItemValue(n, value == null ? '' : String(value));
+        return;
       case 'open_region':
       case 'close_region':
         for (const el of targets(da)) {
@@ -731,7 +738,7 @@ const pgkilnUnsaved = (() => {
         const fn = da.fn && actions.get(da.fn);
         if (!fn) return console.warn(`pgkiln: no function "${da.fn}" registered (pgkiln.actions.register) for dynamic action ${da.id}`);
         try {
-          await fn({ value, items: da.items, region: da.region ? document.getElementById(`R${da.region}`) : null, elements: targets(da), message: da.message });
+          await fn({ value, items: da.items, region: da.region ? document.getElementById(`R${da.region}`) : null, elements: targets(da), message: da.message, element: componentElement });
         } catch (e) {
           console.error(e);
           showError(e.message);
@@ -920,6 +927,58 @@ const pgkilnUnsaved = (() => {
       runChain(regionRun('facets_change', document.getElementById(`R${changed.replace(/\D/g, '')}`)));
     }
   }
+  // (161) component events of grid, calendar, map and tree regions (trigger: the region). The component
+  // raises pgkiln:component {event, element, value}; detail.cancelled tells it a cancel_event holds
+  // (the calendar's Create link, the tree node's link) and detail.ran how many actions run.
+  document.addEventListener('pgkiln:component', (e) => {
+    const d = e.detail || {};
+    const region = d.element && d.element.closest && d.element.closest('section[id^="R"], div[id^="R"], dialog[id^="R"]');
+    const run = regionRun(d.event, region);
+    d.ran = run.length;
+    if (!run.length) return;
+    const value = d.value == null ? '' : String(d.value);
+    if (run.some((da) => da.action === 'cancel_event' && conditionHolds(da, value))) d.cancelled = true;
+    componentElement = d.element;
+    runChain(run, value).finally(() => (componentElement = null));
+  });
+  // grid_save: the page that comes back after a grid's Save
+  for (const id of meta.savedGrids || []) {
+    const run = regionRun('grid_save', document.getElementById(`R${id}`));
+    if (run.length) runChain(run);
+  }
+  // calendar_view_change: the page that comes back from a calendar's view or period link (cal_changed=<region>)
+  {
+    const params = new URLSearchParams(location.search);
+    const changed = params.get('cal_changed');
+    if (changed) {
+      params.delete('cal_changed');
+      history.replaceState(history.state, '', `${location.pathname}${params.size ? `?${params}` : ''}${location.hash}`);
+      const region = document.getElementById(`R${changed.replace(/\D/g, '')}`);
+      const run = regionRun('calendar_view_change', region);
+      if (run.length) runChain(run, region.querySelector('.calendar')?.dataset.view || '');
+    }
+  }
+  document.addEventListener('click', (e) => {
+    const a = e.target.closest?.('.calendar .cal-toolbar a[href]');
+    const region = a && a.closest('section[id^="R"], div[id^="R"]');
+    if (!region || !regionRun('calendar_view_change', region).length) return;
+    const url = new URL(a.href, location.href);
+    url.searchParams.set('cal_changed', region.id.slice(1));
+    a.href = url.pathname + url.search + url.hash;
+  }, true);
+  // tree_selection_change: a node's label chosen (not the disclosure of a linked branch); the node is marked
+  document.addEventListener('click', (e) => {
+    const node = e.target.closest?.('.tree-view li[data-node]');
+    if (!node) return;
+    const summary = e.target.closest('summary');
+    if (summary && !summary.querySelector(':scope > span:not(.sr-only), :scope > a')) return;
+    const d = { event: 'tree_selection_change', element: node, value: node.dataset.node };
+    document.dispatchEvent(new CustomEvent('pgkiln:component', { detail: d }));
+    if (!d.ran) return;
+    node.closest('.tree-view').querySelectorAll('li.tree-selected').forEach((li) => li.classList.remove('tree-selected'));
+    node.classList.add('tree-selected');
+    if (d.cancelled) e.preventDefault();
+  });
   // after_refresh: a region replaced by a refresh, a lazy load or a master row
   document.addEventListener('pgkiln:replaced', (e) => {
     const run = regionRun('after_refresh', e.detail);
@@ -1143,10 +1202,23 @@ const pgkilnUnsaved = (() => {
 
   // ------------------------------------------------------------ calendar
   // Create on click: a click on an empty day or hour slot follows its "+" link.
+  // (161) a day or hour chosen (a click on the cell or its "+"): calendar_date_select; its cancel_event keeps the link closed
+  let addClicked = false;
   document.addEventListener('click', (e) => {
-    const cell = e.target.closest?.('.calendar [data-add]');
-    if (!cell || e.target.closest('a, button')) return;
-    cell.querySelector(':scope > .cal-add')?.click();
+    if (addClicked) return void (addClicked = false);
+    const cell = e.target.closest?.('.calendar [data-date]');
+    if (!cell) return;
+    const add = e.target.closest('a.cal-add');
+    if (!add && e.target.closest('a, button')) return;
+    const d = { event: 'calendar_date_select', element: cell, value: cell.dataset.date };
+    document.dispatchEvent(new CustomEvent('pgkiln:component', { detail: d }));
+    if (d.cancelled) return void e.preventDefault();
+    const link = !add && cell.hasAttribute('data-add') && cell.querySelector(':scope > .cal-add');
+    if (link) {
+      addClicked = true;
+      link.click();
+      addClicked = false;
+    }
   });
   // Drag and drop (mouse): drop an event on a day or hour slot; the server moves it
   // and sends the calendar back. Without JS (and from the keyboard) the event's
@@ -1442,6 +1514,9 @@ const pgkilnUnsaved = (() => {
     return row;
   }
 
+  /** (161) grid_row_init: a new row (Add row, Duplicate); the condition sees the row's number among the new rows */
+  const rowInit = (row) => document.dispatchEvent(new CustomEvent('pgkiln:component', { detail: { event: 'grid_row_init', element: row, value: row.dataset.newRow } }));
+
   /** The editable control of a cell, if any. */
   const control = (td) => td?.querySelector('input:not([type=hidden]), select');
 
@@ -1482,6 +1557,7 @@ const pgkilnUnsaved = (() => {
     if (add) {
       const row = addRow(add.closest('[data-grid]'));
       row?.querySelector('input:not([type=hidden]), select')?.focus();
+      if (row) rowInit(row);
       return;
     }
     // Duplicate: the row's values in a new row (without JS a link does it on the server)
@@ -1498,6 +1574,7 @@ const pgkilnUnsaved = (() => {
         if (from && control(td) && control(from)) setCell(td, control(from).tagName === 'SELECT' ? control(from).value : cellText(from));
       }
       control(row.querySelector('td[data-col]:not([hidden])'))?.focus();
+      rowInit(row);
       return;
     }
     if (e.target.closest('[data-grid-del]')) {
@@ -3247,6 +3324,8 @@ document.addEventListener('DOMContentLoaded', () => {
     // without a Referer: the tiles get the site's origin only (no paths or item values)
     window.L.tileLayer(data.tiles, { attribution: data.attribution, maxZoom: 19, referrerPolicy: 'strict-origin-when-cross-origin' }).addTo(map);
     const popup = (p) => {
+      // (161) a marker or shape clicked (its popup opens): map_object_click sees its id, else its title
+      el.dispatchEvent(new CustomEvent('pgkiln:component', { bubbles: true, detail: { event: 'map_object_click', element: el, value: p.id ?? p.title ?? '' } }));
       // built with the DOM, not HTML strings: titles and texts are data
       const box = document.createElement('div');
       const b = document.createElement('strong');
@@ -3290,6 +3369,8 @@ document.addEventListener('DOMContentLoaded', () => {
     if (data.layers.some((l) => l.kind === 'heat')) heatLegend(map, data.legend);
     if (several) layerSwitch(map, group, built, data.layersLabel);
     if (f) areaFilter(map, f);
+    // (161) map_change: moved or zoomed by the user (after the first view); the condition sees the zoom level
+    map.on('moveend', () => el.dispatchEvent(new CustomEvent('pgkiln:component', { bubbles: true, detail: { event: 'map_change', element: el, value: map.getZoom() } })));
   }
 });
 

package/public/builder.css

@@ -401,6 +401,10 @@ body.ide {
 .ide-head-actions { margin-left: auto; }
 .ide-tabs { display: flex; gap: 4px; margin-top: 12px; overflow-x: auto; scrollbar-width: thin; }
 .ide-page > .ide-tabs { margin-top: 0; border-bottom: 1px solid var(--border); }
+/* (sprint 163) regions and two-column rows stacked on a page always have a gap between them (pages used to rely on
+   an explicit .u-spacer, and the ones without one let a region touch the one above); not the regions side by side in a
+   grid, which have the grid's gap; :where() keeps it weaker than any page's own margin rule */
+:where(.ide-page :is(.region, .columns, :has(> .region)) + :is(.region, .columns, :has(> .region)):not(:is(.columns, .qs-columns, .vec-columns, .ws-cols, .wh-top, [class*="grid"]) > *)) { margin-top: 1rem; }
 .ide-tab {
   position: relative; display: inline-flex; align-items: center; gap: 6px; padding: 8px 11px 9px; color: var(--muted); text-decoration: none;
   border-bottom: 2px solid transparent; border-radius: var(--radius-sm) var(--radius-sm) 0 0; white-space: nowrap; font-weight: 550;
@@ -1340,7 +1344,7 @@ pre.wrap-pre { white-space: pre-wrap; overflow-wrap: anywhere; }
 .cron-field-grid input { width: 100%; font-family: var(--mono, monospace); }
 .cron-preview { border-left: 3px solid var(--accent); padding: 0.4rem 0.8rem; margin: 0.6rem 0; background: var(--accent-soft); border-radius: 0 4px 4px 0; }
 .cron-runs { margin: 0.25rem 0 0; padding-left: 1.4rem; font-variant-numeric: tabular-nums; }
-.cron-error { color: var(--danger, #b42318); }
+.cron-error { color: var(--danger); }
 .cron-sql { white-space: pre-wrap; overflow-wrap: anywhere; }
 /* (sprint 102) SQL Monitor: refresh controls, session actions, bars in Top SQL */
 .sm-toolbar { display: flex; flex-wrap: wrap; align-items: center; gap: 0.5rem; margin-bottom: 0.75rem; }
@@ -1526,7 +1530,7 @@ pre.wrap-pre { white-space: pre-wrap; overflow-wrap: anywhere; }
 .mail-queue-filters .field { min-width: 0; flex: 1 1 160px; max-width: 260px; }
 .mail-queue-stats { grid-template-columns: repeat(auto-fill, minmax(140px, 1fr)); }
 .mail-queue-stats .stat b { font-size: 1.3rem; }
-.stat.stat-bad b { color: var(--danger, #b42318); }
+.stat.stat-bad b { color: var(--danger); }
 .inline-form { display: inline; margin: 0; }
 .mail-failures .buttons { flex-wrap: wrap; gap: 6px; }
 .mail-answer { overflow-wrap: anywhere; font-family: var(--font-mono, monospace); font-size: 0.85em; }
@@ -1648,3 +1652,22 @@ a.cp-type:hover, a.cp-type:focus-visible { border-color: var(--accent); }
 
 /* (sprint 139, AP-6) OpenTelemetry */
 .otel-problem { color: var(--danger); overflow-wrap: anywhere; }
+
+/* (sprint 163) an application's REST API page: status pills under the intro, the New client form behind a button */
+.api-intro { max-width: 80ch; margin: 0 0 0.6rem; }
+.api-status { list-style: none; display: flex; flex-wrap: wrap; gap: 8px; padding: 0; margin: 0; }
+.api-status li { display: inline-block; border: 1px solid var(--border); border-radius: 14px; padding: 3px 12px; font-size: 0.875rem; overflow-wrap: anywhere; }
+.api-status li.is-ok > span:first-child { color: var(--success); }
+.api-status li.is-bad { border-color: var(--danger); }
+.api-status li.is-bad > span:first-child { color: var(--danger); font-weight: 700; }
+.api-top { align-items: start; }
+.api-top form > .field + .field { margin-top: 0.9rem; }
+.api-sub { font-size: 0.95rem; margin: 1.25rem 0 0.5rem; }
+.api-new > summary { list-style: none; display: inline-flex; }
+.api-new > summary::-webkit-details-marker { display: none; }
+.api-new[open] > summary { margin-bottom: 0.75rem; }
+.api-new-body { border-top: 1px solid var(--border); padding-top: 0.75rem; }
+.api-client-actions { display: flex; flex-wrap: wrap; gap: 6px; justify-content: flex-end; }
+.api-client-actions select { width: auto; min-height: 0; padding-block: 0.2rem; font-size: 0.8125rem; }
+.api-client-actions .inline-form { display: flex; gap: 6px; align-items: center; }
+.api-clients td.actions { text-align: end; }

package/public/data-modeler.js

@@ -10,6 +10,9 @@
 // Strict CSP: no inline styles; geometry goes into SVG attributes, sizes through the CSSOM.
 (() => {
   'use strict';
+  // (sprint 162) texts in the builder's language: #builder-texts (shell(), keys js.*), English in en.ts
+  const TEXTS = (() => { try { return JSON.parse(document.getElementById('builder-texts')?.dataset.texts || '{}'); } catch { return {}; } })();
+  const msg = (key, params = {}) => (TEXTS[key] ?? key).replace(/\{(\w+)\}/g, (m, k) => (k in params ? String(params[k]) : m));
   // the data dictionary's Print button
   for (const b of document.querySelectorAll('.dm-dict-actions [data-dm=print]')) {
     b.hidden = false;
@@ -104,7 +107,7 @@
     btn('redo').disabled = !redo.length;
     const d = dirty();
     btn('save').classList.toggle('btn-hot', d);
-    status.textContent = d ? 'Unsaved changes' : '';
+    status.textContent = d ? msg('js.dm.unsaved') : '';
   }
   function remember(before) {
     undo.push(before);
@@ -136,15 +139,15 @@
       format: 'json',
       positions: JSON.stringify([...boxes].map(([name, b]) => ({ name, x: Math.round(b.x), y: Math.round(b.y) }))),
     });
-    status.textContent = 'Saving…';
+    status.textContent = msg('js.dm.saving');
     try {
       const res = await fetch(saveForm.action, { method: 'POST', body, credentials: 'same-origin', headers: { accept: 'application/json' } });
       if (!res.ok) throw new Error(String(res.status));
       saved = JSON.stringify(snapshot());
       changed();
-      status.textContent = 'Saved';
+      status.textContent = msg('js.dm.saved');
     } catch (e) {
-      status.textContent = `Not saved (${e.message}): try again`;
+      status.textContent = msg('js.dm.not_saved', { error: e.message });
     }
   }
   btn('save').addEventListener('click', save);
@@ -333,7 +336,7 @@
       ctx.drawImage(img, 0, 0, W, H);
       c.toBlob((blob) => blob && download(blob, `${fileName}.png`), 'image/png');
     };
-    img.onerror = () => (status.textContent = 'The PNG could not be made: export SVG instead');
+    img.onerror = () => (status.textContent = msg('js.dm.no_png'));
     img.src = `data:image/svg+xml;charset=utf-8,${encodeURIComponent(svgText())}`;
   });
   btn('print').addEventListener('click', () => {

package/public/sql-monitor.js

@@ -7,6 +7,9 @@
 // JavaScript the page's Refresh link reloads it.
 (() => {
   'use strict';
+  // (sprint 162) texts in the builder's language: #builder-texts (shell(), keys js.*), English in en.ts
+  const TEXTS = (() => { try { return JSON.parse(document.getElementById('builder-texts')?.dataset.texts || '{}'); } catch { return {}; } })();
+  const msg = (key, params = {}) => (TEXTS[key] ?? key).replace(/\{(\w+)\}/g, (m, k) => (k in params ? String(params[k]) : m));
   const live = document.querySelector('[data-sm-live]');
   const controls = document.querySelector('[data-sm-controls]');
   if (!live || !controls) return;
@@ -26,7 +29,7 @@
 
   const show = () => {
     pause.setAttribute('aria-pressed', paused ? 'true' : 'false');
-    pause.textContent = paused ? 'Resume' : 'Pause';
+    pause.textContent = paused ? msg('js.sm.resume') : msg('js.sm.pause');
     live.classList.toggle('is-paused', paused);
   };
   const schedule = () => {
@@ -52,7 +55,7 @@
       paused = true;
       show();
       const note = live.querySelector('[data-sm-updated]');
-      if (note) note.textContent = 'Refresh stopped: the monitor could not be reached (signed out?). Reload the page.';
+      if (note) note.textContent = msg('js.sm.stopped');
     }
   }
   select.addEventListener('change', () => {