create-procode 0.0.0-stage → 1.1.0

package/templates/base/src/AdapterProvider/SampleContacts.ts.tmpl

@@ -0,0 +1,136 @@
+/**
+ * The adapter for the sample "Contacts" screen (screenId "sample-contacts").
+ *
+ * An adapter is a PURE TRANSLATOR between the API's shape and the screen's
+ * shape. It must not issue HTTP and must not hold UI state.
+ * Every hook is optional — implement only the ones the screen needs:
+ *
+ *   defaultViewModel           initial { screenData, supportiveData }
+ *   deserializedModelData      API response        -> UI shape
+ *   deserializedSupportiveData lookup/dropdown data -> UI shape
+ *   keyValueMappinig           API data -> label/value pairs   (sic: the
+ *                              framework spells it this way)
+ *   serializedRequestParam     UI state -> API request body
+ *   generateQueryParams        filter/sort/paging -> query string
+ *
+ * THIS SAMPLE HAS NO BACKEND. `defaultViewModel` seeds the rows the grid shows
+ * (the core replaces its empty seed with whatever this returns), so the screen renders and every button works without an API.
+ * Going live means: declare `apiConfig` in the schema, bind LOAD_SCREEN_DATA,
+ * and let `deserializedModelData` below shape the response — the seed rows
+ * simply stop being used.
+ */
+
+export type Contact = {
+  id: number;
+  name: string;
+  email: string;
+  department: string;
+  city: string;
+  joined: string;
+  status: "Active" | "Inactive";
+  /** Rendered by the grid as HTML — every grid cell is an HTML sink. */
+  statusBadge: string;
+};
+
+/** A status pill the grid can render — theme badge classes, no literal colours. */
+export const statusBadge = (status: Contact["status"]) =>
+  `<span class="qo-badge qo-badge-${status === "Active" ? "success" : "default"} qo-badge-sm qo-badge-fixed">${status}</span>`;
+
+/** Totals for the summary tiles. Recomputed by the sample actions after every change. */
+export const summarise = (records: Contact[]) => ({
+  total: records.length,
+  active: records.filter((r) => r.status === "Active").length,
+  departments: new Set(records.map((r) => r.department)).size,
+});
+
+const seed: Omit<Contact, "statusBadge">[] = [
+  { id: 1, name: "Ava Thompson",    email: "ava.thompson@example.com",    department: "Sales",       city: "Austin",   joined: "2023-02-14", status: "Active" },
+  { id: 2, name: "Liam Patel",      email: "liam.patel@example.com",      department: "Engineering", city: "Denver",   joined: "2022-09-01", status: "Active" },
+  { id: 3, name: "Sofia Martinez",  email: "sofia.martinez@example.com",  department: "Support",     city: "Miami",    joined: "2024-01-22", status: "Inactive" },
+  { id: 4, name: "Noah Kim",        email: "noah.kim@example.com",        department: "Finance",     city: "Seattle",  joined: "2021-06-30", status: "Active" },
+  { id: 5, name: "Emma Rossi",      email: "emma.rossi@example.com",      department: "Sales",       city: "Chicago",  joined: "2023-11-05", status: "Active" },
+  { id: 6, name: "Oliver Nguyen",   email: "oliver.nguyen@example.com",   department: "Engineering", city: "Boston",   joined: "2020-03-18", status: "Inactive" },
+  { id: 7, name: "Mia Johansson",   email: "mia.johansson@example.com",   department: "Support",     city: "Portland", joined: "2024-05-09", status: "Active" },
+  { id: 8, name: "Ethan Okafor",    email: "ethan.okafor@example.com",    department: "Finance",     city: "Atlanta",  joined: "2022-12-12", status: "Active" },
+];
+
+/** The editor's empty state. `mode` drives the SHOW rule on the form ("" = hidden, "add" | "edit"). */
+export const emptyEditor = () => ({
+  mode: "",
+  id: null as number | null,
+  name: "",
+  email: "",
+  department: null as { label: string; value: string } | null,
+  joined: null as string | null,
+  active: true,
+  notes: "",
+  region: null as { label: string; value: string } | null,
+  referenceCode: "",
+});
+
+export class SampleContacts {
+  /** Shapes the screen before any data arrives. Every field a widget binds to
+   *  should exist here, or the first render reads undefined. */
+  defaultViewModel = (_props?: any) => {
+    const records: Contact[] = seed.map((r) => ({ ...r, statusBadge: statusBadge(r.status) }));
+    return {
+      screenData: {
+        // The full set the sample's stand-in "API" serves from. With a real
+        // backend this key does not exist — the server holds the data.
+        contactsSource: records,
+        // The GRID reads { records, total } — that shape is mandatory.
+        // The grid's onScreenDataLoad event fills it (CUS_SAMPLE_LOAD_ROWS, or
+        // LOAD_SCREEN_DATA once there is an API); seeded here so the first
+        // paint is never empty.
+        contacts: { records, total: records.length },
+        summary: summarise(records),
+        editor: emptyEditor(),
+        // Written by the grid's bulk actions and read by the alert widgets'
+        // SHOW rules.
+        deleteConfirm: null,
+        statusConfirm: null,
+        saveNotice: null,
+      },
+      supportiveData: null,
+    };
+  };
+
+  /** API response -> the shape the schema's screenDataField paths expect.
+   *  Used once `apiConfig.get` exists; the seed above is ignored from then on. */
+  deserializedModelData = (response: any) => {
+    const rows: any[] = response?.data?.records ?? response?.records ?? response?.data ?? [];
+    const records: Contact[] = rows.map((r) => ({
+      id: r.id,
+      name: r.name ?? "",
+      email: r.email ?? "",
+      department: r.department ?? "",
+      city: r.city ?? "",
+      joined: r.joined ?? "",
+      status: r.status === "Inactive" ? "Inactive" : "Active",
+      statusBadge: statusBadge(r.status === "Inactive" ? "Inactive" : "Active"),
+    }));
+    return {
+      contacts: { records, total: response?.data?.total ?? response?.total ?? records.length },
+      summary: summarise(records),
+      editor: emptyEditor(),
+    };
+  };
+
+  /** Screen state -> the request body for FORMSUBMIT_* / CREATE_ASYNC. The
+   *  editor holds the DROPDOWN's whole { label, value } object,
+   *  so the scalar is extracted here, where the API shape belongs. */
+  serializedRequestParam = (viewModel: any) => {
+    const e = viewModel?.screenData?.editor ?? {};
+    return {
+      id: e.id,
+      name: e.name,
+      email: e.email,
+      department: e.department?.value ?? null,
+      region: e.region?.value ?? null,
+      joined: e.joined,
+      status: e.active ? "Active" : "Inactive",
+      notes: e.notes,
+      referenceCode: e.referenceCode,
+    };
+  };
+}

