create-procode 0.0.0-stage → 1.0.0

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

@@ -0,0 +1,43 @@
+import React from "react";
+import { WidgetTypes } from "../constant";
+import MyWidget from "./Widgets/MyWidget";
+import SectionNav from "./Widgets/SectionNav";
+
+/**
+ * Extension point 3 of 5: custom widgets, resolved by WidgetTypes constant.
+ *
+ * Resolution order across the whole app is custom -> template -> standard, so
+ * registering a type name that already exists overrides it EVERYWHERE. Do not
+ * register a custom TEXTBOX, DATE, DATERANGE, RADIOGROUP, CHECKBOX or DIALOG —
+ * vs-template's grid toolbar depends on those and you will visibly break the
+ * global-search box.
+ *
+ * A widget is presentation only. It receives its value through props and writes
+ * back through props.onChange; it never fetches its own data.
+ */
+class CustomWidgetFactory {
+  private static factory: CustomWidgetFactory;
+  private widgetMap = new Map<string, React.FC<any>>();
+
+  private constructor() {
+    this.createWidgetMap();
+  }
+
+  static get() {
+    if (!CustomWidgetFactory.factory) {
+      CustomWidgetFactory.factory = new CustomWidgetFactory();
+    }
+    return CustomWidgetFactory.factory;
+  }
+
+  private createWidgetMap(): void {
+    this.widgetMap.set(WidgetTypes.MY_WIDGET, MyWidget);
+    this.widgetMap.set(WidgetTypes.SECTION_NAV, SectionNav);
+  }
+
+  getWidgets() {
+    return this.widgetMap;
+  }
+}
+
+export default CustomWidgetFactory;

package/templates/base/src/Factory/RuleEffects/readOnlyEffect.ts.tmpl

@@ -0,0 +1,27 @@
+import type { RuleEffectFc } from "procode-lowcode-core";
+
+/**
+ * CUS_READONLY — the element is read-only while the rule's condition is met.
+ *
+ * A rule effect receives the target element and the condition that matched
+ * (undefined when none did) and returns the element's replacement. The engine
+ * re-runs every rule until nothing changes (up to 50 passes), on screen init
+ * and on every view-model change, so an effect must be:
+ *
+ *   total       — write the property on BOTH branches; the engine keeps no copy
+ *                 of the authored value to restore.
+ *   idempotent  — return {} when the element is already right, or the loop
+ *                 never settles.
+ *   pure        — no fetch, dispatch or toast; a new object, never a mutation.
+ *
+ * Any key written onto the element reaches the widget as a prop. TEXTBOX and
+ * TEXTAREA honour `readOnly`; DROPDOWN and COMBOBOX do not — for those use the
+ * standard DISABLE_ELEMENT effect instead.
+ *
+ *   { "effect": "CUS_READONLY", "config": { "otherwise": false }, "conditionList": [ … ] }
+ */
+export const readOnlyEffect: RuleEffectFc = ({ uiElement, condition, rule }) => {
+  const readOnly = condition ? true : Boolean(rule.config?.otherwise);
+  if (uiElement.readOnly === readOnly) return {};
+  return { modifiedUiElement: { ...uiElement, readOnly } };
+};

package/templates/base/src/Factory/Validations/myValidation.ts.tmpl

