@qoretechnologies/reqraft 0.10.64 → 0.10.65-pr.137.g20c3bec

package/src/components/dpqlEditor/dpqlProbe.ts

@@ -1,165 +0,0 @@
-// Copyright 2026 Qore Technologies, s.r.o.
-/**
- * One shared, lazily-opened DPQL document used to ask the server "is this
- * text really an expression?" on behalf of plain form fields that have no
- * editor of their own.
- *
- * ## Why a singleton, and why it is cheap
- *
- * `ReqraftLspClient` multiplexes every document over ONE socket per endpoint
- * (`LspSharedConnection`), and `initialize` runs once for that socket. A
- * probe is therefore not a new connection — it is one extra `didOpen`, and
- * one `QorusDpqlActionSession` in the server's `uriToDpqlSession` map. Even
- * so it is a single shared document rather than one per field: a form with
- * forty expression-capable options would otherwise open forty of them to ask
- * the same question.
- *
- * Nothing is opened until a field actually probes, so a form whose author
- * never types anything expression-shaped costs nothing at all.
- *
- * The document is opened with NO provider context. Verified against the live
- * server: `textDocument/didOpen` with `languageId: 'dpql'` and no metadata
- * still builds a session, and `dpql/parse` answers on it. Record-field
- * references (`@name`) do not resolve to a provider's fields without that
- * context, which is fine — detection asks about the SHAPE of the expression,
- * and the editor the author lands in binds the real context.
- *
- * No `target_type` is sent. Detection asks "is this an expression", not "is
- * it the right type"; a type mismatch is a thing to show the author INSIDE
- * the expression editor, not a reason to refuse to open it.
- */
-import { ReqraftLspClient } from '../../utils/lspClient';
-
-/** What a probe answers. Never throws — a failure is `success: false`. */
-export interface IDpqlProbeResult {
-  success: boolean;
-  expression: Record<string, any> | null;
-  diagnostics: Array<{ severity?: number | string; message?: string; code?: string | number }>;
-}
-
-const FAILED: IDpqlProbeResult = { success: false, expression: null, diagnostics: [] };
-
-/** Opaque, non-secret document URI — the server keys its session by this. */
-const PROBE_URI = 'dpql://probe/detection';
-
-/**
- * How many parsed texts to remember. Typing walks through many prefixes of
- * the same expression, and an author re-typing a value should not re-ask.
- */
-const MAX_CACHE_ENTRIES = 200;
-
-class DpqlProbe {
-  private client: ReqraftLspClient | null = null;
-  private opened: Promise<ReqraftLspClient> | null = null;
-  private users = 0;
-  private readonly cache = new Map<string, IDpqlProbeResult>();
-
-  /** Register a consumer; the document is still not opened until it probes. */
-  acquire(): void {
-    this.users += 1;
-  }
-
-  /** Drop a consumer, closing the shared document when the last one goes. */
-  release(): void {
-    this.users = Math.max(0, this.users - 1);
-
-    if (this.users === 0) {
-      this.close();
-    }
-  }
-
-  /**
-   * Parse `text` on the shared probe document. Resolves to `FAILED` rather
-   * than rejecting, for any reason at all — a field must never break because
-   * the instance is unreachable.
-   */
-  async parse(text: string): Promise<IDpqlProbeResult> {
-    const cached = this.cache.get(text);
-
-    if (cached) {
-      return cached;
-    }
-
-    let result = FAILED;
-
-    try {
-      const client = await this.open();
-      const response = await client.customRequest<Partial<IDpqlProbeResult>>('dpql/parse', {
-        uri: PROBE_URI,
-        text,
-      });
-
-      result = {
-        success: response?.success ?? false,
-        expression: response?.expression ?? null,
-        diagnostics: response?.diagnostics ?? [],
-      };
-    } catch {
-      // Unreachable instance, closed socket, request timeout: the field
-      // simply learns nothing and leaves the typed text exactly as it is.
-      result = FAILED;
-    }
-
-    this.remember(text, result);
-
-    return result;
-  }
-
-  /** Open (once) and return the shared document's client. */
-  private open(): Promise<ReqraftLspClient> {
-    if (this.opened) {
-      return this.opened;
-    }
-
-    this.opened = (async (): Promise<ReqraftLspClient> => {
-      const client = new ReqraftLspClient({ languageId: 'dpql', uri: PROBE_URI });
-
-      await client.connect();
-      // `didOpen` is a notification on the same socket as the request that
-      // follows it, so the server has the session by the time the parse
-      // arrives — no readiness poll needed.
-      client.didOpen('');
-      this.client = client;
-
-      return client;
-    })().catch((error) => {
-      // Allow a later probe to retry a connection that failed once.
-      this.opened = null;
-      throw error;
-    });
-
-    return this.opened;
-  }
-
-  private remember(text: string, result: IDpqlProbeResult): void {
-    if (this.cache.size >= MAX_CACHE_ENTRIES) {
-      const oldest = this.cache.keys().next();
-
-      if (!oldest.done) {
-        this.cache.delete(oldest.value);
-      }
-    }
-
-    this.cache.set(text, result);
-  }
-
-  private close(): void {
-    const client = this.client;
-
-    this.client = null;
-    this.opened = null;
-    this.cache.clear();
-
-    try {
-      client?.disconnect();
-    } catch {
-      // best-effort teardown
-    }
-  }
-}
-
-/**
- * The process-wide probe. Exported for tests, which reset it between cases;
- * application code goes through `useDpqlProbe`.
- */
-export const dpqlProbe = new DpqlProbe();