package/templates/base/src/CustomAction.ts.tmpl

@@ -0,0 +1,47 @@
+import { setField } from "./Factory/Actions/setField";
+import { myAction, suggestReferenceCode } from "./Factory/Actions/myAction";
+import { loadRows, openRow, updateRows, saveContact, confirmBody, noticeBody } from "./Factory/Actions/sampleContacts";
+
+/**
+ * Extension point 4 of 5: custom actions, resolved by a CUS_-prefixed key.
+ *
+ * Resolution is custom -> template -> standard. A key no tier knows is logged
+ * and toasted as "This action is not available" — a missing entry here is the
+ * first thing to check. A Map, not an object literal: on a plain object,
+ * actionMap["constructor"] returns a function the core would invoke.
+ *
+ * Write a custom action only for logic none of the standard keys expresses,
+ * and NEVER to make an HTTP call. The standard keys —
+ *   NAVIGATE, NAVIGATE_BACK, MODIFY_MODEL, SET_VALUES, LOAD_SCREEN_DATA,
+ *   LOAD_SUPPORTIVE_DATA, FORMSUBMIT_UPDATE_ASYNC, FORMSUBMIT_CREATE_ASYNC,
+ *   CREATE_ASYNC, UPDATE_ASYNC, DELETE_ASYNC, GET_ASYNC
+ * plus vs-template's MENUNAVIGATE — cover all normal data access.
+ *
+ * Template widgets call app actions too: GRIDTOOLBAR's getUniqueViewId
+ * (its callBack must be called synchronously), MENU's loadMenuDetails, and the
+ * alert boxes' handleHeader / handleBody. Register those keys here as well.
+ *
+ * The CUS_SAMPLE_* keys stand in for DELETE_ASYNC / UPDATE_ASYNC /
+ * FORMSUBMIT_CREATE_ASYNC because this sample has no backend; each says so in
+ * its header. CUS_SET_FIELD is the one worth keeping: it lets a button reach
+ * MODIFY_MODEL with a config-declared value.
+ */
+class CustomActionFactory {
+  private actionMap = new Map<string, (props: any, ...args: any[]) => any>([
+    ["CUS_SET_FIELD", setField],
+    ["CUS_MY_ACTION", myAction],
+    ["CUS_SUGGEST_CODE", suggestReferenceCode],
+    ["CUS_SAMPLE_LOAD_ROWS", loadRows],
+    ["CUS_SAMPLE_OPEN_ROW", openRow],
+    ["CUS_SAMPLE_UPDATE_ROWS", updateRows],
+    ["CUS_SAMPLE_SAVE", saveContact],
+    ["CUS_SAMPLE_CONFIRM_BODY", confirmBody],
+    ["CUS_SAMPLE_NOTICE_BODY", noticeBody],
+  ]);
+
+  getAction(key: string) {
+    return this.actionMap.get(key) ?? null; // never throw: this runs outside the core's try/catch
+  }
+}
+
+export default CustomActionFactory;