@@ -0,0 +1,52 @@
+/**
+ * A custom validator.
+ *
+ * THE CONTRACT — the core's ValidationInvoker calls every validator, standard
+ * or custom, as
+ *
+ *   validationFc({ validation, viewModel, eventService, value })
+ *     -> { isValid: boolean; message: string }
+ *
+ * (procode-core/src/Validation/ValidationInvoker.ts, `executeValidations`) and
+ * pushes `message` into the field's error list when `isValid` is false.
+ * Returning a bare boolean is the classic mistake: `{ isValid, message }`
+ * destructured from `true` is `undefined` twice, so the field collects an
+ * `undefined` message and the validation-message HOC throws on render —
+ * "Cannot read properties of undefined (reading 'replaceAll')" — taking the
+ * whole screen to the error boundary.
+ *
+ *   validation   the rule as authored in the schema: { name, message, params, … }
+ *   value        the value at the rule's screenDataField (or the widget's)
+ *   viewModel    the whole { screenData, supportiveData } — for cross-field rules
+ *
+ * Referenced from a schema as:
+ *
+ *   "validations": [
+ *     { "name": "REQUIRED",      "message": "Please enter a value",
+ *       "executeOrder": 1, "executeMode": "ONVALUECHANGE|ONSUBMIT" },
+ *     { "name": "MY_VALIDATION", "message": "Use capitals, digits and underscore only",
+ *       "executeOrder": 2, "executeMode": "ONVALUECHANGE|ONSUBMIT" }
+ *   ]
+ *
+ * Leave emptiness to REQUIRED. A validator that also rejects "" makes a blank
+ * optional field show the wrong message. Use the schema's `message` so the
+ * text is authored next to the rule, with a fallback for a rule that omits it.
+ */
+export const myValidation = ({
+  validation,
+  value,
+}: {
+  validation: { message?: string; params?: Record<string, any> };
+  value: any;
+  viewModel?: any;
+  eventService?: any;
+}): { isValid: boolean; message: string } => {
+  if (value === null || value === undefined || value === "") {
+    return { isValid: true, message: "" };
+  }
+  const isValid = /^[A-Z0-9_]+$/.test(String(value));
+  return {
+    isValid,
+    message: isValid ? "" : validation?.message || "Use capitals, digits and underscore only",
+  };
+};

package/templates/base/src/Factory/Widgets/MyWidget/index.tsx.tmpl

@@ -0,0 +1,101 @@
+import { TextBox, Button } from "procode-lowcode-kendo-widget/widgets";
+
+/**
+ * A custom widget — presentation only, and COMPOSED FROM LIBRARY WIDGETS.
+ *
+ * Two rules bind every file in this folder:
+ *
+ *   1. Whatever a custom widget needs inside it — a text box, a dropdown, a
+ *      date picker, a button, an icon, a dialog — is rendered with the
+ *      library's component for it, imported from
+ *      procode-lowcode-kendo-widget/widgets. Not a raw <input>, and NEVER
+ *      `import { TextBox } from "@progress/kendo-react-inputs"`: that
+ *      component would sit outside the theme's focus/disabled/invalid
+ *      treatment, the label and validation HOCs, widgetStyle, registerIcons
+ *      and the override seam, and look different from the schema TEXTBOX
+ *      beside it. The ESLint config refuses such an import unless a
+ *      `procode-escalation:` comment sits on the line above it — legitimate
+ *      only for a control the catalog does not wrap.
+ *
+ *   2. It never fetches its own data. A widget that calls an API loses the
+ *      loading counter and skeletons, status-code toasts, 422 -> field-error
+ *      routing and a schema-visible endpoint. Data belongs to `apiConfig`
+ *      plus a standard action bound to a schema event.
+ *
+ * The props arrive from useWidgetProps and are passed STRAIGHT
+ * THROUGH. Every library widget relays change as
+ * onChange(null, screenDataField, value, event) — the same shape a schema
+ * TEXTBOX raises — so the CUS_MY_ACTION::MODIFY_MODEL chain below sees exactly
+ * what it would see on a standard field, and the label, the REQUIRED asterisk
+ * and the validation message under the box are drawn by the library.
+ *
+ * Referenced from a schema as:
+ *
+ *   {
+ *     "uiElementType": "WIDGET",
+ *     "widgetType": "MY_WIDGET",
+ *     "title": "Reference code",
+ *     "screenDataField": "screenData.referenceCode",
+ *     "applicableOn": "referenceCode",
+ *     "skeletonType": "SQUARE_LARGE",
+ *     "events": {
+ *       "onChange": { "key": "MODIFY_MODEL" },
+ *       "onReload": { "key": "CUS_SUGGEST_CODE::MODIFY_MODEL" }
+ *     }
+ *   }
+ */
+const MyWidget = (props: any) => {
+  // props.value            — current value at props.screenDataField
+  // props.screenDataField  — the dot-path this widget is bound to
+  // props.onChange         — (callBack, fieldPath, newValue, event) => void
+  // props.validations      — the runtime's current error messages (string[])
+  // props.availableValidations — the schema's rules (drives the REQUIRED mark)
+  // props.dynamicEvents    — EVERY event declared on the element, by name
+  // ...plus every other key authored on the element in the schema
+
+  return (
+    <div className="prc-flx-container prc-verticle qo-gap-y-sm qo-padding-sm">
+      <TextBox
+        name={props.screenDataField}
+        screenDataField={props.screenDataField}
+        value={props.value}
+        onChange={props.onChange}
+        onBlur={props.onBlur}
+        label={{
+          title: props.title,
+          isApply: Boolean(props.title),
+          position: "top",
+          widgetStyle: { className: "qo-label prc-blc-inline-container" },
+        }}
+        placeHolder={props.placeHolder ?? props.placeholder}
+        disabled={props.disabled ?? false}
+        // A field a CUSTOM WIDGET renders never passes through a schema, so it
+        // never gets a widgetStyle from one and falls back to Kendo's own 30px.
+        // qo-h-control puts it on the same 40px ramp as every schema field
+        // beside it. `qo-size-*` does not exist in the theme.
+        widgetStyle={{ className: "qo-h-control" }}
+        validations={props.validations}
+        availableValidations={props.availableValidations}
+        viewModel={props.viewModel}
+      />
+
+      {/* An event the prop types do not name is reached through dynamicEvents,
+          so a renamed schema event shows up as undefined here rather than as a
+          type error somewhere else. The library Button calls onClick(null);
+          the field path is passed on as the first EVENT ARGUMENT so the
+          action (CUS_SUGGEST_CODE) knows which field to fill. */}
+      <Button
+        title="Suggest a code"
+        role="button"
+        type="button"
+        fillMode="outline"
+        togglable={false}
+        defaultImageUrl=""
+        widgetStyle={{ className: "qo-btn qo-btn-sm qo-btn-outline-default qo-text-primary" }}
+        onClick={() => props.dynamicEvents?.onReload?.(null, props.screenDataField)}
+      />
+    </div>
+  );
+};
+
+export default MyWidget;

