pgkiln 0.72.0 → 0.74.0

package/docs/guide/05-items.md

@@ -23,6 +23,9 @@ page, optionally inside a region. Name them `P<page>_<NAME>` (uppercase letters,
 | `switch` | on/off switch | `true` / `false` |
 | `checkbox_group` | several checkboxes | **colon-separated** return values, e.g. `10:30`; (137) `{"switches": true}` shows each as a switch, one per line |
 | `multiselect` | multi-select list | **colon-separated** return values |
+| `shuttle` | (140) two lists, *Available* and *Selected*, with buttons to move values across and put the chosen ones in order ([Shuttle](#shuttle-select-one-and-select-many)); a multi-select list without JavaScript | **colon-separated** return values, in the chosen order |
+| `select_one` | (140) a search field over the list of values: typing filters a list under it ([Select One](#shuttle-select-one-and-select-many)); a select list without JavaScript | the chosen return value |
+| `select_many` | (140) as `select_one`, for several values shown as chips with a remove button; a multi-select list without JavaScript | **colon-separated** return values |
 | `display` | read-only text (shows the display value for list items) | whatever was set |
 | `hidden` | not rendered | set by URL (with checksum), fetch or processes |
 | `file` | file upload ([chapter 16](16-files.md)); on phones the camera with `{"capture": "environment"}`, photos made smaller with `{"max_px": 1600}` ([chapter 17](17-mobile.md)) | the id of the uploaded temporary file (a uuid) |
@@ -191,7 +194,8 @@ 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,
-multi-selects, popup LOVs, grid columns and display items. Three forms:
+multi-selects, shuttles, Select One and Select Many items, popup LOVs, grid columns and display
+items. Three forms:
 
 1. **A SELECT returning (display, return)**. Bind variables are allowed:
    ```sql
@@ -205,8 +209,9 @@ multi-selects, popup LOVs, grid columns and display items. Three forms:
    list can also read a web service: give it a **REST data source** and query the rows from
    `rest` ([chapter 19](19-rest-data-sources.md#lists-of-values)).
 
-On submit, the value of a select list, radio group, checkbox group, multi-select or popup LOV (each
-value of a multi-value item), and of a grid column with a list of values, must be one its list
+On submit, the value of a select list, radio group, checkbox group, multi-select, shuttle, Select
+One, Select Many or popup LOV (each value of a multi-value item), and of a grid column with a list
+of values, must be one its list
 returns at that moment, for that user: a list that leaves out departments a user may not pick also
 keeps a crafted request from choosing them. Otherwise the item gets *"choose a value from the
 list"*. For a list that may legitimately miss the current value, set `"any_value": true` in the
@@ -241,6 +246,41 @@ new search starts over at the first page. A browser without `IntersectionObserve
 The HR example's page 26 (*Pick an employee*) has one with name, job and department columns;
 page 47 (*Component details*) one over 6,000 rows, 100 a page.
 
+## Shuttle, Select One and Select Many
+
+(sprint 140; APEX: Shuttle, and 24.2's Select One and Select Many) Three list items for choosing from
+a list of values, each a plain select list without JavaScript (the page saves the same values):
+
+- **Shuttle** (`shuttle`): two lists side by side, *Available* and *Selected* (stacked on phones),
+  with a filter field over the available values. Move values across with the buttons between the
+  lists (*Move all* », *Move* ›, *Remove* ‹, *Remove all* «), by double-clicking one, or with the
+  keyboard: **Enter** moves the marked values across, **Delete** removes them from *Selected*, and in
+  *Selected* **Alt+↑ / Alt+↓** move them up or down (with **Shift**: to the top or bottom; the buttons
+  ⤒ ↑ ↓ ⤓ do the same). The value is the chosen return values **in their order**, colon-separated
+  (`7566:7902`), so `string_to_array(:P50_MEMBERS, ':') with ordinality` keeps the order. Without
+  JavaScript the shuttle is a multi-select list (the chosen values first, in their order); a value
+  posted from it comes in the list's order.
+- **Select One** (`select_one`): a search field. Clicking it or typing opens a list box under it
+  that shows the list's display values containing what was typed (case-insensitive); **↑ / ↓**
+  move through it, **Enter** chooses, **Escape** closes. Emptying the field chooses no value.
+  `{"null_label": "- None -"}` names the empty entry, `false` leaves it out (a required item).
+- **Select Many** (`select_many`): the same, for several values: the chosen ones are chips above the
+  field, each with a remove button (named *Remove …* for screen readers); **Backspace** in the
+  empty field removes the last one, Enter on a chosen value in the list removes it again. The
+  value is colon-separated, like a multi-select.
+
+Like the other list items they are checked against their list of values on submit, take
+`cascade_parents` (a cascading shuttle is reloaded with its new values), show their display values
+(comma-separated, in order) when read-only, and dynamic actions see the colon-separated value
+(*Set value* with `A:B` chooses those values). The list box searches the rows the page read
+(`max_rows`, 5,000 by default): for lists of tens of thousands of rows use a [Popup LOV](#popup-lov),
+which searches on the server. Texts such as *Move all*, *Selected* and *Remove {value}* are runtime
+messages (`shuttle.*`, `lov.search`, `item.tag_remove`) an application can replace with a text
+message of the same name.
+
+HR page 50 (*Project team*, Administration) has a Select One of departments, a shuttle of that
+department's employees (cascading) and a Select Many of skills.
+
 ## Cascading lists of values
 
 A list that depends on another item, for example managers filtered by department:

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

@@ -37,7 +37,8 @@ src/
   restcatalog.ts           (095) REST source catalogs: checks, fromOpenApi (OpenAPI 3 / Swagger 2 → services: parameters with "key",
                            rows and columns from the response schema, write-back from collection and item paths, notes), catalog
                            files, load/insert/replace, sourceFromService
-  workspace-export.ts      (sprint 67) a workspace's components as a file (pgkiln-workspace/1) and importWorkspace (one transaction)
+  workspace-export.ts      (sprint 67) a workspace's components as a file (pgkiln-workspace/1) and importWorkspace (one transaction);
+                           (sprint 141) workspace_files, remote_servers (an existing server keeps its base URL), web_credentials (no secrets)
   team.ts                  (sprint 113) Team Development's data: workspaceDevelopers (members and administrators: assignees, @mentions),
                            issueHtml (markdownHtml + mentions), recordMentions, logIssue (history), teamSetup, teamCounts, pageIssues,
                            exportTeam / importTeam (the workspace export's "team" part)
@@ -134,6 +135,10 @@ src/
   network-acl.ts           (sprint 118, WS-9) workspace network access lists (meta.workspace.network_*): scopeForApp/scopeForWorkspace
                            (no cache), parseHostList, recordRefusal/purgeRefusals (meta.network_refusal, 7 days), mailHostAddress
                            (a workspace mail service's SMTP host: both lists, resolved once, the checked address connected to)
+  remote-servers.ts        (sprint 141, AP-7) remote servers (meta.remote_server): serverProblems, serverUrl (PGKILN_SERVER_* env var
+                           wins over base_url), joinUrl, resolveSource (a REST source on a server: full URL + the server's default
+                           credential; used by loadSource/fetchSource/callOperation), catalog and AI service URLs (owner pool,
+                           the application's own workspace only)
   datapump.ts              (sprint 103, DA-16) Schema Export / Import jobs (meta.dump_job): findTools (pg_dump/pg_restore ≥ the
                            server's major), startExport (pg_dump, argument array, PGPASSWORD), readToc/parseToc (pg_restore --list),
                            startImport (pg_restore -f - run in one transaction between schema renames; data-only in FK order),
@@ -220,7 +225,12 @@ src/
     processes.ts           download (file or zip from a query, safe headers), workflow processes, configuration checks of chains
     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
+    static-files.ts        (068) static application files (/a/<alias>/static/<name>), the <script>/<link> tags of a page; (141) static
+                           workspace files (/a/<alias>/workspace-files/<name>, the application's own workspace's only, owner pool);
+                           #APP_FILES# / #WORKSPACE_FILES# are substituted in context.ts substitute and template-components.ts
     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)
@@ -228,7 +238,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
@@ -375,6 +388,10 @@ src/
                            list (workspaceAdmin), Check a URL (nothing called), the workspaces (administrators), refused calls
     workspace-mail.ts      (sprint 118, WS-9) a workspace's own mail service (/builder/workspaces/:id/mail, WORKSPACE_<id>): its
                            administrators only, write-only secret, checks through mail.ts runCheck with the workspace's guard
+    workspace-resources.ts (sprint 141, AP-7) Workspace utilities → Static workspace files (/builder/workspace-files), Remote servers
+                           (/builder/remote-servers: URL now, network verdict, used by; renaming moves sources/catalogs) and Web
+                           credentials (/builder/workspace-credentials: write-only secrets): the current workspace, its developers see,
+                           its administrators change
     shared.ts              Shared Components and access control
     designer.ts            page designer: component tree (with computations and branches), layout canvas and gallery, property editor, toolbar;
                            (sprint 86) GET /builder/apps/:app/pages/:no, /builder/pages/:id redirects browsers there (designerUrl in ui.ts)
@@ -519,7 +536,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
@@ -545,6 +563,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
@@ -622,6 +641,8 @@ test/
   blueprint-from-app.test.ts  a blueprint of HR: checks clean, pages and menu, notes, a working copy with sample rows, workspaces
   rest-catalogs.test.ts    OpenAPI/Swagger reading, parameter keys, catalog files, the builder's pages, a data source from a service
   workspace-transfer.test.ts  a workspace's export, import into another workspace (added, kept, replaced, all or nothing), groups, access
+  workspace-resources.test.ts  (sprint 141) remote servers (checks, env var, HR's CRM moves its sources, credentials, renames, catalogs,
+                           AI services, the Advisor), static workspace files styling two applications, workspace credentials, the export
   tree-charts.test.ts      treemap and sunburst (the hierarchy, cycles, squarify), timeline (lanes, rows, points and periods)
   gantt-move.test.ts       an editable Gantt's markup, the move route, dates, who may drag, the builder's settings
   find-workspace.test.ts   developers' addresses, builder mail, the workspaces mail, the same answer, limits
@@ -641,6 +662,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/docs/guide/16-files.md

@@ -21,6 +21,8 @@ This chapter covers three things that deal with files:
 | Interactive report → Download → CSV / Excel / PDF | Actions → **Download CSV / Excel / PDF** |
 | Shared Components → Report Layouts | Shared Components → **Report layouts** |
 | Print (browser) | Actions → **Print**, and a print stylesheet on every page |
+| Static Application Files (`#APP_FILES#`) | Shared Components → **Static application files** ([chapter 3](03-builder.md#static-application-files)) |
+| Static Workspace Files (`#WORKSPACE_FILES#`) | Workspace utilities → **Static workspace files** ([below](#static-workspace-files)) |
 
 ## File upload items
 
@@ -206,6 +208,33 @@ address or the credential. Downloads are limited to `MAX_UPLOAD_MB`.
 Large files in bytea columns are fine up to tens of megabytes. For bigger files or large numbers
 of them, store them in object storage and keep the key in the table.
 
+## Static workspace files
+
+Files a developer ships with the applications, rather than files users upload: CSS, JavaScript, JSON, images, fonts
+and PDFs. An application has its own (Shared Components → **Static application files**,
+[chapter 3](03-builder.md#static-application-files)); since sprint 141 a **workspace** has them too (Workspace
+utilities → **Static workspace files**; APEX: Static Workspace Files), shared by every application of the workspace,
+for example one stylesheet with the company's colours.
+
+| Write | Means |
+|---|---|
+| `#WORKSPACE_FILES#brand.css` in *Every page loads* (or a page's *JavaScript and CSS files*) | Every page (that page) loads the workspace's `brand.css` with `<link>` (a `.js` file with `<script src defer>`), after pgkiln's own, in list order with the application's own files |
+| `#WORKSPACE_FILES#logo.png` in HTML, a template, a list entry, a link | `/a/<alias>/workspace-files/logo.png` |
+| `#APP_FILES#guide.pdf` | `/a/<alias>/static/guide.pdf`, the application's own file |
+
+Each application serves the workspace's files from its own address, `/a/<alias>/workspace-files/<name>`, to anyone
+(don't put secrets in them): only its own workspace's files, never another workspace's. Pages link to
+`…?v=<version>`, which browsers keep for a year; a change gives a new version.
+
+The rules are those of static application files: names of letters, digits, `_`, `-` and `.` with an extension from a
+fixed list; **no HTML** (the database refuses it too); up to 5 MB a file; `X-Content-Type-Options: nosniff`; an SVG or
+PDF opened on its own is sandboxed, so a script in it never runs. The workspace's administrators upload, write, rename
+and delete them; its developers see the list (with the applications and pages that load each file) and open a file in
+a sandboxed preview. They travel with the [workspace export](03-builder.md#export-and-import), not with an
+application's.
+
+HR example (part 76): `brand.css` is a workspace file; HR loads it as `#WORKSPACE_FILES#brand.css`.
+
 ## Data loading
 
 Both ways of loading accept:

package/docs/guide/19-rest-data-sources.md

@@ -84,6 +84,12 @@ Shared Components → **Web credentials** → ＋ Add.
 | OAuth2 password, Refresh token | `oauth2`: the password of the OAuth2 user (`password` grant), or a refresh token obtained elsewhere (`refresh_token` grant). Write-only like the secret, each with its own **Remove** button |
 | Valid for URLs | URL prefixes the credential may be sent to, e.g. `https://api.example.com/v2/`. Recommended: a source or process that points elsewhere fails instead of sending the secret |
 
+**Workspace web credentials** (sprint 141): Workspace utilities → **Web credentials** holds credentials with the same
+properties for every application of the workspace ([chapter 3](03-builder.md#static-workspace-files-remote-servers-and-web-credentials)).
+Wherever a credential is named (a source, the `invoke_api` process and step, `meta.web_request`, a remote server's
+default credential, object storage), the application's own credential of that name is used, else the workspace's.
+Another workspace's credentials are never found.
+
 For `oauth2`, pgkiln asks the token endpoint for an access token, keeps it until 30 seconds before
 it expires, renews it with the refresh token when the endpoint gave one, and asks for a new one when
 the service answers 401. Access tokens are kept in the server's memory only.
@@ -118,9 +124,10 @@ Shared Components → **REST data sources** → ＋ Add.
 | Property | Meaning |
 |---|---|
 | Name | Uppercase, e.g. `COUNTRIES` |
-| URL | `https://api.example.com/v1/cities/{city}/weather`: `{name}` is a path parameter. The host is fixed: parameters can only come after it |
+| Remote server | Optional (sprint 141): a [remote server](#remote-servers) of the workspace, e.g. `CRM`; the URL is then the path after its base URL |
+| URL | `https://api.example.com/v1/cities/{city}/weather`: `{name}` is a path parameter. The host is fixed: parameters can only come after it. With a remote server: `/v1/cities/{city}/weather` |
 | Method | `GET`, `POST`, `PUT`, `PATCH`, `DELETE` |
-| Web credential | The name of a web credential, or empty |
+| Web credential | The name of a web credential (the application's, else the workspace's), or empty: on a remote server, the server's default credential |
 | Parameters | JSON: `[{"name": "city", "in": "path", "default": "&P1_CITY.", "required": true}, {"name": "units", "in": "query", "default": "metric"}]`. `in` is `path`, `query`, `header` or `body`. Defaults may use `&ITEM.` substitutions. `key`: the service's own name for a query, header or body parameter when it isn't lower case with `_`, e.g. `{"name": "page_size", "in": "query", "key": "pageSize"}`; `Authorization`, `Cookie`, `Host` and the transport headers can't be header parameters |
 | Headers | JSON: extra request headers, e.g. `{"Accept-Language": "en"}`. Not for secrets (use a web credential); `Authorization`, `Cookie`, `Host` and the transport headers can't be set |
 | Body | For `POST`, `PUT`, `PATCH`: a JSON template, `{name}` becomes the parameter's value as a JSON string. Empty: the `body` parameters as a JSON object |
@@ -143,6 +150,30 @@ call; define them so reports keep their columns when the service changes.
 Path parameters are URL-encoded (`.` and `..` are refused), query parameters appended, header
 parameters sent as headers (one line only), so a value from an item can never change the host.
 
+### Remote servers
+
+A **remote server** (sprint 141; APEX: Remote Servers) is a named base URL of the workspace, kept under Workspace
+utilities → **Remote servers** ([chapter 3](03-builder.md#static-workspace-files-remote-servers-and-web-credentials)):
+a static id (`CRM`), this installation's base URL (`http://127.0.0.1:3100`) and/or an environment variable
+`PGKILN_SERVER_CRM` that wins when set, and an optional default web credential. A source on a server keeps only its
+path (`/a/hr/rest/v1/departments`); every call uses the server's URL **of that moment**, so changing the server (or
+setting `PGKILN_SERVER_CRM=https://crm.example.com` on the production server) moves every source on it at once,
+including write-back, synchronisation, the builder's *Test* and `invoke_api`.
+
+- The resolved URL passes every check a full URL does: the allow-list, the workspace's
+  [network access list](03-builder.md#network-access) (whose page lists each server's host) and the address checks
+  when the connection is made. A server pointed at a private address is refused unless the installation allows it.
+- The path is a path: it starts with `/` or `?` (or is empty), with no `//` or `..` segments, so it can't name another
+  host.
+- A server that doesn't exist in the application's workspace fails the call with *Remote server X does not exist in
+  this application's workspace*. An application export names the server; it imports where the server is missing, and
+  the import message and the [Advisor](03-builder.md#advisor) (a warning) name it.
+- A [REST source catalog](#rest-source-catalogs) can be on a server too, and so can an
+  [AI service](03-builder.md#ai-services).
+
+HR example (part 76): server **CRM** stands for the HR API on `http://127.0.0.1:3100`; DEPARTMENTS, DEPARTMENT and
+EMPLOYEES_API name it.
+
 ### Regions on a REST data source
 
 A region's **REST data source** property (page designer → Source) makes it read the source's
@@ -262,6 +293,9 @@ A catalog comes from:
 - a **catalog file** downloaded from another workspace or installation (*Download* on the catalog's page);
 - **by hand**: a name and base URL, then *Add a service*.
 
+A catalog may name a **remote server** of the workspace (the catalog's page, *Remote server*; sprint 141): its services
+are then paths after the server's URL, and the base URL is optional.
+
 Reading an OpenAPI document, pgkiln takes for each `GET`, `POST`, `PUT`, `PATCH` and `DELETE` operation:
 
 | From the document | Becomes |
@@ -279,7 +313,8 @@ YAML documents: convert them to JSON first (most services offer `openapi.json` t
 
 **Making a data source from a catalog**: an application's Shared Components → REST data sources → ＋ Add shows *From a
 REST source catalog* when the application's workspace has catalogs: pick a service, optionally another name and one
-of the application's web credentials. The data source is a **copy** (URL = base URL + path): changing or deleting the
+of the web credentials (the application's or the workspace's). The data source is a **copy** (URL = base URL + path; on a
+catalog with a **remote server**, sprint 141: the server and the path, so the source moves with the server): changing or deleting the
 catalog later doesn't change it, and *Replace from a document* on a catalog's page replaces only the catalog's
 services. Credentials never belong to a catalog: each application signs in with its own web credential.
 
@@ -335,6 +370,9 @@ values, processes and workflow steps refer to sources and credentials by name, s
   internal addresses need `PGKILN_REST_PRIVATE_HOSTS` as well.
 - A workspace's [network access list](03-builder.md#network-access) narrows the allow-list for its
   applications (it can't widen it).
+- A [remote server](#remote-servers)'s URL is checked like any other URL; its environment variable can only be a
+  `PGKILN_SERVER_…` name, so no other part of the server's environment becomes a URL. Only the workspace's
+  administrators change its servers and credentials.
 - Secrets are encrypted with a key outside the database, write-only in the builder, excluded from
   exports and from the runtime role, and never logged. Use **Valid for URLs** so a credential is
   only ever sent to its own service.

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/examples/hr/hr_76_remote_servers.sql

@@ -0,0 +1,48 @@
+-- =====================================================================
+-- HR example, part 76: a remote server and a static workspace file
+-- (sprint 141, AP-7; migration 141; docs/guide/19-rest-data-sources.md
+--  "Remote servers", docs/guide/16-files.md "Static workspace files")
+--
+-- Remote server CRM (Workspace utilities → Remote servers) stands for the
+-- web service of part 23: the HR example's own REST API on
+-- http://127.0.0.1:3100. The REST data sources DEPARTMENTS, DEPARTMENT and
+-- EMPLOYEES_API now name the server and keep only their path
+-- (/a/hr/rest/v1/departments, ...). Moving the API to another host changes
+-- one value: the server's base URL, e.g. https://crm.example.com, or the
+-- server's environment variable PGKILN_SERVER_CRM, which wins when it is
+-- set (one value per environment: development, test, production). Every
+-- source on the server follows at once; the new host must still be on the
+-- allow-list (PGKILN_REST_ALLOWED_HOSTS) and the workspace's network
+-- access list.
+--
+-- brand.css is a static workspace file: every application of the
+-- workspace may load it. HR loads it on every page as
+-- #WORKSPACE_FILES#brand.css (Shared Components → Static application
+-- files → Every page loads); another application of the workspace adds the
+-- same line to share the styles.
+-- =====================================================================
+
+insert into meta.remote_server (workspace_id, static_id, name, description, base_url, env_var)
+select meta.app_workspace(a.id), 'CRM', 'HR API (CRM)',
+       'The HR example''s REST API, served by this pgkiln server. Set PGKILN_SERVER_CRM on another environment.',
+       'http://127.0.0.1:3100', 'PGKILN_SERVER_CRM'
+  from meta.app a where a.alias = 'hr'
+on conflict (workspace_id, static_id) do nothing;
+
+update meta.rest_source s
+   set server = 'CRM', url = substr(s.url, length('http://127.0.0.1:3100') + 1)
+  from meta.app a
+ where a.id = s.app_id and a.alias = 'hr' and s.server is null
+   and s.name in ('DEPARTMENTS', 'DEPARTMENT', 'EMPLOYEES_API') and s.url like 'http://127.0.0.1:3100/%';
+
+insert into meta.workspace_file (workspace_id, name, mime, content)
+select meta.app_workspace(a.id), 'brand.css', 'text/css', convert_to($css$/* A static workspace file (Workspace utilities → Static workspace files):
+   the applications of the workspace load it as #WORKSPACE_FILES#brand.css. */
+.region-header h2 { letter-spacing: .01em; }
+.ws-brand { color: var(--accent, #2b62c4); font-weight: 600; }
+$css$, 'utf8')
+  from meta.app a where a.alias = 'hr'
+on conflict (workspace_id, name) do nothing;
+
+update meta.app set static_includes = static_includes || '{#WORKSPACE_FILES#brand.css}'
+ where alias = 'hr' and not ('#WORKSPACE_FILES#brand.css' = any (static_includes));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pgkiln",
-  "version": "0.72.0",
+  "version": "0.74.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; }