package/templates/base/src/CustomAuthorizationProvider.ts.tmpl

@@ -0,0 +1,77 @@
+import {
+  AuthzContext,
+  AuthzKind,
+  AuthzResult,
+  IAuthorizationProvider,
+} from "procode-lowcode-core";
+
+/**
+ * The core ships no authorization provider. When you pass none, the getter
+ * returns undefined and every gate reads that as "authorization disabled" —
+ * fail-open. Passing one gates three kinds:
+ *
+ *   AuthzKind.SCREEN  keyed by the screen's slug. Denied => every widget locked
+ *                     in skeleton mode, your message as a toast, no data fetch.
+ *   AuthzKind.WIDGET  keyed by `permissionKey` on the element. Denied => the
+ *                     widget is hidden SILENTLY; the message is ignored.
+ *   AuthzKind.ACTION  keyed by `permissionKey` on the event. Denied => the click
+ *                     is blocked and your message is toasted.
+ *
+ * Gate every surface that shows the same records. A list screen with a grid and
+ * a card view behind a toggle needs one key on both — gating only the grid
+ * leaves the card view as an open bypass.
+ */
+export default class CustomAuthorizationProvider implements IAuthorizationProvider {
+  // Default to GRANTED while wiring up, so the screen behaves exactly as it did
+  // before the keys existed. The gates are then provable without taking
+  // anything away from anyone until the real fetch below says so.
+  private perms = { add: true, grid: true, save: true };
+
+  /**
+   * Called ONCE per screen change, before any widget renders, and AWAITED — the
+   * core holds the screen in PENDING (skeleton) until it settles. That is what
+   * stops a denied widget from flashing on screen before the answer arrives, so
+   * the real permission fetch must live here and nowhere else.
+   *
+   * A rejection here is fail-CLOSED for the screen. If a lookup failure should
+   * NOT deny, catch it and decide deliberately.
+   */
+  async loadPermissions(context: AuthzContext): Promise<void> {
+    if (context.slug === "sample") {
+      // const res = await fetchPermissions(context.slug);
+      // this.perms = { add: res.add, grid: res.grid, save: res.save };
+      // Flip any of these to false and reload to SEE the gate work: the grid
+      // disappears, or the button click is refused with the message below.
+      this.perms = { add: true, grid: true, save: true };
+    }
+  }
+
+  isAuthorized(kind: AuthzKind, permissionKey: string, context: AuthzContext): AuthzResult {
+    if (kind === AuthzKind.SCREEN) {
+      // Deny a whole screen here — e.g. `context.slug === "admin" && !this.perms.admin`
+      // — and every widget on it stays in skeleton mode with your message toasted.
+      void context;
+      return { authorized: true }; // omit `message` to use the core's default
+    }
+
+    // WIDGET and ACTION are both keyed by the schema-authored permissionKey.
+    // Denied widgets are hidden silently, so no message is worth setting.
+    if (permissionKey === "sample.grid") {
+      return { authorized: this.perms.grid };
+    }
+
+    // A denied action DOES toast.
+    if (permissionKey === "sample.add") {
+      return this.perms.add
+        ? { authorized: true }
+        : { authorized: false, message: "Adding contacts isn't allowed for your role." };
+    }
+    if (permissionKey === "sample.save") {
+      return this.perms.save
+        ? { authorized: true }
+        : { authorized: false, message: "Saving contacts isn't allowed for your role." };
+    }
+
+    return { authorized: true }; // un-keyed elements are always allowed
+  }
+}

