pgkiln 0.71.0 → 0.73.0

package/docs/guide/09-reference.md

@@ -649,6 +649,9 @@ pgkiln's icons; its filter box also searches the Lucide icons by name and search
 | `GET/POST /a/:alias/account`, `POST /a/:alias/account/password`, `POST /a/:alias/account/theme`, `POST /a/:alias/account/style` | My account, own password, the light/dark switch, the [style variant](14-globalization.md#style-variants-theme-roller) switch |
 | `POST /a/:alias/tz` | The browser's time zone for the session (automatic time zone; sent by `app.js`, CSRF token required) |
 | any page `?lang=xx` | Switch the language for the session |
+| `POST /a/:alias/telemetry` | (0.72) Browser spans of a page whose trace goes to an OpenTelemetry collector (sent by `app.js`; a signed token of the page, 204) |
+| `GET /metrics` | (0.72) Metrics in the Prometheus text format, when switched on: an administrator's builder session or `Authorization: Bearer <metrics token>` ([chapter 1](01-installation.md#monitoring-with-opentelemetry)) |
+| `GET /healthz` | `ok` when the database is reachable (503 otherwise) |
 | `/builder/...` | Builder |
 | PostgREST (separate service, `API_URL`) | REST API of each app's `api` schema, see [chapter 13](13-rest-api.md) |
 | `/static/...` | CSS, JavaScript, icons |

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

@@ -59,6 +59,9 @@ What's missing is listed in the [feature parity matrix](../apex-feature-parity.m
 | `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)) |
+| Shuttle, Select One, Select Many (24.2) items | Item types `shuttle` (ordered, colon-separated), `select_one` and `select_many` (a search field over the list of values; chips): plain selects without JavaScript ([chapter 5](05-items.md#shuttle-select-one-and-select-many)) |
+| Classic Report region (report templates, pagination types) | Region type `classic_report`: `report_template` `standard`, `value_pairs`, `badges` or `media_list`; `pagination` `total`, `range` or `none` ([chapter 4](04-pages-and-regions.md#classic_report-classic-report)) |
+| Breadcrumb region (Breadcrumb Bar), Help Text region and page help | Region types `breadcrumb` (from each page's *Breadcrumb parent*; no separate breadcrumb shared component) and `help_text`; the page's *Help text* (Markdown) ([chapter 4](04-pages-and-regions.md#breadcrumb-and-help_text)) |
 | 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)) |

package/docs/guide/12-development.md

@@ -190,6 +190,16 @@ src/
   debug.ts                 debug messages: DebugLog (levels, timed steps, NOTICEs of meta.debug from appTx), started in
                            loadContext, stored after the response (onResponse hook → meta.debug_save), hourly purge
   icons.ts                 icon helper (sprite in public/icons.svg)
+  telemetry/               (sprint 139, AP-6) OpenTelemetry without the SDK: trace.ts (the current trace in AsyncLocalStorage,
+                           startTrace/endTrace, withSpan/rootSpan/recordSpan, traceApp, traceparent, a span per statement by
+                           patching pg.Client#query, sanitizeSql/redactText, counters and histograms), config.ts (the instance's
+                           settings: meta.setting otel_* over OTEL_* variables; workspaces' telemetry columns; app → workspace,
+                           cached 30 s), export.ts (a queue per collector, OTLP/HTTP JSON for traces, logs and metrics, values
+                           only where included, gauges from the queues, prometheusText(), sendTest()), http.ts (a trace per
+                           request, request metrics, GET /metrics, POST /a/:alias/telemetry), browser.ts (the page's signed
+                           <meta name="pgkiln-trace"> in layout.ts and relay() of what app.js reports). Spans come from
+                           webclient.ts (outgoing calls, traceparent), ai/service.ts logUsage, runtime/ai-agents.ts logToolCall,
+                           mail/mail.ts sendOne, workflow.ts runWorkflow; logs from session.ts logActivity
   history.ts               (sprint 138, AP-5) change history and checksums: meta.app_snapshot (the export after the last recorded
                            change), recordHistory() (export again, workingcopy.ts components() of both, each added/changed/deleted
                            component with its files before and after into meta.component_change; called by app-updates.ts onSend,
@@ -211,6 +221,8 @@ src/
     logic.ts               computations (the page's and (102) the application's), branches (page, URL, function returning a URL, another application) and their conditions
     shortcuts.ts           (103) "NAME" shortcuts in static content, help texts and confirm messages
     render.ts              page chrome (nav, breadcrumb), dynamic action JSON, theme (the page's nonce'd <style>, light/dark and style switches)
+    page-regions.ts        (sprint 140) breadcrumb and help_text regions: breadcrumbLinks (also the title bar's trail, left out when the
+                           page has a breadcrumb region), the page's help text (meta.page.help) as Markdown with escaped &ITEM. values
     styles.ts              base styles (BASE_STYLES: Iris, Lavender, Standard; baseStyleOf → html data-style), Theme Roller style variants: fixed lists (fonts, sizes, corners), parseStyle/appStyles checks, the request's
                            style (user choice, default), themeCss() (only hex values and constants reach the CSS); (sprint 117) NAV_APPEARANCES
                            (Pillar Light / Dark), navAppearance() → the <body> classes nav-pillar-*, the header strip (--strip)
@@ -218,7 +230,10 @@ src/
     regions.ts             region shell + chart (drill-down links, gauge settings)/cards/dynamic dispatch with row limits, lazy placeholder and cache, buttons (menu buttons, badges; (124) menu entries {action} → data-menu-entry for menu_entry dynamic actions)
     report.ts, report-views.ts (group by, pivot, chart), compute.ts (computed column expressions), grid.ts (aggregates, row actions, Actions menu, single row view, layoutFromForm), grid-layout.ts (column layouts: clean, arrange, per user), master-detail.ts (signed master row selection, details), facets.ts (facetChart: a facet's counts as a chart, sprint 65), items.ts
                            (report.ts: paging with row ranges and max_rows, keyset paging (keysetPlan, seekCondition, signed r<id>_k), pagerNav, streamed CSV/Excel downloads with a cursor;
-                           items.ts: lovOptions, searchLov/lovLookup for popup LOVs, served by POST /a/:alias/:page/lov/:item/search in routes.ts)
+                           (140) classic_report through renderReport: reportState drops the interactive settings, classicTemplate (value_pairs, badges, media_list),
+                           pagination total/range/none;
+                           items.ts: lovOptions, searchLov/lovLookup for popup LOVs, served by POST /a/:alias/:page/lov/:item/search in routes.ts;
+                           LOV_TYPES / LOV_CHECKED / MULTI_VALUE: the list item types (shuttle, select_one, select_many since 140) checked on submit and colon-separated)
     region-cache.ts        region caching (keys per scope, CSRF placeholder, invalidation on submit) and lazy regions (GET …/region/:id is in routes.ts)
     gantt-move.ts          (sprint 69) Gantt drag and drop: ganttEditable, targetTime, moveGanttTask (the task in the region's
                            query, gantt_move with :TASK_ID/:NEW_START/:NEW_END); the dragging itself is in app.js
@@ -392,6 +407,9 @@ src/
     vector-providers.ts    (sprint 136, AP-1) Shared Components → Vector providers (/apps/:id/vector-providers: list, provider form,
                            test, delete) and Workspace utilities → Vector providers (/vector-providers: pgvector status, Create
                            extension for administrators, the workspace's providers and vector columns); pgvectorNote()
+    telemetry.ts           (sprint 139, AP-6) Workspace utilities → OpenTelemetry (/telemetry: the collector, signals, values, user,
+                           browser spans, /metrics and its token, status per collector, Send a test span; administrators) and a
+                           workspace's own (/workspaces/:id/telemetry: as the instance / off / own collector; its administrators)
     data-security.ts       (sprint 119) a table's Security: GET/POST /sql/objects/security?o= (policies, roles × columns, masks), Preview / Apply
     object-actions.ts      (sprint 94) an object's ⋯ menu (objectMenu) in the worksheet and the Object Browser: Quick DDL (objectDdl), Drop with
                            dependents, Add index / trigger / policy as drafts; GET /sql/objects/action, /sql/objects/panel (Open in a panel)
@@ -506,7 +524,8 @@ public/
                            (sprint 117) navigation tree states, RTL via logical properties, body.nav-pillar-*, u-color-*-subtle, the busy bar)
   app.js                   client runtime: dialogs (dialog_closed actions), popup LOVs (sprint 115: the next page loads on scroll through an
                            IntersectionObserver, ‹/More without one), dynamic actions (focus, classes, messages; sprint 115: wait_popup /
-                           remove_wait_popup as a modal <dialog class="wait-popup">, pgkiln.waitPopup(), the menu_entry event), grids (add/duplicate rows, master-detail refresh, move/resize columns, copy/paste of cell ranges), menus, lazy regions, maps (Leaflet layers, marker clusters, heat layer, layer legend, area/distance filter) (no inline JS)
+                           remove_wait_popup as a modal <dialog class="wait-popup">, pgkiln.waitPopup(), the menu_entry event), (sprint 140) shuttle()
+                           and selectPick() (Select One / Many: combobox + listbox, chips) over the item's hidden <select>, grids (add/duplicate rows, master-detail refresh, move/resize columns, copy/paste of cell ranges), menus, lazy regions, maps (Leaflet layers, marker clusters, heat layer, layer legend, area/distance filter) (no inline JS)
   code-editor.js, .css     builder code editor: enhances <textarea data-code>, highlighting, suggestions (no dependencies);
                            (sprint 108) the current line, and read-only <pre data-code-view="sql|plpgsql|json|html"> highlighted;
                            its colours are the --ce-* tokens in builder.css
@@ -532,6 +551,7 @@ test/
   globalization.test.ts    masks on HR page 29, time zones, the de/fr/es texts
   files.test.ts            file items: storage, limits, downloads, temporary files
   items.test.ts            rich text, Markdown, rating, combobox, date range, password reveal and QR code items
+  item-region-types.test.ts (sprint 140) shuttle, select one/many, classic report, breadcrumb and help text: gallery, runtime, export, Advisor, HR page 50
   dataload.test.ts         parsing, Load Data, the data_load process
   sampledata.test.ts       Sample Data: CHECK parsing, proposals, option errors, seeds and streams, preview/insert/rollback, parents first, downloads, saved generators
   unload.test.ts           Unload Data: CSV/JSON/XLSX/XML output, read back with Load Data, read-only and one-statement checks, streaming
@@ -628,6 +648,7 @@ test/
   e2e/worksheet.test.ts    (sprint 91) the SQL Worksheet in a browser: run keys, tabs, navigator, drag and drop, splitters, phone, no JavaScript;
                            (107) transaction mode: badge, reload, Rollback, closing a tab, Autocommit switch, beforeunload
   e2e/items.test.ts        sprint 26 item types in a browser: editors, tags, stars, dates, reveal; without JavaScript
+  e2e/item-region-types.test.ts (sprint 140) the shuttle (buttons, keyboard, order) and Select One / Many in a browser; without JavaScript; 390 px
   e2e/designer.test.ts     page designer: panes per width, drag and drop, keyboard, Arrange buttons, builder theme
   e2e/calendar.test.ts     calendar drag and drop and create on click, view switching, chart drill-down
   e2e/gantt.test.ts        Gantt drag and drop: moving a task, its end, the keyboard, a click still drills down, the phone

package/examples/hr/hr_75_item_region_types.sql

@@ -0,0 +1,81 @@
+-- =====================================================================
+-- HR example, part 75: the item and region types of sprint 140 (AP-4;
+-- migration 140; docs/guide/05-items.md, 04-pages-and-regions.md)
+--
+-- Page 50 "Project team" (Administration → Project team) puts a team
+-- together the way an APEX page would:
+--
+--   - P50_DEPTNO, a Select One (a searchable single pick) of the
+--     departments;
+--   - P50_MEMBERS, a Shuttle of that department's employees (a cascading
+--     list of values: choosing another department reloads it). The chosen
+--     employees keep their order (Move up / Move down), stored
+--     colon-separated like a multiselect: 7839:7566:7902;
+--   - P50_SKILLS, a Select Many (chips) of a static list of values.
+--   Without JavaScript the three are a plain select list and two
+--   multi-selection lists, and Save works the same;
+--   - "Chosen team", a Classic Report (no Actions menu) of the chosen
+--     employees in the shuttle's order, and "Head count", a classic report
+--     with the badges template;
+--   - a Breadcrumb region in the Breadcrumb bar position (the title bar
+--     then leaves its own trail out), and a Help Text region showing the
+--     page's help text (Page → Help text, Markdown).
+-- Save keeps the values in the session only: the page has no table.
+-- =====================================================================
+
+insert into meta.page (app_id, page_no, name, title, parent_page, help)
+select id, 50, 'Project team', 'Project team', 1,
+$h$Put a **project team** together:
+
+1. Choose a *department* (type to search the list).
+2. Move its employees from **Available** to **Selected** (double-click, Enter, or the › and » buttons) and put them in order with the arrow buttons.
+3. Choose the skills the team needs, then **Save**.
+
+Team lead for now: &APP_USER..$h$
+  from meta.app where alias = 'hr';
+
+insert into meta.region (page_id, seq, title, type, columns, template, position, source, config)
+select p.id, r.seq, r.title, r.type, r.cols, r.template, r.position, r.source, r.config::jsonb
+  from meta.page p join meta.app a on a.id = p.app_id, (values
+  (5, 'Breadcrumb', 'breadcrumb', 12, 'plain', 'breadcrumb', null, '{}'),
+  (10, 'Team', 'static', 8, 'standard', null, null, '{}'),
+  (20, 'How it works', 'help_text', 4, 'standard', null, null, '{}'),
+  (30, 'Chosen team', 'classic_report', 8, 'standard', null,
+   'select e.empno, e.ename, e.job, d.dname
+  from unnest(string_to_array(:P50_MEMBERS, '':'')) with ordinality m(empno, n)
+  join hr.emp e on e.empno::text = m.empno
+  left join hr.dept d on d.deptno = e.deptno
+ order by m.n',
+   '{"headings": {"empno": "No.", "ename": "Name", "job": "Job", "dname": "Department"}, "sortable": false, "pagination": "none", "empty": "Nobody chosen yet: move employees to Selected and save."}'),
+  (40, 'Head count', 'classic_report', 4, 'standard', null,
+   'select d.dname as label, count(e.empno) as value
+  from hr.dept d left join hr.emp e on e.deptno = d.deptno
+ group by d.dname order by d.dname',
+   '{"report_template": "badges", "pagination": "none"}')
+  ) as r (seq, title, type, cols, template, position, source, config)
+ where a.alias = 'hr' and p.page_no = 50;
+
+insert into meta.item (page_id, region_id, seq, name, label, type, lov, config, help)
+select p.id, r.id, i.seq, i.name, i.label, i.type, i.lov, i.config::jsonb, i.help
+  from meta.page p join meta.app a on a.id = p.app_id
+  join meta.region r on r.page_id = p.id and r.title = 'Team', (values
+  (10, 'P50_DEPTNO', 'Department', 'select_one', 'select dname, deptno from hr.dept order by 1', '{"wide": true}', null),
+  (20, 'P50_MEMBERS', 'Team members', 'shuttle',
+   'select ename || '' ('' || coalesce(job, ''-'') || '')'' as d, empno as r from hr.emp where deptno = :P50_DEPTNO order by ename',
+   '{"cascade_parents": "P50_DEPTNO", "wide": true}', 'In the order they lead the project.'),
+  (30, 'P50_SKILLS', 'Skills needed', 'select_many',
+   'STATIC:SQL;SQL,PL/pgSQL;PLPGSQL,TypeScript;TS,Design;DESIGN,Testing;TEST,Accessibility;A11Y',
+   '{"wide": true}', null)
+  ) as i (seq, name, label, type, lov, config, help)
+ where a.alias = 'hr' and p.page_no = 50;
+
+insert into meta.button (page_id, region_id, seq, name, label, action, hot)
+select p.id, r.id, 10, 'SAVE', 'Save', 'submit', true
+  from meta.page p join meta.app a on a.id = p.app_id
+  join meta.region r on r.page_id = p.id and r.title = 'Team'
+ where a.alias = 'hr' and p.page_no = 50;
+
+insert into meta.nav_entry (app_id, parent_id, seq, label, icon, target_page)
+select a.id, n.id, 70, 'Project team', 'users', 50
+  from meta.app a join meta.nav_entry n on n.app_id = a.id and n.label = 'Administration' and n.parent_id is null
+ where a.alias = 'hr';

package/package.json

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

package/public/app.css

@@ -1693,6 +1693,54 @@ td.tc-cell { overflow-wrap: anywhere; }
 }
 .tag-remove:hover, .tag-remove:focus-visible { background: var(--surface-3); }
 
+/* (140) shuttle: two lists, the move buttons between them and the order buttons after them (stacked on phones) */
+.shuttle-ui { display: grid; grid-template-columns: minmax(0, 1fr) auto minmax(0, 1fr) auto; gap: 0.5rem; align-items: stretch; }
+.shuttle-col { display: flex; flex-direction: column; gap: 0.35rem; min-width: 0; }
+.shuttle-col .shuttle-list { flex: 1; min-height: 9rem; }
+.shuttle-moves, .shuttle-order { display: flex; flex-direction: column; justify-content: center; gap: 0.3rem; }
+.shuttle-btn { min-width: 2.4rem; justify-content: center; font-size: 1rem; line-height: 1; }
+[dir=rtl] .shuttle-moves .shuttle-btn span { display: inline-block; transform: scaleX(-1); }
+@media (max-width: 640px) {
+  .shuttle-ui { grid-template-columns: minmax(0, 1fr) auto; }
+  .shuttle-col:first-child { grid-column: 1 / -1; }
+  .shuttle-moves { grid-column: 1 / -1; flex-direction: row; justify-content: center; }
+  .shuttle-moves .shuttle-btn span { display: inline-block; transform: rotate(90deg); }
+}
+/* (140) select one / select many: a search field with a list box under it; chips above it */
+.select-pick-ui { position: relative; display: flex; flex-direction: column; gap: 0.3rem; min-width: 0; }
+.select-pick-list {
+  position: absolute; z-index: 30; top: 100%; inset-inline: 0; margin: 0.15rem 0 0; padding: 0.25rem 0; list-style: none; max-height: 16rem; overflow-y: auto;
+  background: var(--surface); border: 1px solid var(--border); border-radius: calc(var(--radius) * 0.75); box-shadow: var(--shadow);
+}
+.select-pick-list[hidden] { display: none; }
+.select-pick-list li { padding: 0.4rem 0.7rem; cursor: pointer; overflow-wrap: anywhere; }
+.select-pick-list li[aria-selected=true] { font-weight: 600; }
+.select-pick-list li[aria-selected=true]::before { content: "✓ "; }
+.select-pick-list li.is-active, .select-pick-list li:hover { background: var(--surface-3); }
+.select-pick-list li.select-pick-none { cursor: default; color: var(--muted); }
+/* (140) a breadcrumb region and a help text region */
+.region-crumbs .crumbs { font-size: 0.9rem; margin: 0; }
+.region-crumbs .crumbs [aria-current] { color: var(--text); font-weight: 600; }
+.help-text { overflow-wrap: anywhere; }
+.help-text > :first-child { margin-top: 0; }
+.help-text > :last-child { margin-bottom: 0; }
+/* (140) classic report templates */
+.cr-pairs { display: flex; flex-direction: column; gap: 0.75rem; }
+.cr-pairs dl { display: grid; grid-template-columns: minmax(6rem, max-content) minmax(0, 1fr); gap: 0.25rem 1rem; margin: 0; padding-bottom: 0.75rem; border-bottom: 1px solid var(--border); }
+.cr-pairs dl:last-child { border-bottom: 0; padding-bottom: 0; }
+.cr-pairs dt { font-weight: 600; color: var(--muted); overflow-wrap: anywhere; }
+.cr-pairs dd { margin: 0; overflow-wrap: anywhere; }
+.cr-badges { display: grid; grid-template-columns: repeat(auto-fill, minmax(min(100%, 9rem), 1fr)); gap: 0.6rem; list-style: none; margin: 0; padding: 0; }
+.cr-badges li { display: flex; flex-direction: column; align-items: center; gap: 0.2rem; padding: 0.7rem; border: 1px solid var(--border); border-radius: var(--radius); text-align: center; overflow-wrap: anywhere; }
+.cr-badges .cr-badge-value { font-size: 1.4rem; font-weight: 700; }
+.cr-badges .cr-badge-label { font-size: 0.85rem; color: var(--muted); }
+.cr-media { list-style: none; margin: 0; padding: 0; }
+.cr-media li { padding: 0.6rem 0; border-bottom: 1px solid var(--border); overflow-wrap: anywhere; }
+.cr-media li:last-child { border-bottom: 0; }
+.cr-media .cr-media-title { font-weight: 600; }
+.cr-media .cr-media-text { margin: 0.15rem 0 0; color: var(--muted); }
+@media (max-width: 640px) { .cr-pairs dl { grid-template-columns: minmax(0, 1fr); } }
+
 .date-range { display: flex; flex-wrap: wrap; gap: 0.4rem 0.8rem; }
 .range-part { display: flex; align-items: center; gap: 0.4rem; flex: 1 1 12rem; min-width: 0; }
 .range-part .sub { font-size: 0.85rem; color: var(--muted); min-width: 2.2rem; }