pgkiln 0.31.0 → 0.35.0

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

@@ -13,6 +13,25 @@ A page has a number (unique in the app), a name, a title, and these behaviours:
 | `requires_auth` | boolean | `false` makes the page public in an app with a login |
 | `authz` | scheme name | Who may open it (403 otherwise) |
 | `protection` | `checksum`, `unrestricted` | Whether URL item values need a checksum |
+| `warn_unsaved` | boolean | Ask before the user leaves the page with unsaved changes, see [below](#warn-on-unsaved-changes) |
+
+### Warn on unsaved changes
+
+With **Warn on unsaved changes** (Page Designer → Page → Appearance; APEX: the page attribute of the
+same name), the browser asks *"You have unsaved changes. Leave this page anyway?"* when the user
+leaves the page while an item has a value other than the one the page was shown with: a link, a
+redirect button (such as *Cancel*), the navigation menu, closing a dialog (its × or Escape),
+reloading or closing the tab. Submitting the page with a button doesn't ask (that saves). After a
+submit that failed (a validation error), the values on the page are not saved yet, so leaving asks
+even without a further change. The check is in the browser (`pgkiln.isChanged()` tells your own
+JavaScript, like APEX's `apex.page.isChanged()`); without JavaScript there is none.
+
+- **Leave an item out** with `{"warn_unsaved": false}` in its attributes (APEX: the item's *Warn on
+  Unsaved Changes: Ignore*), for example a search field.
+- The interactive grid has its own check of unsaved rows, which is always on.
+- A value a dynamic action changes on page load counts as a change.
+- The create page wizards switch it on for the form pages they make; existing pages have it off
+  until you switch it on.
 
 ### Dialogs and drawers
 
@@ -113,6 +132,8 @@ database only checks the shape (at most 12 names of lower case letters, digits a
 | [`template_component`](#template-components) | Each row (or all rows) of a SELECT through a template component: badges, contact cards, timelines, your own |
 | [`tasks`](06-processing.md#approvals-and-the-task-list) | Task list: approvals and actions for the signed-in user |
 | [`workflows`](06-processing.md#workflows) | Workflow console: the workflows the user started or administers |
+| [`search`](#search-search-region) | One search field over several sources (search configurations), results grouped per source |
+| [`url`](#url-url-region) | Another site's page (or a page of this server) in a sandboxed frame |
 | [`static`](#static-and-dynamic-content) | Fixed HTML with `&ITEM.` substitutions |
 | [`dynamic`](#static-and-dynamic-content) | HTML produced by a SELECT |
 
@@ -411,6 +432,18 @@ that column.
 Typical form buttons (as generated by the wizard): *Cancel* (redirect), *Delete* (condition
 `:P3_ID is not null`), *Apply Changes* (same condition) and *Create* (condition `:P3_ID is null`).
 
+**Lost updates** (APEX: *Prevent Lost Updates* and *Lock Row*). When the form fetches its row, the
+page also gets a checksum of the row's form columns (file columns aside). On *Save* or *Delete*,
+`form_dml` locks the row (`SELECT … FOR UPDATE`), computes the checksum again and refuses the
+change when it differs: *"Someone else changed this record after you opened it. Reload the page to
+see the current values, then make your changes again."* Nothing is written, and the other user's
+change is kept. Columns that are not on the form don't count, and the checksum doesn't depend on
+the user's time zone or date format. The check is on by default; switch it off for one form with
+`{"lost_update": false}` in the region's attributes. The checksum is `meta.row_version(table,
+key_column, key, columns)`, which runs as the application's role (so its grants and row level
+security apply). A process that changes the same row *before* `form_dml` in the same submit makes
+the check fail: change the row after `form_dml`, or switch the check off.
+
 The easiest way to get a form is the **Report and form** wizard, which opens the form as a modal
 dialog from the report, or the **Form** wizard for a form page on its own (see
 [Create pages from a table](03-builder.md#create-pages-from-a-table-wizards)). The Cards, Calendar,
@@ -1264,6 +1297,88 @@ first rows and a *Show all* button), `char-counter` (item: a maximum length with
 an event in `pgkiln_plugins.event_log`). HR example part 47 installs them and uses all four on page
 40 (*Plug-ins*).
 
+### `search` (search region)
+
+One search field over several sources, with the results grouped per source (APEX 22.2: the Search
+region and search configurations). Each source is a **search configuration** (Shared Components →
+Search configurations):
+
+| Property | Meaning |
+|---|---|
+| Name | The static ID the region names, e.g. `CUSTOMERS` |
+| Label | The heading of its results (translated like the page's texts) |
+| Sequence | The order of the groups |
+| Source type, source | `table`: a table or view (`sales.customers`) · `sql`: a SELECT, `:ITEM` binds allowed · `list`: the entries of a [list](#list-lists) the user may see (their label and description are searched, they link where the entry links) |
+| Searchable columns | The columns the search text is looked for in. Empty: the title, subtitle and description columns |
+| Title, subtitle, description, badge column | What each result shows. The title is required (table, sql), and results are ordered by it |
+| Icon | An [icon name](09-reference.md#icons), or `#COLUMN#` for a column that holds icon names |
+| Link | Where a result goes: `{"page": 3, "items": {"P3_ID": "#ID#"}}` (`#COLUMN#` is the row's value; the link gets a checksum, a modal page opens as a dialog) |
+| Maximum results | Per configuration, 1–100 (default 10); "Showing the first *n* rows." when there are more |
+
+**How it searches.** Each word of the search text must be found (case-insensitively, anywhere in
+the value) in one of the searchable columns, so `clerk mil` finds MILLER the clerk. `%` and `_` are
+plain characters. The text is a query parameter, never SQL; the queries run as the application's
+role (its grants and row level security apply), each on its own, so a configuration that fails
+shows its error and the others still answer. The found words are marked in the results.
+
+```sql
+-- a configuration on a query: employees with their department
+select e.empno, initcap(e.ename) as name, initcap(e.job) as job, d.dname as department
+  from hr.emp e left join hr.dept d on d.deptno = e.deptno
+```
+
+with searchable columns `name, job, department`, title `name`, subtitle `job`, badge `department`
+and link `{"page": 3, "items": {"P3_EMPNO": "#EMPNO#"}}`.
+
+**The region**: attributes
+
+| Key | Meaning |
+|---|---|
+| `configs` | The configurations it searches, e.g. `["CUSTOMERS", "ORDERS"]`; empty or left out: all of the application's |
+| `item` | Search with this page item's value (`"P1_SEARCH"`) instead of a field of the region's own; refresh the region from a dynamic action, or let the item submit the page |
+| `placeholder` | The field's placeholder |
+| `min_length` | Search only from this many characters (default 1) |
+| `empty` | The text when nothing is found (default "Nothing found.") |
+
+The region's own field is a GET form (`?s<region id>=text`, so a search can be bookmarked) and works
+without JavaScript; with JavaScript it searches while the user types and replaces only the results.
+The Advisor plans every configuration with the columns it names and reports names a region uses
+that don't exist. Search configurations are exported with the application. The HR example's page 42
+searches employees, departments and the shortcuts list.
+
+### `url` (URL region)
+
+Shows another site's page in the region, in a sandboxed `<iframe>` (APEX: URL region).
+
+**Source**: the URL. Its scheme and host are written out, so an item can never choose which site is
+shown; `&ITEM.` substitutions are allowed after the host and are URL-encoded:
+
+```text
+https://reports.example.com/dashboard?customer=&P3_CUSTOMER_ID.&lang=&APP_LANGUAGE.
+```
+
+- `https://` only (`http://` for `localhost` during development), no user name or password in the
+  URL. A path that starts with `/` shows a page of this server, such as another pgkiln application
+  (`/a/portal/1`).
+- The page's Content-Security-Policy gets `frame-src` for exactly the origins of its visible URL
+  regions; other pages frame nothing. The Advisor reports a URL that isn't allowed.
+- The other site decides whether it may be framed: many sites forbid it (`X-Frame-Options` or
+  `frame-ancestors`), and the browser then shows an empty frame. Under the frame, *Open in a new tab*
+  opens the page itself.
+- The region's title is the frame's accessible name.
+
+Attributes:
+
+| Key | Meaning |
+|---|---|
+| `height` | The frame's height in pixels, 100–4000 (default 480); the width is the region's |
+| `sandbox` | The frame's sandbox flags, from `allow-scripts`, `allow-forms`, `allow-popups`, `allow-same-origin`, `allow-downloads`, `allow-modals` and `allow-popups-to-escape-sandbox`. Default: the first four (most sites need them to work). `false`: no sandbox. Navigating the whole window (`allow-top-navigation`) is never allowed |
+| `fullscreen` | `true`: the framed page may go full screen (videos, maps) |
+
+```json
+{"height": 640, "sandbox": ["allow-scripts", "allow-same-origin"], "fullscreen": true}
+```
+
 ### `static` and `dynamic` content
 
 - **`static`**: `source` is HTML written by the developer, with `&ITEM.` substitutions

package/docs/guide/05-items.md

@@ -33,6 +33,8 @@ page, optionally inside a region. Name them `P<page>_<NAME>` (uppercase letters,
 | `combobox` | free text with suggestions from the list of values; several values become tags | **colon-separated** values, e.g. `SQL:Sales` |
 | `daterange` | two date pickers, *From* and *To* | `from:to`, e.g. `2026-01-01:2026-06-30` |
 | `qrcode` | display only: the value as a QR code (SVG drawn on the server) | whatever was set |
+| `image` | display only: a picture from a URL in the value, or a BLOB from a query ([Display image](#display-image-and-geocoded-address)) | a URL, or nothing |
+| `address` | a text field with *Check address*: the installation's geocoder offers matching addresses ([Geocoded address](#display-image-and-geocoded-address)) | the address as text |
 | `plugin` | an [item plug-in](04-pages-and-regions.md#plug-ins-with-their-own-code): a text field its JavaScript enhances; `config`: `{"plugin": "char_counter", "attributes": {"MAX": "140"}}` | text |
 
 Use multi-value items in SQL with `string_to_array`:
@@ -70,6 +72,7 @@ Attributes (`config`):
 | Key | Meaning |
 |---|---|
 | `submit_on_change` | `true`: submit the page when the value changes (typical for report filters) |
+| `warn_unsaved` | `false`: a change of this item doesn't count for the page's [warn on unsaved changes](04-pages-and-regions.md#warn-on-unsaved-changes) |
 | `null_label` | Text of the empty option in select lists (default `- Select -`); `false` removes the empty option |
 | `cascade_parents` | Comma-separated items this list depends on, see [cascading lists](#cascading-lists-of-values) |
 | `wide` | `true`: take the full width of the form |
@@ -129,6 +132,50 @@ the Markdown is shown as text, and the result passes through the same allow-list
 
 The HR example's page 20 *Reviews* (`examples/hr/hr_20_items.sql`) uses all of them.
 
+## Display image and geocoded address
+
+**Display image** (`image`, APEX: *Display Image*) shows a picture and can't be submitted. Two
+sources:
+
+- **A URL in the item's value** (a computation, a process or a form fetch sets it): an `https://`
+  URL, a path on this server (`/a/hr/static/logo.png`) or a `data:image/png;base64,…` URL. Other
+  schemes (`http:`, `javascript:`, URLs with a user name) show nothing. The page's
+  Content-Security-Policy allows pictures from exactly the `https` origins its image items show
+  when it is rendered.
+- **A BLOB from a query**: `{"sql": "select photo, photo_mime from hr.emp where empno = :P43_EMPNO::int"}`.
+  The first column of the first row is the picture (`bytea`), the second its MIME type (else it is
+  recognised from the bytes: PNG, JPEG, GIF, WebP). The browser loads it from
+  `/a/<alias>/<page>/image/<item>`, which runs the query as the application's role with the
+  session's item values, after the page's authorization and the item's own; it is never cached,
+  sandboxed and at most 20 MB.
+
+`config`: `{"alt": "Photo of &P43_ENAME.", "width": 160, "height": 160}` (the alternative text,
+`&ITEM.` substitutions allowed; it defaults to the label).
+
+**Geocoded address** (`address`, APEX: *Geocoded Address*) is a text field with a *Check address*
+button. The server asks the installation's geocoder for the typed text and shows up to five
+matching addresses; the one chosen replaces the text, and with
+`{"coordinates_item": "P43_LOCATION"}` its position goes into that item as `latitude,longitude`
+(the format of a `location` item, so a map region can show it). `{"country": "nl"}` (or `"nl,be"`)
+limits the search to those countries. The answers come in the user's language.
+
+The geocoder is set per installation with **`GEOCODER_URL`**, any API that speaks Nominatim's
+search (`?q=…&format=jsonv2`): your own [Nominatim](https://nominatim.org), LocationIQ
+(`https://eu1.locationiq.com/v1/search` with `GEOCODER_KEY`) or, within its usage policy (an
+absolute maximum of one request per second, no heavy use), `https://nominatim.openstreetmap.org/search`.
+Each session may ask once a second. Without `GEOCODER_URL` an address item is a plain text item.
+
+The HR example's page 43 *Data and settings* (`examples/hr/hr_53_data_settings.sql`) has both.
+
+## Keeping values per user
+
+`{"persist": "user"}` on any item (APEX: *Maintain session state: Per User*) keeps its value for
+the signed-in user across sessions: when a page shows the item and the session has no value for it
+yet, the user's last value comes back; a submit of the page (also a plain submit, e.g. *submit on
+change*) saves the value the user could change, in the same transaction as the page's processes.
+The value is a [user preference](06-processing.md#user-preferences) named like the item. Public
+pages and applications without sign-in keep nothing.
+
 ## Lists of values
 
 A list of values (LOV) provides the options of select lists, radio groups, checkbox groups,

package/docs/guide/06-processing.md

@@ -167,6 +167,36 @@ end if;
 All changes of the submit are rolled back, and the page is shown again with the entered
 values so the user can correct them.
 
+**Error handling function** (Settings → *Errors and sessions*; APEX: Error Handling Function). A
+function of your own rewrites every error message users see: those raised in PL/pgSQL, the friendly
+constraint messages and the "reference" messages of unexpected errors.
+
+```sql
+create function sales.error_message(e jsonb) returns jsonb language plpgsql as $$
+begin
+  if e->>'constraint' = 'order_customer_fk' then
+    return jsonb_build_object('message', 'Choose an existing customer.');
+  end if;
+  if (e->>'internal')::boolean then
+    return jsonb_build_object('message', 'Something went wrong. Quote ' || (e->>'reference') || ' to the help desk.');
+  end if;
+  return null;   -- keep the message
+end $$;
+```
+
+It gets `message` (what pgkiln would show), `original_message`, `code` (SQLSTATE), `constraint`,
+`table`, `column`, `detail`, `hint`, `component` (where it happened, e.g. `process "Save order"`),
+`page`, `user`, `internal` (true for an unexpected error) and `reference` (its activity log id), and
+returns `{"message": "…"}` or null. It runs as the application's role, in a transaction of its own,
+with a 2-second limit; when it fails or returns null the message stays as it was. Debug mode shows
+the real error and doesn't call it.
+
+### Ajax callbacks
+
+A process with point **ajax** runs when JavaScript calls it by name, `pgkiln.server.process('NAME')`
+(APEX: On Demand processes, `apex.server.process`), and answers JSON; see
+[chapter 7](07-dynamic-actions.md#ajax-callbacks).
+
 ### Debug messages
 
 Like APEX's debug, pgkiln can record what each request of an application did and how long every
@@ -182,6 +212,10 @@ application's settings):
 | 6 trace | Also each region, process, application process and computation with its duration, and the session (page, user, language, time zone) |
 | 9 everything | Also the posted item values, computed values, skipped processes, hidden regions and other SQL notices |
 
+A developer can also switch debug on for **their own session** only, from the
+[developer toolbar](03-builder.md#developer-toolbar) on the running application: the application
+stays out of debug for everyone else.
+
 Each recorded request lists its entries with the time since the start of the request and, for
 timed steps, their duration. Add your own from any application SQL (processes, region sources,
 conditions, your PL/pgSQL functions), as with `apex_debug.message`:
@@ -240,6 +274,27 @@ a MIME type that doesn't look like one becomes `application/octet-stream`; the r
 sniffed (`nosniff`), is sandboxed by its Content-Security-Policy and isn't cached. At most 1000
 files and 100 MB per download.
 
+#### Data export
+
+With `{"export": "<format>"}` the query returns **rows**, and the download is those rows as one
+file (APEX: `APEX_DATA_EXPORT`): `csv`, `json`, `xml`, `html`, `xlsx` (Excel) or `pdf`.
+
+```json
+{"export": "xlsx", "file_name": "employees-&P43_DEPTNO.", "title": "Employees"}
+```
+
+| Key | Meaning |
+|---|---|
+| `export` | The format |
+| `file_name` | The name without extension, `&ITEM.` substitutions allowed (default: the process name) |
+| `title` | The title of an HTML or PDF file |
+| `layout` | A [report layout](16-files.md#report-layouts) for the PDF (paper, margins, logo) |
+| `separator` | CSV: one character instead of `,` |
+
+Column names are the headings (`hire_date` → *Hire Date*, translated like report headings in Excel
+and PDF). Excel keeps numbers and dates as numbers and dates; Excel and PDF hold at most 100,000
+rows. From SQL, `meta.data_export` makes the same CSV, JSON, XML and HTML ([below](#data-export-from-sql)).
+
 ### Execution chains
 
 A `chain` process runs its **children**: the processes of the page whose `parent_process` is the
@@ -295,6 +350,30 @@ looks up the employee (a `sql` child) and then starts the ONBOARDING workflow (a
 *Stop onboarding* terminates it; *Year-end check* is a background chain whose jobs the region
 "My background jobs" lists from `meta.process_jobs`.
 
+### Send e-mail
+
+A `send_email` process (APEX: *Send E-Mail*) queues a mail through the application's [mail
+service](#sending-e-mail), without SQL:
+
+```json
+{"to": "&P5_EMAIL.", "cc": "&P5_MANAGER_EMAIL.", "subject": "Order &P5_ID. shipped",
+ "body": "Dear &P5_NAME., your order is on its way.",
+ "body_html": "<p>Dear &P5_NAME.,</p><p>your order is on its way.</p>",
+ "attachments": "select content, filename, mime from sales.invoice where order_id = :P5_ID"}
+```
+
+or with an [e-mail template](#e-mail-templates):
+
+```json
+{"to": "&P5_EMAIL.", "template": "ORDER_SHIPPED", "placeholders": {"NAME": "&P5_NAME.", "ORDER_ID": "&P5_ID."}}
+```
+
+`to`, `cc`, `bcc` (several addresses separated by commas), `from`, `reply_to`, `subject` and `body`
+take `&ITEM.` substitutions as they are; in `body_html` the item values are HTML-escaped.
+`attachments` is a SELECT (binds allowed) with the columns `content` (bytea), `filename` and `mime`,
+one attachment per row. The mail is queued in the page's transaction: when a later process fails,
+nothing is sent. It can run in a background chain too.
+
 ### Send push notification
 
 A `send_push` process (APEX: *Send Push Notification*) sends a [push
@@ -514,6 +593,61 @@ select (select empno from hr.emp where lower(username) = lower(:APP_USER)) as ai
 
 `&AI_ENAME.` then greets the user on the dashboard.
 
+## Application settings
+
+**Shared Components → Application settings** (APEX: *Application Settings*, `APEX_APP_SETTING`)
+are named values an administrator changes after deployment: a support address, a limit, a switch.
+Each has a name (`SUPPORT_EMAIL`), a value, a description, optionally a list of **valid values**,
+and *Value required*. Application code reads and changes them:
+
+```sql
+select meta.get_app_setting('SUPPORT_EMAIL');
+select meta.set_app_setting('LEAVE_APPROVAL', 'hr');   -- one of its valid values
+```
+
+Both work for the current application only, called as its own database role (application code),
+and raise an error for an unknown name, a value outside the valid values or an empty required one.
+Settings are exported with the application, values included. An import over an installed
+application (CLI, MCP, a working copy merge) keeps the **installed** value of every setting marked
+*Keep the installed value on upgrade* (the default); with the mark off, the file's value wins. When
+the application's build status is *Run only*, its existing settings can still be edited.
+
+## User preferences
+
+Values kept per user and application across sessions (APEX: `APEX_UTIL.GET_PREFERENCE`,
+`SET_PREFERENCE`, `REMOVE_PREFERENCE`):
+
+```sql
+select meta.set_preference('report.rows', '50');        -- the signed-in user
+select meta.get_preference('report.rows');              -- null when there is none
+select meta.remove_preference('report.rows');
+select meta.get_preference('report.rows', 'blake');     -- another user of the application
+```
+
+Names are letters, digits, `_`, `.` and `-` (at most 100); values at most 32,000 bytes; at most 500
+preferences per user. Setting one needs a signed-in user. Items with `{"persist": "user"}` keep their
+values this way ([Keeping values per user](05-items.md#keeping-values-per-user)). Preferences are data of
+the installation: not exported, kept by an import over the application, deleted with it.
+
+## Data export from SQL
+
+`meta.data_export(query, format, options)` (APEX: `APEX_DATA_EXPORT.EXPORT`) returns a query's
+rows as a file (`bytea`): `csv`, `json` (an array of objects), `xml` (`query_to_xml`) or `html` (a
+table). It runs with the **caller's** privileges, so grants and row level security apply as to the
+query itself. Attach the file to a mail, store it, or send it with a download process:
+
+```sql
+select meta.add_mail_attachment(
+         meta.send_mail('boss@example.com', 'Staff', 'Attached.'),
+         meta.data_export('select empno, ename, sal from hr.emp order by ename', 'csv', '{"separator": ";"}'),
+         'staff.csv', 'text/csv');
+```
+
+Options: `separator` (CSV, one character), `header` (`false`: no heading line), `bom` (`false`: no
+UTF-8 byte order mark, which Excel needs to read UTF-8), `title` (HTML). CSV fields are quoted when
+needed, and text that a spreadsheet would run as a formula (`=`, `+`, `-`, `@`) gets a leading
+apostrophe, as in report downloads. Excel and PDF come from the [download process](#data-export).
+
 ## Automations
 
 **Shared Components → Automations** run SQL or PL/pgSQL on a schedule, like APEX automations:
@@ -604,6 +738,79 @@ creates or replaces the single action (the column itself stays empty).
 
 If you prefer the database to schedule work, [pg_cron](15-extensions.md) still works next to this.
 
+## Sending e-mail
+
+Like APEX's `APEX_MAIL`, applications send e-mail from SQL, from a *Send e-mail* process and from
+e-mail templates. Where APEX sends only through an SMTP server with a user name and password,
+pgkiln sends through any of these **mail services** (Workspace utilities → [Mail
+services](03-builder.md#mail-services), administrators):
+
+| Provider | How pgkiln hands mail over | Credentials |
+|---|---|---|
+| SMTP | Any SMTP server or relay, STARTTLS or TLS | User name and password, or **OAuth2** (SASL XOAUTH2 with a token from the client credentials grant: Microsoft Entra for Exchange Online, or another identity provider's token URL) |
+| Microsoft 365 (Graph) | Microsoft Graph `sendMail` as the From mailbox | An Entra application (tenant, client ID, client secret) with the application permission **Mail.Send**; restrict it to the sending mailboxes with an application access policy |
+| Amazon SES | SES API v2, the raw MIME message, Signature Version 4 | Region, access key ID and secret access key (an IAM user allowed `ses:SendEmail`) |
+| Resend, Postmark, SendGrid, Mailgun | Their HTTP APIs | An API key (Postmark: a server token; Mailgun: also the sending domain and region) |
+| Log only | Nothing is sent: the server's log shows each mail | – (development and demos) |
+
+Microsoft retires basic authentication (a password) for SMTP in Exchange Online: use SMTP with OAuth2
+or the Graph provider. Secrets are stored encrypted with `PGKILN_SECRET_KEY`, are write-only in the
+builder, never exported and never readable by applications. Each service lists the **From
+addresses** it may send as (an address, or `@example.com` for a whole domain); an administrator
+chooses each application's service, its From address and an optional **limit per day**.
+
+**How mail is sent.** `meta.send_mail` and the others only *queue* the mail, in the caller's
+transaction: a transaction that rolls back sends nothing. After the commit, the server sends it at
+once (`NOTIFY`), or on the scheduler's next pass. A failure that may pass (a network problem, HTTP
+429 or 5xx, an SMTP 4xx answer) is tried again after 1, 4, 16 and 64 minutes; the fifth failure, or a
+refusal (an unknown recipient, a sender the provider doesn't accept), marks the mail *error*.
+Applications → Activity → **Mail** shows each mail with its outcome, and sends a failed one again or
+cancels a queued one. Mail is kept 30 days.
+
+### From SQL
+
+```sql
+-- APEX_MAIL.SEND
+select meta.send_mail(
+  p_to        => 'jane@example.com, john@example.com',
+  p_subject   => 'Your leave was approved',
+  p_body      => 'Enjoy your holiday!',                   -- plain text
+  p_body_html => '<p>Enjoy your <b>holiday</b>!</p>',     -- HTML (optional)
+  p_cc        => null, p_bcc => null, p_reply_to => 'hr@example.com',
+  p_from      => null);                                   -- null: the application's From address
+
+-- APEX_MAIL.ADD_ATTACHMENT, in the same transaction
+with m as (select meta.send_mail('jane@example.com', 'Invoice 42', 'Attached.') as id)
+select meta.add_mail_attachment(m.id, i.pdf, 'invoice-42.pdf', 'application/pdf')
+  from m, sales.invoice i where i.id = 42;
+```
+
+See [chapter 9](09-reference.md#e-mail-from-sql) for every function and its limits. The functions
+work for the **current application** only when the caller runs as that application's database role
+(pages, processes, automations, workflows and background chains do); the SQL Workshop is not an
+application.
+
+### E-mail templates
+
+Shared Components → **E-mail templates** (APEX: Email Templates): a name, a subject, an HTML body
+and a plain text body with `#PLACEHOLDERS#`. In the HTML body `#NAME#` is the value HTML-escaped and
+`#NAME!RAW#` the value as it is (trusted HTML only); in the subject and the plain text the value is
+as it is. Names are case-insensitive; a placeholder without a value stays as written.
+
+```sql
+select meta.send_mail_template('LEAVE_DECIDED',
+         jsonb_build_object('NAME', 'Jane', 'STATUS', 'approved', 'START', '1 Aug 2026'),
+         'jane@example.com');
+```
+
+Templates are exported with the application; mail services, the application's service and the
+mail log belong to the installation and are not.
+
+**HR example.** The template `LEAVE_DECIDED` tells an employee that a leave request was approved or
+rejected: a trigger on `hr.leave_request` queues it when the status changes. The example's mail
+service `DEVELOPMENT_LOG` is of provider *log only*, so nothing leaves the server until an
+administrator gives HR a real service.
+
 ## Approvals and the task list
 
 Approvals (APEX: Task Definitions, the Approvals component and the Unified Task List) let an
@@ -676,8 +883,9 @@ open tasks so they don't linger: `select meta.close_tasks('EXPENSE_APPROVAL', :P
 | `meta.task_events` | View: the history and comments of those tasks |
 
 The task tables themselves are closed to the application's role: rights are checked by these
-functions and views, for every call. pgkiln sends no e-mail; put a task list on the home page, or
-use an automation to remind owners of overdue tasks.
+functions and views, for every call. To tell owners by e-mail, call
+[`meta.send_mail`](#sending-e-mail) from the task definition's SQL or from an automation that
+reminds owners of overdue tasks; or put a task list on the home page.
 
 **Example:** in the HR sample application, a leave request creates a `LEAVE_APPROVAL` task for the
 employee's manager; *My tasks* (page 14) approves or rejects it through `hr.decide_leave`, the same

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

@@ -10,8 +10,8 @@ your own from a static application file.
 
 | Property | Meaning |
 |---|---|
-| `event` | `change` (an item's value changed), `click` (a button was clicked), `load` (the page loaded) or `dialog_closed` (a modal dialog opened from the page was submitted and closed) |
-| `trigger_element` | For `change`: one or more item names, comma separated. For `click`: a button name. For `dialog_closed`: the dialog page numbers, comma separated (empty: any dialog) |
+| `event` | When it runs, see [Events](#events) |
+| `trigger_element` | What it listens to: item names (`change`, `focus`, `blur`, `key_release`), a button name (`click`), region ids or static ids (`after_refresh`, `selection_change`), dialog page numbers (`dialog_closed`; empty: any dialog) or event names (`custom`), comma separated. Empty for `load` and `before_submit` |
 | `condition_type`, `condition_value` | Optional client-side condition on the (first) trigger item's value (for `dialog_closed`: on the dialog's page number): `equals`, `not_equals`, `in_list` (comma-separated values), `is_null`, `is_not_null` |
 | `action` | What to do, see below |
 | `affected_items`, `affected_region_id` | What it acts on |
@@ -23,6 +23,31 @@ your own from a static application file.
 | `authz` | Only for authorized users |
 | `build_option` | Only while the [build option](06-processing.md#build-options) is included |
 
+## Events
+
+| Event | Runs when | Trigger |
+|---|---|---|
+| `change` | An item's value changed | Item names |
+| `click` | A button was clicked | A button name |
+| `load` | The page has loaded | – |
+| `dialog_closed` | A modal dialog opened from the page was submitted and closed ([below](#dialog-closed)) | Dialog page numbers (empty: any) |
+| `focus` / `blur` | An item gets / loses the focus (APEX: Get Focus, Lose Focus) | Item names |
+| `key_release` | A key is released in an item | Item names |
+| `after_refresh` | A region was refreshed (`refresh_region`), loaded lazily or shown for another master row | Region ids or static ids |
+| `selection_change` | Rows are selected in a report with [row selection](04-pages-and-regions.md#row-selection), or another master row in a grid; the condition sees the selected values, colon separated | Region ids or static ids |
+| `before_submit` | The page is about to be submitted; a declined `confirm` keeps the page | – |
+| `custom` | JavaScript raised the event: `pgkiln.trigger('ORDER_SAVED', value)` (APEX: custom events, `apex.event.trigger`) | Event names (case-insensitive) |
+
+**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
+`confirm` that is declined stops the actions after it, and for `before_submit` the submit too:
+
+| Sequence | Event | Action | Message / items |
+|---|---|---|---|
+| 10 | `click` on `DELETE_ALL` | `confirm` | *Delete every selected row?* |
+| 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 |
+
 ## Actions
 
 | Action | Runs in | Effect |
@@ -45,11 +70,44 @@ your own from a static application file.
 | `plugin` | browser | Runs the [dynamic action plug-in](04-pages-and-regions.md#plug-ins-with-their-own-code) named in `code`, with `config` `{"attributes": {…}}` (`&ITEM.` filled in); the function gets the same context as *Execute JavaScript* plus `attributes` |
 | `execute_javascript` | browser | Calls the function named in `code`, which a [static application file](03-builder.md#static-application-files) registered; see [below](#execute-javascript) |
 | `push_subscribe` | browser | Turns on [push notifications](17-mobile.md#push-notifications) on the user's device: the browser asks for permission, then the device is registered. Use it with `click` (browsers ask only after one). `message` is shown when it worked, the browser's reason when not. The app needs push notifications on |
+| `confirm` | browser | Asks `message`; **No stops the actions after it** (and the submit, for `before_submit`) |
+| `close_dialog` | browser | In a modal page: closes it; the page below refreshes, or runs its `dialog_closed` actions (APEX: Close Dialog) |
+| `cancel_dialog` | browser | In a modal page: closes it without refreshing the page below |
+| `clear` | browser | Empties the affected items |
+| `open_region` / `close_region` | browser | Opens or closes a *collapsible* region; another region is shown or hidden |
+| `download` | server | Downloads the file of the [download process](06-processing.md#download) named in `code` (a process of the page, with its authorization and condition), after sending `items_to_submit`; the page stays as it is |
+| `print` | browser | The browser's print dialog |
+| `current_position` | browser | The device's position as `latitude,longitude` (5 decimals) into the first affected item |
+| `share` | browser | The device's share sheet with the page's title, `message` and address; where there is none, the address is copied |
 
 Server-side actions first store `items_to_submit` in session state, run as the application's
 database role like everything else, and check the page's and the dynamic action's authorization.
 The SQL itself never reaches the browser.
 
+## Ajax callbacks
+
+A page process with point **ajax** (APEX: an On Demand process) runs only when JavaScript calls it by
+name, and answers JSON; an application process with point *ajax* can be called from every page (a
+page's own process of that name wins). Only processes of type `sql` answer.
+
+```js
+// in a static application file
+const r = await pgkiln.server.process('ORDER_TOTAL', { items: ['P5_ORDER_ID'], x01: 'EUR' });
+r.data.total;   // the first row of the process's last statement
+r.rows;         // its rows (at most 1000)
+r.items;        // the page and application items it set (also set on the page)
+```
+
+```sql
+-- the process ORDER_TOTAL (point ajax): :X01 … :X10 are the x01 … x10 sent
+select sum(qty * price) as total, :X01 as currency from sales.order_line where order_id = :P5_ORDER_ID::int
+```
+
+`items` is a list of item names (their current values are sent) or `{"P5_ID": "7"}`; only items the
+user may change are set, as on a submit. The process runs as the application's role with its
+authorization, condition and build option; errors come back as `{ "error": "…" }` (the promise
+rejects). The request carries the page's CSRF token and needs page access.
+
 ## Execute JavaScript
 
 APEX's *Execute JavaScript Code* runs code typed into the action. pgkiln's Content-Security-Policy

package/docs/guide/08-security.md

@@ -47,8 +47,9 @@ The builder and the runtime cover what APEX offers for its accounts:
 The `meta.set_password`/`expire`/`unexpire` functions are owner-only. Grant them to an app role if
 you want to build user administration pages inside an application.
 
-pgkiln doesn't send e-mail, so there is no self-service "forgot password" link (APEX apps don't
-have one out of the box either). A user who forgot their password asks an administrator, who
+There is no self-service "forgot password" link (APEX apps don't have one out of the box either;
+an application can build one with [e-mail](06-processing.md#sending-e-mail) and its own token
+table). A user who forgot their password asks an administrator, who
 sets a temporary one under **Users → account → Set password**, with *Require change of password
 on first use* ticked (the default).
 
@@ -327,6 +328,16 @@ like for other users (an account of the same name, if there is one), or from the
 in authorization schemes. The login page has the user name and password form only: *Keep me signed
 in*, LDAP, single sign-on and the password-change form are not used by these apps.
 
+### Session timeout warning
+
+Sessions end after the idle time (`SESSION_IDLE_MINUTES`, or Instance settings) and at their maximum
+length (`SESSION_MAX_HOURS`). Signed-in users are warned before (Settings → *Errors and sessions* →
+*Session timeout warning*, default 120 seconds; 0: no warning; APEX: Session Timeout Warning): a
+dialog says when the session ends and offers **Stay signed in**, which marks the session active
+(POST `/a/<alias>/session/extend`, with the session's CSRF token). At the maximum length the user can
+only save their work; when the session has ended the dialog offers to sign in again and comes back
+to the page.
+
 ### Keep me signed in
 
 Under **Settings → Sign-in methods**, *"Keep me signed in" for (days)* (1–365) adds a checkbox to the

package/docs/guide/09-reference.md

@@ -13,6 +13,11 @@ triggers, your own functions).
 | `meta.jwt_claims()` | jsonb | The verified JWT claims of a PostgREST request, or NULL |
 | `meta.app_language()` | text | The language of the request (`nl`, `en-GB`, …) |
 | `meta.message(name, variadic params)` | text | A text message in the current language, `%0`…`%9` replaced; falls back to the base and primary language |
+| `meta.lang(text, language default null)` | text | A [dynamic translation](14-globalization.md#dynamic-translations) of a value from a table in the session's (or the given) language, else the text (APEX: `APEX_LANG.LANG`) |
+| `meta.get_app_setting(name)`, `meta.set_app_setting(name, value)` | text / void | An [application setting](06-processing.md#application-settings) of the current application (APEX: `APEX_APP_SETTING`); application code only |
+| `meta.get_preference(name, user default null)`, `meta.set_preference(name, value, user default null)`, `meta.remove_preference(name, user default null)` | text / void | A [user preference](06-processing.md#user-preferences) of the signed-in (or the given) user in the current application (APEX: `APEX_UTIL.*_PREFERENCE`) |
+| `meta.data_export(query, format default 'csv', options jsonb default '{}')` | bytea | A query's rows as a CSV, JSON, XML or HTML file, run with the caller's privileges ([data export](06-processing.md#data-export-from-sql); APEX: `APEX_DATA_EXPORT`) |
+| `meta.csv_field(value, separator default ',', is_text default true)` | text | One CSV field: quoted when needed, a formula neutralised |
 | `meta.password_days_left(username)` | int | Days until the password expires (0: must change now, NULL: never) |
 | `meta.v(name)` | text | The session-state value of an item (use it inside functions and `DO` blocks) |
 | `meta.set_tenant(tenant)` | void | Sets (or with NULL or `''` clears) the current session's tenant (APEX: `apex_session.set_tenant_id`): at once and for the session's next requests. Workflows and tasks then carry it and show only to that tenant ([chapter 6](06-processing.md#tenants)) |
@@ -93,6 +98,22 @@ select meta.web_request_source('EXCHANGE', '{"currency": "EUR"}');
 - Application roles can't read `meta.web_request_log`; the owner can, e.g. in the SQL Workshop:
   `select id, status, status_code, url, message from meta.web_request_log order by id desc`.
 
+### E-mail from SQL
+
+[Sending e-mail](06-processing.md#sending-e-mail) (APEX: `APEX_MAIL`). The application needs a mail
+service (an administrator chooses it under Workspace utilities → Mail services).
+
+| Function | Returns |
+|---|---|
+| `meta.send_mail(p_to, p_subject, p_body, p_body_html, p_from, p_cc, p_bcc, p_reply_to)` | Queues a mail and returns its id (APEX_MAIL.SEND). `p_to`, `p_cc`, `p_bcc`: addresses separated by commas or semicolons, at most 50 together (plain addresses, no display names); `p_subject`: one line, at most 998 characters; `p_body` (plain text) and/or `p_body_html`, each at most 1 MB; `p_from`: an address the service may send as (default: the application's); `p_reply_to`: one address |
+| `meta.send_mail_template(p_template, p_placeholders jsonb, p_to, p_cc, p_bcc, p_from, p_reply_to)` | The same with an [e-mail template](06-processing.md#e-mail-templates) and its placeholder values (APEX_MAIL.SEND with `p_template_static_id`) |
+| `meta.add_mail_attachment(p_mail_id, p_content bytea, p_filename, p_mime)` | Adds a file to a mail queued **in the same transaction** (APEX_MAIL.ADD_ATTACHMENT); at most 20 files and 20 MB per mail, 10 MB per file |
+| `meta.mail_status(p_mail_id)` | `queued`, `sending`, `sent`, `error` or `cancelled`; NULL for another application's mail |
+
+The mail is sent by the server **after the transaction commits**. Over the application's limit per
+day `meta.send_mail` raises an error. Application roles can't read the queue; the owner can:
+`select id, app_id, to_addresses, subject, status, attempts, message from meta.mail_queue order by id desc`.
+
 ### Push notifications from SQL
 
 APEX_PWA push notifications ([chapter 17](17-mobile.md#push-notifications)); the application needs

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

@@ -52,7 +52,11 @@ What's missing is listed in the [feature parity matrix](../apex-feature-parity.m
 | Pagination *Row Ranges X to Y*, *Maximum Row Count*, region *Lazy Loading*, *Server Cache* | `"pagination": "range"`, `max_rows`, `"lazy": true`, `"cache": {"scope", "seconds"}` ([large tables](04-pages-and-regions.md#large-tables)) |
 | `APEX_UTIL.CHANGE_CURRENT_USER_PW`, `RESET_PASSWORD`, `EXPIRE_END_USER_ACCOUNT` | My account page; `meta.set_password()`, `meta.expire_password()` ([chapter 8](08-security.md#passwords-and-my-account)) |
 | Progressive Web App push notifications: `APEX_PWA.SEND_PUSH_NOTIFICATION`, `HAS_PUSH_SUBSCRIPTION`, *Send Push Notification* process, the subscription settings page | `meta.send_push(user, title, body, page, items)`, `meta.has_push_subscription(user)`, process type `send_push`, *My account → Notifications* and the dynamic action `push_subscribe` ([chapter 17](17-mobile.md#push-notifications)) |
-| `APEX_MAIL`, Send E-Mail process, e-mail templates | Not included: pgkiln doesn't send mail. Queue mail in a table and deliver it with your own service, or use an extension such as `pg_smtp_client` ([chapter 15](15-extensions.md)) |
+| `APEX_MAIL`, Send E-Mail process, e-mail templates | `meta.send_mail`, `meta.send_mail_template`, `meta.add_mail_attachment`, the `send_email` process and Shared Components → E-mail templates (`#NAME#` placeholders) ([chapter 6](06-processing.md#sending-e-mail)). Instead of the instance's SMTP settings: mail services with SMTP (password or OAuth2), Microsoft Graph, Amazon SES, Resend, Postmark, SendGrid or Mailgun. `APEX_MAIL.PUSH_QUEUE` is not needed: mail goes out right after the commit |
+| `APEX_APP_SETTING`, `APEX_UTIL.GET/SET/REMOVE_PREFERENCE`, *Maintain session state: Per User* | Shared Components → Application settings and `meta.get_app_setting`/`meta.set_app_setting`; `meta.get_preference`/`set_preference`/`remove_preference`; `{"persist": "user"}` on an item ([chapter 6](06-processing.md#application-settings)) |
+| `APEX_DATA_EXPORT.EXPORT` | `meta.data_export(query, format, options)` (CSV, JSON, XML, HTML) and the download process's `{"export": "xlsx"}` (also PDF) ([chapter 6](06-processing.md#data-export-from-sql)) |
+| `APEX_LANG.LANG`, dynamic translations | Shared Components → Dynamic translations and `meta.lang(text)` ([chapter 14](14-globalization.md#dynamic-translations)) |
+| Display Image, Geocoded Address items | Item types `image` and `address` (geocoder: `GEOCODER_URL`) ([chapter 5](05-items.md#display-image-and-geocoded-address)) |
 | Translated applications (XLIFF), `APEX_LANG.MESSAGE`, `&APP_TEXT$NAME.` | Translations in the app (XLIFF/CSV import and export), `meta.message()`, `&APP_TEXT$NAME.` ([chapter 14](14-globalization.md)) |
 | Application date format mask | Settings → Globalization → Date format (Oracle-style masks) |
 | Number format masks (`FML999G999G990D00`) on columns and items | `{"formats": {...}}` on report, grid and cards columns, `{"format_mask": "..."}` on charts and number/display items ([chapter 14](14-globalization.md#number-formats)) |