package/templates/base/src/Factory/Actions/myAction.ts.tmpl

@@ -0,0 +1,51 @@
+/**
+ * Two custom actions that back the sample's custom widget (MY_WIDGET).
+ *
+ * Signature: (props, ...eventArgs). For an `onChange` the event args are
+ * (fieldPath, newValue, event); for an `onClick` there are usually none, unless
+ * the widget chooses to pass some — MyWidget passes its field path on reload.
+ *
+ * `props` carries:
+ *   actionProps        { key, config } — config is whatever you authored in the
+ *                      schema under the event.
+ *   callBack           The next action in the chain, or the framework's default
+ *                      continuation. Call it to hand off.
+ *   viewModel          The current { screenData, supportiveData }. READ-ONLY —
+ *                      write through callBack or the store.
+ *   navigate           React Router's NavigateFunction.
+ *   eventService       The per-screen event bus. emit("DATASTATE_ACTION") /
+ *                      emit("DISPATCH_STORE") reach the store directly.
+ *   executeValidation  Run a field's validations on demand; returns
+ *                      { isComponentValid, invalidMessages }.
+ *   uiElementGroupId   Which element group fired the event.
+ *
+ * Bound and chained from a schema as:
+ *
+ *   "events": {
+ *     "onChange": { "key": "CUS_MY_ACTION::MODIFY_MODEL" },
+ *     "onReload": { "key": "CUS_SUGGEST_CODE::MODIFY_MODEL" }
+ *   }
+ *
+ * `::` chains actions left to right; each step's callBack is the next step.
+ */
+
+/** CUS_MY_ACTION — normalise the typed value, then hand it to MODIFY_MODEL. */
+export const myAction = (props: any, fieldPath: string, newValue: any) => {
+  const cleaned = String(newValue ?? "").trim().toUpperCase().replace(/[^A-Z0-9_]/g, "_");
+
+  // Hand the value to the next action in the chain. When this action is chained
+  // as CUS_MY_ACTION::MODIFY_MODEL, callBack IS the MODIFY_MODEL step — so pass
+  // the REAL field path. Passing "screenData" instead makes MODIFY_MODEL
+  // validate a field name that does not exist, and the field's own error
+  // never clears.
+  props?.callBack?.(null, fieldPath, cleaned);
+};
+
+/** CUS_SUGGEST_CODE — a computed value for a field. MyWidget raises
+ *  onReload(null, fieldPath), so the path arrives as the first event arg. */
+export const suggestReferenceCode = (props: any, fieldPath?: string) => {
+  const field = fieldPath ?? props?.actionProps?.config?.field;
+  if (!field) return;
+  const code = `CT_${Math.random().toString(36).slice(2, 6).toUpperCase()}`;
+  props?.callBack?.(null, field, code);
+};

