pgkiln 0.55.0 → 0.57.0

package/SECURITY.md

@@ -110,6 +110,8 @@ first version (MVP). Every finding below has a regression test in
 | Data security per table (sprint 119) | SQL Workshop → a table → Security writes `GRANT` / `REVOKE` and a masking view, so it needs a signed-in developer and the CSRF token, and works only on tables of the workspace's schemas (never pgkiln's own or the system's: 404). Table, column, view and role names reach SQL quoted; view names and application roles that could break out of their quotes are refused. The masking role is `nologin`, a member of the reader roles, so row level security still applies inside the view, and the generated SQL refuses to run when that role would bypass RLS. MCP `run_query` with an application runs as that application's database role (read-only) and refuses unknown applications. |
 | App Gallery (sprint 120) | Installing a sample app runs shipped SQL as the owner, so only administrators may, with the CSRF token, into their current workspace; a request names only a key of `gallery.json` of its own kind (sample, starter, utility), never a path, and the file names in the catalogue must match fixed patterns. The script and the workspace placement run in one transaction: a failing script leaves nothing behind. Utility apps are blueprints: any developer installs one into their own workspace, only after the review. An installed sample is edited only from its own workspace. The search term is escaped. |
 | Builder language (sprint 121) | Only the codes of the builder's languages are accepted: anything else on a sign-in link is ignored (also a repeated parameter), the status bar's menu refuses it (400) and checks the CSRF token. A sign-in link sets only an HttpOnly, SameSite=Lax cookie that the sign-in page reads; a developer's stored choice changes only through their own signed-in session. Translated texts are escaped like the English ones; placeholders are filled with escaped values unless the code passes markup on purpose (`tx.rich`). |
+| Ask and smart filters set facets (sprint 122) | A phrase can only set facets of the faceted search and smart filters regions on the page that the user sees, on their configured columns; values and range bounds become the facets' own URL parameters (bounds checked as numbers or dates) and reach SQL as query parameters, never as text. Values in a phrase are looked up in the report's rows with a query parameter, as the application's role. A facet chip's Remove is checked against the chips the form showed (a tampered key is refused). Sample apps keep their demo accounts with known passwords: install them on development or demo instances only. |
+| Builder texts in the browser (sprint 123) | The builder's JavaScript gets its texts as JSON in an attribute (`<div id="builder-texts" data-texts>`), escaped like any attribute value, so builder pages still have no inline script. The texts are the fixed message files, never data; scripts put them into the page with `textContent` and attributes, not as HTML. |
 
 ## Findings of the MVP review and their fixes
 

package/docs/apex-feature-parity.md