package/src/components/dpqlEditor/dpqlTags.ts

@@ -1,114 +0,0 @@
-// Copyright 2026 Qore Technologies, s.r.o.
-// DPQL tag rendering — colors per template prefix, field-meta tooltips,
-// `getTagProps` callback for ReqoreRichTextEditor.
-
-import { IReqoreTagProps } from '@qoretechnologies/reqore/dist/components/Tag';
-import { IReqoreFormTemplates } from '@qoretechnologies/reqore/dist/components/Textarea';
-import { describeTemplateReference, templateTooltip } from '../../helpers/templates';
-import { ISlateElement } from '../smartEditor/types';
-import { IDpqlFieldMeta } from './useDpqlSession';
-
-/** Color scheme for tag rendering, keyed by template prefix. */
-export const TEMPLATE_COLORS: Record<
-  string,
-  { bg: string; border: string; fg: string }
-> = {
-  data:        { bg: 'rgba(56, 132, 244, 0.22)', border: 'rgba(56, 132, 244, 0.55)', fg: '#7bb8ff' },
-  local:       { bg: 'rgba(156, 86, 214, 0.22)', border: 'rgba(156, 86, 214, 0.55)', fg: '#c9a0f0' },
-  timestamp:   { bg: 'rgba(72, 199, 142, 0.22)', border: 'rgba(72, 199, 142, 0.55)', fg: '#7ee6b8' },
-  config:      { bg: 'rgba(230, 162, 60, 0.22)', border: 'rgba(230, 162, 60, 0.55)', fg: '#f0c878' },
-  autovar:     { bg: 'rgba(214, 86, 156, 0.22)', border: 'rgba(214, 86, 156, 0.55)', fg: '#e8a0d0' },
-  globalvar:   { bg: 'rgba(214, 86, 156, 0.22)', border: 'rgba(214, 86, 156, 0.55)', fg: '#e8a0d0' },
-  localvar:    { bg: 'rgba(214, 86, 156, 0.22)', border: 'rgba(214, 86, 156, 0.55)', fg: '#e8a0d0' },
-  dynamic:     { bg: 'rgba(230, 162, 60, 0.22)', border: 'rgba(230, 162, 60, 0.55)', fg: '#f0c878' },
-  static:      { bg: 'rgba(230, 162, 60, 0.22)', border: 'rgba(230, 162, 60, 0.55)', fg: '#f0c878' },
-  temp:        { bg: 'rgba(230, 162, 60, 0.22)', border: 'rgba(230, 162, 60, 0.55)', fg: '#f0c878' },
-  step:        { bg: 'rgba(230, 162, 60, 0.22)', border: 'rgba(230, 162, 60, 0.55)', fg: '#f0c878' },
-  foreach:     { bg: 'rgba(72, 199, 142, 0.22)', border: 'rgba(72, 199, 142, 0.55)', fg: '#7ee6b8' },
-  for:         { bg: 'rgba(72, 199, 142, 0.22)', border: 'rgba(72, 199, 142, 0.55)', fg: '#7ee6b8' },
-};
-
-export const DEFAULT_TEMPLATE_COLOR = {
-  bg: 'rgba(150, 150, 150, 0.22)',
-  border: 'rgba(150, 150, 150, 0.55)',
-  fg: '#c8c8c8',
-};
-
-export const FIELD_REF_COLOR = {
-  bg: 'rgba(86, 182, 214, 0.22)',
-  border: 'rgba(86, 182, 214, 0.55)',
-  fg: '#7dd4f0',
-};
-
-export const getTemplatePrefixColor = (value: string): string => {
-  const colonIdx = value.indexOf(':');
-  const prefix = colonIdx > 1 ? value.slice(1, colonIdx).toLowerCase() : '';
-  return (TEMPLATE_COLORS[prefix] || DEFAULT_TEMPLATE_COLOR).fg;
-};
-
-export interface IDpqlTagRendererOptions {
-  /**
-   * Color template (`$…`) tags with the `info` intent instead of the per-prefix
-   * palette. For read-only render surfaces (the Explain panel) that mirror
-   * qorus-ide, where template tags are uniformly `info`. The server's
-   * `renderExpression` carries no built-in / event-trigger metadata (verified
-   * against the live LSP), so `info` is the whole scheme here — there's nothing
-   * to promote to qorus purple / success. The editable editor omits this and
-   * keeps the per-prefix palette for telling prefixes apart at a glance.
-   */
-  templateTagsUseIntent?: boolean;
-  /**
-   * The template catalogue the surface offers. A reference found in it reads
-   * as the name it was chosen by — `trim(Choices[0].message.content)` rather
-   * than the `$data:{…}` path — with the entry's description as its hover; one
-   * that is not found keeps its path.
-   */
-  templates?: IReqoreFormTemplates;
-}
-
-/**
- * Build the `tagRenderer` callback for DpqlEditor. Closes over the live
- * `fieldMeta` map so `@field` tooltips reflect the latest schema returned
- * by `dpql/setContext`.
- */
-export function makeDpqlTagRenderer(
-  fieldMeta: Record<string, IDpqlFieldMeta>,
-  options: IDpqlTagRendererOptions = {}
-) {
-  return (tag: ISlateElement): IReqoreTagProps => {
-    const tagValue = tag.value?.toString();
-    if (!tagValue) return {};
-
-    if (tagValue.startsWith('@')) {
-      const fieldName = tagValue.slice(1);
-      const meta = fieldMeta[fieldName];
-      const tooltip = meta
-        ? `${meta.display_name || fieldName}${
-            meta.type?.name ? ` (${meta.type.name})` : ''
-          }${meta.short_desc ? `\n${meta.short_desc}` : ''}`
-        : undefined;
-
-      return {
-        icon: 'Database2Line',
-        color: FIELD_REF_COLOR.fg as `#${string}`,
-        tooltip,
-        label: meta?.display_name || fieldName,
-      };
-    }
-
-    if (tagValue.startsWith('$')) {
-      const named = options.templates && describeTemplateReference(options.templates, tagValue);
-      return {
-        icon: 'ExchangeDollarLine',
-        ...(named?.item ?
-          { label: named.label, tooltip: templateTooltip(options.templates, tagValue) }
-        : {}),
-        ...(options.templateTagsUseIntent
-          ? { intent: 'info' as const }
-          : { color: getTemplatePrefixColor(tagValue) as `#${string}` }),
-      };
-    }
-
-    return {};
-  };
-}