package/templates/base/src/Factory/Actions/sampleContacts.ts.tmpl

@@ -0,0 +1,244 @@
+/**
+ * The custom actions behind the sample "Contacts" screen.
+ *
+ * Before adding one of your own: a custom action is for COMPUTATION and
+ * ORCHESTRATION between standard steps. Writing a value is MODIFY_MODEL, loading is LOAD_SCREEN_DATA, saving
+ * is FORMSUBMIT_CREATE_ASYNC, confirming is CONFOMATIONALERTBOX, navigating is
+ * NAVIGATE — none of those needs a CUS_ key.
+ *
+ * This sample has no backend, so a few of these stand in for a standard action
+ * that would otherwise talk to an API. Each such stand-in says so in its header
+ * and names the standard key that replaces it when the screen goes live.
+ *
+ * Every handler has the signature (props, ...eventArgs) and hands its result
+ * to the next chain step through `props.callBack(null, field, value)`. Where a
+ * handler needs to write more than one path at once it dispatches through the
+ * event bus instead, which is the documented host-side write.
+ */
+
+import { summarise, statusBadge, emptyEditor, type Contact } from "../../AdapterProvider/SampleContacts";
+
+// ---------------------------------------------------------------------------
+// CUS_SAMPLE_LOAD_ROWS — the grid asked for data.
+//
+// SAMPLE STAND-IN for LOAD_SCREEN_DATA + apiConfig.get.
+// The grid raises `onScreenDataLoad(resultHandler)` on mount and again whenever
+// its sort, column search or pagination state changes (data-load mode B);
+// `resultHandler` arrives as `props.callBack` and writes what it is given to
+// the grid's screenDataField. A server would read the same grid state from the
+// request the adapter's generateQueryParams builds; here it is read straight
+// off the view model and applied to the in-memory set: sort by
+// `state.sort[0]`, filter by every `localSearch.appliedQuery` row ("contains",
+// case-insensitive — the only operator the column search emits).
+// Paging is left to the server on purpose: the grid re-slices locally what a
+// mode-B load returns, so a real page would be sliced twice.
+// ---------------------------------------------------------------------------
+export const loadRows = (props: any) => {
+  const screenData = props?.viewModel?.screenData ?? {};
+  const state = screenData[GRID_STATE_KEY] ?? {};
+  props?.callBack?.(project(screenData.contactsSource ?? [], state));
+};
+
+const GRID_STATE_KEY = "contactsGridState"; // = the grid's config.uiElementGroupId, minus "screenData."
+
+/** Apply the grid's sort and column-search state to the full set. */
+export const project = (source: Contact[], state: any): { records: Contact[]; total: number } => {
+  const filters: any[] = state?.localSearch?.appliedQuery?.filters ?? [];
+  let records = source.filter((row: any) =>
+    filters.every((f) => {
+      const needle = String(f?.value ?? "").trim().toLowerCase();
+      return !needle || String(row?.[f.field] ?? "").toLowerCase().includes(needle);
+    }),
+  );
+  const sort = state?.sort?.[0];
+  if (sort?.field) {
+    const dir = sort.dir === "desc" ? -1 : 1;
+    records = [...records].sort((a: any, b: any) =>
+      String(a?.[sort.field] ?? "").localeCompare(String(b?.[sort.field] ?? ""), undefined, { numeric: true }) * dir,
+    );
+  }
+  return { records, total: records.length };
+};
+
+// ---------------------------------------------------------------------------
+// CUS_SAMPLE_OPEN_ROW — a grid row was activated: load it into the editor.
+//
+// The GRID raises `navigate` with { dataItemKey, value }. With a real edit
+// screen this event is NAVIGATE with a STATE_SELECTED_DATA param (the
+// PromptManager pattern); this sample edits inline, so the
+// row is looked up and handed to MODIFY_MODEL.
+// ---------------------------------------------------------------------------
+export const openRow = (props: any, selected?: { dataItemKey: string; value: any }) => {
+  const records: Contact[] = props?.viewModel?.screenData?.contactsSource ?? [];
+  const key = selected?.dataItemKey ?? "id";
+  const row = records.find((r: any) => r?.[key] === selected?.value);
+  if (!row) return;
+  props?.callBack?.(null, "screenData.editor", {
+    ...emptyEditor(),
+    mode: "edit",
+    id: row.id,
+    name: row.name,
+    email: row.email,
+    department: { label: row.department, value: row.department },
+    // The DATE widget binds a Date object (or null) — a string reaches Kendo's
+    // calendar and throws `date.getTime is not a function`. With
+    // an API this conversion belongs in the adapter's deserializedModelData.
+    joined: row.joined ? new Date(row.joined) : null,
+    active: row.status === "Active",
+  });
+};
+
+// ---------------------------------------------------------------------------
+// CUS_SAMPLE_UPDATE_ROWS — a bulk action was CONFIRMED for the selected rows.
+//
+// SAMPLE STAND-IN. With an API these events are DELETE_ASYNC / UPDATE_ASYNC
+// with their own apiConfig verb block and a `refresh: true` on the action —
+// the framework then re-fetches the grid.
+// Here the rows are updated in memory from the event config:
+//   { "remove": true }                 delete
+//   { "set": { "status": "Inactive" } } patch
+//
+// Invoked by the grid as (props, selectedData) with `props.callBack` bound to
+// the grid's own "clear the selection" continuation, so the write goes through
+// the bus and the callback is honoured afterwards.
+// ---------------------------------------------------------------------------
+export const updateRows = (props: any, selectedData: any[] = []) => {
+  const config = props?.actionProps?.config ?? {};
+  const screenData = props?.viewModel?.screenData ?? {};
+  const source: Contact[] = screenData.contactsSource ?? [];
+  const ids = new Set(selectedData.map((r: any) => r?.id));
+
+  const next = config.remove
+    ? source.filter((r) => !ids.has(r.id))
+    : source.map((r) => {
+        if (!ids.has(r.id)) return r;
+        const patched = { ...r, ...(config.set ?? {}) } as Contact;
+        return { ...patched, statusBadge: statusBadge(patched.status) };
+      });
+
+  writeScreenData(props, {
+    ...screenData,
+    contactsSource: next,
+    contacts: project(next, screenData[GRID_STATE_KEY]),
+    summary: summarise(next),
+  });
+  props?.callBack?.();
+};
+
+// ---------------------------------------------------------------------------
+// CUS_SAMPLE_SAVE — validate the editor with the FRAMEWORK'S validators, then
+// upsert the row and show the success dialog.
+//
+// SAMPLE STAND-IN. With an API the Save button is FORMSUBMIT_CREATE_ASYNC /
+// FORMSUBMIT_UPDATE_ASYNC: it validates every visible
+// widget, POSTs `serializedRequestParam`, toasts per responseConfig and
+// navigates — and this whole action is deleted. Nothing here invents a
+// validator: each editor field's own `validations` are run through the
+// `executeValidation` seam the core hands every action, and the
+// messages land in the same store slice the standard path writes.
+//
+// Chained as "CUS_SAMPLE_SAVE::MODIFY_MODEL": on failure the chain stops at the
+// field errors; on success the next step receives the whole screenData.
+// ---------------------------------------------------------------------------
+export const saveContact = (props: any) => {
+  const screenData = props?.viewModel?.screenData ?? {};
+  const editor = screenData.editor ?? {};
+
+  const errors = validateWidgetsUnder(props, "screenData.editor.");
+  dispatch(props, "loadValidation", errors);
+  if (Object.values(errors).some((m) => m.length > 0)) return;
+
+  const source: Contact[] = screenData.contactsSource ?? [];
+  const status: Contact["status"] = editor.active ? "Active" : "Inactive";
+  const row: Contact = {
+    id: editor.id ?? Math.max(0, ...source.map((r) => r.id)) + 1,
+    name: editor.name,
+    email: editor.email,
+    department: editor.department?.value ?? "",
+    city: source.find((r) => r.id === editor.id)?.city ?? "—",
+    joined: typeof editor.joined === "string" ? editor.joined : toIsoDate(editor.joined),
+    status,
+    statusBadge: statusBadge(status),
+  };
+  const next = editor.id
+    ? source.map((r) => (r.id === row.id ? row : r))
+    : [...source, row];
+
+  props?.callBack?.(null, "screenData", {
+    ...screenData,
+    contactsSource: next,
+    contacts: project(next, screenData[GRID_STATE_KEY]),
+    summary: summarise(next),
+    editor: emptyEditor(),
+    saveNotice: {
+      visibleMode: "SHOW",
+      message: `${row.name} was ${editor.id ? "updated" : "added"}. With an API this is FORMSUBMIT_CREATE_ASYNC and a responseConfig toast.`,
+    },
+  });
+};
+
+// ---------------------------------------------------------------------------
+// CUS_SAMPLE_CONFIRM_BODY — put the selection count into a dialog's body.
+//
+// The alert widgets raise `handleBody(setBody, messageBody, value)`. Every widget event has the shape (callBack, ...args), so the action
+// receives it as (props, messageBody, value) with `props.callBack` = setBody —
+// the same convention as every other event, and the same pattern as
+// vsbackoffice's CUS_GETCONFIRMATIONBODYMSG. `value` is what the grid wrote to
+// the alert's screenDataField: it carries `selectedData`.
+// ---------------------------------------------------------------------------
+export const confirmBody = (props: any, body?: string, value?: any) => {
+  const count = value?.selectedData?.length ?? 0;
+  props?.callBack?.(String(body ?? "").replace("{count}", String(count)).replace("{s}", count === 1 ? "" : "s"));
+};
+
+// ---------------------------------------------------------------------------
+// CUS_SAMPLE_NOTICE_BODY — the success dialog's text comes from what
+// CUS_SAMPLE_SAVE wrote to screenData.saveNotice.message.
+// ---------------------------------------------------------------------------
+export const noticeBody = (props: any, body?: string, value?: any) => {
+  props?.callBack?.(String(body ?? "").replace("{message}", String(value?.message ?? "")));
+};
+
+// ---------------------------------------------------------------------------
+// helpers — the two documented host-side seams.
+// ---------------------------------------------------------------------------
+
+/** dispatch(appActions[name](payload)) through the event bus. */
+const dispatch = (props: any, name: string, payload: any) => {
+  const appActions = props?.eventService?.emit("DATASTATE_ACTION");
+  const store = props?.eventService?.emit("DISPATCH_STORE");
+  const creator = appActions?.[name];
+  if (typeof creator === "function" && typeof store === "function") store(creator(payload));
+};
+
+const writeScreenData = (props: any, value: any) => dispatch(props, "updateViewModel", { key: "screenData", value });
+
+/** Run each widget's own `validations` (ONSUBMIT) for every visible WIDGET
+ *  bound under `prefix`, exactly as FORMSUBMIT_* does before it posts. */
+const validateWidgetsUnder = (props: any, prefix: string): Record<string, string[]> => {
+  const uiSchema = props?.eventService?.emit("UISCHEMA");
+  const errors: Record<string, string[]> = {};
+  const walk = (el: any) => {
+    if (!el) return;
+    if (el.uiElementType === "WIDGET") {
+      if (el.visible !== false && el.screenDataField?.startsWith(prefix) && el.validations?.length) {
+        const result = props?.executeValidation?.({
+          executeMode: "ONSUBMIT",
+          screenDataField: el.screenDataField,
+          validations: el.validations,
+        });
+        errors[el.screenDataField] = result?.invalidMessages ?? [];
+      }
+      return;
+    }
+    (el.cells ?? []).forEach(walk);
+    (el.children ?? []).forEach(walk);
+  };
+  walk(uiSchema?.rootScreenElement);
+  return errors;
+};
+
+const toIsoDate = (value: any) => {
+  const d = value instanceof Date ? value : value ? new Date(value) : null;
+  return d && !Number.isNaN(d.getTime()) ? d.toISOString().slice(0, 10) : "";
+};

