ngx-t-forms-types 0.0.30 → 0.0.34

package/dist/skillet/workflow-context.d.ts

@@ -0,0 +1,95 @@
+/**
+ * The form inside the workflow.
+ *
+ * A form built with this package is never filled in on its own: it is the form
+ * of one STEP of a workflow, opened on a transaction that already carries the
+ * answers of earlier steps, and judged by what the engine does with its answers
+ * afterwards. The Form Creation Guide (`doc/guides/form-creation-guide.md`,
+ * "The form inside the workflow") sets out the rules that follow from that,
+ * and this module carries the two of them a model cannot honour unless the
+ * caller tells it something only the caller knows.
+ *
+ * ## Why this is hand-maintained
+ *
+ * Everything else in `src/skillet` is derived from this package — enums, Joi,
+ * the editor config — so it cannot fall behind. The facts here come from
+ * OUTSIDE it: the transaction document's own fields live in the workflow
+ * engine and its shared schema, and the system inputs are injected by the
+ * consuming application. Nothing in these typings declares them, so they are
+ * restated here with their source named, and the guide is the place to check
+ * them against. When the guide's reserved-names table changes, this list
+ * changes with it.
+ */
+/**
+ * Control names a form must never use.
+ *
+ * The engine merges every step's answers into one flat record keyed by control
+ * name and stores that record on the transaction document beside the
+ * document's own fields. A control named like one of those fields is
+ * overwritten, shadowed in lists, or misread as the payload envelope
+ * (`data`, `validations`). The `SYSTEM_*` and financial-cycle names are
+ * injected by the application as read-only system inputs and would collide
+ * the same way.
+ *
+ * Source: the guide's reserved-names table, read on 2026-09-03 from the
+ * transaction schema in iserve-shared-types (`schemas/FormVal`), the engine's
+ * document shape in ngx-t-workflow-typings (`WorkFlowDocument.interface.ts`)
+ * and the consuming application's system inputs
+ * (`app-configs/ngx-t-forms-config.service.ts`).
+ */
+export declare const RESERVED_CONTROL_NAMES: readonly ["_id", "reference", "status", "createdAt", "updatedAt", "previousDocRef", "originDocId", "workflowId", "docId", "data", "validations", "archive", "seal", "sealed", "checkedOut", "checkedOutDocId", "busy", "users", "activeWorkflow", "systemReference", "SYSTEM_TAGS", "SYSTEM_BY_USER", "SYSTEM_OVERDUE", "SYSTEM_STEP_MEMBERS", "failed", "failReason", "nextRunAt", "lastRunAt", ...string[]];
+/**
+ * The user-step types that carry a form. Decision gates, end steps, email
+ * steps and public portals carry none; they read answers already captured.
+ */
+export type WorkflowStepType = 'initiate' | 'append' | 'review' | 'adjudication';
+/** A control name a later step of the workflow reads. */
+export interface ExpectedControl {
+    /** The control name exactly as the reading step spells it. */
+    name: string;
+    /**
+     * What reads it and what that makes it, in a few words:
+     * "decision gate compares it against 30000, so a number", or
+     * "list column shown as currency". Sharpens the choice of element and type.
+     */
+    purpose?: string;
+}
+/**
+ * What the caller knows about the step this form is for.
+ *
+ * None of it is knowable from a prompt: the step type dictates what the form
+ * must contain, the step's control name is chosen by the workflow designer,
+ * and the names later steps read or earlier steps already answered exist only
+ * in the workflow. Supplied, they become the sentences a model needs in order
+ * to produce a form the engine can route.
+ */
+export interface WorkflowStepContext {
+    /** Which kind of step the form serves. */
+    type: WorkflowStepType;
+    /**
+     * The control name the step itself names: for a review step the toggle the
+     * engine routes on, for an adjudication step the adjudication output.
+     */
+    controlName?: string;
+    /**
+     * Control names later steps read — gate operands, list columns, the end
+     * step's schedule date, an email step's keys. Each must exist on this form,
+     * spelled exactly, typed as its purpose demands, required and never hidden.
+     */
+    expectedControls?: readonly ExpectedControl[];
+    /**
+     * Control names answered on an earlier step that this form should open with.
+     * The engine prefills by name, so the same name is how an earlier answer is
+     * carried forward; any other name starts a new field.
+     */
+    prefilledControlNames?: readonly string[];
+}
+/**
+ * Renders the step context as the prose appended to the form's description.
+ *
+ * Written once, at form level, rather than repeated on every column: the rules
+ * are about which fields the form must contain and how they are named, and a
+ * column has no way to see the others. The form description is the one place
+ * the model reads before it writes any of them.
+ */
+export declare function describeWorkflowStep(step: WorkflowStepContext): string;

package/dist/skillet/workflow-context.js

