@qoretechnologies/reqraft 0.10.54 → 0.10.55-pr.115.g37abdfc

package/src/components/form/engine/rowMenuContext.ts

@@ -0,0 +1,159 @@
+// Copyright 2026 Qore Technologies, s.r.o.
+import { IReqoreDropdownItem } from '@qoretechnologies/reqore/dist/components/Dropdown/list';
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+
+/**
+ * SEAM (reqraft): an editor publishes its own actions into the row's ⋮ menu.
+ *
+ * A row already renders one overflow menu — Edit fullscreen, Remove field, and
+ * any `optionActions` the host injected — and the comment on it has always said
+ * why: *"this row already has a menu, so they reuse it rather than adding a
+ * second one beside it."* An EDITOR could not reach that menu, so an editor
+ * with affordances of its own had no choice but to draw a second ⋮ inside the
+ * value cell. The IDE's template field does exactly that, and the two menus
+ * ended up side by side on one control, at slightly different widths.
+ *
+ * `optionActions` does not solve it: that seam is host configuration, resolved
+ * from the option's name and schema before the editor exists, so it cannot know
+ * what the editor can offer *now* — whether its templates have loaded, whether
+ * the value is already an expression, which custom items the field was given.
+ *
+ * ## Why registration is keyed, and by whom
+ *
+ * Menu items carry `onClick` handlers, so they are a new array on every render
+ * and cannot be compared by value. An editor therefore publishes a `key`
+ * alongside them: a primitive describing WHICH items it is currently offering
+ * (`'expression,template'`). The row re-renders only when a publisher's key
+ * changes, so a re-rendering editor cannot drive the row into a state loop.
+ *
+ * Each registration also belongs to ONE publisher. A single shared slot let
+ * two publishers in the same row — an expression builder's operands — overwrite
+ * each other's key on every render, which re-rendered the row and both of them,
+ * which published again: a synchronous render loop that froze the page. And a
+ * slot that outlived its editor kept that editor's handlers after it unmounted,
+ * so a row closed and reopened offered items that did nothing. Registrations
+ * are therefore per publisher, withdrawn on unmount, and a click always reaches
+ * the handler from the publisher's latest render.
+ *
+ * Publish with `useRowMenuPublisher`; provide with `useRowMenuRegistry`.
+ */
+export interface IRowMenuRegistration {
+  /**
+   * Publish a publisher's menu items into the containing row's ⋮.
+   *
+   * @param publisherId identifies the publishing editor (one per mounted editor)
+   * @param key a primitive describing which items are being offered; the row
+   * re-renders only when it changes
+   * @param items the items to merge, or an empty array to contribute none
+   */
+  registerRowMenuItems: (publisherId: string, key: string, items: IReqoreDropdownItem[]) => void;
+  /** Withdraw a publisher's items — when it unmounts or leaves the row. */
+  unregisterRowMenuItems: (publisherId: string) => void;
+}
+
+/**
+ * Absent outside a compact row — the classic (non-compact) render path has no
+ * row menu to merge into, and an editor there keeps drawing its own control.
+ */
+export const RowMenuContext = createContext<IRowMenuRegistration | undefined>(undefined);
+
+/**
+ * The row-menu channel for the row this editor is inside, or `undefined` when
+ * there is no row menu to publish into.
+ *
+ * An editor that finds it should render no menu of its own; one that does not
+ * must keep rendering its own, or its actions become unreachable.
+ */
+export const useRowMenu = (): IRowMenuRegistration | undefined => useContext(RowMenuContext);
+
+/**
+ * Publish `items` into `rowMenu` for as long as the calling editor is mounted.
+ * `rowMenu` is passed rather than read here so an editor can claim the channel
+ * and hide it from what it renders (see `TemplateField`).
+ */
+export const useRowMenuPublisher = (
+  rowMenu: IRowMenuRegistration | undefined,
+  key: string,
+  items: IReqoreDropdownItem[]
+): void => {
+  const publisherId = useId();
+
+  useEffect(() => {
+    rowMenu?.registerRowMenuItems(publisherId, key, items);
+  }, [rowMenu, publisherId, key, items]);
+
+  useEffect(() => () => rowMenu?.unregisterRowMenuItems(publisherId), [rowMenu, publisherId]);
+};
+
+/**
+ * The row side of the channel: the registration to provide, and the items the
+ * row's ⋮ should list.
+ */
+export const useRowMenuRegistry = (): {
+  rowMenu: IRowMenuRegistration;
+  items: IReqoreDropdownItem[];
+} => {
+  // Which publishers are offering which item SET — the only state, so only a
+  // change of set re-renders the row.
+  const [keys, setKeys] = useState<Record<string, string>>({});
+  // Each publisher's items from its latest render, read at click time.
+  const latest = useRef<Record<string, IReqoreDropdownItem[]>>({});
+
+  const registerRowMenuItems = useCallback(
+    (publisherId: string, key: string, items: IReqoreDropdownItem[]) => {
+      latest.current[publisherId] = items;
+      setKeys((previous) =>
+        previous[publisherId] === key ? previous : { ...previous, [publisherId]: key }
+      );
+    },
+    []
+  );
+
+  const unregisterRowMenuItems = useCallback((publisherId: string) => {
+    delete latest.current[publisherId];
+    setKeys((previous) => {
+      if (!(publisherId in previous)) {
+        return previous;
+      }
+      const next = { ...previous };
+      delete next[publisherId];
+      return next;
+    });
+  }, []);
+
+  const rowMenu = useMemo(
+    () => ({ registerRowMenuItems, unregisterRowMenuItems }),
+    [registerRowMenuItems, unregisterRowMenuItems]
+  );
+
+  const items = useMemo(
+    () =>
+      Object.keys(keys).flatMap((publisherId) =>
+        (latest.current[publisherId] ?? []).map((item, index) =>
+          item.onClick
+            ? {
+                ...item,
+                // Same key, same item set, so the index still names this item;
+                // the handler is whatever the publisher rendered last.
+                onClick: ((...args: unknown[]) =>
+                  (latest.current[publisherId]?.[index]?.onClick as
+                    | ((...clickArgs: unknown[]) => unknown)
+                    | undefined)?.(...args)) as IReqoreDropdownItem['onClick'],
+              }
+            : item
+        )
+      ),
+    [keys]
+  );
+
+  return { rowMenu, items };
+};