package/src/components/dpqlEditor/index.ts

@@ -1,41 +0,0 @@
-// Copyright 2026 Qore Technologies, s.r.o.
-// Public surface of the DpqlEditor component.
-
-export { DpqlEditor } from './DpqlEditor';
-export type {
-  IDpqlEditorProps,
-  IDpqlEditorRef,
-  IDpqlParseResult,
-  ISlateElement,
-  ISlateText,
-  TSlateNode,
-  TDpqlFields,
-} from './types';
-export { dpqlProbe } from './dpqlProbe';
-export type { IDpqlProbeResult } from './dpqlProbe';
-export { useDpqlProbe } from './useDpqlProbe';
-export type { TDpqlProbeFn } from './useDpqlProbe';
-export { useDpqlSession } from './useDpqlSession';
-export type {
-  IDpqlFieldMeta,
-  IUseDpqlSessionOptions,
-  IUseDpqlSessionResult,
-} from './useDpqlSession';
-// `useDpqlSyntaxHighlighting` removed in 0.10.0 — syntax highlighting
-// is now LSP-driven via `useLspSemanticTokens` inside SmartEditor.
-// See design/SMART_EDITOR_UX.md §7.
-export {
-  dpqlSlateConverter,
-  getTagLabel,
-  isTagCompletion,
-  plainTextToSlate,
-  slateSelectionToOffset,
-  slateToPlainText,
-} from './dpqlHelpers';
-export {
-  DEFAULT_TEMPLATE_COLOR,
-  FIELD_REF_COLOR,
-  TEMPLATE_COLORS,
-  makeDpqlTagRenderer,
-} from './dpqlTags';
-export { dpqlCompletionInserter } from './dpqlInserter';