@@ -0,0 +1,128 @@
+/**
+ * The form inside the workflow.
+ *
+ * A form built with this package is never filled in on its own: it is the form
+ * of one STEP of a workflow, opened on a transaction that already carries the
+ * answers of earlier steps, and judged by what the engine does with its answers
+ * afterwards. The Form Creation Guide (`doc/guides/form-creation-guide.md`,
+ * "The form inside the workflow") sets out the rules that follow from that,
+ * and this module carries the two of them a model cannot honour unless the
+ * caller tells it something only the caller knows.
+ *
+ * ## Why this is hand-maintained
+ *
+ * Everything else in `src/skillet` is derived from this package — enums, Joi,
+ * the editor config — so it cannot fall behind. The facts here come from
+ * OUTSIDE it: the transaction document's own fields live in the workflow
+ * engine and its shared schema, and the system inputs are injected by the
+ * consuming application. Nothing in these typings declares them, so they are
+ * restated here with their source named, and the guide is the place to check
+ * them against. When the guide's reserved-names table changes, this list
+ * changes with it.
+ */
+/**
+ * Control names a form must never use.
+ *
+ * The engine merges every step's answers into one flat record keyed by control
+ * name and stores that record on the transaction document beside the
+ * document's own fields. A control named like one of those fields is
+ * overwritten, shadowed in lists, or misread as the payload envelope
+ * (`data`, `validations`). The `SYSTEM_*` and financial-cycle names are
+ * injected by the application as read-only system inputs and would collide
+ * the same way.
+ *
+ * Source: the guide's reserved-names table, read on 2026-09-03 from the
+ * transaction schema in iserve-shared-types (`schemas/FormVal`), the engine's
+ * document shape in ngx-t-workflow-typings (`WorkFlowDocument.interface.ts`)
+ * and the consuming application's system inputs
+ * (`app-configs/ngx-t-forms-config.service.ts`).
+ */
+export const RESERVED_CONTROL_NAMES = [
+    '_id',
+    'reference',
+    'status',
+    'createdAt',
+    'updatedAt',
+    'previousDocRef',
+    'originDocId',
+    'workflowId',
+    'docId',
+    'data',
+    'validations',
+    'archive',
+    'seal',
+    'sealed',
+    'checkedOut',
+    'checkedOutDocId',
+    'busy',
+    'users',
+    'activeWorkflow',
+    'systemReference',
+    'SYSTEM_TAGS',
+    'SYSTEM_BY_USER',
+    'SYSTEM_OVERDUE',
+    'SYSTEM_STEP_MEMBERS',
+    'failed',
+    'failReason',
+    'nextRunAt',
+    'lastRunAt',
+    ...['CURRENT', 'NEXT', 'PREVIOUS'].flatMap((cycle) => [
+        `${cycle}_FINANCIAL_CYCLE`,
+        `${cycle}_FINANCIAL_CYCLE_START_DATE`,
+        `${cycle}_FINANCIAL_CYCLE_END_DATE`,
+        `${cycle}_SPRINT_START_DATE`,
+        `${cycle}_SPRINT_END_DATE`,
+    ]),
+];
+const quote = (name) => `'${name}'`;
+/**
+ * The step-type sentences, one per type. Marked in the guide as engine rules
+ * (what the engine does) and house rules (what the builder's author requires);
+ * both are restated here rather than paraphrased so they cannot drift apart.
+ */
+function describeStepType(step) {
+    switch (step.type) {
+        case 'initiate':
+            return 'It is the first capture of a new transaction. The transaction reference number is generated by the engine from the step, so never ask the user for it.';
+        case 'append':
+            return 'It adds to a transaction that already carries earlier answers. Reuse an earlier control name only to show that answer and let this step correct it, read-only and on the first slide; otherwise every name must be new.';
+        case 'review': {
+            const name = step.controlName
+                ? `exactly ${quote(step.controlName)}`
+                : "exactly the step's control name, which the request must state";
+            return `Its one requirement is a toggle whose formControlName is ${name}: required, never conditionally hidden, with trueLabel and falseLabel naming the two outcomes such as 'Approve' and 'Reject'. The engine approves when that value is true and rejects when it is false. Add a signature. Reviewers read the whole transaction beside this form, so do not repeat earlier answers; at most add a comment shown only when the toggle is off.`;
+        }
+        case 'adjudication': {
+            const name = step.controlName
+                ? ` under the formControlName ${quote(step.controlName)}`
+                : '';
+            return `It must contain a workflowAdjudication element${name} whose adjudicationStep matches the stage the workflow step adjudicates; the engine does nothing further with it.`;
+        }
+    }
+}
+/**
+ * Renders the step context as the prose appended to the form's description.
+ *
+ * Written once, at form level, rather than repeated on every column: the rules
+ * are about which fields the form must contain and how they are named, and a
+ * column has no way to see the others. The form description is the one place
+ * the model reads before it writes any of them.
+ */
+export function describeWorkflowStep(step) {
+    const parts = [
+        `This form serves the ${step.type} step of a workflow. Every step's answers merge into one record keyed by control name, so a control name is new unless it is deliberately carrying an earlier answer forward.`,
+        describeStepType(step),
+    ];
+    const expected = step.expectedControls ?? [];
+    if (expected.length) {
+        const list = expected
+            .map((c) => (c.purpose ? `${quote(c.name)} (${c.purpose})` : quote(c.name)))
+            .join('; ');
+        parts.push(`Later steps read these control names, so each must exist on this form spelled exactly as given, be required, and never be conditionally hidden: ${list}. A value a decision gate compares must be stored as a number, a real boolean, or a single-word option value.`);
+    }
+    const prefilled = step.prefilledControlNames ?? [];
+    if (prefilled.length) {
+        parts.push(`These were answered on an earlier step; use exactly the same control name so the field opens prefilled, and mark it readonly unless this step may correct it: ${prefilled.map(quote).join(', ')}.`);
+    }
+    return parts.join(' ');
+}