package/src/components/form/engine/rowOpenPicker.ts

@@ -0,0 +1,27 @@
+import { createContext } from 'react';
+
+/**
+ * "The row you are in has just been opened, and the control you are is the one
+ * it offers — so show the choices."
+ *
+ * A compact row is read-first: collapsed, it prints the value; clicked, it
+ * mounts the editor. For a PICKER the editor is a closed trigger printing the
+ * same value the read row had just printed, so the row opened and nothing on
+ * screen changed — the author had to click a second time to reach the list.
+ * Read-first is the collapsed row's job; it must not be the answer twice.
+ *
+ * The row decides, because only the row knows both things that matter: that the
+ * AUTHOR opened it (a row the form opens to show a value must not throw a list
+ * over it) and WHICH control it offers (`findRowFocusTarget` — the same scan
+ * that hands over the caret). The control obeys, because only the control knows
+ * how it opens.
+ *
+ * A one-shot pulse rather than a standing flag: it is `true` for exactly the
+ * commit in which the editor acts on it, and false again afterwards, so an
+ * editor that remounts later — a picker whose catalogue reloaded, after the
+ * author had closed it — does not reopen itself off a stale instruction.
+ *
+ * Exported so a host's own editor can obey it too: read it with
+ * `useContext(RowOpenPickerContext)` and open on the rising edge.
+ */
+export const RowOpenPickerContext = createContext<boolean>(false);

package/src/components/form/engine/typeChoices.ts

@@ -0,0 +1,63 @@
+// Copyright 2026 Qore Technologies, s.r.o.
+/**
+ * Which options offer the per-type choices ("Integer", "Text", "Hash", …) in
+ * the row's menu.
+ *
+ * A field that pins no concrete type has to give the author some way to say
+ * what kind of value they mean, and the row menu is where that lives — the
+ * alternative, a standalone *"Please select data type"* control, replaces a
+ * typable field with a pick-only one.
+ *
+ * The rule was `ui_type === 'any'`, which is one of the three ways a schema
+ * says "untyped", so the choices went missing on the other two:
+ *
+ *  - **`type: 'auto'` with no `ui_type` at all.** This is how the server
+ *    declares an assertion's Expected Value, so that field never offered them.
+ *    They appeared only inside an expression, where the OPERAND's schema does
+ *    say `ui_type: 'any'` — so the same option offered them in the Visual view
+ *    and not in the Text view, which reads as the menu losing items.
+ *  - **A host's own untyped editor.** The IDE renders Expected Value through
+ *    `test-reference`, a `ui_type` reqraft knows nothing about; the field is no
+ *    less untyped for having a custom editor.
+ *
+ * `ui_type` is asked FIRST and on its own: a schema that names a concrete
+ * editor (`ui_type: 'string'`) has pinned the field even if its storage `type`
+ * is still `auto`.
+ */
+import type { TQorusFormFieldSchema } from '@qoretechnologies/ts-toolkit';
+import { firstDeclaredType, UNTYPED_OPTION_TYPES } from '../../../helpers/optionUiTypes';
+
+/**
+ * The spellings that mean "no concrete type" wherever they appear.
+ *
+ * Re-exported from the type vocabulary in `helpers/optionUiTypes`, which is
+ * where it now lives so non-component code can ask the same question.
+ */
+export const BuiltInAnyLikeTypes: readonly string[] = UNTYPED_OPTION_TYPES;
+
+/**
+ * Does this option leave its type up to the author?
+ *
+ * @param option the option's schema entry
+ * @param extraUiTypes host `ui_type` names that are untyped editors of their
+ * own — see `FormEngine`'s `anyLikeUiTypes`
+ */
+export const offersTypeChoices = (
+  option: TQorusFormFieldSchema | undefined,
+  extraUiTypes?: string[]
+): boolean => {
+  if (!option) {
+    return false;
+  }
+
+  const uiType: string | undefined = option.ui_type;
+
+  if (uiType) {
+    return BuiltInAnyLikeTypes.includes(uiType) || !!extraUiTypes?.includes(uiType);
+  }
+
+  // No `ui_type`: the storage type is the only thing that can pin the field,
+  // read as the field is rendered (`firstDeclaredType`).
+  const type = firstDeclaredType(option.type);
+  return type !== undefined && BuiltInAnyLikeTypes.includes(type);
+};

