@qoretechnologies/reqraft 0.10.55-pr.124.g77dd26c → 0.10.55

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,80 @@
+import { IReqoreFormTemplates } from '@qoretechnologies/reqore/dist/components/Textarea';
+import { IRichtextSegment } from './common';
+/** 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.
+ *
+ * `getTagLabel` only where the token IS reqraft's grammar. It reads a token as
+ * `<key>: <path>` and drops the leading `$`, which is right for `$local:name`
+ * and nonsense for a host's own spelling: an unnamed `$._case.mode` came out as
+ * `._case.mode`, a string that is neither the reference nor a name for it. With
+ * nothing to call it, the reference itself is the honest answer — the same
+ * floor `describeTemplateReference` documents.
+ */
+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`.
+ *
+ * `tokenGrammar` is the field's own `templateToken`, and it is the reason this
+ * takes a third argument at all: without it the editor knew only reqraft's
+ * built-in `$key:{path}` and drew a host's own spelling (`$._case.mode`) as raw
+ * text, while the collapsed row that opens it — which IS given the grammar —
+ * drew the same reference as a named chip. The two surfaces have to recognise
+ * the same references, so they resolve them with the same
+ * `lineReferenceSpans`.
+ */
+export declare const templateTextToNodes: (text: string, templates?: IReqoreFormTemplates, tokenGrammar?: RegExp | string) => ITemplateTextParagraph[];
+/** The string the paragraphs stand for: each chip written as its reference. */
+export declare const templateNodesToText: (nodes?: ReadonlyArray<{
+    children?: unknown[];
+}>) => string;
+/**
+ * `text` as prose runs and reference chips.
+ *
+ * The read-only twin of {@link templateTextToNodes}: the editor turns the same
+ * string into chips a cursor can move around, this turns it into segments a row
+ * can draw. A value is very often a reference INSIDE something the author
+ * wrote — `$._case.mode != 'simulate'` — and the comparison is theirs and stays
+ * exactly as typed; only the reference becomes a chip.
+ *
+ * Three ways a reference is recognised, in the order a longer match wins:
+ *
+ *  1. the grammar the FIELD declares (`templateToken`), which is the only thing
+ *     that knows the extent of a host's own spelling;
+ *  2. reqraft's own token grammar, so `$local:name` embedded in prose is drawn
+ *     the way the template picker would name it;
+ *  3. any value the field's catalogue actually offers, so a host that declares
+ *     no grammar still gets the references it named drawn as names.
+ *
+ * Which references are recognised, and how overlaps resolve, is
+ * `lineReferenceSpans` — the same answer {@link templateTextToNodes} builds the
+ * editor's chips from.
+ */
+export declare const templateTextSegments: (text: string, templates?: IReqoreFormTemplates, tokenGrammar?: RegExp | string) => IRichtextSegment[];
+/** Does this text hold a reference at all? The one question a caller asks
+ *  before deciding whether the chipped rendering applies — answered by the
+ *  same pass that would draw it, so the two cannot disagree. */
+export declare const hasTemplateText: (text: string, templates?: IReqoreFormTemplates, tokenGrammar?: RegExp | string) => boolean;
+//# 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;AAEzF,OAAO,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAO5C,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;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iBAAiB,cAAe,oBAAoB,GAAG,SAAS,SAAS,MAAM,KAAG,MAM9F,CAAC;AAqKF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,mBAAmB,SACxB,MAAM,cACA,oBAAoB,iBACjB,MAAM,GAAG,MAAM,KAC7B,sBAAsB,EAmBrB,CAAC;AAEL,+EAA+E;AAC/E,eAAO,MAAM,mBAAmB,WAAY,cAAc;IAAE,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAA;CAAE,CAAC,KAAG,MAWvE,CAAC;AAMhB;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,oBAAoB,SACzB,MAAM,cACA,oBAAoB,iBACjB,MAAM,GAAG,MAAM,KAC7B,gBAAgB,EAmClB,CAAC;AAEF;;gEAEgE;AAChE,eAAO,MAAM,eAAe,SACpB,MAAM,cACA,oBAAoB,iBACjB,MAAM,GAAG,MAAM,KAC7B,OAC4F,CAAC"}

package/dist/helpers/templateText.js

@@ -0,0 +1,291 @@
+"use strict";
+var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
+    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasTemplateText = exports.templateTextSegments = exports.templateNodesToText = exports.templateTextToNodes = exports.templateChipLabel = void 0;
+var dpqlHelpers_1 = require("../components/dpqlEditor/dpqlHelpers");
+var templates_1 = require("./templates");
+/**
+ * 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.
+ *
+ * `getTagLabel` only where the token IS reqraft's grammar. It reads a token as
+ * `<key>: <path>` and drops the leading `$`, which is right for `$local:name`
+ * and nonsense for a host's own spelling: an unnamed `$._case.mode` came out as
+ * `._case.mode`, a string that is neither the reference nor a name for it. With
+ * nothing to call it, the reference itself is the honest answer — the same
+ * floor `describeTemplateReference` documents.
+ */
+var templateChipLabel = function (templates, value) {
+    var _a = (0, templates_1.describeTemplateReference)(templates, value), label = _a.label, item = _a.item;
+    if (item) {
+        return label;
+    }
+    return value.includes(':') ? (0, dpqlHelpers_1.getTagLabel)(value) : value;
+};
+exports.templateChipLabel = templateChipLabel;
+// ---------------------------------------------------------------------------
+// Finding the references in a string. ONE pass, used by both the editor's
+// document and the read-only row: the two disagreeing about what counts as a
+// reference is the whole defect this file exists to close, and the only way
+// they cannot disagree is by asking the same question of the same code.
+// ---------------------------------------------------------------------------
+/**
+ * Every value the catalogue offers, longest first.
+ *
+ * A host may write its references in a grammar reqraft has never seen — a Qorus
+ * test spells one `$._case.mode`, which `TEMPLATE_TOKEN_SOURCE` cannot match
+ * because it has no `$key:` at all. Asking the field's own list which strings
+ * it NAMES settles that without reqraft guessing at anybody's syntax, and it is
+ * the same question the whole-value branch of the read row already asks
+ * (`findTemplate`).
+ *
+ * Longest first so `$.result.status` is recognised before `$.result`, which is
+ * a prefix of it; `aliasValues` are included because a catalogue may spell the
+ * same reference two ways (see `matchesTemplateValue`).
+ */
+/* Keyed on the catalogue's identity, because a form hands the SAME object to
+   every row it draws and a row draws on every keystroke elsewhere in the form.
+   Walking a 29-item catalogue per row per render is work with one answer. */
+var catalogueValueCache = new WeakMap();
+var catalogueValues = function (templates) {
+    if (!templates) {
+        return [];
+    }
+    var cached = catalogueValueCache.get(templates);
+    if (cached) {
+        return cached;
+    }
+    var values = new Set();
+    var walk = function (items) {
+        items === null || items === void 0 ? void 0 : items.forEach(function (item) {
+            var _a, _b;
+            if (typeof (item === null || item === void 0 ? void 0 : item.value) === 'string' && item.value) {
+                values.add(item.value);
+            }
+            (_b = (_a = item === null || item === void 0 ? void 0 : item.metadata) === null || _a === void 0 ? void 0 : _a.aliasValues) === null || _b === void 0 ? void 0 : _b.forEach(function (alias) {
+                if (typeof alias === 'string' && alias) {
+                    values.add(alias);
+                }
+            });
+            walk(item === null || item === void 0 ? void 0 : item.items);
+        });
+    };
+    walk(templates === null || templates === void 0 ? void 0 : templates.items);
+    // `Array.from`, not a spread: this file is emitted by `tsconfig.prod.json`,
+    // which targets ES5 and cannot down-level a Set spread without `downlevelIteration`.
+    var sorted = Array.from(values).sort(function (a, b) { return b.length - a.length; });
+    catalogueValueCache.set(templates, sorted);
+    return sorted;
+};
+/**
+ * Where a literal catalogue value occurs in `line`, as whole references only.
+ *
+ * The boundary check is what stops `$.result` being chipped out of the middle
+ * of `$.result.status` when the catalogue names only the shorter one: a
+ * reference that continues into a further path step is not the reference the
+ * catalogue named, and half a path drawn as a name would be a lie about what
+ * the value reads.
+ */
+var literalSpans = function (line, literal) {
+    var spans = [];
+    var from = 0;
+    for (;;) {
+        var start = line.indexOf(literal, from);
+        if (start === -1) {
+            break;
+        }
+        var end = start + literal.length;
+        var before = start > 0 ? line[start - 1] : '';
+        var after = end < line.length ? line[end] : '';
+        if (!/[\w$]/.test(before) && !/[\w.[]/.test(after)) {
+            spans.push({ start: start, end: end });
+        }
+        from = start + 1;
+    }
+    return spans;
+};
+/** Where a grammar matches in `line`. A fresh expression each time: a shared
+ *  `/g` instance carries `lastIndex` between calls. */
+var patternSpans = function (line, source) {
+    var spans = [];
+    var pattern = new RegExp(source, 'g');
+    var match;
+    while ((match = pattern.exec(line)) !== null) {
+        if (match[0] === '') {
+            pattern.lastIndex += 1;
+            continue;
+        }
+        spans.push({ start: match.index, end: match.index + match[0].length });
+    }
+    return spans;
+};
+/** A grammar as a source string, however the field declared it. */
+var grammarSource = function (grammar) {
+    if (grammar instanceof RegExp) {
+        return grammar.source;
+    }
+    return typeof grammar === 'string' && grammar ? grammar : undefined;
+};
+/**
+ * The references one line holds, in order and non-overlapping.
+ *
+ * Three ways a reference is recognised, in the order a longer match wins:
+ *
+ *  1. the grammar the FIELD declares (`templateToken`), which is the only thing
+ *     that knows the extent of a host's own spelling;
+ *  2. reqraft's own token grammar, so `$local:name` embedded in prose is drawn
+ *     the way the template picker would name it;
+ *  3. any value the field's catalogue actually offers, so a host that declares
+ *     no grammar still gets the references it named drawn as names.
+ *
+ * Overlaps resolve to the longest span starting earliest, so a catalogue entry
+ * never carves a shorter name out of a longer reference.
+ */
+var lineReferenceSpans = function (line, templates, tokenGrammar) {
+    var declared = grammarSource(tokenGrammar);
+    var candidates = __spreadArray(__spreadArray(__spreadArray([], (declared ? patternSpans(line, declared) : []), true), patternSpans(line, templates_1.TEMPLATE_TOKEN_SOURCE), true), catalogueValues(templates).flatMap(function (literal) { return literalSpans(line, literal); }), true).sort(function (a, b) { return a.start - b.start || b.end - a.end; });
+    var spans = [];
+    var cursor = 0;
+    candidates.forEach(function (span) {
+        if (span.start < cursor) {
+            // Already inside a reference that started earlier, or covered by a longer
+            // one at the same position — either way it is not its own token.
+            return;
+        }
+        spans.push(span);
+        cursor = span.end;
+    });
+    return spans;
+};
+// ---------------------------------------------------------------------------
+// The string as the EDITOR's document.
+// ---------------------------------------------------------------------------
+/**
+ * `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`.
+ *
+ * `tokenGrammar` is the field's own `templateToken`, and it is the reason this
+ * takes a third argument at all: without it the editor knew only reqraft's
+ * built-in `$key:{path}` and drew a host's own spelling (`$._case.mode`) as raw
+ * text, while the collapsed row that opens it — which IS given the grammar —
+ * drew the same reference as a named chip. The two surfaces have to recognise
+ * the same references, so they resolve them with the same
+ * `lineReferenceSpans`.
+ */
+var templateTextToNodes = function (text, templates, tokenGrammar) {
+    return (text !== null && text !== void 0 ? text : '').split('\n').map(function (line) {
+        var children = [];
+        var last = 0;
+        lineReferenceSpans(line, templates, tokenGrammar).forEach(function (span) {
+            var value = line.slice(span.start, span.end);
+            var item = (0, templates_1.describeTemplateReference)(templates, value).item;
+            children.push({ text: line.slice(last, span.start) });
+            children.push({
+                type: 'tag',
+                value: value,
+                label: (0, exports.templateChipLabel)(templates, value),
+                metadata: item === null || item === void 0 ? void 0 : item.metadata,
+                children: [{ text: '' }],
+            });
+            last = span.end;
+        });
+        children.push({ text: line.slice(last) });
+        return { type: 'paragraph', children: children };
+    });
+};
+exports.templateTextToNodes = templateTextToNodes;
+/** The string the paragraphs stand for: each chip written as its reference. */
+var templateNodesToText = function (nodes) {
+    return (nodes !== null && nodes !== void 0 ? nodes : [])
+        .map(function (paragraph) {
+        var _a;
+        return ((_a = paragraph === null || paragraph === void 0 ? void 0 : paragraph.children) !== null && _a !== void 0 ? _a : [])
+            .map(function (node) {
+            var _a;
+            return typeof (node === null || node === void 0 ? void 0 : node.text) === 'string' ? node.text
+                : (node === null || node === void 0 ? void 0 : node.type) === 'tag' ? String((_a = node.value) !== null && _a !== void 0 ? _a : '')
+                    : '';
+        })
+            .join('');
+    })
+        .join('\n');
+};
+exports.templateNodesToText = templateNodesToText;
+// ---------------------------------------------------------------------------
+// The same string, drawn for READING rather than edited.
+// ---------------------------------------------------------------------------
+/**
+ * `text` as prose runs and reference chips.
+ *
+ * The read-only twin of {@link templateTextToNodes}: the editor turns the same
+ * string into chips a cursor can move around, this turns it into segments a row
+ * can draw. A value is very often a reference INSIDE something the author
+ * wrote — `$._case.mode != 'simulate'` — and the comparison is theirs and stays
+ * exactly as typed; only the reference becomes a chip.
+ *
+ * Three ways a reference is recognised, in the order a longer match wins:
+ *
+ *  1. the grammar the FIELD declares (`templateToken`), which is the only thing
+ *     that knows the extent of a host's own spelling;
+ *  2. reqraft's own token grammar, so `$local:name` embedded in prose is drawn
+ *     the way the template picker would name it;
+ *  3. any value the field's catalogue actually offers, so a host that declares
+ *     no grammar still gets the references it named drawn as names.
+ *
+ * Which references are recognised, and how overlaps resolve, is
+ * `lineReferenceSpans` — the same answer {@link templateTextToNodes} builds the
+ * editor's chips from.
+ */
+var templateTextSegments = function (text, templates, tokenGrammar) {
+    var source = String(text !== null && text !== void 0 ? text : '');
+    if (!source) {
+        return [];
+    }
+    var segments = [];
+    var pushText = function (value) {
+        if (!value)
+            return;
+        var last = segments[segments.length - 1];
+        if ((last === null || last === void 0 ? void 0 : last.kind) === 'text') {
+            last.text += value;
+        }
+        else {
+            segments.push({ kind: 'text', text: value });
+        }
+    };
+    source.split('\n').forEach(function (line, lineIndex) {
+        if (lineIndex) {
+            pushText('\n');
+        }
+        var cursor = 0;
+        lineReferenceSpans(line, templates, tokenGrammar).forEach(function (span) {
+            pushText(line.slice(cursor, span.start));
+            var value = line.slice(span.start, span.end);
+            segments.push({ kind: 'tag', value: value, text: (0, exports.templateChipLabel)(templates, value) });
+            cursor = span.end;
+        });
+        pushText(line.slice(cursor));
+    });
+    return segments;
+};
+exports.templateTextSegments = templateTextSegments;
+/** Does this text hold a reference at all? The one question a caller asks
+ *  before deciding whether the chipped rendering applies — answered by the
+ *  same pass that would draw it, so the two cannot disagree. */
+var hasTemplateText = function (text, templates, tokenGrammar) {
+    return (0, exports.templateTextSegments)(text, templates, tokenGrammar).some(function (segment) { return segment.kind === 'tag'; });
+};
+exports.hasTemplateText = hasTemplateText;
+//# sourceMappingURL=templateText.js.map

package/dist/helpers/templateText.js.map

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

package/dist/helpers/templates.d.ts

@@ -1,3 +1,4 @@
+import { TReqoreTooltipProp } from '@qoretechnologies/reqore/dist/types/global';
 import { IReqoreFormTemplates } from '@qoretechnologies/reqore/dist/components/Textarea';
 import { TReqoreDropdownItem } from '@qoretechnologies/reqore/dist/components/Dropdown/list';
 /**
@@ -62,7 +63,12 @@ export declare const isBracedTemplateToken: (value?: unknown) => value is string
  *
  * The match must break at a path boundary (`.` or `[`) so `choicesOther` is
  * never named after `choices`, and the token keys must agree so a `$config:`
- * item never names a `$data:` value.
+ * item never names a `$data:` value — "no key" included, so the key-less
+ * grammar and the keyed one never name each other's references.
+ *
+ * Both grammars arrive here: `$data:{create.choices[0]}` and the key-less
+ * `$.create.status` are the same question asked in two spellings, and a
+ * catalogue written in either one names the walks its author took past it.
  */
 export declare const findTemplateByPath: (templates: IReqoreFormTemplates, value: string) => {
     item: TReqoreDropdownItem;
@@ -90,6 +96,11 @@ export declare const resolveTemplateLabel: (templates: IReqoreFormTemplates | un
  * never fetches one), and there the raw token is the only thing left to show.
  * Showing it as `$data:{…}` renders a value as code; showing the path renders
  * it as a name, which is the honest floor.
+ *
+ * Only a BRACED wrapper is stripped, because only a braced wrapper is one.
+ * A key-less `$._case.mode` stripped of its `$` reads as `._case.mode`, which
+ * is neither the reference nor a name for it; with nothing to call it, the
+ * reference as written is the honest answer.
  */
 export declare const getTemplateReferencePath: (value: string) => string;
 /**
@@ -103,19 +114,26 @@ export declare const describeTemplateReference: (templates: IReqoreFormTemplates
     label: string;
     item?: TReqoreDropdownItem;
 };
-export type TTemplateTextSegment = {
-    kind: 'text';
-    text: string;
-} | {
-    kind: 'token';
-    text: string;
-};
 /**
- * Splits prose that embeds template tokens into its literal and token parts —
- * `trim("$data:{…}")` becomes `trim("`, the token, `")`. Used to chip the
- * references inside a rendered expression instead of printing them raw.
+ * What a chosen template's hover should say.
+ *
+ * The reference itself — `$._case.title`, `$data:{dc_ai_reply.choices[0]…}` —
+ * is an implementation detail of the grammar, and it was what every template
+ * chip put in its tooltip. An author hovering a chip wants to know WHAT VALUE
+ * this is, and the catalogue already carries that: the entry's `description`
+ * is the prose the picker lists it under, written from the schema that declares
+ * it, with its type appended.
+ *
+ * So the hover reads as a small card — the value's name as the title, its
+ * description as the body — and the path stays where it is genuinely needed:
+ * the field's own help, which teaches the grammar with a worked example, and
+ * the picker, for the walks no list can hold.
+ *
+ * Falls back to the resolved label (itself the stripped path when the catalogue
+ * explains nothing), because a surface with no catalogue must still say what
+ * the value is rather than nothing at all.
  */
-export declare const splitTemplateTokens: (text?: string) => TTemplateTextSegment[];
+export declare const templateTooltip: (templates: IReqoreFormTemplates | undefined, value: string) => TReqoreTooltipProp;
 export declare const filterTemplatesByType: (templates?: IReqoreFormTemplates, fieldType?: string, hasArgSchema?: boolean) => IReqoreFormTemplates;
 interface ITemplateItemPayload {
     display_name?: string;

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

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