pgkiln 0.80.0 → 0.82.0

package/src/ai/embeddings.ts

@@ -18,8 +18,13 @@ import { AiError } from './types.ts';
 // The dimensions are part of the definition: every embedding is checked against them, and the builder checks
 // them against the vector column (vector(n)) a search configuration or a vector column helper uses.
 
-export type VectorProviderType = 'ai_service' | 'function';
-export const VECTOR_PROVIDER_TYPES: VectorProviderType[] = ['ai_service', 'function'];
+export type VectorProviderType = 'ai_service' | 'function' | 'database_model';
+export const VECTOR_PROVIDER_TYPES: VectorProviderType[] = ['ai_service', 'function', 'database_model'];
+/** (sprint 151, migration 146) the extensions that run a model in the database: pgml = PostgresML's pgml.embed(model, text) */
+export const MODEL_ENGINES = ['pgml'] as const;
+export type ModelEngine = (typeof MODEL_ENGINES)[number];
+/** A provider that embeds in the database (meta.embed, as the caller): a function, or a model in the database. */
+export const embedsInDatabase = (p: { type?: unknown }) => p.type === 'function' || p.type === 'database_model';
 
 export interface VectorProvider {
   name: string;
@@ -32,6 +37,8 @@ export interface VectorProvider {
   dimensions: number;
   /** function: schema.name */
   function?: string;
+  /** (151) database_model: the extension that runs the model (model: its name, e.g. intfloat/e5-small-v2) */
+  engine?: ModelEngine;
   /** ai_service: texts per request (background embedding; default 64) */
   batch_size?: number;
   /** ai_service: requests per minute (background embedding; default 60) */
@@ -59,7 +66,7 @@ export function vectorProviderProblems(p: unknown): string[] {
   const what = `Vector provider ${typeof p.name === 'string' ? p.name : '?'}`;
   const out: string[] = [];
   if (typeof p.name !== 'string' || !PROVIDER_NAME.test(p.name)) out.push(`${what}: the name (static ID) is upper case letters, digits and _ (e.g. DOC_EMBEDDINGS).`);
-  if (!VECTOR_PROVIDER_TYPES.includes(p.type)) out.push(`${what}: the type is ai_service or function.`);
+  if (!VECTOR_PROVIDER_TYPES.includes(p.type)) out.push(`${what}: the type is ai_service, function or database_model.`);
   if (p.description !== undefined && p.description !== null && (typeof p.description !== 'string' || p.description.length > 500)) out.push(`${what}: the description is text (at most 500 characters).`);
   if (!intIn(p.dimensions, 1, MAX_DIMENSIONS)) out.push(`${what}: the dimensions are a whole number from 1 to ${MAX_DIMENSIONS}.`);
   if (p.type === 'ai_service') {
@@ -67,6 +74,12 @@ export function vectorProviderProblems(p: unknown): string[] {
     if (typeof p.model !== 'string' || !MODEL.test(p.model)) out.push(`${what}: the embedding model is its name, e.g. text-embedding-3-small or nomic-embed-text.`);
     if (p.function !== undefined) out.push(`${what}: an AI service provider has no function.`);
   }
+  if (p.type === 'database_model') {
+    if (!MODEL_ENGINES.includes(p.engine)) out.push(`${what}: the engine is ${MODEL_ENGINES.join(' or ')} (the extension that runs the model in the database).`);
+    if (typeof p.model !== 'string' || !MODEL.test(p.model)) out.push(`${what}: the model is its name, e.g. intfloat/e5-small-v2.`);
+    if (p.service !== undefined || p.function !== undefined) out.push(`${what}: a database model provider has no AI service or function.`);
+  }
+  if (p.type !== 'database_model' && p.engine !== undefined) out.push(`${what}: only a database model provider has an engine.`);
   if (p.type === 'function') {
     if (typeof p.function !== 'string' || !FUNCTION_NAME.test(p.function)) out.push(`${what}: the function is schema.name, e.g. sales.embed.`);
     if (p.service !== undefined || p.model !== undefined) out.push(`${what}: a function provider has no AI service or model.`);
@@ -126,11 +139,11 @@ export interface EmbedInfo extends Pick<CallInfo, 'appId' | 'pageNo' | 'user' |
 export async function embedTexts(p: VectorProvider, texts: string[], info: EmbedInfo, client?: Queryable): Promise<number[][]> {
   if (!texts.length) return [];
   const input = texts.map((t) => String(t ?? '').slice(0, MAX_TEXT_CHARS));
-  if (p.type === 'function') {
-    if (!client) throw new AiError('config', `Vector provider ${p.name}: a function provider needs a database connection.`);
+  if (embedsInDatabase(p)) {
+    if (!client) throw new AiError('config', `Vector provider ${p.name}: a ${p.type === 'function' ? 'function' : 'database model'} provider needs a database connection.`);
     const rows = (await client.query('select meta.embed(t, $2, $3) as v from unnest($1::text[]) with ordinality u(t, n) order by n', [input, p.name, info.appId])).rows;
     return rows.map((r: { v: number[] | null }) => {
-      if (!Array.isArray(r.v)) throw new AiError('output', `Vector provider ${p.name}: the function returned no embedding.`);
+      if (!Array.isArray(r.v)) throw new AiError('output', `Vector provider ${p.name}: the ${p.type === 'function' ? 'function' : 'model'} returned no embedding.`);
       return r.v.map(Number);
     });
   }
@@ -183,7 +196,7 @@ const RECENT_MS = 10 * 60_000;
 
 /** The embedding of one search text (AI service providers: kept a few minutes in this process's memory). */
 export async function embedQuery(p: VectorProvider, text: string, info: EmbedInfo, client?: Queryable): Promise<number[]> {
-  if (p.type === 'function') return (await embedTexts(p, [text], info, client))[0];
+  if (embedsInDatabase(p)) return (await embedTexts(p, [text], info, client))[0];
   const key = JSON.stringify([info.appId, p.name, p.service, p.model, p.dimensions, text]);
   const hit = recent.get(key);
   if (hit && Date.now() - hit.at < RECENT_MS) return hit.v;

package/src/appfiles.ts

@@ -108,11 +108,11 @@ function sniff(b: Buffer) {
 // Code columns that move to a sibling file when they are long or multi-line.
 const CODE: Record<string, Record<string, string>> = {
   region: { source: 'sql', condition: 'sql' },
-  item: { default_value: 'sql', readonly_condition: 'sql' },
+  item: { default_value: 'sql', readonly_condition: 'sql', condition_expr: 'sql' },
   button: { condition: 'sql', badge_query: 'sql' },
-  dynamic_action: { code: 'sql' },
-  validation: { expression: 'sql' },
-  process: { code: 'sql' },
+  dynamic_action: { code: 'sql', server_condition_expr: 'sql' },
+  validation: { expression: 'sql', condition_expr: 'sql' },
+  process: { code: 'sql', condition_expr: 'sql' },
   computation: { expression: 'sql', condition_expr: 'sql' },
   branch: { condition_expr: 'sql' },
   app_process: { code: 'sql' },

package/src/builder/advisor.ts

@@ -1,3 +1,4 @@
+import { declarativeCondition } from './conditions.ts';
 import type { FastifyInstance } from 'fastify';
 import pg from 'pg';
 import { applyBinds, splitStatements } from '../binds.ts';
@@ -52,15 +53,16 @@ export function sqlFields(kind: string, row: any): { name: string; shape: SqlSha
     case 'region':
       return [
         ...(['report', 'classic_report', 'grid', 'chart', 'cards', 'calendar', 'map', 'tree', 'dynamic'].includes(row.type) && row.source?.trim() && !row.rest_source ? [{ name: 'source', shape: 'select' as const }] : []),
-        { name: 'condition', shape: 'boolean' },
+        ...conditionSql(row, 'condition'),
       ];
     case 'item':
       return [
         ...(row.lov?.trim() && !/^(STATIC|LOV):/i.test(row.lov.trim()) ? [{ name: 'lov', shape: 'select' as const }] : []),
         { name: 'readonly_condition', shape: 'boolean' },
+        ...conditionSql(row),
       ];
     case 'button':
-      return [{ name: 'condition', shape: 'boolean' }, { name: 'badge_query', shape: 'select' }];
+      return [...conditionSql(row, 'condition'), { name: 'badge_query', shape: 'select' }];
     case 'computation':
     case 'app_computation':
       return [
@@ -70,9 +72,16 @@ export function sqlFields(kind: string, row: any): { name: string; shape: SqlSha
     case 'branch':
       return conditionSql(row);
     case 'dynamic_action':
-      return row.action === 'set_value' ? [{ name: 'code', shape: 'select' }] : row.action === 'execute_sql' ? [{ name: 'code', shape: 'statements' }] : [];
+      return [
+        ...(row.action === 'set_value' ? [{ name: 'code', shape: 'select' as const }] : row.action === 'execute_sql' ? [{ name: 'code', shape: 'statements' as const }] : []),
+        ...conditionSql({ condition_type: row.server_condition_type }, 'server_condition_expr'),
+      ];
     case 'validation':
-      return row.type === 'sql' ? [{ name: 'expression', shape: 'boolean' }] : row.type === 'regex' ? [{ name: 'expression', shape: 'regex' }] : [];
+      return [
+        ...(row.type === 'sql' ? [{ name: 'expression', shape: 'boolean' as const }] : row.type === 'regex' ? [{ name: 'expression', shape: 'regex' as const }]
+          : row.type === 'exists' || row.type === 'not_exists' ? [{ name: 'expression', shape: 'select' as const }] : []),
+        ...conditionSql(row),
+      ];
     case 'process':
       return [
         ...(row.type === 'sql' ? [{ name: 'code', shape: 'statements' as const }] : row.type === 'download' ? [{ name: 'code', shape: 'select' as const }] : []),
@@ -104,9 +113,14 @@ export function sqlFields(kind: string, row: any): { name: string; shape: SqlSha
   }
 }
 
-/** The SQL of a computation's or branch's condition (migration 029). */
-const conditionSql = (row: any): { name: string; shape: SqlShape }[] =>
-  row.condition_type === 'sql' ? [{ name: 'condition_expr', shape: 'boolean' }] : row.condition_type === 'exists' || row.condition_type === 'not_exists' ? [{ name: 'condition_expr', shape: 'select' }] : [];
+/**
+ * The SQL of a server-side condition (migrations 029, 147). `field` holds the expression; for regions and
+ * buttons (`condition`) no type means SQL.
+ */
+const conditionSql = (row: any, field = 'condition_expr'): { name: string; shape: SqlShape }[] => {
+  const type = row.condition_type || (field === 'condition' && row.condition?.trim() ? 'sql' : null);
+  return type === 'sql' ? [{ name: field, shape: 'boolean' }] : type === 'exists' || type === 'not_exists' ? [{ name: field, shape: 'select' }] : [];
+};
 
 export const EXPLAINABLE = /^\s*(\(|select|with|values|table|insert|update|delete|merge)\b/i;
 
@@ -273,6 +287,28 @@ function structureFindings(x: AppRows): Finding[] {
     else if (!all.some((r) => r.kind === 'region' && r.row.type === 'login' && r.row.page_id === page.id))
       out.push({ severity: 'error', entry: null, field, message: `Page ${app.login_page} has no Login region: nobody can sign in.` });
   }
+  // (154, CD-2) a SQL condition one declarative type can say: no query, and it reads in words in the tree
+  for (const r of all) {
+    const field = r.kind === 'region' || r.kind === 'button' ? 'condition'
+      : ['item', 'validation', 'process', 'computation', 'app_computation', 'branch'].includes(r.kind) ? 'condition_expr' : null;
+    if (!field || (r.row.build_option ?? '') === 'COMMENTED_OUT') continue;
+    const sql = (r.row.condition_type ?? (field === 'condition' ? 'sql' : null)) === 'sql' ? r.row[field] : null;
+    const d = sql ? declarativeCondition(sql) : null;
+    if (!d) continue;
+    const what = [d.condition_expr && `expression ${d.condition_expr}`, d.condition_value && `value ${d.condition_value}`].filter(Boolean).join(', ');
+    out.push({ severity: 'info', entry: x.byKey.get(`${r.kind}-${r.row.id}`) ?? null, field: 'Server-side condition',
+      message: `The SQL condition ${String(sql).trim()} can be the condition type ${d.condition_type}${what ? ` (${what})` : ''}: decided without a query, and shown in words.` });
+  }
+  // (155, CD-1) a SQL validation one declarative type says exactly
+  const VALIDATION_OF: Record<string, string> = { item_not_null: 'not_null', item_equals: 'equals', item_in_list: 'in_list' };
+  for (const r of all) {
+    if (r.kind !== 'validation' || r.row.type !== 'sql' || (r.row.build_option ?? '') === 'COMMENTED_OUT') continue;
+    const d = declarativeCondition(r.row.expression);
+    const type = d && VALIDATION_OF[d.condition_type ?? ''];
+    if (!d || !type) continue;
+    out.push({ severity: 'info', entry: x.byKey.get(`validation-${r.row.id}`) ?? null, field: 'Type',
+      message: `The SQL validation ${String(r.row.expression).trim()} can be the type ${type} with associated item ${d.condition_expr}${d.condition_value ? ` and value ${d.condition_value}` : ''}: no query.` });
+  }
   const groups = new Set(all.filter((r) => r.kind === 'page_group').map((r) => r.row.name));
   for (const p of [...pages].sort((a, b) => a.page_no - b.page_no))
     if (p.page_group != null && !groups.has(p.page_group))

package/src/builder/code-editor.ts

@@ -29,12 +29,14 @@ export type CodeLang = 'sql' | 'plpgsql' | 'json' | 'html' | 'text';
 const STATEMENTS = new Set(['supporting_script.script', 'process.code', 'app_process.code', 'automation_action.code', 'task_definition.action_code', 'dynamic_action.code']);
 /** The Advisor check per field (none: no check). */
 const CHECKS: Record<string, SqlShape> = {
-  'region.source': 'select', 'region.condition': 'boolean', 'item.lov': 'select', 'item.readonly_condition': 'boolean',
-  'button.condition': 'boolean', 'validation.expression': 'boolean', 'process.code': 'statements', 'authz_scheme.value': 'boolean',
+  'region.source': 'select', 'item.lov': 'select', 'item.readonly_condition': 'boolean',
+  'process.code': 'statements', 'authz_scheme.value': 'boolean',
   'lov.query': 'select', 'app_process.code': 'statements', 'automation.query': 'select', 'automation_action.code': 'statements', 'automation_action.condition': 'boolean',
   'document_template.query': 'select', 'report_query.query': 'select', 'task_definition.action_code': 'statements', 'dynamic_action.code': 'statements',
   'button.badge_query': 'select', 'list.query': 'select', 'list_entry.condition': 'boolean',
 };
+/** (147) The expression fields of server-side conditions (their type select names how to read them). */
+const CONDITION_EXPRS = ['computation', 'app_computation', 'branch', 'process', 'item', 'validation'].map((k) => `${k}.condition_expr`).concat('dynamic_action.server_condition_expr');
 /** Fields whose check follows the component's type select, like SWITCH ("none": no check). */
 const CHECK_SWITCH: Record<string, string> = {
   'dynamic_action.code': 'action:set_value=select,*=statements',
@@ -42,22 +44,24 @@ const CHECK_SWITCH: Record<string, string> = {
   'region.source': 'type:static=none,form=none,facets=none,smart_filters=none,display_selector=none,tasks=none,workflows=none,list=none,data_reporter=none,form_designer=none,ai_assistant=none,*=select',
   'computation.expression': 'type:sql_query=select,*=none',
   'app_computation.expression': 'type:sql_query=select,*=none',
-  'computation.condition_expr': 'condition_type:sql=boolean,exists=select,not_exists=select,*=none',
-  'app_computation.condition_expr': 'condition_type:sql=boolean,exists=select,not_exists=select,*=none',
-  'branch.condition_expr': 'condition_type:sql=boolean,exists=select,not_exists=select,*=none',
+  // (147) every component's server-side condition: SQL types are checked, the others are names and values
+  ...Object.fromEntries(CONDITION_EXPRS.map((k) => [k, `${k.endsWith('server_condition_expr') ? 'server_condition_type' : 'condition_type'}:sql=boolean,exists=select,not_exists=select,*=none`])),
+  'validation.expression': 'type:sql=boolean,exists=select,not_exists=select,*=none',
+  'region.condition': 'condition_type:=boolean,sql=boolean,exists=select,not_exists=select,*=none',
+  'button.condition': 'condition_type:=boolean,sql=boolean,exists=select,not_exists=select,*=none',
 };
 /** Fields whose language follows the component's type select: "type:value=lang,…" (other values: SQL). */
 const SWITCH: Record<string, string> = {
   'region.source': 'type:static=html,form=text',
-  'validation.expression': 'type:regex=text,not_null=text',
+  'validation.expression': 'type:sql=sql,exists=sql,not_exists=sql,function_body=plpgsql,function_error=plpgsql,*=text',
   'authz_scheme.value': 'type:role=text',
   'dynamic_action.code': 'action:set_value=sql',
   'computation.expression': 'type:static=text,item=text,function_body=plpgsql',
   'app_computation.expression': 'type:static=text,item=text,function_body=plpgsql',
   'shortcut.value': 'type:text=text,html=html,function_body=plpgsql',
-  'computation.condition_expr': 'condition_type:item_null=text,item_not_null=text,item_equals=text,item_not_equals=text',
-  'app_computation.condition_expr': 'condition_type:item_null=text,item_not_null=text,item_equals=text,item_not_equals=text',
-  'branch.condition_expr': 'condition_type:item_null=text,item_not_null=text,item_equals=text,item_not_equals=text',
+  ...Object.fromEntries(CONDITION_EXPRS.map((k) => [k, `${k.endsWith('server_condition_expr') ? 'server_condition_type' : 'condition_type'}:sql=sql,exists=sql,not_exists=sql,function_body=plpgsql,=sql,*=text`])),
+  'region.condition': 'condition_type:=sql,sql=sql,exists=sql,not_exists=sql,function_body=plpgsql,*=text',
+  'button.condition': 'condition_type:=sql,sql=sql,exists=sql,not_exists=sql,function_body=plpgsql,*=text',
 };
 /** Language when no SWITCH value matches. */
 const fallback = (key: string): CodeLang => (STATEMENTS.has(key) ? 'plpgsql' : 'sql');
@@ -66,7 +70,7 @@ const fallback = (key: string): CodeLang => (STATEMENTS.has(key) ? 'plpgsql' : '
 function pick(sw: string, row: any): string | undefined {
   const [col, list] = sw.split(':');
   const pairs = list.split(',').map((p) => p.split('='));
-  return (pairs.find(([val]) => val === row?.[col]) ?? pairs.find(([val]) => val === '*'))?.[1];
+  return (pairs.find(([val]) => val === (row?.[col] ?? '')) ?? pairs.find(([val]) => val === '*'))?.[1];
 }
 
 /** Language of a component field in the property editor, or null for a plain field. */

package/src/builder/components.ts

@@ -22,6 +22,8 @@ import { DATA_LOAD_DEF_SPEC } from './dataload.ts';
 import { processProblems } from '../runtime/processes.ts';
 import { BUTTON_OPTIONS, ITEM_OPTIONS, REGION_OPTIONS } from '../runtime/template-options.ts';
 import { checkGroupMembers } from '../subscriptions.ts';
+import { CONDITION_TYPES } from '../metadata.ts';
+import { styleProblem } from '../runtime/da-styles.ts';
 
 export type FieldKind =
   | 'text' | 'int' | 'bool' | 'code' | 'json' | 'select' | 'upper'
@@ -78,14 +80,27 @@ const AUTHZ_HELP = 'Authorization scheme; prefix with ! to negate. MUST_NOT_BE_P
 const BUILD_HELP = 'Build option (Shared Components): the component exists only while the option is included; "Not" only while it is excluded.';
 const buildOption = (group?: string): Field => ({ name: 'build_option', label: 'Build option', kind: 'build_option', help: BUILD_HELP, ...(group ? { group } : {}) });
 
-const CONDITION_TYPES = ['', 'sql', 'exists', 'not_exists', 'item_null', 'item_not_null', 'item_equals', 'item_not_equals', 'request_in'];
-const CONDITION_HELP = 'sql: a boolean expression · exists / not_exists: a query · item_*: the item\'s name below · request_in: the button(s) pressed, in Value.';
-const conditionFields = (group: string): Field[] => [
-  { name: 'condition_type', label: 'Condition', kind: 'select', options: CONDITION_TYPES, group, help: CONDITION_HELP },
-  { name: 'condition_expr', label: 'Expression / item', kind: 'code', group, help: 'e.g. :P3_STATUS = \'OPEN\' (sql) · select 1 from sales.orders where id = :P3_ID (exists) · P3_ID (item_*)' },
-  { name: 'condition_value', label: 'Value', kind: 'text', group, help: 'item_equals / item_not_equals: the value · request_in: e.g. SAVE,CREATE' },
+// (147) one catalogue of server-side condition types for every component (meta.condition_ok)
+const CONDITION_HELP = 'sql: a boolean expression · exists / not_exists: a query that returns a row / no row · function_body: PL/pgSQL returning boolean · '
+  + 'item_*: the item\'s name in Expression · request_in / request_not_in: the button(s) pressed · page_in / page_not_in: page numbers · '
+  + 'page_is_dialog: the page is a modal dialog · user_signed_in / user_public · language_in / language_not_in: language codes · always / never. '
+  + 'Only the SQL types run a query (as the application\'s role); the others are decided by the server.';
+const VALUE_HELP = 'item_equals / item_not_equals: the value · item_equals_item: the other item\'s name · item_in_list: values separated by colons (CLERK:ANALYST) · '
+  + 'request_in: e.g. SAVE,CREATE · page_in: e.g. 1,3 · language_in: e.g. de,pt-br';
+/** The type, expression and value of a server-side condition; `expr` is the expression column, `type` the type column. */
+const conditionFields = (group: string, expr = 'condition_expr', type = 'condition_type', value = 'condition_value', common = false): Field[] => [
+  { name: type, label: 'Condition type', kind: 'select', options: ['', ...CONDITION_TYPES], group, help: CONDITION_HELP, ...(common ? { common } : {}) },
+  { name: expr, label: 'Condition expression / item', kind: 'code', group, help: 'e.g. :P3_STATUS = \'OPEN\' (sql) · select 1 from sales.orders where id = :P3_ID (exists) · return :P3_QTY > 0; (function_body) · P3_ID (item_*)', ...(common ? { common } : {}) },
+  { name: value, label: 'Condition value', kind: 'text', group, help: VALUE_HELP, ...(common ? { common } : {}) },
 ];
 
+// (148, CD-1) APEX's validation types
+const VALIDATION_TYPES = ['sql', 'exists', 'not_exists', 'function_body', 'function_error', 'not_null', 'not_null_or_zero', 'not_zero', 'no_spaces',
+  'alphanumeric', 'numeric', 'valid_date', 'valid_timestamp', 'equals', 'not_equals', 'in_list', 'not_in_list', 'chars_only', 'chars_any', 'chars_none', 'regex'];
+const VALIDATION_HELP = 'APEX: Expression (sql), Rows returned / No rows returned (exists / not_exists), Function Body returning Boolean / Error Text (function_body / function_error), '
+  + 'Item is NOT NULL / NOT NULL or zero / NOT zero / contains no spaces / alphanumeric / numeric / a valid date (in the application\'s date format) / a valid timestamp, '
+  + 'Item = / != Value, Item is (NOT) contained in Value, contains only / at least one / none of the characters, matches Regular Expression. Format checks pass an empty item: add not_null for a required one.';
+
 /** JSON "menu" field: empty means no menu (null), not {}. */
 const menuBeforeSave = async (v: Record<string, unknown>) => {
   if (v.menu === '{}' || v.menu === '[]') v.menu = null;
@@ -116,7 +131,7 @@ export const COMPONENTS: Record<string, ComponentSpec> = {
       { name: 'title', common: true, label: 'Title', kind: 'text', group: 'Identification' },
       { name: 'static_id', label: 'Static ID', kind: 'text', group: 'Identification',
         help: 'Optional, unique on the page: lower case letters, digits, _ and -, starting with a letter. Names the region in exported files (so renaming it keeps them) and is data-static-id on the page, for CSS and JavaScript.' },
-      { name: 'type', common: true, label: 'Type', kind: 'select', options: ['report', 'grid', 'form', 'login', 'chart', 'cards', 'calendar', 'facets', 'smart_filters', 'display_selector', 'tasks', 'workflows', 'map', 'tree', 'template_component', 'list', 'static', 'dynamic', 'data_reporter', 'form_designer', 'ai_assistant', 'plugin', 'url', 'search', 'classic_report', 'breadcrumb', 'help_text'], group: 'Identification' },
+      { name: 'type', common: true, label: 'Type', kind: 'select', options: ['report', 'grid', 'form', 'login', 'chart', 'cards', 'calendar', 'facets', 'smart_filters', 'display_selector', 'tasks', 'workflows', 'map', 'tree', 'template_component', 'list', 'static', 'dynamic', 'data_reporter', 'form_designer', 'ai_assistant', 'plugin', 'url', 'search', 'classic_report', 'breadcrumb', 'help_text', 'workflow_diagram'], group: 'Identification' },
       { name: 'source', common: true, label: 'Source', kind: 'code', wide: true, group: 'Source',
         help: 'report/grid/classic_report: a SELECT (use :ITEM binds) · chart: label column + one numeric column per series · cards: title, subtitle, body, badge, icon · calendar: start_date, end_date, title · map: lat and lng (or location "lat,lng"), title, body, geojson · tree: id, parent_id, label, icon · template_component: any SELECT (its columns are #COLUMN# in the template), or empty for one instance · dynamic: a SELECT returning HTML (escape with meta.html_escape) · static: HTML with &ITEM. substitutions · url: the page to show, https://host/path?q=&P1_ITEM. (the host is written out; items are URL-encoded) or a path on this server (/a/other/1).' },
       { name: 'rest_source', label: 'REST data source', kind: 'rest_source', group: 'Source',
@@ -131,7 +146,7 @@ export const COMPONENTS: Record<string, ComponentSpec> = {
         help: 'Where the region shows (APEX: Layout → Position). banner: above everything else in the page; breadcrumb: in the bar under the title; left / right: in the side column of a page with template Left or Right side column (on other pages in the body); footer: after the body. Empty is body.' },
       { name: 'template_options', label: 'Template options', kind: 'options', choices: REGION_OPTIONS, group: 'Appearance',
         help: 'CSS classes from a fixed list, added to the region (APEX: Template Options). "Hide the header" applies to the standard template.' },
-      { name: 'condition', common: true, label: 'Server-side condition (SQL)', kind: 'code', group: 'Security', help: 'Boolean expression; the region renders only when true.' },
+      ...conditionFields('Server-side condition', 'condition', 'condition_type', 'condition_value', true),
       { name: 'authz', common: true, label: 'Authorization', kind: 'authz', group: 'Security', help: AUTHZ_HELP },
       buildOption('Security'),
       { name: 'config', label: 'Attributes (JSON)', kind: 'json', wide: true, group: 'Attributes',
@@ -149,7 +164,8 @@ export const COMPONENTS: Record<string, ComponentSpec> = {
     validate: (v) => formatSettingsProblem(v.config),
     fields: [
       { name: 'name', common: true, label: 'Name', kind: 'upper', help: 'Referenced in SQL as :NAME, e.g. P3_NAME', group: 'Identification' },
-      { name: 'type', common: true, label: 'Type', kind: 'select', options: ['text', 'textarea', 'number', 'date', 'datetime', 'select', 'popup_lov', 'radio', 'checkbox', 'switch', 'checkbox_group', 'multiselect', 'email', 'tel', 'url', 'color', 'file', 'location', 'richtext', 'markdown', 'rating', 'combobox', 'daterange', 'qrcode', 'image', 'address', 'hidden', 'display', 'password', 'plugin', 'shuttle', 'select_one', 'select_many'], group: 'Identification' },
+      { name: 'type', common: true, label: 'Type', kind: 'select', options: ['text', 'textarea', 'number', 'date', 'datetime', 'select', 'popup_lov', 'radio', 'checkbox', 'switch', 'checkbox_group', 'multiselect', 'email', 'tel', 'url', 'color', 'file', 'location', 'richtext', 'markdown', 'rating', 'combobox', 'daterange', 'qrcode', 'image', 'address', 'hidden', 'display', 'password', 'plugin', 'shuttle', 'select_one', 'select_many', 'image_upload', 'autocomplete', 'percent_graph', 'display_map'], group: 'Identification',
+        help: '(sprint 158) image_upload: a file item for pictures (image/*, cropping {"crop": "free" | "1:1" | "4:3" …}, {"max_px": 1600} before upload; file column settings as a file item) · autocomplete: a text field with suggestions from the list of values, any text allowed · percent_graph: a 0–100 value as a bar · display_map: a small map of "lat,lng" (the value, or {"coordinates_item": "P3_LOCATION"}; {"zoom": 15}).' },
       { name: 'label', common: true, label: 'Label', kind: 'text', group: 'Identification' },
       { name: 'region_id', common: true, label: 'Region', kind: 'region', group: 'Layout' },
       { name: 'seq', label: 'Sequence', kind: 'int', group: 'Layout' },
@@ -160,6 +176,7 @@ export const COMPONENTS: Record<string, ComponentSpec> = {
         help: 'CSS classes from a fixed list, added to the item (APEX: Template Options).' },
       { name: 'required', common: true, label: 'Value required', kind: 'bool', group: 'Validation' },
       { name: 'help', label: 'Help text', kind: 'text', group: 'Validation' },
+      ...conditionFields('Server-side condition'),
       { name: 'readonly_condition', label: 'Read-only condition (SQL)', kind: 'code', group: 'Security', help: 'When true the item is shown read-only and ignored on submit.' },
       { name: 'authz', label: 'Authorization', kind: 'authz', group: 'Security', help: AUTHZ_HELP },
       buildOption('Security'),
@@ -194,7 +211,7 @@ export const COMPONENTS: Record<string, ComponentSpec> = {
       { name: 'slot', common: true, label: 'Button position', kind: 'select', options: ['', 'region', 'create', 'edit', 'change', 'copy', 'help', 'up', 'previous', 'close', 'delete', 'next'], group: 'Layout',
         help: 'A region button\'s place (APEX: Button Position): create, edit, change, copy, help and up in the region\'s header; previous, close and delete at the left of its bottom bar, next at the right. Empty or region: with its other buttons (the header of reports and charts, the bottom of forms and static content).' },
       { name: 'seq', label: 'Sequence', kind: 'int', group: 'Layout' },
-      { name: 'condition', label: 'Server-side condition (SQL)', kind: 'code', group: 'Security', help: 'e.g. :P3_ID is not null — also re-checked when the button is pressed.' },
+      ...conditionFields('Server-side condition', 'condition'),
       { name: 'authz', label: 'Authorization', kind: 'authz', group: 'Security', help: AUTHZ_HELP },
       buildOption('Security'),
     ],
@@ -212,16 +229,21 @@ export const COMPONENTS: Record<string, ComponentSpec> = {
         ? 'CSS classes: up to five names of lower case letters, digits, - and _, separated by spaces.'
         : v.action === 'execute_javascript' && !/^[A-Za-z_$][\w$.-]{0,99}$/.test(String(v.code ?? '').trim())
           ? 'Execute JavaScript: Code is the name of a function a static file registers with pgkiln.actions.register(name, fn), e.g. highlightLate.'
-          : null,
+          : v.action === 'set_style'
+            ? styleProblem((typeof v.config === 'string' ? (() => { try { return JSON.parse(v.config as string); } catch { return null; } })() : (v.config as any))?.styles)
+            : null,
     fields: [
       { name: 'name', label: 'Name', kind: 'text', group: 'When' },
-      { name: 'event', label: 'Event', kind: 'select', options: ['change', 'click', 'load', 'dialog_closed', 'focus', 'blur', 'key_release', 'after_refresh', 'selection_change', 'before_submit', 'custom', 'menu_entry'], group: 'When',
-        help: 'dialog_closed: a modal dialog opened from this page was submitted and closed (instead of reloading the page), e.g. refresh a region. focus / blur / key_release: an item gets or loses the focus, a key is released in it. after_refresh: a region was refreshed or loaded. selection_change: rows were selected in a report (row selection) or a grid\'s master row. before_submit: the page is about to be submitted (a declined confirm keeps it). custom: JavaScript raised it with pgkiln.trigger(\'NAME\', value). menu_entry (Menu entry chosen): an entry {"label": …, "action": "NAME"} of a menu button was chosen. The actions of one event and trigger run in sequence order; a declined confirm stops the ones after it.' },
+      { name: 'event', label: 'Event', kind: 'select', options: ['change', 'click', 'load', 'dialog_closed', 'focus', 'blur', 'key_release', 'after_refresh', 'selection_change', 'before_submit', 'custom', 'menu_entry',
+        'double_click', 'key_down', 'key_press', 'mouse_enter', 'mouse_leave', 'select', 'resize', 'scroll', 'page_unload', 'before_refresh', 'facets_change'], group: 'When',
+        help: '(sprint 156) double_click, mouse_enter, mouse_leave: items, buttons or regions. key_down, key_press (a key that types a character), select (text selected): items. resize, scroll: the window (no trigger). page_unload: the page is left (only quick, local actions finish). before_refresh: a region is about to be refreshed by a Refresh action. facets_change: a faceted search or smart filters region\'s facets were applied (trigger: that region). ' + 'dialog_closed: a modal dialog opened from this page was submitted and closed (instead of reloading the page), e.g. refresh a region. focus / blur / key_release: an item gets or loses the focus, a key is released in it. after_refresh: a region was refreshed or loaded. selection_change: rows were selected in a report (row selection) or a grid\'s master row. before_submit: the page is about to be submitted (a declined confirm keeps it). custom: JavaScript raised it with pgkiln.trigger(\'NAME\', value). menu_entry (Menu entry chosen): an entry {"label": …, "action": "NAME"} of a menu button was chosen. The actions of one event and trigger run in sequence order; a declined confirm stops the ones after it.' },
       { name: 'trigger_element', label: 'Item(s) / button / region / page / event', kind: 'upper', group: 'When', help: 'Comma separated: 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), event names (custom), menu entry action names or menu button names (menu_entry: any of its entries; a client-side condition tests the entry\'s name). Empty for load and before_submit.' },
-      { name: 'condition_type', label: 'Client-side condition', kind: 'select', options: ['', 'equals', 'not_equals', 'in_list', 'is_null', 'is_not_null'], group: 'When' },
+      { name: 'condition_type', label: 'Client-side condition', kind: 'select', options: ['', 'equals', 'not_equals', 'greater', 'greater_equal', 'less', 'less_equal', 'in_list', 'not_in_list', 'is_null', 'is_not_null'], group: 'When',
+        help: 'On the (first) trigger item\'s value. greater / less: numbers as numbers, other values (ISO dates) as text; an empty value fails them. in_list / not_in_list: comma-separated values.' },
       { name: 'condition_value', label: 'Condition value', kind: 'text', group: 'When' },
-      { name: 'action', label: 'Action', kind: 'select', options: ['show', 'hide', 'enable', 'disable', 'set_value', 'execute_sql', 'refresh_region', 'refresh_item', 'alert', 'submit', 'set_focus', 'add_class', 'remove_class', 'show_success', 'show_error', 'clear_errors', 'ai_generate', 'execute_javascript', 'plugin', 'push_subscribe', 'confirm', 'close_dialog', 'cancel_dialog', 'clear', 'open_region', 'close_region', 'download', 'print', 'current_position', 'share', 'wait_popup', 'remove_wait_popup'], group: 'Action',
-        help: 'show/hide/enable/disable reverse automatically when the condition is false. set_focus: the first affected item (or the region). show_error: on the affected items, or at the top. clear_errors: of the affected items, or all. ai_generate: runs the "Generate text with AI" process named in Code through AJAX, without submitting the page (on a submit button, the button submits instead when JavaScript is off). execute_javascript: calls the function named in Code, registered by a static application file (Shared Components → Static Application Files). push_subscribe: turns on push notifications on the user\'s device (use it on click: browsers ask only after one; the app needs push notifications on in Settings → Progressive Web App); Message is shown when it worked. confirm: asks Message; No stops the actions after it. close_dialog / cancel_dialog: close the modal page this runs on (close_dialog refreshes the page below and runs its dialog_closed actions). clear: empties the affected items. open_region / close_region: a collapsible region opens or closes (another region shows or hides). download: the file of the download process named in Code (Items to submit are sent first). print: the browser\'s print dialog. current_position: the device\'s position as latitude,longitude into the first affected item. share: the device\'s share sheet for this page (Message as the text), or the link copied. wait_popup: a modal "please wait" overlay (Message as its text) until remove_wait_popup or the next page, e.g. on before_submit around a long process, or wait_popup, execute_sql, remove_wait_popup around an Ajax call.' },
+      { name: 'action', label: 'Action', kind: 'select', options: ['show', 'hide', 'enable', 'disable', 'set_value', 'execute_sql', 'refresh_region', 'refresh_item', 'alert', 'submit', 'set_focus', 'add_class', 'remove_class', 'show_success', 'show_error', 'clear_errors', 'ai_generate', 'execute_javascript', 'plugin', 'push_subscribe', 'confirm', 'close_dialog', 'cancel_dialog', 'clear', 'open_region', 'close_region', 'download', 'print', 'current_position', 'share', 'wait_popup', 'remove_wait_popup',
+        'cancel_event', 'set_style', 'collapse_tree', 'expand_tree', 'show_ai_assistant', 'trigger_geocoding', 'open_report_dialog'], group: 'Action',
+        help: '(sprint 156) cancel_event: stops the actions after it and the event\'s own effect (a button\'s submit or link, a typed key). set_style: {"styles": {"color": "#b42318", "font-weight": "bold"}} in the attributes, on the affected items or region. collapse_tree / expand_tree: every node of the affected tree region. show_ai_assistant: opens the affected AI assistant region (or its inline dialog) and puts the cursor in it. trigger_geocoding: the affected geocoded address item looks its text up. open_report_dialog: Code names the dialog of the affected interactive report (filter, columns, sort, highlight, compute, aggregate, chart, group, pivot, break, rows, saved). ' + 'show/hide/enable/disable reverse automatically when the condition is false. set_focus: the first affected item (or the region). show_error: on the affected items, or at the top. clear_errors: of the affected items, or all. ai_generate: runs the "Generate text with AI" process named in Code through AJAX, without submitting the page (on a submit button, the button submits instead when JavaScript is off). execute_javascript: calls the function named in Code, registered by a static application file (Shared Components → Static Application Files). push_subscribe: turns on push notifications on the user\'s device (use it on click: browsers ask only after one; the app needs push notifications on in Settings → Progressive Web App); Message is shown when it worked. confirm: asks Message; No stops the actions after it. close_dialog / cancel_dialog: close the modal page this runs on (close_dialog refreshes the page below and runs its dialog_closed actions). clear: empties the affected items. open_region / close_region: a collapsible region opens or closes (another region shows or hides). download: the file of the download process named in Code (Items to submit are sent first). print: the browser\'s print dialog. current_position: the device\'s position as latitude,longitude into the first affected item. share: the device\'s share sheet for this page (Message as the text), or the link copied. wait_popup: a modal "please wait" overlay (Message as its text) until remove_wait_popup or the next page, e.g. on before_submit around a long process, or wait_popup, execute_sql, remove_wait_popup around an Ajax call.' },
       { name: 'affected_items', label: 'Affected items', kind: 'upper', group: 'Action' },
       { name: 'affected_region_id', label: 'Affected region', kind: 'region', group: 'Action' },
       { name: 'code', label: 'SQL', kind: 'code', wide: true, group: 'Action', help: 'set_value: a SELECT whose columns set the affected items · execute_sql: any SQL; returned columns named like items set them · ai_generate: the name of an ai_generate process on this page (its output items are updated; items to submit default to the items its prompts use) · execute_javascript: the name of a function registered with pgkiln.actions.register(name, fn) in a static file the page loads.' },
@@ -229,6 +251,7 @@ export const COMPONENTS: Record<string, ComponentSpec> = {
       { name: 'message', label: 'Message (alert, confirm, show_success, show_error, wait_popup)', kind: 'text', group: 'Action' },
       { name: 'config', label: 'Plug-in attributes (JSON)', kind: 'json', group: 'Action', help: 'plugin: {"attributes": {"NAME": "value or &ITEM."}} (Shared Components → Plug-ins lists each plug-in\'s attributes).' },
       { name: 'css_classes', label: 'CSS classes (add_class, remove_class)', kind: 'text', group: 'Action', help: 'Up to five class names, e.g. is-highlight is-muted (lower case letters, digits, - and _).' },
+      ...conditionFields('Server-side condition', 'server_condition_expr', 'server_condition_type', 'server_condition_value'),
       { name: 'seq', label: 'Sequence', kind: 'int', group: 'Security' },
       { name: 'authz', label: 'Authorization', kind: 'authz', group: 'Security', help: AUTHZ_HELP },
       buildOption('Security'),
@@ -244,11 +267,17 @@ export const COMPONENTS: Record<string, ComponentSpec> = {
     defaults: { type: 'sql' },
     fields: [
       { name: 'name', label: 'Name', kind: 'text' },
-      { name: 'type', label: 'Type', kind: 'select', options: ['sql', 'not_null', 'regex'] },
-      { name: 'item_name', label: 'Associated item', kind: 'upper' },
-      { name: 'expression', label: 'Expression', kind: 'code', wide: true, help: 'sql: boolean expression that must be true · regex: POSIX pattern' },
+      { name: 'type', label: 'Type', kind: 'select', options: VALIDATION_TYPES, help: VALIDATION_HELP },
+      { name: 'item_name', label: 'Associated item', kind: 'upper', help: 'The item the error shows next to; the item types test its value.' },
+      { name: 'expression', label: 'Expression / value', kind: 'code', wide: true,
+        help: 'sql: a boolean expression that must be true · exists / not_exists: a query · function_body: PL/pgSQL returning boolean · function_error: PL/pgSQL returning the error text (null: valid) · equals / not_equals: the value · in_list / not_in_list: values separated by colons (CLERK:ANALYST) · chars_*: the characters · regex: a POSIX pattern' },
       { name: 'message', label: 'Error message', kind: 'text' },
+      { name: 'display_location', label: 'Display location', kind: 'select', options: ['', 'inline_and_notification', 'inline', 'notification'],
+        help: 'Where the error shows: inline with the item and in the notification at the top, inline only (empty: inline, with "correct the errors below" at the top), or in the notification only. Without an associated item it is always in the notification.' },
       { name: 'when_button', label: 'When button pressed', kind: 'upper' },
+      { name: 'always_execute', label: 'Always execute', kind: 'bool', help: 'Also for a DELETE request (other validations without When button pressed are skipped for DELETE).' },
+      { name: 'authz', label: 'Authorization', kind: 'authz', help: AUTHZ_HELP },
+      ...conditionFields('Server-side condition'),
       { name: 'seq', label: 'Sequence', kind: 'int' },
       buildOption(),
     ],
@@ -269,8 +298,9 @@ export const COMPONENTS: Record<string, ComponentSpec> = {
     },
     fields: [
       { name: 'name', label: 'Name', kind: 'text' },
-      { name: 'type', label: 'Type', kind: 'select', options: ['sql', 'form_dml', 'grid_dml', 'data_load', 'invoke_api', 'download', 'chain', 'workflow', 'ai_generate', 'plugin', 'send_push', 'send_email'],
-        help: 'download: a file from the query in Code · chain: runs the processes that name it as their chain, in sequence (optionally in the background) · workflow: start, terminate or retry a workflow · ai_generate: Generate text with AI (an AI service the application may use) · send_push: a push notification to a user\'s devices (Settings → Progressive Web App → push notifications)' },
+      { name: 'type', label: 'Type', kind: 'select', options: ['sql', 'form_dml', 'grid_dml', 'data_load', 'invoke_api', 'download', 'chain', 'workflow', 'ai_generate', 'plugin', 'send_push', 'send_email',
+        'close_dialog', 'clear_session_state', 'reset_pagination', 'user_preferences', 'server_geocoding', 'print_report', 'human_task_create', 'human_task_manage', 'form_init'],
+        help: '(sprint 157, settings in Attributes) close_dialog: {"items": ["P5_ID"]} closes the modal page, handing these items to the page below · clear_session_state: {"items": [...], "pages": [3], "all": false} · reset_pagination: reports and grids start on their first page · user_preferences: {"action": "set", "preference": "DEFAULT_DEPT", "item": "P1_DEPT"} or {"action": "reset", …} · server_geocoding: {"address_item": "P3_ADDRESS", "coordinates_item": "P3_LOCATION"} · print_report: {"document": "EMPLOYEE_SHEET"} (a document template or report query) · human_task_create: {"definition": "LEAVE_APPROVAL", "detail_pk": "&P7_ID.", "parameters": {"DAYS": "&P7_DAYS."}, "id_item": "P7_TASK_ID"} · human_task_manage: {"action": "approve", "task": "&P8_TASK_ID.", "comment": "&P8_COMMENT."} (approve, reject, complete with "outcome", claim, release, delegate with "to", cancel) · form_init: APEX\'s Form – Initialization (the form region fetches its row by itself) · download: a file from the query in Code · chain: runs the processes that name it as their chain, in sequence (optionally in the background) · workflow: start, terminate or retry a workflow · ai_generate: Generate text with AI (an AI service the application may use) · send_push: a push notification to a user\'s devices (Settings → Progressive Web App → push notifications)' },
       { name: 'point', label: 'Point', kind: 'select', options: ['submit', 'load', 'ajax'], help: 'A chain\'s processes run when the chain does (their own point is not used). ajax: an Ajax callback (APEX: On Demand) that JavaScript calls by name with pgkiln.server.process(\'NAME\', {items: [\'P1_X\'], x01: …}); SQL processes only; the last statement\'s rows come back as JSON, and the items it sets are set on the page.' },
       { name: 'parent_process', label: 'Chain (parent process)', kind: 'text', help: 'The name of a chain process on this page: this process then runs only inside that chain, in its sequence.' },
       { name: 'code', label: 'Code (SQL / PL/pgSQL call)', kind: 'code', wide: true,

package/src/builder/conditions.ts

@@ -0,0 +1,64 @@
+// (sprint 154, CD-2) A component's server-side condition in words, in the builder's language: the Page
+// Designer's tree shows it on the condition badge ("When the request is SAVE, CREATE").
+import { CONDITION_TYPES, type Condition } from '../metadata.ts';
+import type { BuilderKey, BuilderTranslate } from './i18n.ts';
+
+const TYPES = new Set<string>(CONDITION_TYPES);
+
+/**
+ * A row's server-side condition: a dynamic action's server_condition_*, a condition_type / condition_expr /
+ * condition_value (processes, items, validations…), or a region's or button's `condition` (SQL without a type).
+ * Null when there is none. A dynamic action's client-side condition_type isn't one.
+ */
+export function serverCondition(row: any): Condition | null {
+  if (!row) return null;
+  if (row.server_condition_type) return { condition_type: row.server_condition_type, condition_expr: row.server_condition_expr ?? null, condition_value: row.server_condition_value ?? null };
+  if (row.condition_type && TYPES.has(row.condition_type))
+    return { condition_type: row.condition_type, condition_expr: row.condition_expr ?? row.condition ?? null, condition_value: row.condition_value ?? null };
+  if (typeof row.condition === 'string' && row.condition.trim()) return { condition_type: 'sql', condition_expr: row.condition, condition_value: null };
+  return null;
+}
+
+const listOf = (v: string | null, sep: string) => (v ?? '').split(sep).map((x) => x.trim()).filter(Boolean).join(', ');
+
+/** The condition in words, e.g. "When P3_JOB is one of CLERK, ANALYST". */
+export function conditionWords(tx: BuilderTranslate, c: Condition): string {
+  const type = c.condition_type ?? 'always';
+  const item = (c.condition_expr ?? '').trim();
+  const value = type === 'item_in_list' || type === 'item_not_in_list' ? listOf(c.condition_value, ':')
+    : /^(request|page|language)_/.test(type) && !/dialog/.test(type) ? listOf(c.condition_value, ',')
+    : (c.condition_value ?? '').trim();
+  return tx(`cond.${type}` as BuilderKey, { item, value });
+}
+
+const NAME = '([A-Z][A-Z0-9_]*)';
+const LIT = "'((?:[^']|'')*)'";
+const unq = (s: string) => s.replace(/''/g, "'");
+const lits = (s: string) => [...s.matchAll(/'((?:[^']|'')*)'/g)].map((m) => unq(m[1]));
+
+/**
+ * (154) The declarative type a SQL condition can be, or null: `:P3_X is not null` → item_not_null,
+ * `:REQUEST in ('SAVE', 'CREATE')` → request_in, `:P3_JOB = 'CLERK'` → item_equals… Only whole conditions of one
+ * bind and literals; anything else stays SQL. (The Advisor suggests it.) Negations (<>, not in) aren't offered: in SQL
+ * an empty item makes them null (false), while the declarative types count an empty item as different.
+ */
+export function declarativeCondition(sql: string | null | undefined): Condition | null {
+  const s = (sql ?? '').trim().replace(/;+$/, '').trim().replace(/\s+/g, ' ');
+  let m: RegExpExecArray | null;
+  const c = (condition_type: Condition['condition_type'], condition_expr: string | null, condition_value: string | null): Condition => ({ condition_type, condition_expr, condition_value });
+  if ((m = new RegExp(`^:${NAME} is (not )?null$`, 'i').exec(s))) {
+    if (m[1].toUpperCase() !== m[1]) return null;
+    return c(m[2] ? 'item_not_null' : 'item_null', m[1], null);
+  }
+  if ((m = new RegExp(`^:${NAME} = ${LIT}$`).exec(s))) {
+    if (m[1] === 'REQUEST') return /^[A-Z][A-Z0-9_]*$/.test(m[2]) ? c('request_in', null, m[2]) : null;
+    return m[2] === '' ? null : c('item_equals', m[1], unq(m[2]));
+  }
+  if ((m = new RegExp(`^:${NAME} in \\((${LIT}(?: ?, ?${LIT})*)\\)$`, 'i').exec(s))) {
+    if (m[1].toUpperCase() !== m[1]) return null;
+    const values = lits(m[2]);
+    if (m[1] === 'REQUEST') return values.every((v) => /^[A-Z][A-Z0-9_]*$/.test(v)) ? c('request_in', null, values.join(',')) : null;
+    return values.some((v) => v.includes(':') || v === '') ? null : c('item_in_list', m[1], values.join(':'));
+  }
+  return null;
+}