package/templates/base/src/Factory/Actions/setField.ts.tmpl

@@ -0,0 +1,20 @@
+/**
+ * CUS_SET_FIELD — write a config-declared value to a config-declared path.
+ *
+ * Chained as "CUS_SET_FIELD::MODIFY_MODEL". A BUTTON raises onClick with no
+ * arguments, and MODIFY_MODEL takes (field, value) as EVENT ARGUMENTS, so a
+ * button cannot reach MODIFY_MODEL on its own; this one-liner turns the event
+ * config into those arguments. It is the smallest legitimate custom action
+ * (a payload shaped from config and forwarded through callBack)
+ * and the one worth keeping in every app — "set X when clicked".
+ *
+ *   "onClick": {
+ *     "key": "CUS_SET_FIELD::MODIFY_MODEL",
+ *     "config": { "field": "screenData.editor", "value": { "mode": "add" } }
+ *   }
+ */
+export const setField = (props: any) => {
+  const { field, value } = props?.actionProps?.config ?? {};
+  if (!field) return;
+  props?.callBack?.(null, field, value);
+};

package/templates/base/src/Factory/CustomRuleEffectFactory.ts.tmpl

@@ -0,0 +1,30 @@
+import type { IRuleEffectFactory, RuleEffectFc } from "procode-lowcode-core";
+import { RuleEffectTypes } from "../constant";
+import { readOnlyEffect } from "./RuleEffects/readOnlyEffect";
+
+/**
+ * Custom rule effects, resolved by the `effect` name of a ruleInterpreter rule.
+ *
+ * Resolution is custom -> template -> standard, and only a function counts, so
+ * returning null hands the key on to the next tier. The standard tier owns
+ * SHOW, HIDE, ENABLE_ELEMENT, DISABLE_ELEMENT, ENABLE_REQUIRED,
+ * DISABLE_REQUIRED, ENABLE_VALIDATION, DISABLE_VALIDATION, RESET_VALUE,
+ * COMPUTE_VALUE, CHANGE_LABEL, TOGGLE_CLASS and SET_PROPS. Registering one of
+ * those names here OVERRIDES it on every screen — e.g.
+ * `[EffectType.SHOW, myShow]` with EffectType from procode-lowcode-core.
+ *
+ * An unknown effect is skipped with one warning per key. A Map, not an object
+ * literal: `effects["constructor"]` on a plain object returns a function the
+ * engine would call.
+ */
+class CustomRuleEffectFactory implements IRuleEffectFactory {
+  private effects = new Map<string, RuleEffectFc>([
+    [RuleEffectTypes.CUS_READONLY, readOnlyEffect],
+  ]);
+
+  getEffect(key: string) {
+    return this.effects.get(key) ?? null; // never throw
+  }
+}
+
+export default CustomRuleEffectFactory;

package/templates/base/src/Factory/CustomValidationFactory.tsx.tmpl

@@ -0,0 +1,24 @@
+import { IValidationFactory } from "procode-lowcode-core";
+import { ValidationTypes } from "../constant";
+import { myValidation } from "./Validations/myValidation";
+
+/**
+ * Extension point 5 of 5: custom validations, resolved by ValidationTypes
+ * constant. Resolution is custom -> template -> standard; a name no tier knows
+ * is logged and the field counts as VALID. A validation that "never fires" is
+ * usually a name that does not match the schema's `validations[].name`.
+ *
+ * A validation fn gets ({ validation, viewModel, eventService, value }) and
+ * returns { isValid, message }. It must not throw — a throw aborts the submit.
+ */
+class CustomValidationFactory implements IValidationFactory {
+  private validationMap = new Map<string, (props: any) => { isValid: boolean; message: string }>([
+    [ValidationTypes.MY_VALIDATION, myValidation],
+  ]);
+
+  getValidationFc(key: string) {
+    return this.validationMap.get(key) ?? null; // never throw
+  }
+}
+
+export default CustomValidationFactory;