package/templates/base/src/Factory/Widgets/Notification/index.tsx.tmpl

@@ -0,0 +1,53 @@
+import { forwardRef, useImperativeHandle } from "react";
+import { ToastContainer } from "react-toastify";
+import { errorNotify, successNotify } from "./notifiFunc";
+import "react-toastify/dist/ReactToastify.css";
+
+/**
+ * The notification surface, handed to <Core> as NotificationElement.
+ *
+ * The core keeps a ref to this component and calls showNotification({ message,
+ * type }) on it — for responseConfig toasts, denied actions and validation
+ * summaries. It is the app's ONE toast host: a hand-rolled toast anywhere else
+ * means two stacks that do not know about each other.
+ */
+enum NotifiType {
+  SUCCESS = "SUCCESS",
+  ERROR = "ERROR",
+}
+
+const Notification = forwardRef((_props: any, ref) => {
+  const showNotification = ({ message, type }: any) => {
+    switch (type) {
+      case NotifiType.SUCCESS:
+        successNotify(message);
+        break;
+      case NotifiType.ERROR:
+        errorNotify(message);
+        break;
+      default:
+        break;
+    }
+  };
+
+  useImperativeHandle(ref, () => ({ showNotification }));
+
+  return (
+    <ToastContainer
+      position="bottom-center"
+      autoClose={3000}
+      hideProgressBar={false}
+      newestOnTop
+      closeOnClick
+      rtl={false}
+      pauseOnFocusLoss
+      draggable
+      pauseOnHover
+      theme="colored"
+    />
+  );
+});
+
+Notification.displayName = "Notification";
+
+export default Notification;

package/templates/base/src/Factory/Widgets/Notification/notifiFunc.ts.tmpl

@@ -0,0 +1,9 @@
+import { toast } from "react-toastify";
+
+export const successNotify = (message: string) => {
+  toast.success(message);
+};
+
+export const errorNotify = (message: string) => {
+  toast.error(message);
+};

package/templates/base/src/Factory/Widgets/SectionNav/index.tsx

