pgkiln 0.80.0 → 0.82.0

package/docs/guide/05-items.md

@@ -38,6 +38,10 @@ page, optionally inside a region. Name them `P<page>_<NAME>` (uppercase letters,
 | `qrcode` | display only: the value as a QR code (SVG drawn on the server) | whatever was set |
 | `image` | display only: a picture from a URL in the value, or a BLOB from a query ([Display image](#display-image-and-geocoded-address)) | a URL, or nothing |
 | `address` | a text field with *Check address*: the installation's geocoder offers matching addresses ([Geocoded address](#display-image-and-geocoded-address)) | the address as text |
+| `image_upload` | (158; APEX: Image Upload) a [file item](16-files.md) for pictures: `image/*` only, a preview, cropping before upload (`{"crop": "free"}` by default; `"1:1"`, `"4:3"`, `"3:4"`, `"16:9"`, `"3:2"`, `"2:3"`) and a maximum size applied in the browser (`{"max_px": 1600}`); column settings as a file item's | as a `file` item |
+| `autocomplete` | (158; APEX: Text Field with autocomplete) a text field with suggestions from the list of values; any text may be typed (a one-value `combobox`) | text |
+| `percent_graph` | (158; APEX: Percent Graph) display only: a 0–100 value as a bar (a `<progress>` element, read out as the number); values above 100 show a full bar, other text nothing | whatever was set |
+| `display_map` | (158; APEX: Display Map) display only: a small map of `lat,lng` with a pin, from the [map regions' tile server](04-pages-and-regions.md) (`MAP_TILE_URL`), and a *Show map* link. The position is the value, or another item's: `{"coordinates_item": "P3_LOCATION", "zoom": 15}` | `lat,lng`, or nothing |
 | `plugin` | an [item plug-in](04-pages-and-regions.md#plug-ins-with-their-own-code): a text field its JavaScript enhances; `config`: `{"plugin": "char_counter", "attributes": {"MAX": "140"}}` | text |
 
 Use multi-value items in SQL with `string_to_array`:
@@ -79,6 +83,7 @@ browser's date and time field.
 | `help` | Help text under the field |
 | `lov` | List of values for select/radio/checkbox group/multi-select/popup/display items |
 | `readonly_condition` | SQL expression; when true the item is shown read-only and ignored on submit |
+| `condition_type`, `condition_expr`, `condition_value` | A [server-side condition](06-processing.md#server-side-conditions) (sprint 154): when it doesn't hold, the item isn't rendered and takes no submitted value |
 | `authz` | Authorization scheme; unauthorized users don't see the item and can't set it |
 | `config` | Attributes, see below |
 

package/docs/guide/06-processing.md

@@ -79,11 +79,32 @@ process fails, earlier inserts and updates are rolled back too.
 
 ## Validations
 
-| `type` | Passes when |
-|---|---|
-| `not_null` | the associated item has a value |
-| `sql` | `expression` (a SQL boolean expression, binds allowed) is true |
-| `regex` | the item's value matches `expression` (a POSIX regular expression, checked in Postgres) |
+APEX's validation types (sprint 154–155; APEX: *Validation → Type*):
+
+| `type` | APEX | Passes when |
+|---|---|---|
+| `sql` | Expression | `expression` (a SQL boolean expression, binds allowed) is true |
+| `exists` / `not_exists` | Rows returned / No rows returned | the query in `expression` returns a row / no row |
+| `function_body` | Function Body (returning Boolean) | the PL/pgSQL body in `expression` returns true |
+| `function_error` | Function Body (returning Error Text) | the body returns null or empty; otherwise its text is the error message |
+| `not_null` | Item is NOT NULL | the associated item has a value |
+| `not_null_or_zero` | Item is NOT NULL or zero | the item has a value that is not zero |
+| `not_zero` | Item is NOT zero | the item is empty or not zero |
+| `no_spaces` | Item contains no spaces | the item has no white space |
+| `alphanumeric` | Item is alphanumeric | the item has only letters and digits (any script) |
+| `numeric` | Item is numeric | the item is a number (a number item's format mask is read back first) |
+| `valid_date` | Item is a valid date | the item is a date in the application's date format, or ISO |
+| `valid_timestamp` | Item is a valid timestamp | the item is `YYYY-MM-DD HH:MI[:SS]` (or with a `T`) |
+| `equals` / `not_equals` | Item = Value / Item != Value | the item's value is / isn't `expression` |
+| `in_list` / `not_in_list` | Item is (NOT) contained in Value | the item's value is / isn't one of `expression`'s values, colon separated (`CLERK:ANALYST`) |
+| `chars_only` / `chars_any` / `chars_none` | Item contains only / at least one / none of the characters in Value | checked against the characters of `expression` |
+| `regex` | Item matches Regular Expression | the item's value matches `expression` (a POSIX regular expression, checked in Postgres) |
+
+The format checks (`no_spaces` … `valid_timestamp`, `chars_*`, `regex`, `not_zero`, `not_in_list`,
+`not_equals`) pass an empty item, as APEX's do: add `not_null` (or *Value required*) when it must
+have one. The database refuses a type without the associated item or expression it needs. The SQL
+types run as the application's role; the [Advisor](03-builder.md#advisor) names SQL validations a type
+says exactly (`:P3_SAL is not null` → `not_null`).
 
 Plus: every **required** editable item must have a value.
 
@@ -92,6 +113,10 @@ Plus: every **required** editable item must have a value.
 | `item_name` | The message is shown next to this item (otherwise at the top of the page) |
 | `message` | The error message |
 | `when_button` | Only validate for this request. A `DELETE` request runs only the validations with `when_button` `DELETE` (e.g. "approved requests can't be deleted"), not the item checks |
+| `condition_type`, `condition_expr`, `condition_value` | Only validate when the [server-side condition](#server-side-conditions) holds, e.g. `request_in` `SAVE,CREATE` (sprint 154) |
+| `authz` | Only validate for users the authorization scheme lets through (sprint 155) |
+| `always_execute` | Also validate for a `DELETE` request (APEX: *Always Execute*) |
+| `display_location` | Where the error shows: `inline_and_notification` (next to the item and at the top), `inline` (empty: next to the item, with "correct the errors below" at the top) or `notification` (at the top only). Without an associated item it is at the top |
 
 Example: commission only for salesmen.
 
@@ -122,7 +147,7 @@ two combine well; see error handling below.
 |---|---|
 | `point` | `submit` (after validations) or `load` (when the page is shown, after form fetch) |
 | `when_button` | Only for this request (empty = every submit with a button) |
-| `condition_type`, `condition_expr`, `condition_value` | Only when the [condition](#conditions-of-computations-processes-and-branches) holds (server-side condition, as for computations and branches) |
+| `condition_type`, `condition_expr`, `condition_value` | Only when the [condition](#server-side-conditions) holds (server-side condition, as for computations and branches) |
 | `parent_process` | The name of a `chain` process on the page: this process then runs only inside that chain |
 | `region_id` | The form or grid region, for `form_dml` / `grid_dml` |
 | `config` | Settings of a `data_load`, `invoke_api`, `download`, `chain`, `workflow`, `send_push` or `plugin` process (JSON) |
@@ -393,6 +418,23 @@ queued in the page's transaction and sent after the submit commits; a user witho
 nothing (no error). The application needs push notifications on (Settings → Progressive Web App).
 From SQL the same is `meta.send_push(...)` ([chapter 9](09-reference.md#push-notifications-from-sql)).
 
+### Declarative process types
+
+Sprint 157 (APEX: page process types). Each type calls what pgkiln already has; its settings go in
+the process's attributes (`config`), checked when it is saved and again when it runs.
+
+| `type` | APEX | Settings | What it does |
+|---|---|---|---|
+| `close_dialog` | Close Dialog | `{"items": ["P5_ID"]}` | Closes the modal page after the submit (a modal page closes after a submit anyway; this one also hands the items' values to the page below, where items of the same name take them before its [Dialog Closed](07-dynamic-actions.md#dialog-closed) actions run) |
+| `clear_session_state` | Clear Session State | `{"items": ["P3_NAME"], "pages": [3, 4], "all": false}` | Empties the items, every `P<n>_` item of the pages, or all page and application items |
+| `reset_pagination` | Reset Pagination | – | Reports and grids start on their first page after the submit |
+| `user_preferences` | User Preferences | `{"action": "set", "preference": "DEFAULT_DEPT", "item": "P1_DEPT"}`, or `"reset"` | Stores (or removes) a [user preference](#user-preferences); nothing for the public user |
+| `server_geocoding` | Server Side Geocoding | `{"address_item": "P3_ADDRESS", "coordinates_item": "P3_LOCATION", "country": "nl"}` | The installation's geocoder (`GEOCODER_URL`); the first place's `lat,lng` goes into the coordinates item |
+| `print_report` | Print Report | `{"document": "EMPLOYEE_SHEET"}` | A [document template](16-files.md#document-templates) or report query, sent as the answer to the submit |
+| `human_task_create` | Human Task – Create | `{"definition": "LEAVE_APPROVAL", "detail_pk": "&P7_ID.", "parameters": {"DAYS": "&P7_DAYS."}, "id_item": "P7_TASK_ID"}` | Creates a task ([approvals](#approvals-and-the-task-list)) and puts its id in the item |
+| `human_task_manage` | Human Task – Manage | `{"action": "approve", "task": "&P8_TASK_ID.", "comment": "&P8_COMMENT."}` | `approve`, `reject`, `complete` (with `"outcome"`), `claim`, `release`, `delegate` (with `"to"`) or `cancel`; the task functions decide who may |
+| `form_init` | Form – Initialization | – | Nothing: a form region fetches its row by itself. Kept so imported pages show it |
+
 ### Generate text with AI
 
 An `ai_generate` process (APEX: *Generate Text with AI*) sends a prompt to a large language model
@@ -489,7 +531,7 @@ looked up by SQL, a derived value.
 | `point` | `before_header`: when the page is shown (after the form fetch, before the `load` processes). `after_submit`: after the posted values are stored, before the validations |
 | `type` | How `expression` is read, see below |
 | `expression` | The value, item, query, expression or function body |
-| `condition_type`, `condition_expr`, `condition_value` | Only when the [condition](#conditions-of-computations-processes-and-branches) holds |
+| `condition_type`, `condition_expr`, `condition_value` | Only when the [condition](#server-side-conditions) holds |
 | `authz` | Only for users who pass this authorization scheme |
 | `seq` | Order; later computations see the values of earlier ones |
 
@@ -545,7 +587,7 @@ dialog closes instead, and the calling page reloads.
 | `target_url` | A path inside the application (after `/a/<alias>/`), e.g. `12?view=month` or `account`; `&ITEM.` values are URL-encoded. Other sites are refused (no scheme, `//`, `\` or `..`) |
 | `target_function` | `function`: a PL/pgSQL function body that returns such a path (APEX: *Function returning a URL*), run as the application's role with binds; checked like `target_url` (`meta.branch_path_ok`). An empty result: the branch doesn't apply; a refused one shows a message and is logged |
 | `target_app` | `app`: the alias of another application of this installation (APEX: *Branch to page in another application*). It must exist with that page (else the branch doesn't apply and a message is shown); the items are signed for that application, page and user. That application's own sign-in and authorization apply when the browser gets there |
-| `condition_type`, `condition_expr`, `condition_value` | Only when the [condition](#conditions-of-computations-processes-and-branches) holds |
+| `condition_type`, `condition_expr`, `condition_value` | Only when the [condition](#server-side-conditions) holds |
 | `authz`, `seq`, `build_option` | As for other components |
 
 A `before_header` branch to the page itself is skipped (it would loop).
@@ -560,18 +602,47 @@ begin
 end
 ```
 
-### Conditions of computations, processes and branches
+### Server-side conditions
+
+Every component has the same server-side condition (sprint 154; APEX: *Server-side Condition*):
+regions, items, buttons, dynamic actions, validations, processes, computations, branches and
+application computations. In the Page Designer it is the **Server-side condition** group:
+*Condition type*, *Expression / item* and *Value*.
 
 | `condition_type` | Holds when |
 |---|---|
-| (empty) | always |
-| `sql` | `condition_expr`, a boolean SQL expression, is true |
-| `exists` / `not_exists` | the query in `condition_expr` returns a row / no row |
-| `item_null` / `item_not_null` | the item named in `condition_expr` is empty / has a value |
-| `item_equals` / `item_not_equals` | that item's value is / is not `condition_value` |
-| `request_in` | the request (the button pressed) is one of `condition_value`, comma separated |
-
-A condition whose SQL fails counts as false and shows the error.
+| (empty) | always (a region's or button's `condition` without a type: the SQL below) |
+| `sql` | the expression, a boolean SQL expression, is true |
+| `exists` / `not_exists` | the query in the expression returns a row / no row |
+| `function_body` | the PL/pgSQL body in the expression returns true (`return :P3_QTY::int > 0;`) |
+| `request_in` / `request_not_in` | the request (the button pressed) is / is not one of the value's names, comma separated (`SAVE,CREATE`) |
+| `item_null` / `item_not_null` | the item named in the expression is empty / has a value |
+| `item_zero` / `item_not_zero` | that item is / is not zero (an empty item is not zero) |
+| `item_null_or_zero` / `item_not_null_or_zero` | that item is empty or zero / neither |
+| `item_equals` / `item_not_equals` | that item's value is / is not the value |
+| `item_equals_item` / `item_not_equals_item` | that item's value is / is not the value of the item named in the value |
+| `item_in_list` / `item_not_in_list` | that item's value is / is not one of the value's entries, separated by colons (`CLERK:ANALYST`) |
+| `page_in` / `page_not_in` | the current page is / is not one of the value's page numbers (`1,3`) |
+| `page_is_dialog` / `page_is_not_dialog` | the page is / is not a modal dialog |
+| `user_signed_in` / `user_public` | the user is signed in / is the public user |
+| `language_in` / `language_not_in` | the application's language for this request is / is not one of the value's codes (`de,pt-br`; `pt` also matches `pt-br`) |
+| `always` / `never` | always / never (for a component you want to keep but switch off: a build option does it for a release) |
+
+Only `sql`, `exists`, `not_exists` and `function_body` run SQL, as the application's database
+role, in the request's transaction; the others are decided by the server without a query. The
+database refuses a condition whose expression or value doesn't fit its type (`meta.condition_ok`).
+
+A condition whose SQL fails counts as false and shows the error. Regions and buttons keep their
+`condition` column as the expression: without a type it is SQL, as before, so older exports keep
+working. Dynamic actions name theirs `server_condition_type`, `server_condition_expr` and
+`server_condition_value` (their `condition_type` is the client-side condition): when it doesn't
+hold, the dynamic action isn't on the page.
+
+The Page Designer's tree shows the condition in words on the component's filter badge (*When
+P3_JOB is one of CLERK, ANALYST*), in the builder's language. The
+[Advisor](03-builder.md#advisor) names SQL conditions a type can say exactly (`:P3_ID is not null`,
+`:REQUEST in ('SAVE', 'CREATE')`, `:P3_JOB = 'CLERK'`) as information; `<>` and `not in` stay SQL,
+because in SQL an empty item makes them false.
 
 **HR example, page 22 (Leave planner).** Computations fill the employee (yours, when none is
 chosen: `sql_query` with condition `item_null`), the name (`function_body`) and the pending
@@ -1099,6 +1170,22 @@ background runs with the tenant of the session that queued it. Filter your own t
 (`where tenant_id = meta.tenant_id()`, or a row level security policy). Use row level security in
 the tenant's tables as well: the tenant is a value the application sets, not a database boundary.
 
+### Workflow diagram region
+
+Sprint 160 (APEX 24.2+: Workflow Diagram region). A region of type `workflow_diagram` draws one
+workflow instance in a running application: its version's steps, the ones it went through (green),
+where it is now (blue, several with parallel branches) and a failed step (red, with the error above
+the diagram). Each reached step's tooltip lists when it was reached and what happened. The instance
+id comes from an item:
+
+```json
+{"instance_item": "P9_WORKFLOW_ID"}
+```
+
+It is read through `meta.workflows` as the application's role, so a user sees only workflows they
+started or administer (the Workflow Console's rule); others see the empty text. The diagram is SVG
+drawn on the server: it needs no JavaScript.
+
 ### Send e-mail steps
 
 A `send_mail` step (APEX 26.1: the *Send E-Mail* activity) queues an e-mail through the application's mail service,

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

@@ -12,7 +12,8 @@ your own from a static application file.
 |---|---|
 | `event` | When it runs, see [Events](#events) |
 | `trigger_element` | What it listens to: item names (`change`, `focus`, `blur`, `key_release`), a button name (`click`), region ids or static ids (`after_refresh`, `selection_change`), dialog page numbers (`dialog_closed`; empty: any dialog) or event names (`custom`), comma separated. Empty for `load` and `before_submit` |
-| `condition_type`, `condition_value` | Optional client-side condition on the (first) trigger item's value (for `dialog_closed`: on the dialog's page number): `equals`, `not_equals`, `in_list` (comma-separated values), `is_null`, `is_not_null` |
+| `condition_type`, `condition_value` | Optional client-side condition on the (first) trigger item's value (for `dialog_closed`: on the dialog's page number): `equals`, `not_equals`, `greater`, `greater_equal`, `less`, `less_equal` (numbers as numbers, other values such as ISO dates as text; an empty value fails them), `in_list`, `not_in_list` (comma-separated values), `is_null`, `is_not_null`. APEX's *JavaScript expression* isn't offered: the Content-Security-Policy runs no code from strings; use `execute_javascript` with a registered function |
+| `server_condition_type`, `server_condition_expr`, `server_condition_value` | A [server-side condition](06-processing.md#server-side-conditions) (sprint 154): when it doesn't hold for this request, the dynamic action isn't on the page at all, e.g. `user_signed_in` or `page_is_dialog` |
 | `action` | What to do, see below |
 | `affected_items`, `affected_region_id` | What it acts on |
 | `code` | SQL for server-side actions; the function's name for `execute_javascript` |
@@ -38,6 +39,14 @@ your own from a static application file.
 | `before_submit` | The page is about to be submitted; a declined `confirm` keeps the page | – |
 | `custom` | JavaScript raised the event: `pgkiln.trigger('ORDER_SAVED', value)` (APEX: custom events, `apex.event.trigger`) | Event names (case-insensitive) |
 | `menu_entry` | An entry `{"label": …, "action": "NAME"}` of a [menu button](06-processing.md#menu-buttons-and-badges) was chosen (APEX: Menu entry chosen); the condition sees the entry's name ([below](#menu-entry-chosen)) | Entry names, or menu button names (any of their entries) |
+| `double_click` | An item, button or region was double-clicked (sprint 156) | Item names, button names, region ids or static ids |
+| `key_down` / `key_press` | A key goes down in an item / a key that types a character (APEX: Key Down, Key Press); a `cancel_event` keeps the key out of the field | Item names |
+| `mouse_enter` / `mouse_leave` | The pointer enters / leaves an item, button or region (once per element, not while moving inside it) | Item names, button names, region ids or static ids |
+| `select` | Text is selected in an item | Item names |
+| `resize` / `scroll` | The window is resized / scrolled (at most once per frame) | – |
+| `page_unload` | The page is left (APEX: Page Unload); only quick actions in the browser finish | – |
+| `before_refresh` | A region is about to be refreshed by a `refresh_region` action (APEX: Before Refresh); a `cancel_event` or declined `confirm` keeps it as it is | Region ids or static ids |
+| `facets_change` | A faceted search or smart filters region's facets were applied (APEX: Facets Change); runs on the page that comes back with the new filters | The facets region's id or static id |
 
 **The actions of one event and trigger run one after the other, in sequence order** (APEX: the true
 actions of a dynamic action), each waiting for the one before (a server action for its answer). A
@@ -82,6 +91,12 @@ actions of a dynamic action), each waiting for the one before (a server action f
 | `share` | browser | The device's share sheet with the page's title, `message` and address; where there is none, the address is copied |
 | `wait_popup` | browser | Shows a modal "please wait" popup with `message` (default *Please wait…*) until `remove_wait_popup` or the next page (APEX: Show Wait Popup); [below](#wait-popup) |
 | `remove_wait_popup` | browser | Removes the wait popup (APEX: Remove Wait Popup) |
+| `cancel_event` | browser | Stops the actions after it, and the event's own effect: a button doesn't submit or follow its link, a typed key (`key_down`, `key_press`) stays out of the field, a refresh doesn't happen (APEX: Cancel Event). Sprint 156 |
+| `set_style` | browser | Sets CSS properties on the affected items or region: `{"styles": {"color": "#b42318", "font-weight": "bold"}}` in the attributes (APEX: Set Style). Properties from a fixed list (colours, font, text, border, opacity, visibility, padding, margin, width); values without `url()` or `var()`, checked when saved and again before they reach the page |
+| `collapse_tree` / `expand_tree` | browser | Closes / opens every node of the affected tree region (APEX: Collapse Tree, Expand Tree) |
+| `show_ai_assistant` | browser | Opens the affected AI assistant region (or the inline dialog it sits in) and puts the cursor in its question (APEX: Show AI Assistant) |
+| `trigger_geocoding` | browser | The affected geocoded address item looks its text up, as its *Check address* button does (APEX: Trigger Geocoding) |
+| `open_report_dialog` | browser | Opens a dialog of the affected interactive report: `code` is `filter`, `columns`, `sort`, `highlight`, `compute`, `aggregate`, `chart`, `group`, `pivot`, `break`, `rows` or `saved` (APEX: Invoke Interactive Report Dialog) |
 
 Server-side actions first store `items_to_submit` in session state, run as the application's
 database role like everything else, and check the page's and the dynamic action's authorization.

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

@@ -38,6 +38,13 @@ What's missing is listed in the [feature parity matrix](../apex-feature-parity.m
 | Before-header processes | Process `point = 'load'` |
 | Page computations (static, item, SQL query, SQL expression, PL/SQL function body) | Computations `before_header` / `after_submit`; function bodies are PL/pgSQL ([chapter 6](06-processing.md#computations)) |
 | Branches (page or URL, *When button pressed*, server-side condition), before header and after processing | Branches with `when_button` and a condition; URLs stay inside the application ([chapter 6](06-processing.md#branches)) |
+| Validation types (Rows returned, Expression, Function Body returning Boolean / Error Text, Item is NOT NULL / numeric / a valid date …, Item = Value, Item in Value, character checks, Regular Expression), Always Execute, Display Location | The same types as `type` (`exists`, `sql`, `function_body`, `function_error`, `not_null`, `numeric`, `valid_date`, `equals`, `in_list`, `chars_only`, `regex` …), `always_execute`, `display_location` ([chapter 6](06-processing.md#validations)). Interactive grid column validations aren't there yet: use a validation on the grid's process or a check constraint |
+| Dynamic action events (Double Click, Key Down / Press, Mouse Enter / Leave, Select, Resize, Scroll, Page Unload, Before Refresh, Facets Change), conditions (greater / less than, not in list) and actions (Cancel Event, Set Style, Collapse / Expand Tree, Show AI Assistant, Trigger Geocoding, Invoke Interactive Report Dialog) | The same events, conditions and actions ([chapter 7](07-dynamic-actions.md)). Not yet: grid, calendar, map and tree component events; JavaScript expression conditions (use a registered function) |
+| Workflow Diagram region | `workflow_diagram` with `{"instance_item": …}` ([chapter 6](06-processing.md#workflow-diagram-region)) |
+| Map layers Points, Lines, Polygons, Heat Map, Extruded Polygons | `"layer"`: `markers`, `lines`, `polygons`, `heat`, `extruded` (drawn flat, shaded by height), with fill and line colours, width and opacity per layer or per row ([chapter 4](04-pages-and-regions.md#map)) |
+| Items Image Upload, Text Field with autocomplete, Percent Graph, Display Map | `image_upload`, `autocomplete`, `percent_graph`, `display_map` ([chapter 5](05-items.md#item-types)) |
+| Process types Close Dialog, Clear Session State, Reset Pagination, User Preferences, Server Side Geocoding, Print Report, Human Task – Create / – Manage, Form – Initialization | The same as `type` ([chapter 6](06-processing.md#declarative-process-types)), settings in the attributes |
+| Server-side Condition (Rows returned, Expression, Function Body, Request = / != / is contained in, Item is NULL / NOT NULL / zero / = Value / in colon list, Current page in, Current page is a modal dialog, User is authenticated / public user, Current language in, Always / Never …) | The same list as `condition_type`: `exists`, `sql`, `function_body`, `request_in` / `request_not_in`, `item_null` / `item_not_null` / `item_zero` / `item_equals` / `item_in_list`, `page_in`, `page_is_dialog`, `user_signed_in` / `user_public`, `language_in`, `always` / `never` ([chapter 6](06-processing.md#server-side-conditions)). APEX's colon lists stay colon lists; *Request is contained in* takes commas |
 | Build options (include / exclude) | Build options; `!NAME` for APEX's "exclude when the option is included" ([chapter 6](06-processing.md#build-options)) |
 | Menu button, button badge | Button action `menu`; `badge` / `badge_query` |
 | Dynamic actions *Set Focus*, *Add / Remove Class*, *Show Success / Error Message*, *Clear Errors* | `set_focus`, `add_class` / `remove_class`, `show_success` / `show_error`, `clear_errors` |

package/examples/hr/hr_79_condition_types.sql

@@ -0,0 +1,17 @@
+-- =====================================================================
+-- HR example, part 79: declarative server-side conditions (sprint 154, CD-2)
+--
+-- The Employee page's buttons showed with SQL conditions such as
+-- ":P3_EMPNO is not null". The same tests as condition types: no query,
+-- and the Page Designer's tree says "When P3_EMPNO is not empty".
+-- Department (page 5) gets the same; the leave request's Approve and
+-- Reject (page 7) stay SQL: they call hr.current_empno().
+-- =====================================================================
+
+update meta.button b
+   set condition_type = case when b.condition ~* ' is not null$' then 'item_not_null' else 'item_null' end,
+       condition = substring(b.condition from '^:([A-Z][A-Z0-9_]*) ')
+  from meta.page p join meta.app a on a.id = p.app_id
+ where b.page_id = p.id and a.alias = 'hr' and p.page_no in (3, 5)
+   and b.condition_type is null
+   and b.condition ~ '^:P[35]_(EMPNO|DEPTNO) is (not )?null$';

package/package.json

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

package/public/app.css

@@ -1497,6 +1497,8 @@ path.map-near { stroke: #1f2733; stroke-dasharray: 6 4; fill: #1f2733; fill-opac
 .wf-invoke_api rect { stroke: #1f7a8c; stroke-width: 2; stroke-dasharray: 2 2; }
 .wf-active rect { fill: var(--accent-soft); stroke: var(--accent); stroke-width: 3; }
 .wf-active .wf-name { fill: var(--text); }
+.wf-done rect { fill: var(--success-soft, #e7f5ed); stroke: var(--success, #17794a); }
+.wf-failed rect { fill: var(--danger-soft, #fde7e4); stroke: var(--danger, #b42318); stroke-width: 3; }
 .wf-warnings { background: var(--warning-soft); color: var(--text); border-color: var(--border); }
 .wf-version-actions { display: flex; flex-wrap: wrap; gap: 0.4rem; margin: 0; }
 .wf-version-diagram summary { cursor: pointer; }
@@ -2251,3 +2253,13 @@ body.nav-pillar-dark .t-nav details:has(> summary.in-trail) > ul { border-inline
 .mfa-factors { list-style: none; padding: 0; margin: 0 0 .75rem; }
 .mfa-factors li { padding: .4rem 0; border-bottom: 1px solid var(--border); }
 @media (max-width: 480px) { .mfa-codes { columns: 1; } }
+
+/* (sprint 158) Percent Graph and Display Map items */
+.percent-graph { display: flex; align-items: center; gap: .5rem; }
+.percent-graph progress { flex: 1; max-width: 16rem; height: .75rem; accent-color: var(--t-accent, #2563eb); }
+.percent-graph-value { font-variant-numeric: tabular-nums; min-width: 3.5ch; text-align: right; }
+.display-map { margin: 0; display: inline-block; max-width: 100%; }
+.display-map-tile { position: relative; width: 256px; max-width: 100%; aspect-ratio: 1; overflow: hidden; border-radius: 6px; border: 1px solid var(--t-border, #d0d5dd); }
+.display-map-tile img { display: block; width: 100%; height: 100%; }
+.display-map-pin { position: absolute; width: 14px; height: 14px; margin: -7px 0 0 -7px; border-radius: 50%; background: #d92d20; border: 2px solid #fff; box-shadow: 0 0 0 1px rgba(0,0,0,.35); }
+.display-map figcaption { font-size: .8rem; margin-top: .25rem; }

package/public/app.js

@@ -341,9 +341,17 @@ const pgkilnUnsaved = (() => {
       case 'in_list': return da.cond.value.split(',').map((s) => s.trim()).includes(v);
       case 'is_null': return v === '';
       case 'is_not_null': return v !== '';
+      // (156) numbers compared as numbers, other values (ISO dates) as text
+      case 'greater': return v !== '' && compare(v, da.cond.value) > 0;
+      case 'greater_equal': return v !== '' && compare(v, da.cond.value) >= 0;
+      case 'less': return v !== '' && compare(v, da.cond.value) < 0;
+      case 'less_equal': return v !== '' && compare(v, da.cond.value) <= 0;
+      case 'not_in_list': return !da.cond.value.split(',').map((s) => s.trim()).includes(v);
       default: return true;
     }
   }
+  const NUM = /^\s*-?\d+(\.\d+)?\s*$/;
+  const compare = (a, b) => (NUM.test(a) && NUM.test(b) ? Number(a) - Number(b) : a < b ? -1 : a > b ? 1 : 0);
 
   // ------------------------------------------------------------ messages and errors (dynamic actions)
   // class names a dynamic action may add or remove (the database checks the same pattern)
@@ -499,6 +507,8 @@ const pgkilnUnsaved = (() => {
 
   /** (085) what runDa returns to stop the actions after it (a declined confirm) */
   const STOP = Symbol('stop');
+  /** (156) does a Cancel Event in these actions hold its condition (decided at once, so the event's effect can be stopped)? */
+  const cancels = (list) => list.some((da) => da.action === 'cancel_event' && conditionHolds(da));
   const text = (k) => (meta.texts && meta.texts[k]) || k;
 
   /** The actions of one event and trigger, one after the other in sequence order; false when one stopped them. */
@@ -580,6 +590,37 @@ const pgkilnUnsaved = (() => {
     }
     if (initial || !holds) return;
     switch (da.action) {
+      // (156) stops the actions after it; the triggering event's own effect is stopped by its handler (cancels())
+      case 'cancel_event':
+        return STOP;
+      case 'set_style':
+        for (const el of targets(da)) for (const [k, v] of Object.entries(da.styles || {})) el.style.setProperty(k, v);
+        return;
+      case 'collapse_tree':
+      case 'expand_tree':
+        for (const el of targets(da)) el.querySelectorAll('.tree-view details').forEach((d) => (d.open = da.action === 'expand_tree'));
+        return;
+      case 'show_ai_assistant':
+        for (const el of targets(da)) {
+          const dlg = el.closest('dialog[data-inline-region]') || (el.matches('dialog[data-inline-region]') ? el : null);
+          if (dlg && !dlg.open) dlg.showModal();
+          el.hidden = false;
+          const details = el.querySelector(':scope > details');
+          if (details) details.open = true;
+          const input = el.querySelector('textarea, input[type=text]') || (el.id && document.querySelector(`form[id^="${el.id}"] textarea`));
+          if (input) input.focus();
+          else el.scrollIntoView({ block: 'nearest' });
+        }
+        return;
+      case 'trigger_geocoding':
+        for (const n of da.items) document.querySelector(`[data-geocode="${CSS.escape(n)}"]`)?.click();
+        return;
+      case 'open_report_dialog':
+        for (const el of targets(da)) {
+          const item = da.dialog && el.querySelector(`.ir-item[data-ir-dialog="${CSS.escape(da.dialog)}"]`);
+          if (item) item.open = true;
+        }
+        return;
       case 'alert':
         window.alert(da.message || '');
         return;
@@ -698,6 +739,12 @@ const pgkilnUnsaved = (() => {
         return;
       }
     }
+    // (156) before_refresh: the region's actions run before its refresh is asked for
+    if (da.action === 'refresh_region' && da.region) {
+      const r = document.getElementById(`R${da.region}`);
+      const before = regionRun('before_refresh', r);
+      if (before.length && !(await runChain(before))) return;
+    }
     const data = { ...(extra || {}) };
     for (const n of da.submit) data[n] = itemValue(n);
     const busy = targets(da);
@@ -727,6 +774,12 @@ const pgkilnUnsaved = (() => {
   }
 
   const das = meta.das || [];
+  // region events (trigger: region ids or static ids, case-insensitive)
+  const regionRun = (event, region) => {
+    if (!region || !/^R\d+$/.test(region.id || '')) return [];
+    const keys = [region.id.slice(1), (region.dataset.staticId || '').toLowerCase()].filter(Boolean);
+    return das.filter((da) => da.event === event && da.trigger.some((t) => keys.includes(String(t).toLowerCase())));
+  };
   // (121) an AI agent's javascript tools: after the answer, the registered function of the action
   // (pgkiln.actions.register) and the dynamic actions of the custom event of that name, with the arguments
   scriptsLoaded.then(async () => {
@@ -760,6 +813,8 @@ const pgkilnUnsaved = (() => {
     const btn = e.target.closest('[data-button]');
     if (!btn || e.target.closest('[data-menu-entry]')) return;
     const run = das.filter((da) => da.event === 'click' && da.trigger.includes(btn.dataset.button));
+    // (156) a Cancel Event whose condition holds: the button doesn't submit or follow its link
+    if (cancels(run)) e.preventDefault();
     // "Generate text with AI" on a submit button: the AJAX call replaces the submit
     // (without JavaScript the button submits and the page process runs instead)
     const ai = run.some((da) => da.action === 'ai_generate');
@@ -803,12 +858,68 @@ const pgkilnUnsaved = (() => {
   document.addEventListener('focusin', itemEvent('focus'));
   document.addEventListener('focusout', itemEvent('blur'));
   document.addEventListener('keyup', itemEvent('key_release'));
-  // region events (trigger: region ids or static ids, case-insensitive)
-  const regionRun = (event, region) => {
-    if (!region || !/^R\d+$/.test(region.id || '')) return [];
-    const keys = [region.id.slice(1), (region.dataset.staticId || '').toLowerCase()].filter(Boolean);
-    return das.filter((da) => da.event === event && da.trigger.some((t) => keys.includes(String(t).toLowerCase())));
+  // (156) key_down, key_press (a key that types a character), select (text selected in an item)
+  document.addEventListener('keydown', (e) => {
+    const name = e.target && e.target.name;
+    if (!name) return;
+    const down = das.filter((da) => da.event === 'key_down' && da.trigger.includes(name));
+    const press = e.key && e.key.length === 1 && !e.ctrlKey && !e.metaKey ? das.filter((da) => da.event === 'key_press' && da.trigger.includes(name)) : [];
+    // a Cancel Event on key_down / key_press keeps the key out of the field
+    if (cancels([...down, ...press])) e.preventDefault();
+    if (down.length) runChain(down);
+    if (press.length) runChain(press);
+  });
+  document.addEventListener('select', itemEvent('select'), true);
+  // double_click, mouse_enter, mouse_leave: an item (its name), a button (its name) or a region (id or static id)
+  const elementRun = (event, target) => {
+    if (!target || !target.closest) return [];
+    const item = target.closest('[name]');
+    const btn = target.closest('[data-button]');
+    const region = target.closest('section[id^="R"], div[id^="R"], dialog[id^="R"]');
+    const names = [item && item.name, btn && btn.dataset.button].filter(Boolean);
+    return [...new Set([...das.filter((da) => da.event === event && da.trigger.some((t) => names.includes(t))), ...regionRun(event, region)])];
   };
+  document.addEventListener('dblclick', (e) => {
+    const run = elementRun('double_click', e.target);
+    if (run.length) runChain(run);
+  });
+  // enter / leave: once per element, not again while moving inside it
+  const hovered = new Set();
+  document.addEventListener('mouseover', (e) => {
+    for (const da of elementRun('mouse_enter', e.target)) if (!hovered.has(da)) { hovered.add(da); runChain([da]); }
+  });
+  document.addEventListener('mouseout', (e) => {
+    const leaving = elementRun('mouse_enter', e.target).concat(elementRun('mouse_leave', e.target));
+    const still = new Set([...elementRun('mouse_enter', e.relatedTarget), ...elementRun('mouse_leave', e.relatedTarget)]);
+    for (const da of leaving) {
+      if (still.has(da)) continue;
+      hovered.delete(da);
+      if (da.event === 'mouse_leave') runChain([da]);
+    }
+  });
+  // resize, scroll: the window (at most one run per animation frame)
+  for (const [event, dom] of [['resize', 'resize'], ['scroll', 'scroll']]) {
+    const run = das.filter((da) => da.event === event);
+    if (!run.length) continue;
+    let queued = false;
+    window.addEventListener(dom, () => {
+      if (queued) return;
+      queued = true;
+      requestAnimationFrame(() => { queued = false; runChain(run); });
+    }, { passive: true });
+  }
+  // page_unload: the page is left (only quick, local actions finish)
+  window.addEventListener('pagehide', () => runChain(das.filter((da) => da.event === 'page_unload')));
+  // facets_change: a faceted search region's facets were applied (the page came back from its form)
+  {
+    const params = new URLSearchParams(location.search);
+    const changed = params.get('facets_changed');
+    if (changed) {
+      params.delete('facets_changed');
+      history.replaceState(history.state, '', `${location.pathname}${params.size ? `?${params}` : ''}${location.hash}`);
+      runChain(regionRun('facets_change', document.getElementById(`R${changed.replace(/\D/g, '')}`)));
+    }
+  }
   // after_refresh: a region replaced by a refresh, a lazy load or a master row
   document.addEventListener('pgkiln:replaced', (e) => {
     const run = regionRun('after_refresh', e.detail);
@@ -1011,6 +1122,10 @@ const pgkilnUnsaved = (() => {
     const dlg = document.getElementById('t-dialog');
     if (dlg) dlg.close();
     if (!e.data.reload) return;
+    // (157) items a close_dialog process returned: items of the same name on this page take their values
+    if (e.data.items && typeof e.data.items === 'object')
+      for (const [name, value] of Object.entries(e.data.items))
+        if (/^[A-Z][A-Z0-9_]{0,99}$/.test(name) && typeof value === 'string' && wrapperOf(name)) setItemValue(name, value);
     const page = /^\d{1,9}$/.test(String(e.data.page || '')) ? String(e.data.page) : '';
     const handlers = das.filter((da) => da.event === 'dialog_closed' && (!da.trigger.length || da.trigger.includes(page)));
     if (!handlers.length) return location.reload();
@@ -1248,7 +1363,10 @@ const pgkilnUnsaved = (() => {
 
   // Inside a dialog: close on success or cancel.
   if (window.parent !== window) {
-    const tell = (reload) => window.parent.postMessage({ type: 'pgkiln:close', reload, page: body.dataset.dialogPage || '' }, location.origin);
+    // (157) a close_dialog process's items go along to the page below
+    let items = null;
+    try { items = body.dataset.dialogItems ? JSON.parse(body.dataset.dialogItems) : null; } catch { items = null; }
+    const tell = (reload) => window.parent.postMessage({ type: 'pgkiln:close', reload, page: body.dataset.dialogPage || '', items }, location.origin);
     if (body.dataset.dialogClose) tell(true);
     document.addEventListener('click', (e) => {
       if (!e.target.closest('[data-dialog-cancel]')) return;
@@ -1841,7 +1959,20 @@ document.addEventListener('change', (e) => {
     const custom = e.target.closest('fieldset')?.querySelector('[data-facet-range]');
     custom?.querySelectorAll('input').forEach((i) => (i.value = ''));
   }
-  e.target.form?.requestSubmit();
+  // (156) the page that comes back runs the region's facets_change dynamic actions
+  const f = e.target.form;
+  const region = e.target.closest('[id^="R"]');
+  if (f && region && /^R\d+$/.test(region.id)) {
+    let mark = f.querySelector('input[name="facets_changed"]');
+    if (!mark) {
+      mark = document.createElement('input');
+      mark.type = 'hidden';
+      mark.name = 'facets_changed';
+      f.appendChild(mark);
+    }
+    mark.value = region.id.slice(1);
+  }
+  f?.requestSubmit();
 });
 document.addEventListener('input', (e) => {
   const box = e.target.closest?.('[data-facet-range]');
@@ -3162,6 +3293,17 @@ document.addEventListener('DOMContentLoaded', () => {
   }
 });
 
+// (159) Leaflet path options from a shape layer's checked style
+function shapeStyle(st, kind) {
+  if (!st) return {};
+  const o = {};
+  if (st.stroke_color) o.color = st.stroke_color;
+  if (typeof st.stroke_width === 'number') o.weight = st.stroke_width;
+  if (st.fill_color) { o.fillColor = st.fill_color; o.fill = kind !== 'lines'; }
+  if (typeof st.opacity === 'number') { if (kind === 'lines') o.opacity = st.opacity; else o.fillOpacity = st.opacity; }
+  return o;
+}
+
 // One layer's Leaflet parts: markers (clustered or not) or a heat map, with its lines and areas.
 function layerParts(l, popup, data, several) {
   const parts = [];
@@ -3170,8 +3312,14 @@ function layerParts(l, popup, data, several) {
   else for (const p of l.points) parts.push(placeMarker(p, l, popup, several));
   if (l.shapes.length)
     parts.push(window.L.geoJSON({ type: 'FeatureCollection', features: l.shapes }, {
-      style: () => (several ? { className: `map-c${l.color}` } : {}),
-      onEachFeature: (f, layer) => layer.bindPopup(() => popup(f.properties)),
+      // (159) a lines / polygons / extruded layer's colours, width and opacity (checked on the server: #rrggbb, numbers)
+      style: (f) => ({ ...(several ? { className: `map-c${l.color}` } : {}), ...shapeStyle(f.properties && f.properties.style, l.kind) }),
+      onEachFeature: (f, layer) => {
+        layer.bindPopup(() => popup(f.properties));
+        // a shape's title as its tooltip (and its height on an extruded layer)
+        const tip = [f.properties && f.properties.title, f.properties && typeof f.properties.height === 'number' ? String(f.properties.height) : ''].filter(Boolean).join(': ');
+        if (tip && layer.bindTooltip) layer.bindTooltip(tip, { sticky: true });
+      },
     }));
   return parts;
 }