package/src/components/form/expressions/DpqlRendering.tsx

@@ -0,0 +1,85 @@
+// Copyright 2026 Qore Technologies, s.r.o.
+// How a DPQL expression is shown when it is shown but not edited.
+//
+// ONE rendering for every read-only place an expression appears — the Explain
+// panel, the Text view's Preview, the conversion a type-fit message suggests,
+// a collapsed expression row — so they read the same everywhere: monospace,
+// coloured by the language server's semantic tokens (the canonical tokenizer,
+// see `useLspSemanticTokens`), template references as chips. Before, the same
+// expression could be highlighted in one place, plain proportional text in the
+// next and a bare `<code>` in a third, depending only on which component
+// happened to draw it.
+import { ReqoreMessage } from '@qoretechnologies/reqore';
+import { IReqoreFormTemplates } from '@qoretechnologies/reqore/dist/components/Textarea';
+import { useAsync } from 'react-use';
+import { DpqlEditor } from '../../dpqlEditor';
+import { FormFieldsSkeleton } from '../engine/FormFieldsSkeleton';
+import { IExpressionValue } from './types';
+import { useRenderExpression } from './useRenderExpression';
+
+const noop = (): void => undefined;
+
+export interface IDpqlRenderingProps {
+  /** DPQL, or a readable rendering of it, to show. */
+  text: string;
+  /** The surface's template catalogue: a reference in it reads as its name. */
+  templates?: IReqoreFormTemplates;
+  'data-testid'?: string;
+}
+
+/** Shows `text` as DPQL: monospace, server-coloured, references as chips. */
+export const DpqlRendering = ({ text, templates, 'data-testid': testId }: IDpqlRenderingProps) => (
+  <div className='dpql-rendering' data-testid={testId} style={{ width: '100%', minWidth: 0 }}>
+    <DpqlEditor
+      value={text}
+      onChange={noop}
+      readOnly
+      // The text is a rendering, not something being written: nothing to
+      // diagnose, and a hover would describe tokens of a document nobody edits.
+      showDiagnostics={false}
+      enableHover={false}
+      templateTagsUseIntent
+      templates={templates}
+      // The text is already known; only its colours wait for the server, so
+      // nothing is hidden behind "Connecting to language server…".
+      loadingIndicator={null}
+    />
+  </div>
+);
+
+export interface IExpressionRenderingProps {
+  /** The expression AST to render. */
+  expression: IExpressionValue;
+  /** The surface's template catalogue: a reference in it reads as its name. */
+  templates?: IReqoreFormTemplates;
+  'data-testid'?: string;
+}
+
+/**
+ * The server's readable rendering of `expression`, shown through
+ * `DpqlRendering`. It waits for the server — in the form's one waiting shape —
+ * and says so plainly if the server cannot render, rather than showing an
+ * approximation that reads like the real thing.
+ */
+export const ExpressionRendering = ({
+  expression,
+  templates,
+  'data-testid': testId,
+}: IExpressionRenderingProps) => {
+  const { renderRich } = useRenderExpression();
+  const rendering = useAsync(() => renderRich(expression), [JSON.stringify(expression)]);
+
+  if (rendering.loading) {
+    return <FormFieldsSkeleton rows={1} reason='expression-rendering' />;
+  }
+
+  if (!rendering.value) {
+    return (
+      <ReqoreMessage size='small' intent='muted' flat opaque={false} data-testid={testId}>
+        This expression could not be rendered.
+      </ReqoreMessage>
+    );
+  }
+
+  return <DpqlRendering text={rendering.value.text} templates={templates} data-testid={testId} />;
+};