@@ -0,0 +1,193 @@
+import { useEffect, useState } from "react";
+import { Icon } from "procode-lowcode-kendo-widget/widgets";
+
+// procode-escalation: raw-control — L4 cannot compose this because the catalog
+// has no vertical nav-item primitive: the only clickable text widget is BUTTON,
+// whose library component renders a Kendo Button carrying min-height 40px,
+// padding, a 6px radius, a border and the theme's own hover/focus fill
+// A section row is a 38px flush text row with a 3px left accent bar, a tinted
+// active state and `font: inherit`, so every one of those would have to be
+// overridden — which is the anti-pattern the library-first rule exists to
+// prevent, not an instance of it. VS Backoffice's SPOPSectionNav reaches the
+// same conclusion and uses a raw <button> for the row. The ICON inside the row
+// is still the library widget, per the library-first rule.
+// Catalog candidate: a NAV_LIST / SECTION_NAV widget in procode-vs-template.
+
+/**
+ * SECTION_NAV — the left "Sections" rail on a long form or view screen.
+ *
+ * Ported from VS Backoffice's `SPOP_SECTION_NAV`
+ * (src/Factory/Widgets/SPOPSectionNav/index.tsx), which is the house pattern for
+ * this: a white card with a small uppercase heading and badge, a one-line hint,
+ * then one row per section with an icon, the active row marked by a left accent
+ * bar and a tinted background.
+ *
+ * **IT SCROLLS, IT DOES NOT SWITCH.** Every section is rendered and the whole
+ * form is readable by scrolling; clicking a row just brings that section to the
+ * top of the form panel. So the highlight cannot be driven by a click alone — an
+ * operator who scrolls past three sections without clicking would leave it
+ * stranded on the first. An IntersectionObserver over the section panels keeps
+ * it honest, and the click only sets it optimistically so the row responds
+ * immediately rather than waiting for the smooth scroll to finish.
+ *
+ * That is also why this holds its own state instead of writing through an
+ * action: the highlight changes on every scroll, and dispatching a store update
+ * per scroll frame would be a poor trade for a value nothing else reads. The
+ * bound `screenData.sectionNav` still supplies the heading, the badge, the hint,
+ * the items and the STARTING section.
+ *
+ * ---
+ *
+ * L4 escalation proof: **L0 cannot do this because no widget in the three
+ * packages draws a vertical section list — `TAB` draws a horizontal strip of
+ * label links with an active class, with no icon, no hint and no vertical
+ * card.** The rule engine cannot help either: only
+ * SHOW/HIDE effects exist, so a schema-only version has
+ * to pre-author an active and an inactive copy of every row and pick one — which
+ * is what this screen did before, and which can only ever track a *click*, never
+ * the scroll position.
+ *
+ * Library-first: the glyph is the library `Icon` widget from
+ * `procode-lowcode-kendo-widget/widgets`, which resolves a Kendo SVG icon
+ * through `loadIcon`. No `@fortawesome/*` import — VS Backoffice's copy uses
+ * FontAwesome because that app carries it as a dependency; this one does not,
+ * and adding a second icon set is forbidden.
+ *
+ * Presentation only: it renders what it is given and never fetches.
+ *
+ * Registered as `WidgetTypes.SECTION_NAV`.
+ */
+
+type Item = {
+  /** Matches the section container's `widgetStyle.id` in the schema. */
+  id: string;
+  label: string;
+  /** A Kendo SVG icon name, as `loadIcon` resolves it. Omitted renders no glyph. */
+  icon?: string;
+};
+
+type Nav = {
+  heading?: string;
+  badge?: string;
+  hint?: string;
+  /** The section highlighted before the observer has anything to say. */
+  active?: string;
+  items?: Item[];
+};
+
+type Props = {
+  /** The bound `screenData.<field>` node — see `Nav` above. */
+  value?: Nav;
+  widgetStyle?: { className?: string; id?: string; inline?: Record<string, unknown> };
+};
+
+const text = (v: unknown): string => (v === null || v === undefined ? "" : String(v));
+
+const SectionNav = ({ value, widgetStyle }: Props) => {
+  const items = Array.isArray(value?.items) ? (value!.items as Item[]) : [];
+  const firstId = text(items[0]?.id);
+
+  const [active, setActive] = useState(text(value?.active) || firstId);
+
+  // The ids are the observer's dependency, not the array identity: the schema
+  // rebuilds `items` on every render, so depending on the array would tear the
+  // observer down and rebuild it constantly.
+  const ids = items.map((item) => text(item?.id)).join(",");
+
+  useEffect(() => {
+    const sections = ids
+      .split(",")
+      .filter(Boolean)
+      .map((id) => ({ id, element: document.getElementById(id) }))
+      .filter((entry) => entry.element !== null) as { id: string; element: HTMLElement }[];
+
+    if (sections.length === 0) return;
+
+    // The sections are tall, so "which one is in view" is ambiguous whenever two
+    // are on screen at once. The rule is the topmost one that is intersecting,
+    // in schema order, which is what a reader would call the section they are in.
+    const visible = new Set<string>();
+
+    const observer = new IntersectionObserver(
+      (entries) => {
+        entries.forEach((entry) => {
+          const id = sections.find((s) => s.element === entry.target)?.id;
+          if (!id) return;
+          if (entry.isIntersecting) visible.add(id);
+          else visible.delete(id);
+        });
+
+        const topmost = sections.find((section) => visible.has(section.id));
+        if (topmost) setActive(topmost.id);
+      },
+      {
+        // Ignore the bottom two-thirds: without it the last section never wins,
+        // because a short final panel is on screen at the same time as the one
+        // above it and the one above it always sorts first.
+        rootMargin: "0px 0px -66% 0px",
+        threshold: 0,
+      },
+    );
+
+    sections.forEach((section) => observer.observe(section.element));
+    return () => observer.disconnect();
+  }, [ids]);
+
+  if (items.length === 0) return null;
+
+  const onPick = (id: string) => {
+    // Optimistic: the row responds now rather than after the smooth scroll. The
+    // observer corrects it a moment later if the scroll lands elsewhere.
+    setActive(id);
+    document.getElementById(id)?.scrollIntoView({ behavior: "smooth", block: "start" });
+  };
+
+  const heading = text(value?.heading) || "Sections";
+  const badge = text(value?.badge);
+  const hint = text(value?.hint);
+
+  return (
+    <nav
+      id={widgetStyle?.id}
+      className={`cus-section-nav ${widgetStyle?.className ?? ""}`.trim()}
+      style={widgetStyle?.inline}
+      aria-label={heading}
+    >
+      <div className="cus-section-nav__head">
+        <span className="cus-section-nav__heading">{heading}</span>
+        {badge ? <span className="cus-section-nav__badge">{badge}</span> : null}
+      </div>
+
+      {hint ? <p className="cus-section-nav__hint">{hint}</p> : null}
+
+      <ul className="cus-section-nav__list">
+        {items.map((item) => {
+          const id = text(item?.id);
+          const isActive = id === active;
+          return (
+            <li key={id}>
+              <button
+                type="button"
+                className={`cus-section-nav__item${isActive ? " cus-section-nav__item--active" : ""}`}
+                aria-current={isActive ? "true" : undefined}
+                onClick={() => onPick(id)}
+              >
+                {item?.icon ? (
+                  // The row's own <span> carries the label, so the glyph is
+                  // decorative: aria-hidden on the wrapper, and `title=""` so the
+                  // Icon widget's required prop adds no second accessible name.
+                  <span className="cus-section-nav__icon" aria-hidden="true">
+                    <Icon name={item.icon} title="" fillMode="clear" />
+                  </span>
+                ) : null}
+                <span>{text(item?.label)}</span>
+              </button>
+            </li>
+          );
+        })}
+      </ul>
+    </nav>
+  );
+};
+
+export default SectionNav;