@@ -213,7 +213,7 @@ the 26.2 comparison.)
 | Approvals and task list | ✅ | Task definitions (approval / action, owner roles and users, business administrators, priority, due date, details page), `meta.create_task` from application SQL, a task list region (claim, approve/reject/complete with comment, release, delegate, cancel, history), completion SQL in the same transaction. (sprint 64) **Vacation rules** (a stand-in acts on a user's tasks while the rule is active, checked on every request) and **expiration policies** (expire, renew up to N times, escalate to a role once; a waiting workflow goes on with the outcome `expired`). (sprint 114) **custom outcomes** with labels and colours (Yes / No / Undecided), **task events** on complete, expire and a failed completion SQL (SQL, e-mail or start a workflow; reopen or keep the task) and **notifications** from e-mail templates on create, complete and expire ([chapter 6](guide/06-processing.md#custom-outcomes)) |
 | Workflow (26.1: parallel flows, multi-tenancy) | ✅ | Workflow definitions of task, SQL, switch, wait, **invoke API** (a REST data source or URL through the invoke-API code, response values and the HTTP status into variables, retryable faults, no transaction open during the call) and end steps with variables, started from application SQL, run by the server (NOTIFY + polling) as the app's role; console region (terminate, retry a faulted step); diagram in the builder. **Parallel branches** (split, then a join that waits for all or for the first branch) and **versions** (development, active, inactive; running instances keep theirs) ([chapter 6](guide/06-processing.md#workflows)). (0.31) **Tenants**: `meta.set_tenant()` (APEX: `APEX_SESSION.SET_TENANT_ID`); workflows, their tasks, background chains, the task list, the console and every action follow the session's tenant ([chapter 6](guide/06-processing.md#tenants)). (sprint 114, 26.1 / 26.2) **Send E-Mail** steps (a template or subject and body), **draft** steps allowed only in development versions, branching on custom task outcomes, **migrating running instances** to a newer version (step mapping, preview, one transaction, a log; not yet for instances inside open parallel branches: [chapter 6](guide/06-processing.md#migrating-instances)) and the diagram as **SVG / PNG** |
 | Automations (scheduled) | ✅ | Shared Components → Automations: cron schedules with time zones, once or per row of a query, **several ordered actions** with their own conditions, **error handling** (stop, skip the row and continue, or disable; row errors in the run history), roles, run history and Run now, **on-demand runs from SQL** with `meta.run_automation()` (like `APEX_AUTOMATION.EXECUTE`, synchronous in the caller's transaction), safe with several servers ([chapter 6](guide/06-processing.md#automations)) |
-| AI assistant, natural-language reports (NL2IR), AI agents and tools (26.1) | ✅ | Region type **AI assistant**: a conversation per session, context queries (RAG over developer queries, run as the app's role, read-only), and **tools** the model may call: SQL with bound arguments checked against declared parameters (read-only unless marked as writing, row limit, timeout) and REST data sources, each optionally behind an authorization scheme. **AI Interactive Reports** (sprint 112; 26.1 / 26.2): an "Ask in your own words" box turns a question into the report's own settings (filters, highlights, search, sort, control break, totals, group by, pivot, chart and computed columns such as "bonus is 10% of salary"), never SQL, limited to its shown columns; each setting is a chip with Edit and Remove, plus Undo. Without an AI service a built-in phrase parser (English, Dutch, German) answers ([chapter 4](guide/04-pages-and-regions.md#ask-in-your-own-words-ai-interactive-reports)). Not yet: phrases mapped to faceted search and smart filter values. (sprint 111) **AI Agents** as a shared component (26.1 / 26.2): an AI service, system prompt, reasoning effort (low / medium / high, mapped per provider), approved tools, max steps and tokens and an authorization scheme; an assistant region names one. **AI Tools**: SQL (read-only transaction, the app role through RLS, timeout), PL/pgSQL function, REST data source, JavaScript action (a registered action or custom-event dynamic action), and **Navigate**: pgkiln builds the checksummed URL, only to pages the user may open. Every tool call is logged with its arguments (debug and Activity → AI usage). Providers add Gemini and OpenAI-compatible endpoints (Ollama, vLLM, Azure OpenAI). Answers are not streamed; no OCI provider. `pgvector` covers semantic search on the data side |
+| AI assistant, natural-language reports (NL2IR), AI agents and tools (26.1) | ✅ | Region type **AI assistant**: a conversation per session, context queries (RAG over developer queries, run as the app's role, read-only), and **tools** the model may call: SQL with bound arguments checked against declared parameters (read-only unless marked as writing, row limit, timeout) and REST data sources, each optionally behind an authorization scheme. **AI Interactive Reports** (sprint 112; 26.1 / 26.2): an "Ask in your own words" box turns a question into the report's own settings (filters, highlights, search, sort, control break, totals, group by, pivot, chart and computed columns such as "bonus is 10% of salary"), never SQL, limited to its shown columns; each setting is a chip with Edit and Remove, plus Undo. Without an AI service a built-in phrase parser (English, Dutch, German) answers ([chapter 4](guide/04-pages-and-regions.md#ask-in-your-own-words-ai-interactive-reports)). (sprint 122) Conditions a facet can hold set the page's **faceted search and smart filters** facets (values, excluded values, custom ranges, stars), shown as chips; smart filters with `"ask": true` read a typed phrase and offer it as one suggestion. (sprint 111) **AI Agents** as a shared component (26.1 / 26.2): an AI service, system prompt, reasoning effort (low / medium / high, mapped per provider), approved tools, max steps and tokens and an authorization scheme; an assistant region names one. **AI Tools**: SQL (read-only transaction, the app role through RLS, timeout), PL/pgSQL function, REST data source, JavaScript action (a registered action or custom-event dynamic action), and **Navigate**: pgkiln builds the checksummed URL, only to pages the user may open. Every tool call is logged with its arguments (debug and Activity → AI usage). Providers add Gemini and OpenAI-compatible endpoints (Ollama, vLLM, Azure OpenAI). Answers are not streamed; no OCI provider. `pgvector` covers semantic search on the data side |
 | *Generate Text with AI* process, structured outputs (26.1) | ✅ | **AI services** (Workspace utilities, administrators): Claude through `@anthropic-ai/sdk` or OpenAI through `openai`, encrypted write-only keys (or `ANTHROPIC_API_KEY` / `OPENAI_API_KEY`), per-app access with daily request and token limits, a usage log. Page process `ai_generate` (text into an item, or structured output into several items with a schema built from the items or your own) and a dynamic action that runs it without a page submit; `meta.ai_generate` / `ai_result` / `ai_available` from SQL ([chapter 6](guide/06-processing.md)). Prompts, item values included, go to the chosen provider |
 | Blueprints, spec-driven development (26.1) | ✅ | Create → **From a blueprint**: a JSON spec of tables (types, required, unique, allowed values, references), pages, navigation and sample data; optionally drafted by AI from a description; always reviewed (problems, SQL, pages, menu) before the application is created in one transaction; saved blueprints; (sprint 66) **a blueprint from an existing application** (its tables, pages, menu and optionally sample rows, with notes on what didn't carry over) |
 
@@ -247,10 +247,10 @@ row above where there is one.
 | WS-2 Data Reporter as a workspace tool for business users | ✅ | (sprint 110) App Builder → Data Reporter: datasets, reporting applications with editors and viewers, published reports with stable URLs ([Data and integration](#data-and-integration)) |
 | WS-3 Team Development: issues, labels, milestones, templates | ✅ | (sprint 113) Builder → Team Development with a board and a set-up wizard ([App Builder and development](#app-builder-and-development)) |
 | 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. Not yet: phrases mapped to facets and smart filters |
+| 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: links on the sign-in page, a language menu in the status bar, the choice stored per developer (migration 127). Translated: 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; other screens move over incrementally (English until then). Builder texts are keyed message files with a coverage check in CI |
-| 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, six single-topic apps (Sample Charts, Sample Cards, Sample Calendar, Sample Interactive Grids, Sample Dynamic Actions, Sample Reporting) 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 (maps, approvals, workflows, REST); no remote catalogue |
+| WS-7 The builder in more languages | ✅ | (sprint 121) The builder in Deutsch, English, Español, Français, Nederlands and Português: links on the sign-in page, a language menu in the status bar, the choice stored per developer (migration 127). Translated: 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; other screens move over incrementally (English until then). Builder texts are keyed message files with a coverage check in CI (sprint 123) Also the SQL Worksheet, the Object Browser and Table Properties, with the texts of the browser code. |
+| 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 |
 | WS-11 26.1 component details: infinite scrolling LOVs, Wait Popup, dynamic actions on menu entries | ✅ | (sprint 115) Popup LOVs that load on scroll, Wait Popup dynamic actions, the *Menu entry chosen* event ([Items](#items), [Logic and processing](#logic-and-processing)) |

package/docs/guide/03-builder.md

@@ -274,8 +274,9 @@ device; other developers keep their own. It only changes the builder: your appli
 
 What is translated: the builder's frame (the rail, the top bar and its search, your account menu, the status bar,
 standard messages and error pages), the sign-in page, the Workspace home, the App Builder home, an application's
-home page and its tabs, the Page Designer's toolbar, menus, component tree, panes and gallery, and the SQL Workshop's
-home page and tabs. Other builder pages are still in English (they move over screen by screen); so are the
+home page and its tabs, the Page Designer's toolbar, menus, component tree, panes and gallery, the SQL Workshop's
+home page and tabs, and (sprint 123) the **SQL Worksheet** (with its messages in the browser), the **Object Browser**
+and **Table Properties**. Other builder pages are still in English (they move over screen by screen); so are the
 Page Designer's property names and their help, the links to this guide, and any SQL the builder generates.
 
 ## Workspace home
@@ -367,8 +368,14 @@ server, `?q=`); every word must be in the title or the description.
     four views, create on click, drag and drop through a function), **Sample Interactive Grids** (an editable grid,
     select lists, totals, a frozen column, a row menu, master-detail, the grid's views), **Sample Dynamic Actions**
     (show and hide, values from the server, refresh, messages, a wait popup, classes, an inline dialog) and
-    **Sample Reporting** (interactive report, faceted search, smart filters, a classic report with column options and
-    a column template);
+    **Sample Reporting** (interactive report, faceted search, smart filters that also read a phrase, a classic report
+    with column options and a column template); and (sprint 122; APEX: Sample Maps, Sample Approvals, Sample Data
+    Loading, Sample File Upload and Download) **Sample Maps** (markers and clusters, layers with GeoJSON and a heat
+    map, a map that filters a list by distance, a location item, without PostGIS), **Sample Approvals** (a form
+    starts a workflow: approved by itself below 1,000, otherwise an approval task decided under My tasks; the
+    workflow console; accounts **demo** and **approver**), **Sample Data Loading** (`data_load` processes by column
+    name, through a data load definition and skipping bad rows, with example files to download) and **Sample Files**
+    (a file in the record's columns, several files in a child table, a photo cropped before upload);
   - the **UX Pattern Catalog** (APEX: the Universal Theme app): region templates and template options, button
     styles, item types and form layouts, alerts, badges, colour classes, lists, media lists, timelines, comments,
     avatars, metric cards, empty states, a dialog, a drawer and a side column, each named by its template, option

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

@@ -312,6 +312,23 @@ klerken*, *bonus is 10% van salaris*) and German (*Gehalt über 3000*, *sortiere
 absteigend*, *Summe von Gehalt pro Abteilung*, *nur Angestellte*) work the same way; another
 language adds a phrase table to `src/runtime/ir-phrases.ts`.
 
+**With faceted search or smart filters** on the same report (sprint 122; APEX 26.2), a condition
+that one of their facets can hold sets **that facet** instead of becoming a report filter, so the
+facet panel or the smart filter chips show it and the facet counts follow. The facets' selections
+are chips of the box too (with Remove; the facet region edits them), and Undo and *start over*
+include them:
+
+| Condition | Facet |
+|---|---|
+| *only clerks*, *clerks and analysts* (equals) | a checkbox facet: its values |
+| *not clerks* (differs from) | a checkbox facet with `exclude`: the value, excluded |
+| *salary between 1000 and 3000*, *at least 2000*, *hired in 1981* | a range facet with custom ranges (`custom`): from / to |
+| *rating at least 4* | a star facet: *4 stars & up* |
+
+Anything else (*salary over 3000*, *name contains*, a column without a facet) stays a report
+filter. Only facets of regions the user sees count. A smart filters region can also read its own
+search field this way (`"ask": true`, [below](#smart_filters)).
+
 **With an AI service** (`"ai_filter": {"service": "NAME"}`, an [AI
 service](06-processing.md#generate-text-with-ai) the application may use), the request goes to the
 service with the report's shown columns (names, headings and kinds: text, number, date, boolean),
@@ -950,6 +967,15 @@ that filter. If nothing matches, the term searches all columns of the report.
 | `facets` | As for [`facets`](#facets-faceted-search) (checkbox, range and star; `exclude` and `custom` are for the facets panel) |
 | `suggestions` | Suggestions per facet, 0–10 (default 3) |
 | `placeholder` | The text in the empty search field (translatable) |
+| `ask` | `true`: also read the search text as a phrase (sprint 122; APEX 26.2) |
+
+With `"ask": true` the text typed in the search field is also read as a phrase, with the built-in
+phrases of [*Ask in your own words*](#ask-in-your-own-words-ai-interactive-reports) (no AI service
+needed): *"clerks in sales with salary between 1000 and 3000"*, *"not clerks, salary at least
+2000"*. What the region's facets can hold is offered as the first suggestion, **Understood as:**
+*Job: CLERK · Department: SALES · Salary: 1000 – 3000*; choosing it sets those facets and clears the
+search. Values are looked up in the report's own rows (as query parameters). A single value
+(*"clerk"*) stays the ordinary matching suggestion.
 
 Everything is a link or a GET form on the report's own URL parameters, so it works without
 JavaScript, can be bookmarked and is kept in saved reports. A facets panel and smart filters may

package/docs/guide/12-development.md

@@ -589,6 +589,20 @@ translated label (German nouns). Flash messages are translated where they are se
 display position, button position, component kind and SQL Workshop tool has its run-time key; and that every
 language file has exactly the English keys, the same `{placeholders}`, no empty texts and is mostly translated.
 
+**Texts in the browser** (sprint 123). The builder's own JavaScript (`public/*.js`) asks for texts with keys
+`js.<screen>.<what>`: `shell()` puts every `js.*` key in the developer's language into the page as JSON in an
+attribute, `<div id="builder-texts" hidden data-texts="…">` (escaped like any value; builder pages keep having no
+inline script). A script reads it once and fills placeholders itself:
+
+```js
+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));
+announce(msg('js.ws.copied', { what }));
+```
+
+The coverage check also scans `public/*.js` for `msg('js.…')` and fails when a key has no English text. Text
+from the server (a JSON answer's `message`) is translated on the server.
+
 Stays English by design: the property editor's field names and help, links to the guide, generated SQL, and pages
 not moved yet. The builder's language is separate from an application's languages (`src/i18n.ts`).
 

package/examples/gallery/README.md

@@ -23,6 +23,10 @@ The builder's **App Gallery** (`/builder/gallery`) lists what `gallery.json` nam
 | `sample-grids.sql` | Sample Interactive Grids | an editable grid, select lists, totals, frozen column, row menu, master-detail, views |
 | `sample-dynamic-actions.sql` | Sample Dynamic Actions | show/hide/enable, set value, refresh, messages, wait popup, classes, inline dialog |
 | `sample-reporting.sql` | Sample Reporting | interactive report, faceted search, smart filters, a classic report with column options |
+| `sample-maps.sql` | Sample Maps | markers and clusters, layers with GeoJSON and a heat map, a map filtering a list by distance, a location item |
+| `sample-approvals.sql` | Sample Approvals | a workflow started by a form, an approval task and the task list, the workflow console (accounts demo and approver) |
+| `sample-data-loading.sql` | Sample Data Loading | `data_load` processes: by column name and merged, through a data load definition, skipping rows with errors |
+| `sample-files.sql` | Sample Files | a file in the record's columns, several files in a child table, a photo cropped before upload |
 | `ux-patterns.sql` | UX Pattern Catalog | region templates and options, buttons, items and form layouts, content and page patterns |
 
 Each script creates its own schema (`sample_charts`, …), a role (`app_sample_charts`, …) granted to the runtime, the

package/examples/gallery/gallery.json

@@ -16,6 +16,14 @@
      "description": "Behaviour without JavaScript of your own: show, hide, enable on a condition; values computed on the server; a report refreshed when an item changes; alerts, confirmations, a wait popup, classes, item errors and an inline dialog. Demo account demo / demo."},
     {"key": "sample-reporting", "title": "Sample Reporting", "alias": "sample-reporting", "icon": "file-text", "file": "samples/sample-reporting.sql",
      "description": "Reports and the ways to search them: an interactive report with its form, a faceted search, smart filters, and a classic report with column display options, a column template and a link. Demo account demo / demo."},
+    {"key": "sample-maps", "title": "Sample Maps", "alias": "sample-maps", "icon": "map", "file": "samples/sample-maps.sql",
+     "description": "Maps of Dutch museums without PostGIS: markers with popups and clustering, several layers (a route and an area as GeoJSON, a heat map you switch on), a map that filters the list beside it by distance, and a form with a location item. Demo account demo / demo."},
+    {"key": "sample-approvals", "title": "Sample Approvals", "alias": "sample-approvals", "icon": "list-checks", "file": "samples/sample-approvals.sql",
+     "description": "Purchase requests that start a workflow: approved by itself below 1,000, otherwise an approval task for the role approver, decided under My tasks; the workflow console with its diagram and history. Demo accounts demo / demo (asks) and approver / approver (decides)."},
+    {"key": "sample-data-loading", "title": "Sample Data Loading", "alias": "sample-data-loading", "icon": "file-up", "file": "samples/sample-data-loading.sql",
+     "description": "Loading CSV, Excel and JSON files into a table from a page: merged by the key, through a data load definition that maps other headings and a date format, and skipping rows with errors. Example files to download included. Demo account demo / demo."},
+    {"key": "sample-files", "title": "Sample Files", "alias": "sample-files", "icon": "files", "file": "samples/sample-files.sql",
+     "description": "File upload and download: a file in the record's own column with its name, type, size and date, several files per record in a child table, and a photo cropped square before upload. Demo account demo / demo."},
     {"key": "ux-patterns", "title": "UX Pattern Catalog", "alias": "ux-patterns", "icon": "palette", "file": "samples/ux-patterns.sql",
      "description": "The theme's building blocks to copy from: region templates and template options, button styles, item types and form layouts, alerts, badges, colour classes, lists, media lists, timelines, comments, avatars, metric cards, empty states, dialogs, drawers and side columns. Demo account demo / demo."}
   ],

package/examples/gallery/samples/sample-approvals.sql

@@ -0,0 +1,153 @@
+-- =====================================================================
+-- Sample app "Sample Approvals" (App Gallery → Sample Apps)
+--
+-- Approvals, the task list and a workflow on purchase requests:
+--   * a request is made on a form; creating it starts the PURCHASE workflow
+--   * below 1,000 the workflow approves it by itself (an SQL step)
+--   * from 1,000 it asks for approval: a PURCHASE_APPROVAL task for the
+--     users with the role approver, decided under My tasks; the task's
+--     action records the decision on the request
+--   * the console lists the workflows with their diagram and history
+--
+-- Two accounts: demo / demo asks, approver / approver decides (nobody
+-- approves their own request).
+--
+-- Installed by an administrator from the App Gallery, or with
+--   psql "$DATABASE_URL" -1 -f examples/gallery/samples/sample-approvals.sql
+-- then open /a/sample-approvals and sign in as demo / demo.
+-- =====================================================================
+
+create or replace function pg_temp.page_id(p_alias text, p_page int) returns int language sql stable as
+  $$ select p.id from meta.page p join meta.app a on a.id = p.app_id where a.alias = p_alias and p.page_no = p_page $$;
+
+-- 1. Schema and data ---------------------------------------------------------
+create schema sample_approvals;
+
+create table sample_approvals.purchase (
+  id           int generated always as identity primary key,
+  title        text not null,
+  supplier     text,
+  amount       numeric(10, 2) not null check (amount > 0),
+  status       text not null default 'PENDING' check (status in ('PENDING', 'APPROVED', 'REJECTED')),
+  requested_by text,
+  requested_at timestamptz not null default now(),
+  decided_by   text,
+  note         text
+);
+
+-- who asked, and that a new request is pending, come from the session, not the form
+create function sample_approvals.purchase_defaults() returns trigger language plpgsql as $$
+begin
+  new.requested_by := coalesce(meta.app_user(), current_user);
+  new.status := 'PENDING';
+  new.decided_by := null;
+  return new;
+end
+$$;
+create trigger purchase_defaults before insert on sample_approvals.purchase
+  for each row execute function sample_approvals.purchase_defaults();
+
+-- the decision, from the approval task's action (by the approver) or the workflow's SQL step
+-- (which runs as the user who started the workflow, so it says who decided: 'workflow')
+create function sample_approvals.decide(p_id int, p_outcome text, p_note text, p_by text default null) returns void language plpgsql as $$
+begin
+  update sample_approvals.purchase
+     set status = case lower(p_outcome) when 'approved' then 'APPROVED' when 'rejected' then 'REJECTED' else status end,
+         decided_by = coalesce(p_by, meta.app_user()), note = nullif(p_note, '')
+   where id = p_id and status = 'PENDING';
+end
+$$;
+
+insert into sample_approvals.purchase (title, supplier, amount) values
+  ('Printer toner', 'Office Supplies Ltd', 89.50), ('Standing desks (4)', 'ErgoWorks', 2400.00), ('Team lunch', 'De Kantine', 160.00);
+update sample_approvals.purchase set status = 'APPROVED', requested_by = 'demo', decided_by = 'workflow', note = 'Below 1,000: approved automatically' where title in ('Printer toner', 'Team lunch');
+update sample_approvals.purchase set status = 'APPROVED', requested_by = 'demo', decided_by = 'approver', note = 'Within the budget' where title = 'Standing desks (4)';
+
+-- 2. The application's database role ----------------------------------------
+do $$ begin
+  if not exists (select 1 from pg_roles where rolname = 'app_sample_approvals') then create role app_sample_approvals nologin; end if;
+end $$;
+grant app_sample_approvals to pgkiln_runtime;
+grant usage on schema sample_approvals to app_sample_approvals;
+grant select, insert, update, delete on sample_approvals.purchase to app_sample_approvals;
+grant execute on function sample_approvals.decide(int, text, text, text) to app_sample_approvals;
+
+-- 3. The application ----------------------------------------------------------
+insert into meta.app (alias, name, home_page, authentication, db_role)
+values ('sample-approvals', 'Sample Approvals', 1, 'app_users', 'app_sample_approvals');
+
+insert into meta.app_user (app_id, username, password_hash, roles)
+select a.id, u.name, meta.hash_password(u.name), u.roles
+  from meta.app a, (values ('demo', '{}'::text[]), ('approver', '{approver}'::text[])) as u (name, roles)
+ where a.alias = 'sample-approvals';
+
+insert into meta.task_definition (app_id, name, type, subject, owner_roles, admin_role, priority, due_in, details_page, details_item, action_code)
+select id, 'PURCHASE_APPROVAL', 'approval', 'Purchase: &TITLE. (&AMOUNT.)', '{approver}'::text[], 'approver', 2, '3 days', 3, 'P3_ID',
+       'select sample_approvals.decide(:DETAIL_PK::int, :OUTCOME, :COMMENT)'
+  from meta.app where alias = 'sample-approvals';
+
+insert into meta.workflow_definition (app_id, name, title, description, admin_role, steps)
+select id, 'PURCHASE', 'Purchase: &TITLE.', 'A purchase request: approved by itself below 1,000, otherwise by an approver.', 'approver',
+$s$[
+  {"name": "AMOUNT_CHECK", "type": "switch", "cases": [{"when": ":AMOUNT::numeric >= 1000", "next": "APPROVE"}], "otherwise": "AUTO_APPROVE"},
+  {"name": "AUTO_APPROVE", "type": "sql", "code": "select sample_approvals.decide(:DETAIL_PK::int, 'approved', 'Below 1,000: approved automatically', 'workflow')", "next": "END"},
+  {"name": "APPROVE", "type": "task", "task": "PURCHASE_APPROVAL"},
+  {"name": "END", "type": "end"}
+]$s$::jsonb
+  from meta.app where alias = 'sample-approvals';
+
+insert into meta.page (app_id, page_no, name, title, parent_page)
+select a.id, p.no, p.name, p.name, p.parent
+  from meta.app a, (values (1, 'Sample Approvals', null), (4, 'My tasks', 1), (5, 'Workflows', 1)) as p (no, name, parent)
+ where a.alias = 'sample-approvals';
+
+-- page 2 and its form, page 3: the Report and form wizard on the requests
+select meta.generate_page('sample-approvals', 'report_form', 'sample_approvals.purchase', 2, '{"label": "Purchases", "form_page": 3, "nav": false}');
+update meta.page set parent_page = 1 where app_id = (select id from meta.app where alias = 'sample-approvals') and page_no = 2;
+update meta.region set source = 'select id, title, supplier, amount, status, requested_by, decided_by, note from sample_approvals.purchase order by id desc',
+       config = config || '{"formats": {"amount": "999G999G990D00"}}'
+ where page_id = pg_temp.page_id('sample-approvals', 2) and type = 'report';
+-- the form asks only what the requester decides; the rest is shown, not edited
+update meta.item set type = 'display'
+ where page_id = pg_temp.page_id('sample-approvals', 3) and name in ('P3_STATUS', 'P3_REQUESTED_BY', 'P3_REQUESTED_AT', 'P3_DECIDED_BY', 'P3_NOTE');
+
+-- creating a request starts the workflow, after the row is inserted (P3_ID is then known)
+insert into meta.process (page_id, seq, name, type, code, when_button)
+select pg_temp.page_id('sample-approvals', 3), 15, 'Start the approval', 'sql',
+       $c$select meta.start_workflow('PURCHASE', :P3_ID, jsonb_build_object('TITLE', :P3_TITLE, 'AMOUNT', :P3_AMOUNT))$c$, 'CREATE';
+
+insert into meta.nav_entry (app_id, seq, label, icon, target_page)
+select a.id, n.seq, n.label, n.icon, n.page
+  from meta.app a, (values (10, 'Home', 'home', 1), (20, 'Purchases', 'list', 2), (30, 'My tasks', 'check', 4), (40, 'Workflows', 'route', 5)) as n (seq, label, icon, page)
+ where a.alias = 'sample-approvals';
+
+insert into meta.list (app_id, name, type, description)
+select id, 'APPROVAL_TOPICS', 'static', 'The pages of Sample Approvals' from meta.app where alias = 'sample-approvals';
+
+insert into meta.list_entry (app_id, list_name, seq, label, icon, target_page, description)
+select a.id, 'APPROVAL_TOPICS', e.seq, e.label, e.icon, e.page, e.description
+  from meta.app a, (values
+  (10, 'Purchases', 'list', 2, 'Ask for a purchase: creating it starts the PURCHASE workflow.'),
+  (20, 'My tasks', 'check', 4, 'Approve or reject what waits for you, and follow what you asked for.'),
+  (30, 'Workflows', 'route', 5, 'The workflows you started, with their diagram, current step and history.')
+  ) as e (seq, label, icon, page, description)
+ where a.alias = 'sample-approvals';
+
+insert into meta.region (page_id, seq, title, type, columns, template, source, config)
+select pg_temp.page_id('sample-approvals', r.page), r.seq, r.title, r.type, 12, r.template, r.source, r.config::jsonb
+  from (values
+  (1, 10, 'Sample Approvals', 'static', 'hero',
+   '<p>Signed in as <strong>demo</strong>, ask for a purchase under <em>Purchases</em>. Below 1,000 the workflow approves it at once; from 1,000 it creates an approval task for the role <code>approver</code>. Sign in as <strong>approver</strong> / approver and decide under <em>My tasks</em>: the task''s action writes the decision on the request, and the workflow ends.</p>',
+   '{"icon": "check"}'),
+  (1, 20, 'Topics', 'list', 'plain', null, '{"list": "APPROVAL_TOPICS", "template": "cards"}'),
+  (2, 5, 'About this page', 'static', 'plain',
+   '<p class="lead">The form''s Create button runs the wizard''s row process, then <code>select meta.start_workflow(''PURCHASE'', :P3_ID, …)</code>. A trigger fills in who asked and the status from the session, so the form can''t set them.</p>', '{}'),
+  (4, 5, 'About this page', 'static', 'plain',
+   '<p class="lead">Regions of type <code>tasks</code>: what waits for the signed-in user (as owner, here the role <code>approver</code>), and what they asked for. Approve and Reject run the task definition''s action with <code>:DETAIL_PK</code>, <code>:OUTCOME</code> and <code>:COMMENT</code>.</p>', '{}'),
+  (4, 10, 'Waiting for me', 'tasks', 'standard', null, '{"empty": "Nothing waits for you. Sign in as approver to decide on requests of 1,000 or more."}'),
+  (4, 20, 'Requested by me', 'tasks', 'collapsible', null, '{"context": "initiated", "completed": true, "empty": "You have not asked for anything that needs approval."}'),
+  (5, 5, 'About this page', 'static', 'plain',
+   '<p class="lead">A region of type <code>workflows</code>: the workflows the user started, or with <code>"context": "admin"</code> those they administer (here: approver). Open one for its diagram, current step and history; the initiator and administrators can terminate it.</p>', '{}'),
+  (5, 10, 'Workflows I started', 'workflows', 'standard', null, '{"completed": true}'),
+  (5, 20, 'All purchase workflows (approvers)', 'workflows', 'collapsible', null, '{"context": "admin", "completed": true}')
+  ) as r (page, seq, title, type, template, source, config);

package/examples/gallery/samples/sample-data-loading.sql

@@ -0,0 +1,142 @@
+-- =====================================================================
+-- Sample app "Sample Data Loading" (App Gallery → Sample Apps)
+--
+-- Loading CSV, Excel, JSON and XML files into a table from a page: a load
+-- that matches columns by name and merges by the primary key; a load
+-- through a data load definition that maps other headings, cleans values
+-- and reads a date format; and a load that skips rows with errors and lists
+-- them. The example files are static files of the application.
+--
+-- Installed by an administrator from the App Gallery, or with
+--   psql "$DATABASE_URL" -1 -f examples/gallery/samples/sample-data-loading.sql
+-- then open /a/sample-data-loading and sign in as demo / demo.
+-- =====================================================================
+
+create or replace function pg_temp.page_id(p_alias text, p_page int) returns int language sql stable as
+  $$ select p.id from meta.page p join meta.app a on a.id = p.app_id where a.alias = p_alias and p.page_no = p_page $$;
+
+-- 1. Schema and data ---------------------------------------------------------
+create schema sample_loading;
+
+create table sample_loading.product (
+  code     text primary key check (code ~ '^[A-Z]{2}-\d{3}$'),
+  name     text not null,
+  category text not null check (category in ('TOOLS', 'GARDEN', 'KITCHEN', 'OFFICE')),
+  price    numeric(8, 2) not null check (price > 0),
+  stock    int not null default 0 check (stock >= 0),
+  added    date not null default current_date
+);
+
+insert into sample_loading.product (code, name, category, price, stock, added) values
+  ('TL-001', 'Hammer', 'TOOLS', 14.95, 40, '2026-01-12'),
+  ('TL-002', 'Screwdriver set', 'TOOLS', 19.50, 25, '2026-01-12'),
+  ('GD-001', 'Garden hose 20 m', 'GARDEN', 24.99, 12, '2026-03-02'),
+  ('KT-001', 'Chef''s knife', 'KITCHEN', 39.00, 8, '2026-04-20');
+
+-- 2. The application's database role ----------------------------------------
+do $$ begin
+  if not exists (select 1 from pg_roles where rolname = 'app_sample_loading') then create role app_sample_loading nologin; end if;
+end $$;
+grant app_sample_loading to pgkiln_runtime;
+grant usage on schema sample_loading to app_sample_loading;
+grant select, insert, update, delete on sample_loading.product to app_sample_loading;
+
+-- 3. The application ----------------------------------------------------------
+insert into meta.app (alias, name, home_page, authentication, db_role)
+values ('sample-data-loading', 'Sample Data Loading', 1, 'app_users', 'app_sample_loading');
+
+insert into meta.app_user (app_id, username, password_hash, roles)
+select id, 'demo', meta.hash_password('demo'), '{}' from meta.app where alias = 'sample-data-loading';
+
+-- the example files, served at /a/sample-data-loading/static/<name>
+insert into meta.static_file (app_id, name, mime, content)
+select a.id, f.name, f.mime, convert_to(f.body, 'utf8')
+  from meta.app a, (values
+  ('products.csv', 'text/csv',
+   E'code,name,category,price,stock\nTL-002,Screwdriver set,TOOLS,17.95,30\nTL-003,Spirit level,TOOLS,12.50,15\nOF-001,Stapler,OFFICE,8.95,60\nOF-002,Desk lamp,OFFICE,29.00,10\n'),
+  ('products.json', 'application/json',
+   E'[{"code": "KT-002", "name": "Cutting board", "category": "KITCHEN", "price": 15.5, "stock": 20},\n {"code": "GD-002", "name": "Pruning shears", "category": "GARDEN", "price": 21.95, "stock": 9}]\n'),
+  ('supplier-list.csv', 'text/csv',
+   E'Article no.,Description,Group,Unit price,In stock,Since\ngd-003,  watering   can ,garden,9.99,35,02.05.2026\nkt-003,kitchen   scale,Kitchen,18.75,14,15.06.2026\n'),
+  ('with-errors.csv', 'text/csv',
+   E'code,name,category,price,stock\nOF-003,Notebook,OFFICE,3.50,100\nOF-004,Paper clips,OFFICE,-1,500\nXX,Mystery box,TOYS,10,1\nOF-005,Pencil case,OFFICE,6.25,40\n')
+  ) as f (name, mime, body)
+ where a.alias = 'sample-data-loading';
+
+-- other headings, messy values, a date format: a data load definition (Shared Components → Data load definitions)
+insert into meta.data_load_def (app_id, name, description, table_name, format, mode, columns)
+select a.id, 'SUPPLIER_LIST', 'A supplier''s product list: other headings, codes and groups in lower case, dates as DD.MM.YYYY.',
+       'sample_loading.product', 'csv', 'merge',
+       '[{"source": "Article no.", "column": "code", "transform": ["trim", "upper"]},
+         {"source": "Description", "column": "name", "transform": ["collapse_spaces", "initcap"]},
+         {"source": "Group", "column": "category", "transform": ["trim", "upper"]},
+         {"source": "Unit price", "column": "price", "format": "99990.99"},
+         {"source": "In stock", "column": "stock", "default": "0"},
+         {"source": "Since", "column": "added", "format": "DD.MM.YYYY"}]'
+  from meta.app a where a.alias = 'sample-data-loading';
+
+insert into meta.page (app_id, page_no, name, title, parent_page)
+select a.id, p.no, p.name, p.name, p.parent
+  from meta.app a, (values (1, 'Sample Data Loading', null), (2, 'Products', 1), (3, 'Load a file', 1), (4, 'Load with a definition', 1), (5, 'Skip rows with errors', 1)) as p (no, name, parent)
+ where a.alias = 'sample-data-loading';
+
+insert into meta.nav_entry (app_id, seq, label, icon, target_page)
+select a.id, n.seq, n.label, n.icon, n.page
+  from meta.app a, (values
+  (10, 'Home', 'home', 1), (20, 'Products', 'table', 2), (30, 'Load a file', 'upload', 3),
+  (40, 'Load with a definition', 'upload', 4), (50, 'Skip rows with errors', 'upload', 5)
+  ) as n (seq, label, icon, page)
+ where a.alias = 'sample-data-loading';
+
+insert into meta.list (app_id, name, type, description)
+select id, 'LOAD_TOPICS', 'static', 'The pages of Sample Data Loading' from meta.app where alias = 'sample-data-loading';
+
+insert into meta.list_entry (app_id, list_name, seq, label, icon, target_page, description)
+select a.id, 'LOAD_TOPICS', e.seq, e.label, e.icon, e.page, e.description
+  from meta.app a, (values
+  (10, 'Products', 'table', 2, 'The table the pages load into.'),
+  (20, 'Load a file', 'upload', 3, 'CSV, Excel or JSON with the table''s column names, merged by the product code.'),
+  (30, 'Load with a definition', 'upload', 4, 'Other headings, values in the wrong case and a date format, mapped by a data load definition.'),
+  (40, 'Skip rows with errors', 'upload', 5, 'Load the good rows and list the others, instead of loading nothing.')
+  ) as e (seq, label, icon, page, description)
+ where a.alias = 'sample-data-loading';
+
+insert into meta.region (page_id, seq, title, type, columns, template, source, config, static_id)
+select pg_temp.page_id('sample-data-loading', r.page), r.seq, r.title, r.type, 12, r.template, r.source, r.config::jsonb, r.sid
+  from (values
+  (1, 10, 'Sample Data Loading', 'static', 'hero',
+   '<p>A page with a file item, a button and a <code>data_load</code> process loads a file into a table. It runs as the application''s database role, so grants, constraints, triggers and row level security apply as they do for a form, and by default a file with one bad row loads nothing at all.</p>',
+   '{"icon": "upload"}', null),
+  (1, 20, 'Topics', 'list', 'plain', null, '{"list": "LOAD_TOPICS", "template": "cards"}', null),
+  (2, 10, 'Products', 'report', 'standard',
+   'select code, name, category, price, stock, added from sample_loading.product order by code',
+   '{"formats": {"price": "999G990D00"}, "page_size": 50}', null),
+  (3, 10, 'Load a file', 'static', 'standard',
+   '<p class="lead">The process: <code>{"file_item": "P3_FILE", "table": "sample_loading.product", "mode": "merge"}</code>. Columns are matched by name; a row whose <code>code</code> exists is updated, the others are added. Try <a href="/a/sample-data-loading/static/products.csv" download>products.csv</a> (one update, three new) or <a href="/a/sample-data-loading/static/products.json" download>products.json</a>, then look at <a href="/a/sample-data-loading/2">Products</a>.</p>',
+   '{}', 'load'),
+  (4, 10, 'Load with a definition', 'static', 'standard',
+   '<p class="lead"><a href="/a/sample-data-loading/static/supplier-list.csv" download>supplier-list.csv</a> has other headings (<em>Article no.</em>, <em>Unit price</em>), codes in lower case, extra spaces and dates as 02.05.2026. The data load definition <code>SUPPLIER_LIST</code> maps each heading to a column, trims and upper-cases the code, collapses the spaces in the name and reads the date with <code>DD.MM.YYYY</code>; the process only names it: <code>{"file_item": "P4_FILE", "definition": "SUPPLIER_LIST"}</code>.</p>',
+   '{}', 'load'),
+  (5, 10, 'Skip rows with errors', 'static', 'standard',
+   '<p class="lead"><a href="/a/sample-data-loading/static/with-errors.csv" download>with-errors.csv</a> has a negative price and a code and category the table''s check constraints refuse. With <code>"skip_errors": true</code> the two good rows are loaded and the others are listed with the database''s reason; without it (the other pages) nothing would be loaded.</p>',
+   '{}', 'load')
+  ) as r (page, seq, title, type, template, source, config, sid);
+
+insert into meta.item (page_id, region_id, seq, name, label, type, required, help, config)
+select r.page_id, r.id, 10, 'P' || p.page_no || '_FILE', 'File', 'file', true, 'CSV, Excel (.xlsx) or JSON, at most 2 MB.',
+       '{"accept": ".csv,.tsv,.txt,.xlsx,.json", "max_mb": 2, "wide": true}'
+  from meta.region r join meta.page p on p.id = r.page_id join meta.app a on a.id = p.app_id
+ where a.alias = 'sample-data-loading' and r.static_id = 'load';
+
+insert into meta.button (page_id, region_id, seq, name, label, action, hot)
+select r.page_id, r.id, 10, 'LOAD', 'Load', 'submit', true
+  from meta.region r join meta.page p on p.id = r.page_id join meta.app a on a.id = p.app_id
+ where a.alias = 'sample-data-loading' and r.static_id = 'load';
+
+insert into meta.process (page_id, seq, name, type, when_button, success_message, config)
+select pg_temp.page_id('sample-data-loading', x.page), 10, x.name, 'data_load', 'LOAD', x.message, x.config::jsonb
+  from (values
+  (3, 'Load products', '{inserted} products added, {updated} updated.', '{"file_item": "P3_FILE", "table": "sample_loading.product", "mode": "merge"}'),
+  (4, 'Load a supplier list', '{inserted} products added, {updated} updated.', '{"file_item": "P4_FILE", "definition": "SUPPLIER_LIST"}'),
+  (5, 'Load the good rows', '{inserted} added, {updated} updated, {failed} skipped.', '{"file_item": "P5_FILE", "table": "sample_loading.product", "mode": "merge", "skip_errors": true}')
+  ) as x (page, name, message, config);