@rytass/bpm-core-client 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -1,3 +1,48 @@
+## 0.9.0 (2026-08-17)
+
+### 🚀 Features
+
+- **notification:** lift routing fields onto the created event ([e02270b](https://github.com/Rytass/BPMCore/commit/e02270b))
+- **notification:** let a host observe notifications as they are created ([#21](https://github.com/Rytass/BPMCore/pull/21))
+- **shared:** detect a quorum no approver set can ever satisfy ([5671497](https://github.com/Rytass/BPMCore/commit/5671497))
+- **shared:** expose the decision policy to the workflow toolset ([f6152b0](https://github.com/Rytass/BPMCore/commit/f6152b0))
+
+### 🩹 Fixes
+
+- ⚠️  **template:** reject deleting a referenced category ([#16](https://github.com/Rytass/BPMCore/pull/16))
+- **template:** let a template actually change category ([#17](https://github.com/Rytass/BPMCore/pull/17))
+- **shared:** keep an approver change from discarding a workable policy ([ea6afbe](https://github.com/Rytass/BPMCore/commit/ea6afbe))
+- **e2e:** poll on the expected value in the quorum threshold sanitiser spec ([099529f](https://github.com/Rytass/BPMCore/commit/099529f))
+- **bpm-core-react:** correct decision-policy panel review findings ([ebf0337](https://github.com/Rytass/BPMCore/commit/ebf0337))
+
+### ⚠️  Breaking Changes
+
+- **template:** reject deleting a referenced category  ([#16](https://github.com/Rytass/BPMCore/pull/16))
+  `deleteApprovalTemplateCategory` now throws
+  `BadRequestException` when templates still reference the category, instead
+  of deactivating it and reporting success.
+  The old behaviour substituted a different operation for the one requested
+  and returned the same entity type either way, so a caller could not tell
+  that the delete had not happened — nor that `isActive` had been flipped as
+  a side effect it never asked for. Downstream, the category vanished from
+  groupings because it was now inactive, with nothing to explain why.
+  Deactivation is not lost: `deactivateApprovalTemplateCategory(id)` has
+  always existed and is unchanged, so the fallback was never the only way to
+  reach that state.
+  The designer's category screen already wraps the call in try/catch and
+  surfaces the message, and it only closes the confirmation dialog on
+  success, so the new error reaches the author without a UI change.
+  Reported by a consumer on 0.7.0, who had to re-implement the reference
+  check ahead of the call to avoid telling users something had been deleted
+  when it had not.
+  Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
+
+### ❤️ Thank You
+
+- Chia Yu Pai @fantasywind
+- Claude Opus 5
+- Kai-Chieh Yang
+
 ## 0.7.0 (2026-08-10)
 
 This was a version bump only for bpm-core-client to align it with other projects, there were no code changes.
@@ -9,6 +54,38 @@ All notable changes to `@rytass/bpm-core-client` are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## Unreleased
+
+### Changed
+
+- Form helpers now recognize `autocomplete` and distinguish static option
+  fields from DataSource-backed option fields without changing primitive form
+  values.
+- Added typed catalog, designer preview, and authenticated runtime wrappers
+  for the host-registered form DataSource GraphQL boundary.
+- Approval instance records now expose parsed and raw dynamic option snapshots
+  returned by the server.
+- Added immutable DataSource option merge, selected hydration, unresolved-value,
+  dependency, and value-signature helpers plus the `FormDataSourceFieldStatus`
+  union used by the React renderer.
+- Added immutable builder helpers for DataSource capability filtering, parameter
+  type matching, field/constant bindings, field-key rename propagation, and
+  dependent-field discovery.
+- Added `FORM_DATA_SOURCE_ERROR_CODES`, `readFormDataSourceErrorCode()`,
+  `readFormDataSourceErrorMessage()`, and `readFormSchemaLintMessage()` so
+  consumers can turn the backend's stable DataSource codes into display copy
+  instead of showing the raw code. A code this client does not map yet still
+  yields readable copy rather than leaking the code to the screen. Detection is
+  token-bounded, and a publish failure that joins several lint lines has every
+  code mapped, not just the first. Lint lines that quote a host-chosen parameter
+  or descriptor name are left verbatim, so a parameter named like an error code
+  is not rewritten as that error's copy.
+
+### Fixed
+
+- Explicit `NEXT_PUBLIC_API_URL` base URLs now resolve to `/graphql` before
+  browser requests, matching the documented API-base configuration contract.
+
 Releases are managed by [`nx release`](https://nx.dev/recipes/nx-release) with
 Conventional Commits — see `nx.json` for the release config.
 

package/README.md

@@ -16,6 +16,12 @@ This package contains:
 It does **not** ship React components, hooks, or UI. Hosts can call the
 functions directly from any framework (Next.js / Vite / Remix / plain Node).
 
+Form clients can import the shared option-field contracts from
+`@rytass/bpm-core-shared/form`. `createFieldDefinition()` includes the
+`autocomplete` variant, while the pure form-rendering helpers retain the
+primitive value contract and distinguish static option fields from dynamic
+DataSource references.
+
 ## Package Status
 
 Current version: `0.1.10`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rytass/bpm-core-client",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Framework-agnostic TypeScript client for the Rytass BPM approval workflow GraphQL surface: fetch-based GraphQL transport, REST auth client, pre-baked typed operations for organization, member, form, template, and workflow.",
   "keywords": [
     "bpm",
@@ -73,7 +73,7 @@
     }
   },
   "peerDependencies": {
-    "@rytass/bpm-core-shared": "^0.7.0"
+    "@rytass/bpm-core-shared": "^0.9.0"
   },
   "dependencies": {
     "tslib": "^2.3.0"

package/src/lib/form/form-api.js

@@ -195,7 +195,10 @@ function createFieldDefinition(type, index) {
         required: false,
         type,
     };
-    if (type === 'select' || type === 'radio' || type === 'checkbox') {
+    if (type === 'select' ||
+        type === 'autocomplete' ||
+        type === 'radio' ||
+        type === 'checkbox') {
         return {
             ...base,
             options: [
@@ -224,6 +227,7 @@ function parseVersionJson(version) {
 function readDefaultFieldLabel(type, index) {
     const labels = {
         boolean: '開關',
+        autocomplete: '自動完成',
         checkbox: '複選',
         date: '日期',
         datetime: '日期時間',

package/src/lib/form/form-api.js.map

@@ -1 +1 @@
-{"version":3,"file":"form-api.js","sourceRoot":"","sources":["../../../../../../libs/bpm-core-client/src/lib/form/form-api.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"form-api.js","sourceRoot":"","sources":["../../../../../../libs/bpm-core-client/src/lib/form/form-api.ts"],"names":[],"mappings":"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"}

package/src/lib/form/form-data-source-api.d.ts

@@ -0,0 +1,50 @@
+import { FormDefinitionSchema, FormFieldOption, FormFieldValue, FormUiSchema } from '@rytass/bpm-core-shared/form';
+export type FormDataSourceControl = 'autocomplete' | 'checkbox' | 'radio' | 'select';
+export type FormDataSourceParameterType = 'BOOLEAN' | 'NUMBER' | 'STRING' | 'STRING_ARRAY';
+export type FormDataSourceRevalidationPolicy = 'ALWAYS' | 'WHEN_VALUE_OR_BINDINGS_CHANGE';
+export interface FormDataSourceParameterRecord {
+    readonly key: string;
+    readonly label: string | null;
+    readonly required: boolean;
+    readonly type: FormDataSourceParameterType;
+}
+export interface FormDataSourceDescriptorRecord {
+    readonly description: string | null;
+    readonly key: string;
+    readonly label: string;
+    readonly maximumResultCount: number;
+    readonly minimumSearchLength: number;
+    readonly pageSize: number;
+    readonly paginationMode: 'CURSOR' | 'NONE';
+    readonly parameters: readonly FormDataSourceParameterRecord[];
+    readonly revalidationPolicy: FormDataSourceRevalidationPolicy;
+    readonly returnsCompleteList: boolean;
+    readonly supportedControls: readonly FormDataSourceControl[];
+    readonly supportsSearch: boolean;
+    readonly version: number;
+}
+export interface FormDataSourceOptionsResultRecord {
+    readonly dataSourceKey: string;
+    readonly dataSourceVersion: number;
+    readonly nextCursor: string | null;
+    readonly options: readonly FormFieldOption[];
+}
+export interface PreviewFormFieldOptionsInput {
+    readonly cursor?: string | null;
+    readonly fieldKey: string;
+    readonly formData?: Readonly<Record<string, FormFieldValue>>;
+    readonly schema: FormDefinitionSchema;
+    readonly searchText?: string | null;
+    readonly uiSchema: FormUiSchema;
+}
+export interface RuntimeFormFieldOptionsInput {
+    readonly cursor?: string | null;
+    readonly fieldKey: string;
+    readonly formData?: Readonly<Record<string, FormFieldValue>>;
+    readonly instanceId?: string | null;
+    readonly searchText?: string | null;
+    readonly templateId?: string | null;
+}
+export declare function listFormDataSources(): Promise<readonly FormDataSourceDescriptorRecord[]>;
+export declare function previewFormFieldOptions(input: PreviewFormFieldOptionsInput): Promise<FormDataSourceOptionsResultRecord>;
+export declare function readFormFieldOptions(input: RuntimeFormFieldOptionsInput): Promise<FormDataSourceOptionsResultRecord>;

package/src/lib/form/form-data-source-api.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listFormDataSources = listFormDataSources;
+exports.previewFormFieldOptions = previewFormFieldOptions;
+exports.readFormFieldOptions = readFormFieldOptions;
+const graphql_client_1 = require("../graphql-client");
+const DESCRIPTOR_FIELDS = `
+  description
+  key
+  label
+  maximumResultCount
+  minimumSearchLength
+  pageSize
+  paginationMode
+  parameters {
+    key
+    label
+    required
+    type
+  }
+  revalidationPolicy
+  returnsCompleteList
+  supportedControls
+  supportsSearch
+  version
+`;
+const OPTION_RESULT_FIELDS = `
+  dataSourceKey
+  dataSourceVersion
+  nextCursor
+  options {
+    label
+    value
+  }
+`;
+async function listFormDataSources() {
+    const data = await (0, graphql_client_1.requestGraphQl)(`query FormDataSources { formDataSources { ${DESCRIPTOR_FIELDS} } }`);
+    return data.formDataSources;
+}
+async function previewFormFieldOptions(input) {
+    const data = await (0, graphql_client_1.requestGraphQl)(`query PreviewFormFieldOptions($input: BPMPreviewFormFieldOptionsInput!) {
+      previewFormFieldOptions(input: $input) { ${OPTION_RESULT_FIELDS} }
+    }`, { input: serializePreviewInput(input) });
+    return data.previewFormFieldOptions;
+}
+async function readFormFieldOptions(input) {
+    const data = await (0, graphql_client_1.requestGraphQl)(`query FormFieldOptions($input: BPMRuntimeFormFieldOptionsInput!) {
+      formFieldOptions(input: $input) { ${OPTION_RESULT_FIELDS} }
+    }`, { input: serializeRuntimeInput(input) });
+    return data.formFieldOptions;
+}
+function serializePreviewInput(input) {
+    return {
+        cursor: input.cursor ?? null,
+        fieldKey: input.fieldKey,
+        formDataJson: input.formData ? JSON.stringify(input.formData) : null,
+        schemaJson: JSON.stringify(input.schema),
+        searchText: input.searchText ?? null,
+        uiSchemaJson: JSON.stringify(input.uiSchema),
+    };
+}
+function serializeRuntimeInput(input) {
+    return {
+        cursor: input.cursor ?? null,
+        fieldKey: input.fieldKey,
+        formDataJson: input.formData ? JSON.stringify(input.formData) : null,
+        instanceId: input.instanceId ?? null,
+        searchText: input.searchText ?? null,
+        templateId: input.templateId ?? null,
+    };
+}
+//# sourceMappingURL=form-data-source-api.js.map

package/src/lib/form/form-data-source-api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"form-data-source-api.js","sourceRoot":"","sources":["../../../../../../libs/bpm-core-client/src/lib/form/form-data-source-api.ts"],"names":[],"mappings":";;AAmHA,kDAQC;AAED,0DAWC;AAED,oDAWC;AA/ID,sDAAmD;AA8EnD,MAAM,iBAAiB,GAAG;;;;;;;;;;;;;;;;;;;CAmBzB,CAAC;AAEF,MAAM,oBAAoB,GAAG;;;;;;;;CAQ5B,CAAC;AAEK,KAAK,UAAU,mBAAmB;IAGvC,MAAM,IAAI,GAAG,MAAM,IAAA,+BAAc,EAC/B,6CAA6C,iBAAiB,MAAM,CACrE,CAAC;IAEF,OAAO,IAAI,CAAC,eAAe,CAAC;AAC9B,CAAC;AAEM,KAAK,UAAU,uBAAuB,CAC3C,KAAmC;IAEnC,MAAM,IAAI,GAAG,MAAM,IAAA,+BAAc,EAC/B;iDAC6C,oBAAoB;MAC/D,EACF,EAAE,KAAK,EAAE,qBAAqB,CAAC,KAAK,CAAC,EAAE,CACxC,CAAC;IAEF,OAAO,IAAI,CAAC,uBAAuB,CAAC;AACtC,CAAC;AAEM,KAAK,UAAU,oBAAoB,CACxC,KAAmC;IAEnC,MAAM,IAAI,GAAG,MAAM,IAAA,+BAAc,EAC/B;0CACsC,oBAAoB;MACxD,EACF,EAAE,KAAK,EAAE,qBAAqB,CAAC,KAAK,CAAC,EAAE,CACxC,CAAC;IAEF,OAAO,IAAI,CAAC,gBAAgB,CAAC;AAC/B,CAAC;AAED,SAAS,qBAAqB,CAC5B,KAAmC;IAEnC,OAAO;QACL,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,IAAI;QAC5B,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,YAAY,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI;QACpE,UAAU,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC;QACxC,UAAU,EAAE,KAAK,CAAC,UAAU,IAAI,IAAI;QACpC,YAAY,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,QAAQ,CAAC;KAC7C,CAAC;AACJ,CAAC;AAED,SAAS,qBAAqB,CAC5B,KAAmC;IAEnC,OAAO;QACL,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,IAAI;QAC5B,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,YAAY,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI;QACpE,UAAU,EAAE,KAAK,CAAC,UAAU,IAAI,IAAI;QACpC,UAAU,EAAE,KAAK,CAAC,UAAU,IAAI,IAAI;QACpC,UAAU,EAAE,KAAK,CAAC,UAAU,IAAI,IAAI;KACrC,CAAC;AACJ,CAAC"}

package/src/lib/form/form-data-source-builder.d.ts

@@ -0,0 +1,17 @@
+import { FormDataSourceBinding, FormDataSourceOptionFieldDefinition, FormDefinitionSchema, FormFieldDefinition, FormFieldValue } from '@rytass/bpm-core-shared/form';
+import { FormDataSourceControl, FormDataSourceDescriptorRecord, FormDataSourceParameterType } from './form-data-source-api';
+export interface FormDataSourceBindingFieldOption {
+    readonly id: string;
+    readonly name: string;
+}
+export declare function isFormDataSourceDescriptorCompatible(descriptor: FormDataSourceDescriptorRecord, control: FormDataSourceControl): boolean;
+export declare function readCompatibleFormDataSourceDescriptors(control: FormDataSourceControl, descriptors: readonly FormDataSourceDescriptorRecord[]): readonly FormDataSourceDescriptorRecord[];
+export declare function readFormDataSourceParameterType(field: FormFieldDefinition): FormDataSourceParameterType | null;
+export declare function readCompatibleFormDataSourceBindingFields(parameterType: FormDataSourceParameterType, fields: readonly FormFieldDefinition[], targetFieldKey: string): readonly FormDataSourceBindingFieldOption[];
+export declare function readFormDataSourceBinding(field: FormDataSourceOptionFieldDefinition, parameterKey: string): FormDataSourceBinding | null;
+export declare function upsertFormDataSourceFieldBinding(field: FormDataSourceOptionFieldDefinition, parameterKey: string, binding: FormDataSourceBinding | null): FormDataSourceOptionFieldDefinition;
+export declare function renameFormDataSourceFieldBindings(schema: FormDefinitionSchema, previousFieldKey: string, nextFieldKey: string): FormDefinitionSchema;
+export declare function readFormDataSourceFieldDependencyKeys(field: FormDataSourceOptionFieldDefinition): readonly string[];
+export declare function readFormDataSourceBindingValue(field: FormDataSourceOptionFieldDefinition, parameterKey: string): FormFieldValue | undefined;
+export type FormDataSourceBindingValueKind = 'CONSTANT' | 'FIELD';
+export declare function readFormDataSourceBindingValueKind(binding: FormDataSourceBinding | null): FormDataSourceBindingValueKind | null;

package/src/lib/form/form-data-source-builder.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isFormDataSourceDescriptorCompatible = isFormDataSourceDescriptorCompatible;
+exports.readCompatibleFormDataSourceDescriptors = readCompatibleFormDataSourceDescriptors;
+exports.readFormDataSourceParameterType = readFormDataSourceParameterType;
+exports.readCompatibleFormDataSourceBindingFields = readCompatibleFormDataSourceBindingFields;
+exports.readFormDataSourceBinding = readFormDataSourceBinding;
+exports.upsertFormDataSourceFieldBinding = upsertFormDataSourceFieldBinding;
+exports.renameFormDataSourceFieldBindings = renameFormDataSourceFieldBindings;
+exports.readFormDataSourceFieldDependencyKeys = readFormDataSourceFieldDependencyKeys;
+exports.readFormDataSourceBindingValue = readFormDataSourceBindingValue;
+exports.readFormDataSourceBindingValueKind = readFormDataSourceBindingValueKind;
+const form_1 = require("@rytass/bpm-core-shared/form");
+function isFormDataSourceDescriptorCompatible(descriptor, control) {
+    if (!descriptor.supportedControls.includes(control)) {
+        return false;
+    }
+    return control === 'radio' || control === 'checkbox'
+        ? descriptor.returnsCompleteList && descriptor.maximumResultCount <= 50
+        : true;
+}
+function readCompatibleFormDataSourceDescriptors(control, descriptors) {
+    return descriptors.filter((descriptor) => isFormDataSourceDescriptorCompatible(descriptor, control));
+}
+function readFormDataSourceParameterType(field) {
+    switch (field.type) {
+        case 'boolean':
+            return 'BOOLEAN';
+        case 'checkbox':
+        case 'file_upload':
+            return 'STRING_ARRAY';
+        case 'money':
+        case 'number':
+            return 'NUMBER';
+        case 'autocomplete':
+        case 'radio':
+        case 'select': {
+            const mode = (0, form_1.readFormFieldSelectionMode)(field);
+            return mode === 'multiple' ? 'STRING_ARRAY' : 'STRING';
+        }
+        case 'date':
+        case 'datetime':
+        case 'text':
+        case 'textarea':
+            return 'STRING';
+        default:
+            return null;
+    }
+}
+function readCompatibleFormDataSourceBindingFields(parameterType, fields, targetFieldKey) {
+    return fields
+        .filter((field) => field.fieldKey !== targetFieldKey)
+        .filter((field) => readFormDataSourceParameterType(field) === parameterType)
+        .map((field) => ({ id: field.fieldKey, name: field.label }));
+}
+function readFormDataSourceBinding(field, parameterKey) {
+    return (field.dataSource.bindings.find((binding) => binding.parameter === parameterKey) ?? null);
+}
+function upsertFormDataSourceFieldBinding(field, parameterKey, binding) {
+    const nextBindings = field.dataSource.bindings
+        .filter((candidate) => candidate.parameter !== parameterKey)
+        .concat(binding ? [binding] : []);
+    return {
+        ...field,
+        dataSource: {
+            ...field.dataSource,
+            bindings: nextBindings,
+        },
+    };
+}
+function renameFormDataSourceFieldBindings(schema, previousFieldKey, nextFieldKey) {
+    return {
+        ...schema,
+        fields: schema.fields.map((field) => {
+            if (!(0, form_1.isFormDataSourceFieldDefinition)(field)) {
+                return field;
+            }
+            return {
+                ...field,
+                dataSource: {
+                    ...field.dataSource,
+                    bindings: field.dataSource.bindings.map((binding) => binding.from.kind === 'FIELD' &&
+                        binding.from.fieldKey === previousFieldKey
+                        ? {
+                            ...binding,
+                            from: {
+                                ...binding.from,
+                                fieldKey: nextFieldKey,
+                            },
+                        }
+                        : binding),
+                },
+            };
+        }),
+    };
+}
+function readFormDataSourceFieldDependencyKeys(field) {
+    return field.dataSource.bindings.flatMap((binding) => binding.from.kind === 'FIELD' ? [binding.from.fieldKey] : []);
+}
+function readFormDataSourceBindingValue(field, parameterKey) {
+    const binding = readFormDataSourceBinding(field, parameterKey);
+    return binding?.from.kind === 'CONSTANT' ? binding.from.value : undefined;
+}
+function readFormDataSourceBindingValueKind(binding) {
+    return binding?.from.kind ?? null;
+}
+//# sourceMappingURL=form-data-source-builder.js.map

package/src/lib/form/form-data-source-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"form-data-source-builder.js","sourceRoot":"","sources":["../../../../../../libs/bpm-core-client/src/lib/form/form-data-source-builder.ts"],"names":[],"mappings":"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"}

package/src/lib/form/form-data-source-errors.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Stable error codes raised by the BPM form DataSource GraphQL surface.
+ *
+ * The backend deliberately returns codes rather than prose so it never leaks an
+ * upstream URL, header, query or response body. Consumers are expected to map
+ * them to their own copy; `readFormDataSourceErrorMessage` is the default
+ * mapping used by the bundled React views.
+ */
+export declare const FORM_DATA_SOURCE_ERROR_CODES: readonly ["FORM_DATA_SOURCE_FIELD_NOT_DYNAMIC", "FORM_DATA_SOURCE_INVALID_BINDING", "FORM_DATA_SOURCE_INVALID_DESCRIPTOR", "FORM_DATA_SOURCE_INVALID_PROVIDER_RESULT", "FORM_DATA_SOURCE_MISSING", "FORM_DATA_SOURCE_PARAMETER_LIMIT_EXCEEDED", "FORM_DATA_SOURCE_PROVIDER_FAILURE", "FORM_DATA_SOURCE_RESULT_LIMIT_EXCEEDED", "FORM_DATA_SOURCE_RUNTIME_CONTEXT_FORBIDDEN", "FORM_DATA_SOURCE_SEARCH_NOT_SUPPORTED", "FORM_DATA_SOURCE_SEARCH_TOO_SHORT", "FORM_DATA_SOURCE_TIMEOUT", "FORM_DATA_SOURCE_UNSUPPORTED_CONTROL", "FORM_DATA_SOURCE_VALUE_NOT_RESOLVED", "FORM_DATA_SOURCE_VERSION_MISSING", "FORM_DATA_SOURCE_WAITING_FOR_DEPENDENCIES"];
+export type FormDataSourceErrorCode = (typeof FORM_DATA_SOURCE_ERROR_CODES)[number];
+/**
+ * Extracts the DataSource error code carried by a rejected request, whether it
+ * arrives as the bare code, a GraphQL error message, or an `Error` wrapping
+ * either. Returns `null` for anything that is not a DataSource failure.
+ */
+export declare function readFormDataSourceErrorCode(error: unknown): FormDataSourceErrorCode | null;
+/**
+ * Maps a rejected request to display copy. Returns `null` only when the failure
+ * is not a DataSource error at all, so callers can fall back to their own
+ * message; an unrecognised `FORM_DATA_SOURCE_*` code still yields readable copy
+ * rather than leaking the code itself.
+ */
+export declare function readFormDataSourceErrorMessage(error: unknown): string | null;
+/**
+ * Rewrites a publish-lint line such as
+ * `schema.fields[1].dataSource FORM_DATA_SOURCE_MISSING` into readable copy
+ * while keeping the field path that tells the designer where to look. Lines
+ * without a DataSource code are returned unchanged.
+ */
+export declare function readFormSchemaLintMessage(error: string): string;

package/src/lib/form/form-data-source-errors.js

@@ -0,0 +1,152 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FORM_DATA_SOURCE_ERROR_CODES = void 0;
+exports.readFormDataSourceErrorCode = readFormDataSourceErrorCode;
+exports.readFormDataSourceErrorMessage = readFormDataSourceErrorMessage;
+exports.readFormSchemaLintMessage = readFormSchemaLintMessage;
+/**
+ * Stable error codes raised by the BPM form DataSource GraphQL surface.
+ *
+ * The backend deliberately returns codes rather than prose so it never leaks an
+ * upstream URL, header, query or response body. Consumers are expected to map
+ * them to their own copy; `readFormDataSourceErrorMessage` is the default
+ * mapping used by the bundled React views.
+ */
+exports.FORM_DATA_SOURCE_ERROR_CODES = [
+    'FORM_DATA_SOURCE_FIELD_NOT_DYNAMIC',
+    'FORM_DATA_SOURCE_INVALID_BINDING',
+    'FORM_DATA_SOURCE_INVALID_DESCRIPTOR',
+    'FORM_DATA_SOURCE_INVALID_PROVIDER_RESULT',
+    'FORM_DATA_SOURCE_MISSING',
+    'FORM_DATA_SOURCE_PARAMETER_LIMIT_EXCEEDED',
+    'FORM_DATA_SOURCE_PROVIDER_FAILURE',
+    'FORM_DATA_SOURCE_RESULT_LIMIT_EXCEEDED',
+    'FORM_DATA_SOURCE_RUNTIME_CONTEXT_FORBIDDEN',
+    'FORM_DATA_SOURCE_SEARCH_NOT_SUPPORTED',
+    'FORM_DATA_SOURCE_SEARCH_TOO_SHORT',
+    'FORM_DATA_SOURCE_TIMEOUT',
+    'FORM_DATA_SOURCE_UNSUPPORTED_CONTROL',
+    'FORM_DATA_SOURCE_VALUE_NOT_RESOLVED',
+    'FORM_DATA_SOURCE_VERSION_MISSING',
+    'FORM_DATA_SOURCE_WAITING_FOR_DEPENDENCIES',
+];
+const ERROR_MESSAGES = {
+    FORM_DATA_SOURCE_FIELD_NOT_DYNAMIC: '此欄位不是動態選項欄位。',
+    FORM_DATA_SOURCE_INVALID_BINDING: '選項查詢條件不正確，請重新確認表單內容。',
+    FORM_DATA_SOURCE_INVALID_DESCRIPTOR: '選項來源設定不正確，請聯絡系統管理員。',
+    FORM_DATA_SOURCE_INVALID_PROVIDER_RESULT: '選項來源回傳的資料不正確，請聯絡系統管理員。',
+    FORM_DATA_SOURCE_MISSING: '選項來源已不存在，請聯絡系統管理員。',
+    FORM_DATA_SOURCE_PARAMETER_LIMIT_EXCEEDED: '選項查詢條件過大，請縮減表單內容。',
+    FORM_DATA_SOURCE_PROVIDER_FAILURE: '選項來源目前無法回應，請稍後再試。',
+    FORM_DATA_SOURCE_RESULT_LIMIT_EXCEEDED: '選項數量超過上限，請縮小查詢範圍。',
+    FORM_DATA_SOURCE_RUNTIME_CONTEXT_FORBIDDEN: '沒有權限查詢此欄位的選項。',
+    FORM_DATA_SOURCE_SEARCH_NOT_SUPPORTED: '此選項來源不支援搜尋。',
+    FORM_DATA_SOURCE_SEARCH_TOO_SHORT: '請輸入更多搜尋文字。',
+    FORM_DATA_SOURCE_TIMEOUT: '選項來源回應逾時，請稍後再試。',
+    FORM_DATA_SOURCE_UNSUPPORTED_CONTROL: '此選項來源不支援目前的欄位型態。',
+    FORM_DATA_SOURCE_VALUE_NOT_RESOLVED: '已選取的選項已失效，請重新選擇。',
+    FORM_DATA_SOURCE_VERSION_MISSING: '選項來源版本已不存在，請聯絡系統管理員。',
+    FORM_DATA_SOURCE_WAITING_FOR_DEPENDENCIES: '請先填寫相依欄位。',
+};
+/**
+ * Token-bounded so `XFORM_DATA_SOURCE_TIMEOUT` is not mistaken for a code, and
+ * digit-tolerant so a future code is still recognised as one of ours.
+ */
+const ERROR_CODE_PATTERN = /(?<![A-Za-z0-9_])FORM_DATA_SOURCE_[A-Z0-9_]+(?![A-Za-z0-9_])/u;
+/**
+ * The only lint shape that carries an error code, anchored to the exact path the
+ * backend emits AND to the start of a `'; '`-joined lint segment:
+ * `schema.fields[<n>].dataSource <CODE>`.
+ *
+ * Segment anchoring is what closes the whole family of adversarial names: a
+ * host- or designer-chosen parameter or field key can only ever appear after a
+ * prose prefix
+ * within its segment, never at the segment start, so no name — however it is
+ * spelled — can be mistaken for an emitted code.
+ *
+ * Every other lint line is prose that may quote a host- or designer-chosen name — a
+ * DataSource parameter, a descriptor field, a form field key — and such a name
+ * may legitimately look like an error code. Replacing only this shape is why the
+ * formatter needs no allowlist of prose shapes to avoid rewriting those names.
+ */
+const LINT_LINE_CODE_PATTERN = /(^|; )(schema\.fields\[\d+\]\.dataSource) (FORM_DATA_SOURCE_[A-Z0-9_]+)(?![A-Za-z0-9_])/gu;
+/**
+ * Recognises publish-lint output by the paths it starts its lines with — both
+ * indexed forms (`schema.fields[0]...`) and the unindexed ones the structural
+ * lint emits (`schema.fields fieldKey is duplicated: <key>`). Inside
+ * such a message only the code-bearing shape above may be rewritten; a bare or
+ * wrapped code arrives as a plain error message instead and is mapped whole.
+ */
+const LINT_MESSAGE_PATTERN = /(?:^|; )(?:schema\.|descriptor\.)/u;
+/**
+ * Shown when the backend answers with a DataSource code this package does not
+ * know yet — a newer core against an older client. Without it the raw code
+ * would reach the screen.
+ */
+const UNKNOWN_CODE_MESSAGE = '選項來源發生問題，請稍後再試或聯絡系統管理員。';
+/**
+ * Extracts the DataSource error code carried by a rejected request, whether it
+ * arrives as the bare code, a GraphQL error message, or an `Error` wrapping
+ * either. Returns `null` for anything that is not a DataSource failure.
+ */
+function readFormDataSourceErrorCode(error) {
+    const text = typeof error === 'string'
+        ? error
+        : error instanceof Error
+            ? error.message
+            : '';
+    const match = ERROR_CODE_PATTERN.exec(text);
+    return match &&
+        exports.FORM_DATA_SOURCE_ERROR_CODES.includes(match[0])
+        ? match[0]
+        : null;
+}
+/**
+ * Maps a rejected request to display copy. Returns `null` only when the failure
+ * is not a DataSource error at all, so callers can fall back to their own
+ * message; an unrecognised `FORM_DATA_SOURCE_*` code still yields readable copy
+ * rather than leaking the code itself.
+ */
+function readFormDataSourceErrorMessage(error) {
+    const code = readFormDataSourceErrorCode(error);
+    if (code) {
+        return ERROR_MESSAGES[code];
+    }
+    return readsAsFormDataSourceCode(error) ? UNKNOWN_CODE_MESSAGE : null;
+}
+/**
+ * True when the failure carries a `FORM_DATA_SOURCE_*` token, including codes
+ * this package does not map yet.
+ */
+function readsAsFormDataSourceCode(error) {
+    const text = typeof error === 'string'
+        ? error
+        : error instanceof Error
+            ? error.message
+            : '';
+    return ERROR_CODE_PATTERN.test(text);
+}
+/**
+ * Rewrites a publish-lint line such as
+ * `schema.fields[1].dataSource FORM_DATA_SOURCE_MISSING` into readable copy
+ * while keeping the field path that tells the designer where to look. Lines
+ * without a DataSource code are returned unchanged.
+ */
+function readFormSchemaLintMessage(error) {
+    // A publish failure joins several lint lines, so map every code-bearing
+    // occurrence and leave all prose — including author-chosen names that look like
+    // codes — exactly as the backend wrote it.
+    const mapped = error.replace(LINT_LINE_CODE_PATTERN, (_match, separator, path, code) => `${separator}${path} ${readCodeMessage(code)}`);
+    if (LINT_MESSAGE_PATTERN.test(error)) {
+        return mapped;
+    }
+    // Not lint output: the message is a bare code or wraps one (for example
+    // `GraphQL error: FORM_DATA_SOURCE_TIMEOUT`), so map it as a whole.
+    return readFormDataSourceErrorMessage(error) ?? error;
+}
+function readCodeMessage(code) {
+    return exports.FORM_DATA_SOURCE_ERROR_CODES.includes(code)
+        ? ERROR_MESSAGES[code]
+        : UNKNOWN_CODE_MESSAGE;
+}
+//# sourceMappingURL=form-data-source-errors.js.map

package/src/lib/form/form-data-source-errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"form-data-source-errors.js","sourceRoot":"","sources":["../../../../../../libs/bpm-core-client/src/lib/form/form-data-source-errors.ts"],"names":[],"mappings":"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"}

package/src/lib/form/form-data-source-state.d.ts

@@ -0,0 +1,12 @@
+import { FormDataSourceOptionFieldDefinition, FormFieldOption, FormFieldValue } from '@rytass/bpm-core-shared/form';
+import { FormRendererValues } from './form-rendering';
+export type FormDataSourceFieldStatus = 'IDLE' | 'WAITING_FOR_DEPENDENCIES' | 'LOADING' | 'VALID' | 'STALE' | 'INVALID' | 'UNAVAILABLE';
+/**
+ * Merges immutable option pages while preserving the first-seen order and
+ * letting newer results replace labels for an existing value.
+ */
+export declare function mergeFormDataSourceOptions(...optionLists: readonly (readonly FormFieldOption[])[]): readonly FormFieldOption[];
+export declare function readSelectedFormDataSourceOptions(value: FormFieldValue | undefined, options: readonly FormFieldOption[]): readonly FormFieldOption[];
+export declare function readMissingFormDataSourceOptionValues(value: FormFieldValue | undefined, options: readonly FormFieldOption[]): readonly string[];
+export declare function readMissingFormDataSourceDependencies(field: FormDataSourceOptionFieldDefinition, values: FormRendererValues): readonly string[];
+export declare function readFormDataSourceValueSignature(value: FormFieldValue | undefined): string;