package/templates/base/src/Factory/Widgets/SectionNav/style.scss

@@ -0,0 +1,139 @@
+// The left "Sections" rail — a white bordered card, a small uppercase heading
+// with a badge, a muted hint, then icon rows with the active one tinted and
+// marked by a left accent bar.
+//
+// Ported from VS Backoffice's `.spop-section-nav`
+// (src/Factory/Widgets/SPOPSectionNav/style.scss). Values are stated as theme
+// tokens rather than the literals that file carries as fallbacks — every one of
+// them is defined by procode-vs-theme 2.6.0, so there is nothing to fall back
+// to.
+.cus-section-nav {
+  display: flex;
+  flex-direction: column;
+
+  // Fixed width that cannot be squeezed by the form panel beside it. It lives
+  // here rather than on the schema node because the theme has no no-shrink
+  // class, and an inline width alone would still let flex shrink the card.
+  flex: 0 0 230px;
+
+  // THE CARD MUST NOT SCROLL AWAY. Two arrangements have to work:
+  //   - the form panel beside it is the scroller (what Company Edit/View do),
+  //     so the card is outside it and simply never moves; `sticky` is inert;
+  //   - an ancestor scrolls instead, and `sticky` pins the card to the top of
+  //     that scrollport so it stays in view anyway.
+  // `align-self: flex-start` is required for both: the flex default `stretch`
+  // would make the card full height, leaving sticky no room to travel in.
+  align-self: flex-start;
+  position: sticky;
+  top: 0;
+
+  gap: var(--qo-space-2);
+  padding: var(--qo-space-4) 0 var(--qo-space-2);
+  border: var(--qo-border-width-sm) solid var(--qo-border-light);
+  border-radius: var(--qo-border-radius-sm);
+  background: var(--qo-bg-default);
+
+  &__head {
+    display: flex;
+    align-items: center;
+    gap: var(--qo-space-2);
+    padding: 0 var(--qo-space-4);
+  }
+
+  &__heading {
+    font-family: var(--qo-font-family-primary);
+    font-size: var(--qo-font-size-xs);
+    font-weight: var(--qo-font-weight-semibold);
+    letter-spacing: 0.06em;
+    text-transform: uppercase;
+    color: var(--qo-text-dark);
+  }
+
+  &__badge {
+    padding: 1px 6px;
+    border: var(--qo-border-width-sm) solid var(--qo-text-primary);
+    border-radius: 3px;
+    font-family: var(--qo-font-family-primary);
+    font-size: var(--qo-font-size-xxs);
+    font-weight: var(--qo-font-weight-semibold);
+    letter-spacing: 0.04em;
+    text-transform: uppercase;
+    color: var(--qo-text-primary);
+  }
+
+  &__hint {
+    margin: 0;
+    padding: 0 var(--qo-space-4);
+    font-family: var(--qo-font-family-primary);
+    font-size: var(--qo-font-size-sm);
+    color: var(--qo-text-secondary);
+  }
+
+  &__list {
+    display: flex;
+    flex-direction: column;
+    margin: var(--qo-space-1) 0 0;
+    padding: 0;
+    list-style: none;
+  }
+
+  &__item {
+    display: flex;
+    align-items: center;
+    gap: 10px;
+    width: 100%;
+
+    // 3px of the left padding is the accent bar's lane, so the label does not
+    // shift by 3px when a row becomes active.
+    padding: 9px var(--qo-space-4) 9px 11px;
+    border: 0;
+    border-left: var(--qo-border-width-lg) solid transparent;
+    background: none;
+    font: inherit;
+    font-family: var(--qo-font-family-primary);
+    font-size: var(--qo-font-size-md);
+    color: var(--qo-text-dark);
+    text-align: left;
+    cursor: pointer;
+
+    &:hover {
+      background: var(--qo-bg-secondary);
+    }
+
+    // :focus-visible, so a mouse click leaves no ring — the house rule the
+    // theme's component layer follows throughout.
+    &:focus-visible {
+      outline: var(--qo-border-width-sm) solid var(--qo-text-primary);
+      outline-offset: -1px;
+    }
+  }
+
+  &__item--active {
+    border-left-color: var(--qo-text-primary);
+    background: var(--qo-bg-primary-soft);
+    color: var(--qo-text-primary);
+    font-weight: var(--qo-font-weight-semibold);
+  }
+
+  // The library Icon widget renders a Kendo Button, so the row's own padding
+  // and hover must not be doubled by the button's.
+  &__icon {
+    flex: 0 0 auto;
+    display: inline-flex;
+    color: currentColor;
+
+    .k-button {
+      min-height: 0;
+      padding: 0;
+      border: 0;
+      background: none;
+      color: currentColor;
+      pointer-events: none;
+    }
+
+    .k-svg-icon {
+      width: 14px;
+      height: 14px;
+    }
+  }
+}