package/src/components/dpqlEditor/types.ts

@@ -1,203 +0,0 @@
-// Copyright 2026 Qore Technologies, s.r.o.
-// Type definitions for the DpqlEditor component. Slate node types
-// (`ISlateElement`, `ISlateText`, `TSlateNode`) live in the smartEditor
-// primitive's `types.ts` — re-export them here for backward compat.
-import { IReqoreFormTemplates } from '@qoretechnologies/reqore/dist/components/Textarea';
-
-export type {
-  ISlateElement,
-  ISlateText,
-  TSlateNode,
-} from '../smartEditor/types';
-
-/** Result of a `dpql/parse` request — DPQL-specific custom LSP method. */
-export interface IDpqlParseResult {
-  success: boolean;
-  expression: Record<string, any> | null;
-  /** The type the server inferred for the expression's result. */
-  inferred_type?: string;
-  /** Echo of the `target_type` the request asked about, when one was sent. */
-  target_type?: string;
-  /** `true` when the inferred type already satisfies the target. */
-  type_compatible?: boolean;
-  /** `true` when a conversion to the target exists at all. */
-  auto_coercible?: boolean;
-  /**
-   * `true` when that conversion is only ATTEMPTED, not guaranteed — text used
-   * as a number, whose outcome depends on what the text turns out to hold.
-   * A total conversion (a number used as text) reports `false`, and the server
-   * emits no diagnostic for it: warning about something that cannot fail
-   * teaches authors to ignore the warnings that can.
-   */
-  coercion_may_fail?: boolean;
-  /** The conversion that would make the expression fit, when one would. */
-  suggested_fix?: { text: string; description?: string };
-  diagnostics: Array<{
-    range: {
-      start: { line: number; character: number };
-      end: { line: number; character: number };
-    };
-    message: string;
-    severity?: number;
-    code?: string | number;
-    source?: string;
-  }>;
-}
-
-/** A record's fields for `dpql/setContext`: each field's type (or types) and an optional description. */
-export type TDpqlFields = Record<string, { type: string | string[]; desc?: string }>;
-
-export interface IDpqlEditorProps {
-  /** Current value as plain DPQL text. */
-  value: string;
-  /** Called with plain DPQL text whenever the editor content changes. */
-  onChange: (value: string) => void;
-  /**
-   * Data provider path for context-aware completions. Resolves to the
-   * `provider` field on `dpql/setContext`. Supports the four forms
-   * documented server-side: `@<app>/<action>`, `datasource:name`,
-   * `connection:name`, or a factory string.
-   */
-  provider?: string;
-  /** Record type: `'record'` (default), `'create'`, or `'update'`. */
-  recordType?: string;
-  /** Additional `dpql/setContext` options (forwarded as `options`). */
-  options?: Record<string, any>;
-  /**
-   * The record's fields, for a record no data provider has (a sheet contract's columns and added fields):
-   * each field's type - a Qore type name, or a list of them for a field that may hold any of them - and an
-   * optional description. Sent as `fields` on `dpql/setContext` and at `didOpen`; completion, validation and
-   * hover then offer them. With a provider too, the provider's fields are replaced.
-   */
-  fields?: TDpqlFields;
-  /**
-   * FSM action code, surfaced to the server as `action_code` in `didOpen`
-   * metadata. Used to derive search-context semantics for the editor
-   * (e.g. DPAT_FIND / DPAT_UPDATE / DPAT_DELETE).
-   */
-  actionCode?: number;
-  /**
-   * Optional **minimum** height of the editable area (CSS value). The
-   * editor auto-grows with its content; this is just a floor. Omit for a
-   * single-line field that grows as you type (right for match-expression
-   * fields); pass e.g. `'200px'` for a taller multi-line code editor.
-   */
-  height?: string;
-  /** Read-only mode. */
-  readOnly?: boolean;
-  /**
-   * Whether to render diagnostic underlines. Default `true`. Set `false`
-   * for display-only surfaces whose text is not valid DPQL — e.g. the
-   * expression "Explain" panel (server rendering shown through the editor
-   * for template chips + LSP token colours). See `ISmartEditorProps`.
-   */
-  showDiagnostics?: boolean;
-  /** Whether to show hover popovers (`textDocument/hover`). Default `true`. */
-  enableHover?: boolean;
-  /**
-   * Color template (`$…`) tags with the `info` intent instead of the per-prefix
-   * palette — for read-only render surfaces (the Explain panel) that mirror
-   * qorus-ide's uniform `info` template styling. Default `false` (per-prefix
-   * palette, the editor's at-a-glance prefix coloring).
-   */
-  templateTagsUseIntent?: boolean;
-  /**
-   * The overlay shown while the language server connects. Forwarded to
-   * `SmartEditor`; pass `null` to show the text without one — a read-only
-   * rendering already has its text, and only its colours wait for the server.
-   */
-  loadingIndicator?: React.ReactNode;
-  /**
-   * The template catalogue the surface offers: a `$…` reference found in it
-   * is labelled by its catalogue name. See `IDpqlTagRendererOptions.templates`.
-   */
-  templates?: IReqoreFormTemplates;
-  /** Called when the editor loses focus. */
-  onBlur?: () => void;
-  /**
-   * Opt-in to server-driven plain-text → Slate parsing via the LSP's
-   * `dpql/toRichtext` custom method. When `true`, the editor calls
-   * `dpql/toRichtext({ text: value })` on mount and on every external
-   * `value` change, and uses the server's structured response as the
-   * Slate document. Falls back to the client-side regex parser if the
-   * server request fails, times out, or returns a shape we don't
-   * recognise. While the request is in flight, the editor shows the
-   * "Connecting…" overlay (see `SmartEditor.loadingIndicator`).
-   *
-   * Trade-off: the server understands nested expressions, function
-   * calls with templates inside, and quoted edge cases better than
-   * the client regex — but the server's current `toRichtext` only
-   * recognises `$template:value` patterns, NOT `@field` references.
-   * For DPQL where field refs dominate, the client-side parser is
-   * usually richer. Treat this as an escape hatch for documents that
-   * tickle the client regex's known limitations.
-   *
-   * Default `false`.
-   */
-  useServerParse?: boolean;
-
-  /**
-   * Bind the document's field set to the canonical alert-payload
-   * schema (`severity`, `alert_type`, `alert_code`, `alert_class`,
-   * `interface_type`, `interface_name`, `alert_object`, …). Required
-   * for the Alert Rule / Silence editor to produce correct
-   * completions and diagnostics on `@payload.field` references.
-   *
-   * Server contract: `dpql/setAlertPayloadContext`. The server treats
-   * alert-payload and provider/recordType bindings as **mutually
-   * exclusive** — when this is `true`, the `provider` /
-   * `recordType` / `options` / `actionCode` props are silently
-   * ignored. Toggling this prop back to `false` re-binds the
-   * provider context if one is configured (via `dpql/setContext`).
-   *
-   * Default `false`.
-   */
-  alertPayloadContext?: boolean;
-
-  /**
-   * FSM context for state-aware template completions. When set,
-   * `$data:` / `$fsminput:` template namespaces resolve against the
-   * FSM's state graph; pass `currentState` to narrow `$data:` to a
-   * specific state's payload.
-   *
-   * Exactly one of `fsm` / `draftId` / `fsmId` must be provided.
-   * Pass `undefined` (or omit the prop) to clear any existing FSM
-   * binding for this session.
-   *
-   * Server contract: `dpql/setFsmContext`. Independent of and
-   * composable with `provider`/`recordType` (provider yields field
-   * completions; FSM yields template completions).
-   */
-  fsmContext?: TDpqlFsmContext;
-}
-
-/**
- * FSM context source — exactly one of `fsm` / `draftId` / `fsmId`.
- * The optional `currentState` narrows state-data completions to that
- * state when present.
- */
-export type TDpqlFsmContext =
-  | { fsm: Record<string, any>; currentState?: string; draftId?: never; fsmId?: never }
-  | { draftId: string; currentState?: string; fsm?: never; fsmId?: never }
-  | { fsmId: number; currentState?: string; fsm?: never; draftId?: never };
-
-/** Imperative methods exposed via the `DpqlEditor` ref. */
-export interface IDpqlEditorRef {
-  /** Format the document via `textDocument/formatting`. */
-  format: () => Promise<void>;
-  /**
-   * Validate the document via `dpql/validate`. Returns `{valid: true}`
-   * when the document has no diagnostics, otherwise an array of errors.
-   */
-  validate: () => Promise<{ valid: boolean; errors?: Array<{ message: string }> }>;
-  /**
-   * Parse DPQL text into an expression AST via `dpql/parse`.
-   *
-   * `targetType` asks the server, in the same round trip, whether the
-   * expression's result can satisfy that type — see `coercion_may_fail` on
-   * the result. Omit it to ask only whether the text parses.
-   */
-  parse: (text: string, targetType?: string) => Promise<IDpqlParseResult>;
-  /** Serialize an expression AST back to DPQL text via `dpql/serialize`. */
-  serialize: (expression: Record<string, any>) => Promise<string>;
-}

package/src/components/dpqlEditor/useDpqlProbe.ts

@@ -1,33 +0,0 @@
-// Copyright 2026 Qore Technologies, s.r.o.
-// React access to the shared DPQL detection probe (`dpqlProbe`). The hook
-// itself opens nothing: a field becomes a consumer of the shared document
-// only once it actually asks a question, and stops being one when it
-// unmounts. A form full of fields that never see expression-shaped text
-// therefore never opens the document at all.
-import { useCallback, useEffect, useRef } from 'react';
-import { dpqlProbe, IDpqlProbeResult } from './dpqlProbe';
-
-export type TDpqlProbeFn = (text: string) => Promise<IDpqlProbeResult>;
-
-export const useDpqlProbe = (): TDpqlProbeFn => {
-  const acquired = useRef(false);
-
-  useEffect(
-    () => () => {
-      if (acquired.current) {
-        acquired.current = false;
-        dpqlProbe.release();
-      }
-    },
-    []
-  );
-
-  return useCallback((text: string): Promise<IDpqlProbeResult> => {
-    if (!acquired.current) {
-      acquired.current = true;
-      dpqlProbe.acquire();
-    }
-
-    return dpqlProbe.parse(text);
-  }, []);
-};