@qoretechnologies/reqraft 0.10.53 → 0.10.54-pr.115.g9bc96ed

package/dist/helpers/dpqlDetection.d.ts

@@ -0,0 +1,58 @@
+/** What to do about text that turned out to be an expression. */
+export type TDpqlDetectionOutcome = 
+/** Not an expression, or not one we may act on — leave the field alone. */
+'none'
+/** A real expression, but the text is also a valid literal here: ask. */
+ | 'offer'
+/** A real expression, and the text cannot be a literal here: switch. */
+ | 'switch';
+/**
+ * Cheap, purely lexical "might this be worth asking the server about?".
+ * Never decides anything on its own — see the module comment.
+ */
+export declare const mightBeDpqlExpression: (text: unknown) => boolean;
+/**
+ * The authority: does this `dpql/parse` result describe a REAL expression
+ * rather than a literal or a bare template reference? Accepts either the
+ * field-ready envelope (`{is_expression, value: {exp, args}}`) the server
+ * returns or a bare `{exp, args}` node.
+ */
+export declare const isRealExpressionAst: (expression: unknown) => boolean;
+/**
+ * `true` when any diagnostic is an outright error. The server reports
+ * severity as the string `'error'` on this route and LSP proper uses `1`;
+ * both are accepted rather than assuming one.
+ */
+export declare const hasErrorDiagnostic: (diagnostics?: Array<{
+    severity?: number | string;
+} | undefined | null>) => boolean;
+/**
+ * Could this text stand as a literal value of the field's own type? A type
+ * that accepts any text (`string`, and every type the form validator passes
+ * by default) always can, which is exactly why such a field never
+ * auto-switches. Delegates to the form's own validator so the answer is the
+ * same one the field itself would give.
+ */
+export declare const canBeLiteralOfType: (text: string, type?: string, field?: Record<string, any>) => boolean;
+export interface IClassifyTypedTextArgs {
+    /** The text the author typed into the plain field. */
+    text: string;
+    /** The field's declared type (`ui_type ?? type`). */
+    type?: string;
+    /** The field schema, for validators that consult `validation_regex` etc. */
+    field?: Record<string, any>;
+    /** The `dpql/parse` result for `text`, or `undefined` if it has not run. */
+    parsed?: {
+        success?: boolean;
+        expression?: unknown;
+        diagnostics?: Array<{
+            severity?: number | string;
+        }>;
+    };
+}
+/**
+ * The whole decision, in one pure function so it can be tested without a
+ * server, a socket or a rendered field.
+ */
+export declare const classifyTypedText: ({ text, type, field, parsed, }: IClassifyTypedTextArgs) => TDpqlDetectionOutcome;
+//# sourceMappingURL=dpqlDetection.d.ts.map

package/dist/helpers/dpqlDetection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dpqlDetection.d.ts","sourceRoot":"","sources":["../../src/helpers/dpqlDetection.ts"],"names":[],"mappings":"AAmCA,iEAAiE;AACjE,MAAM,MAAM,qBAAqB;AAC/B,2EAA2E;AACzE,MAAM;AACR,yEAAyE;GACvE,OAAO;AACT,wEAAwE;GACtE,QAAQ,CAAC;AAuDb;;;GAGG;AACH,eAAO,MAAM,qBAAqB,SAAU,OAAO,KAAG,OAYrD,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,eAAgB,OAAO,KAAG,OAazD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,iBACf,MAAM;IAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,GAAG,SAAS,GAAG,IAAI,CAAC,KACrE,OAIC,CAAC;AAEL;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,SACvB,MAAM,SACL,MAAM,UACL,OAAO,MAAM,EAAE,GAAG,CAAC,KAC1B,OAYF,CAAC;AAEF,MAAM,WAAW,sBAAsB;IACrC,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC5B,4EAA4E;IAC5E,MAAM,CAAC,EAAE;QACP,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,UAAU,CAAC,EAAE,OAAO,CAAC;QACrB,WAAW,CAAC,EAAE,KAAK,CAAC;YAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;SAAE,CAAC,CAAC;KACrD,CAAC;CACH;AAED;;;GAGG;AACH,eAAO,MAAM,iBAAiB,mCAK3B,sBAAsB,KAAG,qBAU3B,CAAC"}

package/dist/helpers/dpqlDetection.js

