@rytass/bpm-core-shared 0.20.1 → 0.21.1

package/CHANGELOG.md

@@ -1,3 +1,77 @@
+## 0.21.1 (2026-11-11)
+
+### 🚀 Features
+
+- **workflow-engine:** judge the launchable list with the initiator customFields resolver ([92faedec](https://github.com/Rytass/BPMCore/commit/92faedec))
+- **react:** read the designer's today in the host organization time zone ([9a31ff90](https://github.com/Rytass/BPMCore/commit/9a31ff90))
+- **shared:** add the default organization time zone constant ([3dac42de](https://github.com/Rytass/BPMCore/commit/3dac42de))
+- **workflow-engine:** refuse a submit or resubmit holding more files than maxFiles ([abf75d2f](https://github.com/Rytass/BPMCore/commit/abf75d2f))
+- **shared:** tell which stages can start a manager chain with exactly one person ([6afc0c2d](https://github.com/Rytass/BPMCore/commit/6afc0c2d))
+- **shared:** let a manager chain start from a form pick or an earlier stage ([d181c1e8](https://github.com/Rytass/BPMCore/commit/d181c1e8))
+- **shared:** add excludeNodeActors to user task nodes ([0d6c5c42](https://github.com/Rytass/BPMCore/commit/0d6c5c42))
+- **react:** ask for the approval comment in the designer and on the approve dialog ([f80aaf04](https://github.com/Rytass/BPMCore/commit/f80aaf04))
+- **shared:** add setUserTaskRequireApprovalComment command and AI tool ([efe41c94](https://github.com/Rytass/BPMCore/commit/efe41c94))
+- **workflow-engine:** require a comment when a person approves at a node ([84474780](https://github.com/Rytass/BPMCore/commit/84474780))
+
+### 🩹 Fixes
+
+- **shared:** count excludeNodeActors handing over to the initiator's managers as multiple approvers ([6c5e7de6](https://github.com/Rytass/BPMCore/commit/6c5e7de6))
+- **bpm-core:** build one workflow engine so every caller sees the host resolver ([3e172843](https://github.com/Rytass/BPMCore/commit/3e172843))
+- **workflow-engine:** time out the initiator customFields resolver and keep its errors server-side ([45ff109d](https://github.com/Rytass/BPMCore/commit/45ff109d))
+- **react:** say ad-hoc approvers are not excluded in the excludeNodeActors hint ([815a89c4](https://github.com/Rytass/BPMCore/commit/815a89c4))
+- **shared:** refuse a manager chain notify recipient without a whole-number level ([cdca8b1e](https://github.com/Rytass/BPMCore/commit/cdca8b1e))
+- **workflow-engine:** count a repeated file_upload id once, as the binding does ([d75adb5c](https://github.com/Rytass/BPMCore/commit/d75adb5c))
+- **shared:** keep manager chain level and stage ids as written ([1c741259](https://github.com/Rytass/BPMCore/commit/1c741259))
+- **shared:** require an organization for a notify ORG_UNIT_MANAGER recipient ([1d348b84](https://github.com/Rytass/BPMCore/commit/1d348b84))
+- **workflow-engine:** hold a set-form-field write to member and unit value shapes ([c9d0523c](https://github.com/Rytass/BPMCore/commit/c9d0523c))
+- **shared:** quote the start-level schema line so the INITIATOR example compiles ([f0e64cf9](https://github.com/Rytass/BPMCore/commit/f0e64cf9))
+- **shared:** keep any start level the toolset is handed so validation reports it ([ca7e762f](https://github.com/Rytass/BPMCore/commit/ca7e762f))
+- **shared:** let the policy decide when a lone listed member may hand over to the initiator manager ([418b192b](https://github.com/Rytass/BPMCore/commit/418b192b))
+- **shared:** keep a chain start and start level the toolset cannot read so validation reports them ([2ed228a9](https://github.com/Rytass/BPMCore/commit/2ed228a9))
+- **shared:** keep the chain start when the toolset rewrites an approver ([71e3e1e7](https://github.com/Rytass/BPMCore/commit/71e3e1e7))
+- **shared:** name a start without a type in words and read a fractional start level back ([02b86146](https://github.com/Rytass/BPMCore/commit/02b86146))
+- **shared:** say parallel-branch stages are unsupported in excludeNodeActors hints ([ea6f5efa](https://github.com/Rytass/BPMCore/commit/ea6f5efa))
+- **shared:** describe what a skipped exclusion stage reads ([6c62b03f](https://github.com/Rytass/BPMCore/commit/6c62b03f))
+- **shared:** describe the stage rule in the excludeNodeActors tool and read a broken nodeIds safely ([c7a67f79](https://github.com/Rytass/BPMCore/commit/c7a67f79))
+- **shared:** hold every excludeNodeActors stage to the NODE_ACTOR source rules ([d16f216a](https://github.com/Rytass/BPMCore/commit/d16f216a))
+- **react:** harden the notify recipient panel after review ([17fab8db](https://github.com/Rytass/BPMCore/commit/17fab8db))
+
+### ❤️ Thank You
+
+- Chia Yu Pai @fantasywind
+- Kai-Chieh Yang
+
+## 0.21.0 (2026-11-11)
+
+### 🚀 Features
+
+- **bpm-core-react:** place refused fill values on their fields by path ([0f26687](https://github.com/Rytass/BPMCore/commit/0f26687))
+- **bpm-core-client:** expose refused form values on request errors ([3a5d406](https://github.com/Rytass/BPMCore/commit/3a5d406))
+- **shared:** add structured form data issue contract ([827e26d](https://github.com/Rytass/BPMCore/commit/827e26d))
+- **client:** add a filterable expense example list built on field filters ([3d624fb](https://github.com/Rytass/BPMCore/commit/3d624fb))
+- **react:** filterable toggle in the form builder and list field filters ([e8d58bf](https://github.com/Rytass/BPMCore/commit/e8d58bf))
+- **client:** pass field filters and sort to the approval-instance list ([bbfd789](https://github.com/Rytass/BPMCore/commit/bbfd789))
+- **workflow-engine:** filter and sort approval instances by form fields ([6e4a98f](https://github.com/Rytass/BPMCore/commit/6e4a98f))
+- **template:** refuse to enable a filterable field over conflicting history ([42628b4](https://github.com/Rytass/BPMCore/commit/42628b4))
+- **shared:** declare filterable form fields and the field filter contract ([166389e](https://github.com/Rytass/BPMCore/commit/166389e))
+- **api:** add a staging notify webhook showcase pushed over SSE ([0cb3ea5](https://github.com/Rytass/BPMCore/commit/0cb3ea5))
+
+### 🩹 Fixes
+
+- **client:** read form data issues all or nothing ([c0e4281](https://github.com/Rytass/BPMCore/commit/c0e4281))
+- **shared:** name the table, not a column, for a malformed filterable table ([c4b0420](https://github.com/Rytass/BPMCore/commit/c4b0420))
+- **shared:** describe filterable value mismatches in Chinese ([afd27a7](https://github.com/Rytass/BPMCore/commit/afd27a7))
+- **client:** name data-source values in case titles from the option snapshot ([14ade77](https://github.com/Rytass/BPMCore/commit/14ade77))
+- **shared:** narrow the self-approval flag with typeof in the resolver fallback parser ([19497cf](https://github.com/Rytass/BPMCore/commit/19497cf))
+
+### 🔥 Performance
+
+- **template:** scan instances only for fields a publish newly makes filterable ([b18dda2](https://github.com/Rytass/BPMCore/commit/b18dda2))
+
+### ❤️ Thank You
+
+- Chia Yu Pai @fantasywind
+
 ## 0.20.1 (2026-11-10)
 
 ### 🩹 Fixes

package/README.md

@@ -69,6 +69,11 @@ without a `mode` normalize to `single`; `radio` is always single and
   `ORG_MANAGER_CHAIN` accept an optional `fallback` (`NONE`, `DIRECT`, or
   `POSITION`). The `POSITION` fallback type is not released yet (it landed after
   `v0.16.2`); older engines reject it at run time.
+  `ORG_MANAGER_CHAIN` also takes `startFrom` (`OrgManagerChainStart`: the
+  initiator, the person picked in a form field, or the person who approved an
+  earlier stage) and `startPositionLevel` (managers below it are walked past);
+  both are optional, and an older engine ignores them and climbs from the
+  initiator.
 - Service task actions (`ServiceAction`) have three types. The workflow engine
   executes all three at run time:
   - `NOTIFY`: `channels`, `recipients` (an `ApproverResolver`), optional

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rytass/bpm-core-shared",
-  "version": "0.20.1",
+  "version": "0.21.1",
   "description": "Shared TypeScript contracts for the Rytass BPM approval workflow stack (workflow, form, condition, identity, organization, status types).",
   "keywords": [
     "bpm",

package/src/index.d.ts

@@ -5,6 +5,7 @@ export * from './lib/field-access';
 export * from './lib/field-access-lint';
 export * from './lib/field-access-matrix';
 export * from './lib/form';
+export * from './lib/form-filter';
 export * from './lib/identity';
 export * from './lib/organization';
 export * from './lib/status';

package/src/index.js

@@ -8,6 +8,7 @@ tslib_1.__exportStar(require("./lib/field-access"), exports);
 tslib_1.__exportStar(require("./lib/field-access-lint"), exports);
 tslib_1.__exportStar(require("./lib/field-access-matrix"), exports);
 tslib_1.__exportStar(require("./lib/form"), exports);
+tslib_1.__exportStar(require("./lib/form-filter"), exports);
 tslib_1.__exportStar(require("./lib/identity"), exports);
 tslib_1.__exportStar(require("./lib/organization"), exports);
 tslib_1.__exportStar(require("./lib/status"), exports);

package/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../libs/shared/src/index.ts"],"names":[],"mappings":";;;AAAA,0DAAgC;AAChC,oEAA0C;AAC1C,uEAA6C;AAC7C,6DAAmC;AACnC,kEAAwC;AACxC,oEAA0C;AAC1C,qDAA2B;AAC3B,yDAA+B;AAC/B,6DAAmC;AACnC,uDAA6B;AAC7B,yDAA+B;AAC/B,+DAAqC;AACrC,iEAAuC;AACvC,iEAAuC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../libs/shared/src/index.ts"],"names":[],"mappings":";;;AAAA,0DAAgC;AAChC,oEAA0C;AAC1C,uEAA6C;AAC7C,6DAAmC;AACnC,kEAAwC;AACxC,oEAA0C;AAC1C,qDAA2B;AAC3B,4DAAkC;AAClC,yDAA+B;AAC/B,6DAAmC;AACnC,uDAA6B;AAC7B,yDAA+B;AAC/B,+DAAqC;AACrC,iEAAuC;AACvC,iEAAuC"}

package/src/lib/form-filter.d.ts

@@ -0,0 +1,166 @@
+import { type FormDefinitionSchema, type FormFieldDefinition, type FormFieldOption, type TableColumnDefinition } from './form';
+/**
+ * Filtering and sorting the approval-instance list by form fields (ADR 25).
+ *
+ * Everything that decides "is this value right for a filterable field" lives
+ * here so the write-time check, the enable-time scan of old instances, the
+ * query compiler and the designer all answer the same way.
+ */
+/** Top-level field types a form designer may mark `filterable` (ADR 25 §5.2). */
+export declare const FILTERABLE_FIELD_TYPES: readonly ["autocomplete", "boolean", "checkbox", "date", "datetime", "member", "money", "number", "org_unit", "radio", "select", "text", "textarea"];
+export type FilterableFieldType = (typeof FILTERABLE_FIELD_TYPES)[number];
+/** Table column types a form designer may mark `filterable`: every column type. */
+export declare const FILTERABLE_TABLE_COLUMN_TYPES: readonly TableColumnDefinition['type'][];
+/**
+ * Sort keys that are not form fields. A filterable field must not use one of
+ * these as its `fieldKey`, or a sort request would be ambiguous.
+ */
+export declare const APPROVAL_INSTANCE_SORT_TIME_FIELDS: readonly ["submittedAt", "updatedAt", "completedAt"];
+export type ApprovalInstanceSortTimeField = (typeof APPROVAL_INSTANCE_SORT_TIME_FIELDS)[number];
+export declare function isApprovalInstanceSortTimeField(value: string): value is ApprovalInstanceSortTimeField;
+export declare function isFilterableFieldType(type: FormFieldDefinition['type'], placement?: 'column' | 'top-level'): boolean;
+export type ApprovalInstanceFieldFilterOperator = 'CONTAINS' | 'EQUALS' | 'IN' | 'NOT_EQUALS' | 'RANGE';
+export declare const APPROVAL_INSTANCE_FIELD_FILTER_OPERATORS: readonly ApprovalInstanceFieldFilterOperator[];
+export interface ApprovalInstanceFieldFilter {
+    /** A top-level fieldKey, or `<tableKey>.<columnKey>` for a table column. */
+    readonly fieldKey: string;
+    readonly operator: ApprovalInstanceFieldFilterOperator;
+    /** EQUALS, NOT_EQUALS and CONTAINS read the first value; IN reads them all. */
+    readonly values?: readonly string[];
+    /** RANGE lower bound, inclusive. Decimal string, `YYYY-MM-DD` or ISO 8601. */
+    readonly from?: string;
+    /** RANGE upper bound, inclusive. */
+    readonly to?: string;
+}
+export type ApprovalInstanceSortDirection = 'ASC' | 'DESC';
+export interface ApprovalInstanceSort {
+    /** A top-level filterable fieldKey, or one of {@link APPROVAL_INSTANCE_SORT_TIME_FIELDS}. */
+    readonly field: string;
+    readonly direction?: ApprovalInstanceSortDirection;
+}
+/**
+ * How a filterable value is stored and compared. Several field types share a
+ * kind: `money` compares like `number`, and every option-like field compares
+ * by its stored value.
+ */
+export type FilterableValueKind = 'boolean' | 'date' | 'datetime' | 'member' | 'number' | 'option' | 'org_unit' | 'text';
+export declare function readFilterableValueKind(type: FormFieldDefinition['type']): FilterableValueKind | null;
+/** Operators a field type accepts (ADR 25 §7.2). */
+export declare function readFilterOperatorsForFieldType(type: FormFieldDefinition['type']): readonly ApprovalInstanceFieldFilterOperator[];
+/** A filterable top-level field can be sorted on; a table column cannot (ADR 25 §7.5). */
+export declare function isFilterableFieldSortable(path: FilterableFieldPath): boolean;
+/** One filterable field, top-level or table column, as the list query sees it. */
+export interface FilterableFieldPath {
+    /** `fieldKey`, or `<tableKey>.<columnKey>`. */
+    readonly path: string;
+    readonly tableKey: string | null;
+    /** The key inside a row for a column; the fieldKey for a top-level field. */
+    readonly key: string;
+    readonly field: FormFieldDefinition | TableColumnDefinition;
+    readonly kind: FilterableValueKind;
+    readonly label: string;
+    /** Static options and their labels; `null` for a data-source or non-option field. */
+    readonly staticOptions: readonly FormFieldOption[] | null;
+    /** Labels live in the instance's option snapshot (a top-level data-source field). */
+    readonly usesOptionSnapshot: boolean;
+}
+/**
+ * The fields of `schema` a list query may filter on: every field (or table
+ * column) marked `filterable` whose type allows it. A field marked filterable
+ * with a type that does not allow it is skipped here; the schema lint reports
+ * it.
+ */
+export declare function readFilterableFieldPaths(schema: FormDefinitionSchema | null | undefined): readonly FilterableFieldPath[];
+export declare function findFilterableFieldPath(schema: FormDefinitionSchema | null | undefined, path: string): FilterableFieldPath | null;
+/**
+ * Every field and column of a schema by path, filterable or not. The enable
+ * check compares a new filterable field against what older versions stored
+ * at the same path, whether or not they were filterable then.
+ */
+export declare function readFormFieldTypesByPath(schema: FormDefinitionSchema | null | undefined): ReadonlyMap<string, FormFieldDefinition['type']>;
+export type FilterableValueCheck = {
+    readonly status: 'empty';
+} | {
+    readonly status: 'valid';
+} | {
+    readonly status: 'invalid';
+    readonly expected: string;
+};
+/**
+ * Whether one stored value fits a filterable field (ADR 25 §5.4, §6).
+ *
+ * - Missing and `null` are "no value". So is `""` for a number, money, date,
+ *   datetime or boolean field (a cleared input), and `[]` for a multi-value
+ *   field.
+ * - An option or member field accepts a string or an array of strings either
+ *   way: its `mode` / `multiple` may change between versions without changing
+ *   its type, and the query matches both shapes.
+ */
+export declare function checkFilterableFieldValue(field: FormFieldDefinition | TableColumnDefinition, value: unknown): FilterableValueCheck;
+export declare function isCanonicalDate(value: unknown): value is string;
+export declare function isCanonicalDateTime(value: unknown): value is string;
+/**
+ * A value inside a filterable path that does not fit its field. `path` is the
+ * top-level fieldKey, `<tableKey>.<columnKey>` for a bad cell, or the bare
+ * `tableKey` when the table itself (or one of its rows) is malformed.
+ */
+export interface FilterableValueProblem {
+    readonly path: string;
+    /** Index of the table row, or `null` for a top-level field. */
+    readonly rowIndex: number | null;
+    readonly value: unknown;
+    readonly expected: string;
+}
+/**
+ * Every value in `formData` that does not fit one of `paths`. Used both when
+ * writing (refuse the write) and when enabling a field (refuse to enable while
+ * old instances hold such values). A table that is not an array, or a row that
+ * is not an object, is a problem of every filterable column in it.
+ */
+export declare function readFilterableValueProblems(paths: readonly FilterableFieldPath[], formData: Readonly<Record<string, unknown>> | null | undefined): readonly FilterableValueProblem[];
+/** A field that would become filterable but whose history forbids it. */
+export type FilterableFieldIssue = {
+    readonly kind: 'TYPE_CHANGED';
+    readonly path: string;
+    readonly label: string;
+    readonly type: FormFieldDefinition['type'];
+    /** Older versions, still holding instances, that stored another type here. */
+    readonly conflicts: readonly {
+        readonly versionNumber: number;
+        readonly type: FormFieldDefinition['type'];
+    }[];
+} | {
+    readonly kind: 'INVALID_VALUES';
+    readonly path: string;
+    readonly label: string;
+    readonly type: FormFieldDefinition['type'];
+    readonly invalidInstanceCount: number;
+    /**
+     * The first few, for the message. The stored value is deliberately not
+     * carried: the issue reaches designers who may not read the instance.
+     */
+    readonly samples: readonly {
+        readonly instanceId: string;
+        readonly rowIndex: number | null;
+        readonly expected: string;
+    }[];
+};
+export declare const FILTERABLE_FIELD_ISSUE_SAMPLE_LIMIT = 5;
+/**
+ * The enable check (ADR 25 §5.4), pure: given the schema about to take effect,
+ * the schemas of older versions that hold instances, and those instances'
+ * form data, report every filterable field that may not be enabled.
+ */
+export declare function readFilterableFieldIssues(input: {
+    readonly schema: FormDefinitionSchema | null | undefined;
+    readonly history: readonly {
+        readonly versionNumber: number;
+        readonly schema: FormDefinitionSchema | null | undefined;
+    }[];
+    readonly instances: readonly {
+        readonly id: string;
+        readonly formData: Readonly<Record<string, unknown>> | null | undefined;
+    }[];
+}): readonly FilterableFieldIssue[];
+/** One line per issue, in the words the designer and the publish error use. */
+export declare function describeFilterableFieldIssue(issue: FilterableFieldIssue): string;