package/package.json

@@ -1,60 +1,78 @@
-{
-  "name": "ngx-t-forms-types",
-  "version": "0.0.30",
-  "description": "Typings and interfaces for the ngx-t-forms library for dynamic forms.",
-  "keywords": [
-    "typings",
-    "typescript"
-  ],
-  "homepage": "https://github.com/mashegoTerrence/ngx-t-forms-typings#readme",
-  "bugs": {
-    "url": "https://github.com/mashegoTerrence/ngx-t-forms-typings/issues"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/mashegoTerrence/ngx-t-forms-typings.git"
-  },
-  "license": "ISC",
-  "author": "mashegoterrence@gmail.com",
-  "type": "module",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "files": [
-    "dist"
-  ],
-  "scripts": {
-    "test": "karma start karma.conf.cjs",
-    "clean": "rimraf dist",
-    "typecheck": "tsc --noEmit",
-    "build": "npm run clean && tsc && node scripts/add-js-extensions.mjs",
-    "build:prod": "npm run clean && tsc -p tsconfig.prod.json",
-    "prepublishOnly": "npm run build",
-    "dev": "npm run build --watch"
-  },
-  "dependencies": {
-    "joi": "^18.2.1"
-  },
-  "peerDependencies": {
-    "moment": ">=2.30.1",
-    "rxjs": ">=7.8.0"
-  },
-  "devDependencies": {
-    "@types/jasmine": "^5.1.7",
-    "@types/node": "^22.13.9",
-    "jasmine-core": "^5.6.0",
-    "karma": "^6.4.4",
-    "karma-chrome-launcher": "^3.2.0",
-    "karma-jasmine": "^5.1.0",
-    "karma-webpack": "^5.0.1",
-    "moment": "^2.30.1",
-    "rimraf": "^6.0.1",
-    "rxjs": "~7.8.0",
-    "ts-loader": "^9.5.2",
-    "typescript": "~5.9.2",
-    "webpack": "^5.98.0",
-    "webpack-dev-server": "^5.2.0"
-  }
-}
+{
+  "name": "ngx-t-forms-types",
+  "version": "0.0.34",
+  "description": "Typings and interfaces for the ngx-t-forms library for dynamic forms.",
+  "keywords": [
+    "typings",
+    "typescript"
+  ],
+  "homepage": "https://github.com/mashegoTerrence/ngx-t-forms-typings#readme",
+  "bugs": {
+    "url": "https://github.com/mashegoTerrence/ngx-t-forms-typings/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mashegoTerrence/ngx-t-forms-typings.git"
+  },
+  "license": "ISC",
+  "author": "mashegoterrence@gmail.com",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "test": "karma start karma.conf.cjs",
+    "clean": "rimraf dist",
+    "typecheck": "tsc --noEmit",
+    "build": "npm run clean && tsc && node scripts/add-js-extensions.mjs",
+    "build:prod": "npm run clean && tsc -p tsconfig.prod.json",
+    "prepublishOnly": "npm run build",
+    "dev": "npm run build --watch"
+  },
+  "dependencies": {
+    "joi": "^18.2.1"
+  },
+  "peerDependencies": {
+    "moment": ">=2.30.1",
+    "rxjs": ">=7.8.0",
+    "@hashbrownai/core": ">=0.5.0"
+  },
+  "devDependencies": {
+    "@hashbrownai/core": "^0.5.0",
+    "@types/jasmine": "^5.1.7",
+    "@types/node": "^22.13.9",
+    "jasmine-core": "^5.6.0",
+    "karma": "^6.4.4",
+    "karma-chrome-launcher": "^3.2.0",
+    "karma-jasmine": "^5.1.0",
+    "karma-webpack": "^5.0.1",
+    "moment": "^2.30.1",
+    "rimraf": "^6.0.1",
+    "rxjs": "~7.8.0",
+    "ts-loader": "^9.5.2",
+    "typescript": "~5.9.2",
+    "webpack": "^5.98.0",
+    "webpack-dev-server": "^5.2.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./skillet": {
+      "types": "./dist/skillet/index.d.ts",
+      "default": "./dist/skillet/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "peerDependenciesMeta": {
+    "@hashbrownai/core": {
+      "optional": true
+    }
+  }
+}