@@ -0,0 +1,164 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyTypedText = exports.canBeLiteralOfType = exports.hasErrorDiagnostic = exports.isRealExpressionAst = exports.mightBeDpqlExpression = void 0;
+// Copyright 2026 Qore Technologies, s.r.o.
+/**
+ * Noticing that text typed into a PLAIN (non-expression) field is really a
+ * DPQL expression, and deciding what to do about it.
+ *
+ * The rule this implements, in one sentence: **switch the field into
+ * expression mode only when the text cannot be a valid literal for the
+ * field's type but IS a real expression; otherwise offer, never silently
+ * reinterpret.** Quietly turning the string `a + b` into a concatenation on a
+ * `string` field would destroy a legitimate literal, so a type that accepts
+ * any text never auto-switches — it only ever offers.
+ *
+ * ## Why the server has the last word
+ *
+ * "Does this parse as DPQL?" is NOT a usable test, which is the trap here.
+ * Verified against the live LSP: `dpql/parse` reports `success: true` for
+ * `hello`, for `42`, for `2026-09-06` and for `@a` — it wraps each of them in
+ * a trivial `{exp: 'value', args: [...]}` node. Everything is a valid DPQL
+ * program, because a bare literal is one. So a text that parses tells us
+ * nothing; what tells us something is the SHAPE of the AST that comes back:
+ *
+ * | typed text        | `exp`      | verdict    |
+ * |-------------------|------------|------------|
+ * | `hello`, `42`     | `value`    | a literal  |
+ * | `$local:count`    | `template` | a template |
+ * | `@a > 5`          | `>`        | expression |
+ * | `"a" + "b"`       | `+`        | expression |
+ * | `toInt("5")`      | `toInt`    | expression |
+ *
+ * `isRealExpressionAst` is that test, and it is the only authority. The
+ * lexical pass below decides nothing — its sole job is to keep a server
+ * round-trip off every keystroke of every field.
+ */
+var validations_1 = require("./validations");
+/**
+ * The `exp` values that mean "this is not an expression": a bare literal and
+ * a bare template reference. A template is already the template field's job
+ * (`isValueTemplate`), and a literal is what the plain field is for.
+ */
+var NON_EXPRESSION_OPS = new Set(['value', 'template']);
+/**
+ * Operators and calls whose presence makes a server probe worth the trip.
+ * Deliberately generous — a false positive costs one debounced request that
+ * comes back `exp: 'value'`, while a false negative silently loses the whole
+ * feature.
+ *
+ * ## Why the spacing rules differ per operator
+ *
+ * `-` and `/` are ambiguous: they appear inside values nobody means as
+ * arithmetic — dates (`2026-09-06`), negative numbers (`-5`), paths (`a/b`),
+ * hyphenated names (`well-known-name`). A space next to one is what separates
+ * `@a - 1` from those, so they keep a spacing requirement.
+ *
+ * `+` is NOT ambiguous in that way, and requiring spaces around it lost the
+ * feature for the most natural way to type arithmetic: `2 + 1` was offered as
+ * an expression while `2+1` and `2+ 1` were not, which reads as the detection
+ * working only sometimes. Reported from the live IDE. `+` now counts wherever
+ * it appears; if the text turns out to be an ordinary literal the server says
+ * so and the offer never appears.
+ *
+ * The `-`/`/` rule is also relaxed from "spaces on BOTH sides" to "a space on
+ * either side", so `@a -1` and `@a- 1` are probed too while every ambiguous
+ * value above still is not.
+ */
+var DPQL_OPERATOR_PATTERN = new RegExp([
+    '(==|!=|<>|>=|<=)', // two-character comparisons
+    '[<>*%]', // unambiguous single-character operators
+    '(?<!=)=(?!=)', // a lone `=`, not part of `==`
+    '\\+', // `+` — unambiguous, so spacing is irrelevant
+    '(\\s[-/]|[-/]\\s)', // `-` and `/` need a space on at least one side
+    '\\b(and|or|not|like|in|contains)\\b', // word operators
+].join('|'), 'i');
+/** A function call — `toInt("5")`, `upper(@name)`. */
+var DPQL_CALL_PATTERN = /\b[a-z_]\w*\s*\(/i;
+/**
+ * The longest text worth probing. An expression a person types into a form
+ * field is short; anything longer is a document, and probing it on every
+ * keystroke would be a waste of a round-trip.
+ */
+var MAX_PROBE_LENGTH = 512;
+/**
+ * Cheap, purely lexical "might this be worth asking the server about?".
+ * Never decides anything on its own — see the module comment.
+ */
+var mightBeDpqlExpression = function (text) {
+    if (typeof text !== 'string') {
+        return false;
+    }
+    var trimmed = text.trim();
+    if (!trimmed || trimmed.length > MAX_PROBE_LENGTH) {
+        return false;
+    }
+    return DPQL_OPERATOR_PATTERN.test(trimmed) || DPQL_CALL_PATTERN.test(trimmed);
+};
+exports.mightBeDpqlExpression = mightBeDpqlExpression;
+/**
+ * The authority: does this `dpql/parse` result describe a REAL expression
+ * rather than a literal or a bare template reference? Accepts either the
+ * field-ready envelope (`{is_expression, value: {exp, args}}`) the server
+ * returns or a bare `{exp, args}` node.
+ */
+var isRealExpressionAst = function (expression) {
+    if (!expression || typeof expression !== 'object') {
+        return false;
+    }
+    var envelope = expression;
+    var node = (envelope.exp === undefined && envelope.value && typeof envelope.value === 'object'
+        ? envelope.value
+        : envelope);
+    return typeof node.exp === 'string' && !!node.exp && !NON_EXPRESSION_OPS.has(node.exp);
+};
+exports.isRealExpressionAst = isRealExpressionAst;
+/**
+ * `true` when any diagnostic is an outright error. The server reports
+ * severity as the string `'error'` on this route and LSP proper uses `1`;
+ * both are accepted rather than assuming one.
+ */
+var hasErrorDiagnostic = function (diagnostics) {
+    return !!(diagnostics === null || diagnostics === void 0 ? void 0 : diagnostics.some(function (diagnostic) {
+        var severity = diagnostic === null || diagnostic === void 0 ? void 0 : diagnostic.severity;
+        return severity === 1 || severity === 'error';
+    }));
+};
+exports.hasErrorDiagnostic = hasErrorDiagnostic;
+/**
+ * Could this text stand as a literal value of the field's own type? A type
+ * that accepts any text (`string`, and every type the form validator passes
+ * by default) always can, which is exactly why such a field never
+ * auto-switches. Delegates to the form's own validator so the answer is the
+ * same one the field itself would give.
+ */
+var canBeLiteralOfType = function (text, type, field) {
+    if (!type) {
+        return true;
+    }
+    try {
+        return (0, validations_1.validateField)(type, text, field);
+    }
+    catch (_a) {
+        // A validator that throws must not be read as "this cannot be a
+        // literal" — that would auto-switch the field on the strength of a bug.
+        return true;
+    }
+};
+exports.canBeLiteralOfType = canBeLiteralOfType;
+/**
+ * The whole decision, in one pure function so it can be tested without a
+ * server, a socket or a rendered field.
+ */
+var classifyTypedText = function (_a) {
+    var text = _a.text, type = _a.type, field = _a.field, parsed = _a.parsed;
+    if (!(parsed === null || parsed === void 0 ? void 0 : parsed.success) || !parsed.expression) {
+        return 'none';
+    }
+    if (!(0, exports.isRealExpressionAst)(parsed.expression) || (0, exports.hasErrorDiagnostic)(parsed.diagnostics)) {
+        return 'none';
+    }
+    return (0, exports.canBeLiteralOfType)(text, type, field) ? 'offer' : 'switch';
+};
+exports.classifyTypedText = classifyTypedText;
+//# sourceMappingURL=dpqlDetection.js.map

package/dist/helpers/dpqlDetection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dpqlDetection.js","sourceRoot":"","sources":["../../src/helpers/dpqlDetection.ts"],"names":[],"mappings":"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"}

package/dist/helpers/optionUiTypes.d.ts

@@ -24,7 +24,7 @@ export declare const LEGACY_FIELD_UI_TYPES: readonly ["api-manager", "array", "a
 export declare const KNOWN_QORUS_UI_TYPES: readonly ["string", "long-string", "data", "binary", "richtext", "bool", "boolean", "date", "int", "integer", "float", "number", "byte-size", "timeout", "url", "code-editor", "rgbcolor", "any", "auto", "email", "uri", "uuid", "hostname", "ipv4", "ipv6", "phone", "hash", "free-hash", "list", "free-list", "option_hash", "file", "file-as-string", "collection-documents", "enum", "select-string", "select-array", "multi-select", "workflow", "service", "job", "connection", "mapper", "class", "value-map", "fsm", "qog", "api-schema", "auth-profile", "ai-collection", "ai-endpoint", "ai-guardrail", "ml-model", "release-config", "alertrule", "alertsilence", "installed-release", "business-process", "schema", "test", "processor", "processor-mappings", "data-provider", "tool-catalog", "schema-definition", "test-cases", "test-value-contract", "dpql", "active-windows", "api-manager", "array", "array-auto", "array-of-pairs", "class-array", "class-connectors", "constant-array", "context-selector", "cron", "data-provider-options", "file-array", "fsm-list", "function-array", "http-content", "method-name", "opcua-method-arguments", "opcua-write-values", "options", "select", "service-events", "service-webhooks", "type-selector"];
 export type TLegacyFieldUiType = (typeof LEGACY_FIELD_UI_TYPES)[number];
 export type TKnownQorusUiType = (typeof KNOWN_QORUS_UI_TYPES)[number];
-export declare const isOptionUiType: (type: unknown) => type is "string" | "number" | "boolean" | "file" | "data" | "date" | "email" | "url" | "list" | "auto" | "richtext" | "uri" | "dpql" | "fsm" | "class" | "active-windows" | "code-editor" | "processor-mappings" | "schema-definition" | "test-cases" | "test-value-contract" | "tool-catalog" | "mapper" | "workflow" | "service" | "job" | "connection" | "value-map" | "qog" | "ai-collection" | "ai-endpoint" | "ai-guardrail" | "binary" | "long-string" | "enum" | "int" | "integer" | "float" | "free-list" | "hash" | "rgbcolor" | "free-hash" | "any" | "bool" | "data-provider" | "byte-size" | "timeout" | "uuid" | "hostname" | "ipv4" | "ipv6" | "phone" | "option_hash" | "file-as-string" | "collection-documents" | "select-string" | "select-array" | "multi-select" | "api-schema" | "auth-profile" | "ml-model" | "release-config" | "alertrule" | "alertsilence" | "installed-release" | "business-process" | "schema" | "test" | "processor";
-export declare const isOptionInterfaceUiType: (type: unknown) => type is "fsm" | "class" | "mapper" | "workflow" | "service" | "job" | "connection" | "value-map" | "qog" | "ai-collection" | "ai-endpoint" | "ai-guardrail" | "api-schema" | "auth-profile" | "ml-model" | "release-config" | "alertrule" | "alertsilence" | "installed-release" | "business-process" | "schema" | "test";
-export declare const isKnownQorusUiType: (type: unknown) => type is "string" | "number" | "boolean" | "file" | "data" | "select" | "date" | "email" | "url" | "list" | "auto" | "richtext" | "uri" | "options" | "dpql" | "fsm" | "class" | "active-windows" | "code-editor" | "cron" | "processor-mappings" | "schema-definition" | "test-cases" | "test-value-contract" | "tool-catalog" | "mapper" | "workflow" | "service" | "job" | "connection" | "value-map" | "qog" | "ai-collection" | "ai-endpoint" | "ai-guardrail" | "binary" | "long-string" | "enum" | "int" | "integer" | "float" | "free-list" | "hash" | "rgbcolor" | "free-hash" | "any" | "bool" | "data-provider" | "byte-size" | "timeout" | "uuid" | "hostname" | "ipv4" | "ipv6" | "phone" | "option_hash" | "file-as-string" | "collection-documents" | "select-string" | "select-array" | "multi-select" | "api-schema" | "auth-profile" | "ml-model" | "release-config" | "alertrule" | "alertsilence" | "installed-release" | "business-process" | "schema" | "test" | "processor" | "api-manager" | "array" | "array-auto" | "array-of-pairs" | "class-array" | "class-connectors" | "constant-array" | "context-selector" | "data-provider-options" | "file-array" | "fsm-list" | "function-array" | "http-content" | "method-name" | "opcua-method-arguments" | "opcua-write-values" | "service-events" | "service-webhooks" | "type-selector";
+export declare const isOptionUiType: (type: unknown) => type is "string" | "number" | "boolean" | "file" | "data" | "date" | "email" | "url" | "list" | "auto" | "richtext" | "uri" | "dpql" | "mapper" | "workflow" | "service" | "job" | "connection" | "class" | "fsm" | "value-map" | "qog" | "ai-collection" | "ai-endpoint" | "ai-guardrail" | "binary" | "long-string" | "enum" | "int" | "integer" | "float" | "free-list" | "hash" | "rgbcolor" | "free-hash" | "any" | "bool" | "data-provider" | "processor-mappings" | "tool-catalog" | "code-editor" | "active-windows" | "schema-definition" | "test-cases" | "test-value-contract" | "byte-size" | "timeout" | "uuid" | "hostname" | "ipv4" | "ipv6" | "phone" | "option_hash" | "file-as-string" | "collection-documents" | "select-string" | "select-array" | "multi-select" | "api-schema" | "auth-profile" | "ml-model" | "release-config" | "alertrule" | "alertsilence" | "installed-release" | "business-process" | "schema" | "test" | "processor";
+export declare const isOptionInterfaceUiType: (type: unknown) => type is "mapper" | "workflow" | "service" | "job" | "connection" | "class" | "fsm" | "value-map" | "qog" | "ai-collection" | "ai-endpoint" | "ai-guardrail" | "api-schema" | "auth-profile" | "ml-model" | "release-config" | "alertrule" | "alertsilence" | "installed-release" | "business-process" | "schema" | "test";
+export declare const isKnownQorusUiType: (type: unknown) => type is "string" | "number" | "boolean" | "file" | "data" | "select" | "date" | "email" | "url" | "list" | "auto" | "richtext" | "uri" | "dpql" | "mapper" | "workflow" | "service" | "job" | "connection" | "class" | "fsm" | "value-map" | "qog" | "ai-collection" | "ai-endpoint" | "ai-guardrail" | "binary" | "long-string" | "enum" | "int" | "integer" | "float" | "free-list" | "hash" | "rgbcolor" | "free-hash" | "any" | "bool" | "data-provider" | "processor-mappings" | "tool-catalog" | "code-editor" | "options" | "active-windows" | "cron" | "schema-definition" | "test-cases" | "test-value-contract" | "byte-size" | "timeout" | "uuid" | "hostname" | "ipv4" | "ipv6" | "phone" | "option_hash" | "file-as-string" | "collection-documents" | "select-string" | "select-array" | "multi-select" | "api-schema" | "auth-profile" | "ml-model" | "release-config" | "alertrule" | "alertsilence" | "installed-release" | "business-process" | "schema" | "test" | "processor" | "api-manager" | "array" | "array-auto" | "array-of-pairs" | "class-array" | "class-connectors" | "constant-array" | "context-selector" | "data-provider-options" | "file-array" | "fsm-list" | "function-array" | "http-content" | "method-name" | "opcua-method-arguments" | "opcua-write-values" | "service-events" | "service-webhooks" | "type-selector";
 //# sourceMappingURL=optionUiTypes.d.ts.map

package/dist/helpers/options.d.ts

@@ -20,4 +20,41 @@ export declare const getRequiredOptionMessage: (schema: IQorusFormSchema, groups
  * `'value' in []` is false anyway, but saying so keeps the intent legible.
  */
 export declare const getListElementValue: (element: unknown) => unknown;
+/**
+ * The schema with every one-of group that offers no choice turned back into a
+ * plain required field.
+ *
+ * A `required_groups` group says *"at least one of these"*, and the whole
+ * affordance built on it — the ONE OF header, the `Covers` / `Covered by “X”`
+ * chips, the *"this field or X is required"* message — exists to tell an author
+ * that they have a CHOICE and which way they have answered it. When the group
+ * has a single member in the schema in hand, there is no choice: that field
+ * must be set, which is exactly what `required` already means. Saying it in the
+ * one-of grammar instead is worse than saying nothing, because a green tick
+ * beside a value reads as confirmation of the VALUE — a Qorus test author read
+ * `✓ COVERS` beside their service as "yes, this is the service your test is
+ * about", which the form never said and cannot know.
+ *
+ * This is not a hypothetical: a server may legitimately declare a group over an
+ * API-only alternative it then hides from the form (Qorus test steps put
+ * `target` in a group with `service`, and hide `target`), so the form is handed
+ * one member of a two-member group. The group is still real for the API and
+ * must stay in the schema the server serves; it is only this form that has
+ * nothing to offer.
+ *
+ * The rewrite is exact rather than cosmetic: a one-of over one option and a
+ * required option are the same constraint, so validation, the completion meter
+ * and the required-only filter all keep saying what they said — in the grammar
+ * that fits.
+ *
+ * A field in a degenerate group is required by that group ALONE, so it is
+ * marked required even when it also belongs to a group that does offer a
+ * choice; that other group keeps its affordance and is satisfied by this field
+ * either way. The key is deleted rather than emptied because `[]` is truthy,
+ * and every consumer tests `option.required_groups` for existence.
+ *
+ * Returns the schema unchanged — the same object — when no group degenerates,
+ * so it can sit on a memo without giving every render a new schema identity.
+ */
+export declare const resolveDegenerateRequiredGroups: <T extends IQorusFormSchema>(schema: T) => T;
 //# sourceMappingURL=options.d.ts.map

package/dist/helpers/options.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../../src/helpers/options.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAyB,MAAM,8BAA8B,CAAC;AAEvF,eAAO,MAAM,4BAA4B,WAC/B,gBAAgB,UAChB,MAAM,EAAE,kBACA,MAAM,KACrB,MAAM,EAQR,CAAC;AAEF,eAAO,MAAM,wBAAwB,WAC3B,gBAAgB,UAChB,MAAM,EAAE,gBACF,MAAM,KACnB,MAUF,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,mBAAmB,YAAa,OAAO,KAAG,OAG5C,CAAC"}
+{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../../src/helpers/options.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAyB,MAAM,8BAA8B,CAAC;AAEvF,eAAO,MAAM,4BAA4B,WAC/B,gBAAgB,UAChB,MAAM,EAAE,kBACA,MAAM,KACrB,MAAM,EAQR,CAAC;AAEF,eAAO,MAAM,wBAAwB,WAC3B,gBAAgB,UAChB,MAAM,EAAE,gBACF,MAAM,KACnB,MAUF,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,mBAAmB,YAAa,OAAO,KAAG,OAG5C,CAAC;AAEZ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,eAAO,MAAM,+BAA+B,uCAClC,CAAC,KACR,CA8BF,CAAC"}

package/dist/helpers/options.js

@@ -1,6 +1,17 @@
 "use strict";
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getListElementValue = exports.getRequiredOptionMessage = exports.getOptionsFromRequiredGroups = void 0;
+exports.resolveDegenerateRequiredGroups = exports.getListElementValue = exports.getRequiredOptionMessage = exports.getOptionsFromRequiredGroups = void 0;
 var getOptionsFromRequiredGroups = function (schema, groups, currentOption) {
     return Object.keys(schema)
         .filter(function (option) {
@@ -46,4 +57,70 @@ var getListElementValue = function (element) {
         : element;
 };
 exports.getListElementValue = getListElementValue;
+/**
+ * The schema with every one-of group that offers no choice turned back into a
+ * plain required field.
+ *
+ * A `required_groups` group says *"at least one of these"*, and the whole
+ * affordance built on it — the ONE OF header, the `Covers` / `Covered by “X”`
+ * chips, the *"this field or X is required"* message — exists to tell an author
+ * that they have a CHOICE and which way they have answered it. When the group
+ * has a single member in the schema in hand, there is no choice: that field
+ * must be set, which is exactly what `required` already means. Saying it in the
+ * one-of grammar instead is worse than saying nothing, because a green tick
+ * beside a value reads as confirmation of the VALUE — a Qorus test author read
+ * `✓ COVERS` beside their service as "yes, this is the service your test is
+ * about", which the form never said and cannot know.
+ *
+ * This is not a hypothetical: a server may legitimately declare a group over an
+ * API-only alternative it then hides from the form (Qorus test steps put
+ * `target` in a group with `service`, and hide `target`), so the form is handed
+ * one member of a two-member group. The group is still real for the API and
+ * must stay in the schema the server serves; it is only this form that has
+ * nothing to offer.
+ *
+ * The rewrite is exact rather than cosmetic: a one-of over one option and a
+ * required option are the same constraint, so validation, the completion meter
+ * and the required-only filter all keep saying what they said — in the grammar
+ * that fits.
+ *
+ * A field in a degenerate group is required by that group ALONE, so it is
+ * marked required even when it also belongs to a group that does offer a
+ * choice; that other group keeps its affordance and is satisfied by this field
+ * either way. The key is deleted rather than emptied because `[]` is truthy,
+ * and every consumer tests `option.required_groups` for existence.
+ *
+ * Returns the schema unchanged — the same object — when no group degenerates,
+ * so it can sit on a memo without giving every render a new schema identity.
+ */
+var resolveDegenerateRequiredGroups = function (schema) {
+    if (!schema)
+        return schema;
+    var membersPerGroup = {};
+    Object.values(schema).forEach(function (option) {
+        var _a;
+        (_a = option === null || option === void 0 ? void 0 : option.required_groups) === null || _a === void 0 ? void 0 : _a.forEach(function (group) {
+            var _a;
+            membersPerGroup[group] = ((_a = membersPerGroup[group]) !== null && _a !== void 0 ? _a : 0) + 1;
+        });
+    });
+    var degenerate = function (group) { return membersPerGroup[group] < 2; };
+    if (!Object.keys(membersPerGroup).some(degenerate))
+        return schema;
+    var resolved = {};
+    Object.entries(schema).forEach(function (_a) {
+        var name = _a[0], option = _a[1];
+        var groups = option === null || option === void 0 ? void 0 : option.required_groups;
+        if (!(groups === null || groups === void 0 ? void 0 : groups.some(degenerate))) {
+            resolved[name] = option;
+            return;
+        }
+        var kept = groups.filter(function (group) { return !degenerate(group); });
+        var rest = __assign({}, option);
+        delete rest.required_groups;
+        resolved[name] = __assign(__assign(__assign({}, rest), { required: true }), (kept.length ? { required_groups: kept } : {}));
+    });
+    return resolved;
+};
+exports.resolveDegenerateRequiredGroups = resolveDegenerateRequiredGroups;
 //# sourceMappingURL=options.js.map

package/dist/helpers/options.js.map

@@ -1 +1 @@
-{"version":3,"file":"options.js","sourceRoot":"","sources":["../../src/helpers/options.ts"],"names":[],"mappings":";;;AAEO,IAAM,4BAA4B,GAAG,UAC1C,MAAwB,EACxB,MAAgB,EAChB,aAAsB;IAEtB,OAAO,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC;SACvB,MAAM,CAAC,UAAC,MAAM;;QACb,OAAO,MAAC,MAAM,CAAC,MAAM,CAA2B,CAAC,eAAe,0CAAE,IAAI,CAAC,UAAC,KAAK;YAC3E,OAAA,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAtB,CAAsB,CACvB,CAAC;IACJ,CAAC,CAAC;SACD,MAAM,CAAC,UAAC,MAAM,IAAK,OAAA,MAAM,KAAK,aAAa,EAAxB,CAAwB,CAAC,CAAC;AAClD,CAAC,CAAC;AAZW,QAAA,4BAA4B,gCAYvC;AAEK,IAAM,wBAAwB,GAAG,UACtC,MAAwB,EACxB,MAAgB,EAChB,YAAoB;IAEpB,IAAK,MAAM,CAAC,YAAY,CAA2B,CAAC,QAAQ,EAAE,CAAC;QAC7D,OAAO,wBAAwB,CAAC;IAClC,CAAC;IAED,IAAM,eAAe,GAAG,IAAA,oCAA4B,EAAC,MAAM,EAAE,MAAM,EAAE,YAAY,CAAC;SAC/E,GAAG,CAAC,UAAC,MAAM,IAAK,OAAC,MAAM,CAAC,MAAM,CAA2B,CAAC,YAAY,EAAtD,CAAsD,CAAC;SACvE,IAAI,CAAC,MAAM,CAAC,CAAC;IAEhB,OAAO,wBAAiB,eAAe,iBAAc,CAAC;AACxD,CAAC,CAAC;AAdW,QAAA,wBAAwB,4BAcnC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACI,IAAM,mBAAmB,GAAG,UAAC,OAAgB;IAClD,OAAA,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,OAAO,IAAI,OAAO,CAAC,CAAC;QACtF,OAA8B,CAAC,KAAK;QACvC,CAAC,CAAC,OAAO;AAFT,CAES,CAAC;AAHC,QAAA,mBAAmB,uBAGpB"}
+{"version":3,"file":"options.js","sourceRoot":"","sources":["../../src/helpers/options.ts"],"names":[],"mappings":"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"}

package/dist/helpers/templateItems.d.ts

@@ -0,0 +1,47 @@
+import type { TMarkdownRenderer } from '../components/Description/markdownRendererContext';
+/**
+ * What a template picker should actually list.
+ *
+ * Pickers group templates by category, which is what makes a long catalogue
+ * scannable. A LONE category buys nothing and costs a click: the author opens
+ * the picker, sees one row naming the category, clicks it, and only then sees
+ * the values — with a back arrow as the only other thing on offer. So a single
+ * category is opened for them.
+ *
+ * Two or more categories keep the grouping, because there the headers are doing
+ * real work. This only ever removes a step that could not have gone any other
+ * way.
+ *
+ * Lives here rather than beside either picker: `TemplateField` renders the
+ * "Select Template" dropdown and `RichText` renders the in-editor `$` list, and
+ * `TemplateField` already imports `RichText` — so a shared home is the only one
+ * that does not close an import cycle.
+ */
+export declare const templateItemsToShow: <T>(items: T[] | undefined) => T[] | undefined;
+/**
+ * A picker row's description, DRAWN.
+ *
+ * A description is prose, and a host that writes prose writes markdown: the
+ * same author, in the same dialect, as the field descriptions and schema
+ * messages this package already draws through the host's renderer. Left as a
+ * string, a row explaining that a step needs a **Fixture Output** printed the
+ * asterisks at the reader.
+ *
+ * WHERE THIS MAY BE CALLED, and why it is not simply done at the source: the
+ * template list is a memo KEY in several places — `TemplateField` stringifies
+ * both the incoming `templates` and the resolved `filteredTemplates`, and the
+ * list is handed down to nested fields that stringify it again. `JSON.stringify`
+ * throws on a React element's circular `_owner`, so an element anywhere in the
+ * list takes the whole form down to a blank panel.
+ *
+ * So this runs at the LAST hop only — the call that hands items to a Reqore
+ * control, after every key has been computed — and its result is never passed
+ * on to anything that might stringify it. Reqore itself does not: it draws the
+ * description into a `ReqoreTextEffect` and styled-components filters the prop
+ * off the DOM.
+ *
+ * Without a host renderer the items are returned untouched, so a host that has
+ * no markdown keeps exactly what it had.
+ */
+export declare const renderTemplateItemDescriptions: <T>(items: T[] | undefined, render: TMarkdownRenderer | undefined) => T[] | undefined;
+//# sourceMappingURL=templateItems.d.ts.map

package/dist/helpers/templateItems.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"templateItems.d.ts","sourceRoot":"","sources":["../../src/helpers/templateItems.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mDAAmD,CAAC;AAE3F;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,mBAAmB,aAAe,CAAC,EAAE,GAAG,SAAS,KAAG,CAAC,EAAE,GAAG,SAMtE,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,8BAA8B,aAClC,CAAC,EAAE,GAAG,SAAS,UACd,iBAAiB,GAAG,SAAS,KACpC,CAAC,EAAE,GAAG,SAwBR,CAAC"}

package/dist/helpers/templateItems.js

@@ -0,0 +1,88 @@
+"use strict";
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderTemplateItemDescriptions = exports.templateItemsToShow = void 0;
+/**
+ * What a template picker should actually list.
+ *
+ * Pickers group templates by category, which is what makes a long catalogue
+ * scannable. A LONE category buys nothing and costs a click: the author opens
+ * the picker, sees one row naming the category, clicks it, and only then sees
+ * the values — with a back arrow as the only other thing on offer. So a single
+ * category is opened for them.
+ *
+ * Two or more categories keep the grouping, because there the headers are doing
+ * real work. This only ever removes a step that could not have gone any other
+ * way.
+ *
+ * Lives here rather than beside either picker: `TemplateField` renders the
+ * "Select Template" dropdown and `RichText` renders the in-editor `$` list, and
+ * `TemplateField` already imports `RichText` — so a shared home is the only one
+ * that does not close an import cycle.
+ */
+var templateItemsToShow = function (items) {
+    if ((items === null || items === void 0 ? void 0 : items.length) !== 1) {
+        return items;
+    }
+    var only = items[0];
+    return Array.isArray(only.items) && only.items.length ? only.items : items;
+};
+exports.templateItemsToShow = templateItemsToShow;
+/**
+ * A picker row's description, DRAWN.
+ *
+ * A description is prose, and a host that writes prose writes markdown: the
+ * same author, in the same dialect, as the field descriptions and schema
+ * messages this package already draws through the host's renderer. Left as a
+ * string, a row explaining that a step needs a **Fixture Output** printed the
+ * asterisks at the reader.
+ *
+ * WHERE THIS MAY BE CALLED, and why it is not simply done at the source: the
+ * template list is a memo KEY in several places — `TemplateField` stringifies
+ * both the incoming `templates` and the resolved `filteredTemplates`, and the
+ * list is handed down to nested fields that stringify it again. `JSON.stringify`
+ * throws on a React element's circular `_owner`, so an element anywhere in the
+ * list takes the whole form down to a blank panel.
+ *
+ * So this runs at the LAST hop only — the call that hands items to a Reqore
+ * control, after every key has been computed — and its result is never passed
+ * on to anything that might stringify it. Reqore itself does not: it draws the
+ * description into a `ReqoreTextEffect` and styled-components filters the prop
+ * off the DOM.
+ *
+ * Without a host renderer the items are returned untouched, so a host that has
+ * no markdown keeps exactly what it had.
+ */
+var renderTemplateItemDescriptions = function (items, render) {
+    if (!render || !(items === null || items === void 0 ? void 0 : items.length)) {
+        return items;
+    }
+    return items.map(function (item) {
+        var entry = item;
+        var next = __assign({}, entry);
+        if (typeof entry.description === 'string' && entry.description.trim()) {
+            /* `compact`, for the reason the context gives: a row is a constrained
+               container, and markdown authored as a document opens with a heading
+               that would outgrow the label above it. */
+            next.description = render({ value: entry.description, compact: true });
+        }
+        // Only when the item HAS children — writing the key unconditionally would
+        // give every leaf an `items` a picker could read as an empty submenu.
+        if (Array.isArray(entry.items)) {
+            next.items = (0, exports.renderTemplateItemDescriptions)(entry.items, render);
+        }
+        return next;
+    });
+};
+exports.renderTemplateItemDescriptions = renderTemplateItemDescriptions;
+//# sourceMappingURL=templateItems.js.map

package/dist/helpers/templateItems.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"templateItems.js","sourceRoot":"","sources":["../../src/helpers/templateItems.ts"],"names":[],"mappings":";;;;;;;;;;;;;;AAEA;;;;;;;;;;;;;;;;;GAiBG;AACI,IAAM,mBAAmB,GAAG,UAAK,KAAsB;IAC5D,IAAI,CAAA,KAAK,aAAL,KAAK,uBAAL,KAAK,CAAE,MAAM,MAAK,CAAC,EAAE,CAAC;QACxB,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAA0B,CAAC;IAC/C,OAAO,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAE,IAAI,CAAC,KAAa,CAAC,CAAC,CAAC,KAAK,CAAC;AACtF,CAAC,CAAC;AANW,QAAA,mBAAmB,uBAM9B;AAEF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACI,IAAM,8BAA8B,GAAG,UAC5C,KAAsB,EACtB,MAAqC;IAErC,IAAI,CAAC,MAAM,IAAI,CAAC,CAAA,KAAK,aAAL,KAAK,uBAAL,KAAK,CAAE,MAAM,CAAA,EAAE,CAAC;QAC9B,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,KAAK,CAAC,GAAG,CAAC,UAAC,IAAI;QACpB,IAAM,KAAK,GAAG,IAAkD,CAAC;QACjE,IAAM,IAAI,GAAG,aAAK,KAAK,CAA6B,CAAC;QAErD,IAAI,OAAO,KAAK,CAAC,WAAW,KAAK,QAAQ,IAAI,KAAK,CAAC,WAAW,CAAC,IAAI,EAAE,EAAE,CAAC;YACtE;;wDAE4C;YAC5C,IAAI,CAAC,WAAW,GAAG,MAAM,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,WAAW,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;QACzE,CAAC;QAED,0EAA0E;QAC1E,sEAAsE;QACtE,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;YAC/B,IAAI,CAAC,KAAK,GAAG,IAAA,sCAA8B,EAAC,KAAK,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QACnE,CAAC;QAED,OAAO,IAAS,CAAC;IACnB,CAAC,CAAC,CAAC;AACL,CAAC,CAAC;AA3BW,QAAA,8BAA8B,kCA2BzC"}

package/dist/helpers/templateText.d.ts

@@ -0,0 +1,37 @@
+import { IReqoreFormTemplates } from '@qoretechnologies/reqore/dist/components/Textarea';
+/** A run of text. */
+export interface ITemplateTextLeaf {
+    text: string;
+}
+/** A template reference, drawn as a chip. */
+export interface ITemplateTextTag {
+    type: 'tag';
+    value: string;
+    label: string;
+    metadata?: unknown;
+    children: ITemplateTextLeaf[];
+}
+/** One line of the string. */
+export interface ITemplateTextParagraph {
+    type: 'paragraph';
+    children: Array<ITemplateTextLeaf | ITemplateTextTag>;
+}
+/**
+ * What a reference chip says: the name the catalogue gives the reference, else
+ * the reference as the DPQL Text view labels it (`local: name`), so the same
+ * reference reads alike in the Visual builder and the Text view.
+ */
+export declare const templateChipLabel: (templates: IReqoreFormTemplates | undefined, value: string) => string;
+/**
+ * `text` as paragraphs, one per line, with each template reference a chip.
+ *
+ * A chip is an inline VOID and holds no text of its own, so a cursor can only
+ * sit in the text nodes around it; one is kept on each side even when empty.
+ * The chip's label is `templateChipLabel`.
+ */
+export declare const templateTextToNodes: (text: string, templates?: IReqoreFormTemplates) => ITemplateTextParagraph[];
+/** The string the paragraphs stand for: each chip written as its reference. */
+export declare const templateNodesToText: (nodes?: ReadonlyArray<{
+    children?: unknown[];
+}>) => string;
+//# sourceMappingURL=templateText.d.ts.map

package/dist/helpers/templateText.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"templateText.d.ts","sourceRoot":"","sources":["../../src/helpers/templateText.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,oBAAoB,EAAE,MAAM,mDAAmD,CAAC;AAQzF,qBAAqB;AACrB,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;CACd;AAED,6CAA6C;AAC7C,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,KAAK,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,iBAAiB,EAAE,CAAC;CAC/B;AAED,8BAA8B;AAC9B,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,WAAW,CAAC;IAClB,QAAQ,EAAE,KAAK,CAAC,iBAAiB,GAAG,gBAAgB,CAAC,CAAC;CACvD;AAED;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,cAAe,oBAAoB,GAAG,SAAS,SAAS,MAAM,KAAG,MAG9F,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,SACxB,MAAM,cACA,oBAAoB,KAC/B,sBAAsB,EAqBrB,CAAC;AAEL,+EAA+E;AAC/E,eAAO,MAAM,mBAAmB,WAAY,cAAc;IAAE,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAA;CAAE,CAAC,KAAG,MAWvE,CAAC"}