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

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

@@ -1,107 +0,0 @@
-import { IReqoreFormTemplates } from '@qoretechnologies/reqore/dist/components/Textarea';
-import { firstDeclaredType } from '../../../helpers/optionUiTypes';
-
-/**
- * A field schema that carries a template list of its own.
- *
- * `templates` is deliberately NOT added to `TQorusFormFieldSchema`: that type is
- * owned by ts-toolkit and shared with consumers that have no notion of a form
- * engine, so the capability is read through this narrow view instead of widening
- * the shared type from here. A schema that sets it is offering a list scoped to
- * one field rather than to the whole form.
- */
-export type TFieldWithOwnTemplates = {
-  templates?: IReqoreFormTemplates;
-  /**
-   * The token grammar this field's value is WRITTEN in.
-   *
-   * A host may spell a reference in a grammar that is not reqraft's — a Qorus
-   * test writes `$._case.mode`, which has no `$key:` in it at all — and a field
-   * that speaks one says so here, exactly as it hands down its own `templates`.
-   * Declaring it on the schema is what lets every surface that draws the value
-   * agree about it, instead of printing the raw token the author never typed.
-   *
-   * Both directions read it: the read-only renderings
-   * (`templateTextSegments`) and the rich-text editor a row opens
-   * (`templateTextToNodes`, through `RichTextFormField`'s `templateToken`
-   * prop). They resolve references with the same code, so a row and the editor
-   * it opens cannot disagree about what one is.
-   *
-   * A `RegExp` or its source: a schema that crossed a serialization boundary
-   * carries the string.
-   */
-  templateToken?: RegExp | string;
-};
-
-/**
- * A schema entry carries two type-ish keys with different jobs:
- *
- * - `type` names how the value is STORED and validated (`string`, `hash`, `list`…).
- * - `ui_type` names which EDITOR renders it.
- *
- * For most fields `ui_type` is a storage-compatible refinement (`long-string`,
- * `enum`, `url`) and it is safe to let it win for both jobs. But some `ui_type`s
- * name a bespoke editor whose value is still stored as the plainer `type` — a
- * `cron` editor stores a string, `processor-mappings` stores a hash. Writing
- * those renderer names into the field's `type` breaks validation and round-trips
- * the value through the wrong branch, which is what `RENDERER_ONLY_UI_TYPES`
- * exists to prevent.
- *
- * There is deliberately no derivation here: a renderer-only `ui_type` is not
- * distinguishable from a storage-compatible one by inspecting the value or the
- * `TQorusType` union (`code-editor` and `tool-catalog` are members of it, and
- * the validator has cases for `cron` and `schema-definition`). It is a fact
- * about which editor a name selects, so it has to be declared.
- *
- * `markdown` is the case that makes the rule concrete: the server describes a
- * description field as `type: 'string'` with a `markdown` flag, and a string is
- * exactly what it stores -- but the editor is the split editor/preview one, and
- * the read-first row renders the document rather than printing its source.
- * Without the declaration `getValueType` keeps preferring the stored `string`
- * and neither ever fires.
- */
-export const BUILT_IN_RENDERER_ONLY_UI_TYPES: readonly string[] = [
-  'active-windows',
-  'alert-threshold',
-  'code-editor',
-  'cron',
-  'dpql',
-  'markdown',
-  'processor-mappings',
-  'schema-definition',
-  'test-cases',
-  'test-value-contract',
-  'tool-catalog',
-];
-
-/**
- * A `ui_type` as the predicate takes it: any name, not only a `TQorusType`.
- * The names it exists to recognise are open-ended — `cron` is not a
- * `TQorusType`, and neither is an editor a consumer declares — so typing the
- * argument as the shared union made the predicate uncallable for exactly the
- * values it is for.
- */
-export type TRendererTypeName = string | readonly string[];
-
-/**
- * Build the renderer-only predicate for one FormEngine instance.
- *
- * Consumers inject their own editors through `componentOverrides`, so the set of
- * renderer-only names is open-ended — the IDE ships editors reqraft has never
- * heard of. `extraTypes` (the `rendererOnlyUiTypes` prop) lets a consumer declare
- * its own without waiting on a reqraft release, which is what previously made
- * every new IDE editor a silent value-corruption bug until this list caught up.
- */
-export const createRendererOnlyUiTypeCheck = (
-  extraTypes?: readonly string[]
-): ((type?: TRendererTypeName) => boolean) => {
-  const known = new Set<string>([...BUILT_IN_RENDERER_ONLY_UI_TYPES, ...(extraTypes ?? [])]);
-
-  return (type?: TRendererTypeName): boolean => {
-    const declared = firstDeclaredType(type);
-    return declared !== undefined && known.has(declared);
-  };
-};
-
-/** The default predicate — built-ins only, for module-scope callers with no props. */
-export const isRendererOnlyUiType = createRendererOnlyUiTypeCheck();

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

@@ -1,123 +0,0 @@
-/**
- * Bring a form row into view only when it is not already there, and never
- * under a pinned header.
- *
- * A row that moves between status boxes (filling a field moves it from "Needs
- * attention" to "Set") is followed so the reader does not lose it. That used
- * to be `scrollIntoView({ block: 'center' })`, which scrolls even when the row
- * is already in plain sight, and centres it against the whole scrollport while
- * the box header pinned at the top hides part of it. In the qorus-ide schema
- * editor the moved row landed with the "Needs attention" header (375-423)
- * drawn over it (405).
- *
- * The visible area is the scrollport minus the pinned chrome above the row:
- * the form's sticky toolbar and the sticky header of every status box the row
- * sits in. Both are read from the DOM when the reveal runs, so a host's own
- * offset, a toolbar that wraps, or a header that is not pinned at all are all
- * accounted for without the caller knowing about them.
- */
-
-/** Selectors of the elements whose header may be pinned above a row. */
-const PINNED_HEADER_OWNERS = '.options-readfirst-group, .options-readfirst-scroll > .reqore-panel';
-
-const isScrollable = (element: HTMLElement): boolean => {
-  const { overflowY } = getComputedStyle(element);
-  return (
-    (overflowY === 'auto' || overflowY === 'scroll' || overflowY === 'overlay') &&
-    element.scrollHeight > element.clientHeight
-  );
-};
-
-/** The nearest ancestor that actually scrolls; `undefined` means the viewport. */
-export const findScrollContainer = (element: HTMLElement): HTMLElement | undefined => {
-  for (let parent = element.parentElement; parent; parent = parent.parentElement) {
-    if (parent === document.body || parent === document.documentElement) {
-      return undefined;
-    }
-    if (isScrollable(parent)) {
-      return parent;
-    }
-  }
-  return undefined;
-};
-
-/**
- * How far below the top of the scrollport the pinned chrome above `element`
- * reaches: the largest `top + height` of any sticky header of an enclosing
- * status box or form toolbar. Zero when nothing above it is pinned.
- */
-export const getPinnedChromeHeight = (element: HTMLElement): number => {
-  let clearance = 0;
-  for (
-    let owner = element.parentElement?.closest<HTMLElement>(PINNED_HEADER_OWNERS);
-    owner;
-    owner = owner.parentElement?.closest<HTMLElement>(PINNED_HEADER_OWNERS)
-  ) {
-    const header = owner.querySelector<HTMLElement>(':scope > .reqore-panel-title');
-    if (!header || header.contains(element)) {
-      continue;
-    }
-    const style = getComputedStyle(header);
-    if (style.position !== 'sticky') {
-      continue;
-    }
-    const top = parseFloat(style.top) || 0;
-    clearance = Math.max(clearance, top + header.getBoundingClientRect().height);
-  }
-  return clearance;
-};
-
-/**
- * How far below the top edge of the row's scrollport the pinned chrome reaches.
- *
- * A sticky `top` is measured from the scrollport's top edge INSET BY ITS
- * PADDING, while `scrollIntoView` and `scroll-margin-top` align against the
- * edge itself. Leaving the padding out put an opened row 16px under its box
- * header inside a padded host scroller (the Storybook canvas, and any panel
- * with padding).
- */
-export const getRevealClearance = (element: HTMLElement): number => {
-  const container = findScrollContainer(element);
-  const inset = container ? parseFloat(getComputedStyle(container).paddingTop) || 0 : 0;
-  return inset + getPinnedChromeHeight(element);
-};
-
-/**
- * Whether the whole of `element` is visible below `clearance` (measured from
- * the top edge of its scrollport, see {@link getRevealClearance}).
- */
-export const isRowInView = (element: HTMLElement, clearance: number): boolean => {
-  const container = findScrollContainer(element);
-  const viewTop = container ? container.getBoundingClientRect().top + container.clientTop : 0;
-  const viewBottom =
-    container ?
-      viewTop + container.clientHeight
-    : window.innerHeight || document.documentElement.clientHeight;
-  const rect = element.getBoundingClientRect();
-  return rect.top >= viewTop + clearance && rect.bottom <= viewBottom;
-};
-
-/**
- * Scroll `element` the least distance that shows it clear of the pinned chrome
- * above it — and not at all when it is already fully in view.
- *
- * `scroll-margin-top` is what keeps a row that has to come down from above from
- * stopping under the header: `block: 'nearest'` aligns the row's margin box,
- * so the row itself stops exactly below the pinned chrome.
- *
- * Returns whether a scroll was started.
- */
-export const revealRow = (element: HTMLElement, behavior: ScrollBehavior = 'smooth'): boolean => {
-  // jsdom implements neither layout nor `scrollIntoView`; a missing reveal must
-  // never break a form.
-  if (typeof element.scrollIntoView !== 'function') {
-    return false;
-  }
-  const clearance = getRevealClearance(element);
-  if (isRowInView(element, clearance)) {
-    return false;
-  }
-  element.style.scrollMarginTop = `${clearance}px`;
-  element.scrollIntoView({ block: 'nearest', inline: 'nearest', behavior });
-  return true;
-};

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

@@ -1,101 +0,0 @@
-/**
- * Which control an open compact row hands the caret to.
- *
- * A row's editor is whatever the field's type asks for, and only some of those
- * take typed text. A pick-one renders `ReqoreCheckbox`es (a `[tabindex]`
- * element), a selector renders a `<button>`, a code field a `[contenteditable]`
- * — so a scan that looked for `input`, `textarea` and `[contenteditable]` alone
- * found nothing on most of the first questions a form asks ("which kind?",
- * "which connection?", "which interface?"). The row opened and the caret stayed
- * on whatever made it open.
- *
- * Text entry wins when the row offers it. Every editor that takes typing also
- * draws affordances around it — a template picker, a type menu, a clear button
- * — and those come first in document order often enough that "the first
- * focusable element" would answer a text field with a button beside it.
- */
-
-/** Controls the reader types into. */
-const TEXT_ENTRY_SELECTOR =
-  'input:not([type="hidden"]):not([disabled]), textarea:not([disabled]), [contenteditable="true"]';
-
-/**
- * Everything else a row can offer. `[tabindex]` is what carries reqore's own
- * controls: a checkbox is an icon element made focusable, not an `<input>`.
- */
-const OTHER_CONTROL_SELECTOR =
-  'button:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
-
-/**
- * Subtrees inside the row's value cell that are NOT this field's editor: a
- * sibling field absorbed into this row (a different field, which the engine did
- * not open) and the schema-message strip above the editor (guidance about the
- * value, never a place to put one).
- */
-const NOT_THE_FIELDS_OWN_EDITOR = '.options-readfirst-absorbed, .options-readfirst-info-panel';
-
-const belongsToTheFieldsOwnEditor = (container: HTMLElement, element: Element): boolean => {
-  const foreign = element.closest(NOT_THE_FIELDS_OWN_EDITOR);
-  // `closest` walks past the container too, so a match only disqualifies the
-  // element when it is inside THIS container.
-  return !foreign || !container.contains(foreign);
-};
-
-const firstMatch = (container: HTMLElement, selector: string): HTMLElement | undefined => {
-  const matches = Array.from(container.querySelectorAll<HTMLElement>(selector));
-  return matches.find(
-    (element) =>
-      belongsToTheFieldsOwnEditor(container, element) &&
-      // An element hidden from assistive technology is not a destination for a
-      // caret either — reqore draws decorative, focusable-looking chrome that
-      // way.
-      !element.closest('[aria-hidden="true"]')
-  );
-};
-
-/**
- * The control an open row should focus, or `undefined` when it offers none —
- * a read-only preview, or an editor that has not mounted yet (see the caller,
- * which watches for it to arrive).
- *
- * @param container the row's value cell
- */
-export const findRowFocusTarget = (
-  container: HTMLElement | null | undefined
-): HTMLElement | undefined => {
-  if (!container) {
-    return undefined;
-  }
-  return (
-    firstMatch(container, TEXT_ENTRY_SELECTOR) ?? firstMatch(container, OTHER_CONTROL_SELECTOR)
-  );
-};
-
-/**
- * Controls whose ONLY behaviour is to reveal the choices.
- *
- * A row that opens hands the caret to the control it offers, and for most
- * editors that is the end of it: a text box takes typing, a pick-one's
- * checkboxes take a click. A PICKER is different — its closed state prints the
- * value it already holds, which is the very thing the read row printed, so
- * opening the row changed nothing on screen and the author had to click a
- * second time to see the list. Read-first belongs to the collapsed row; it must
- * not be the answer twice.
- *
- * Declared with `aria-haspopup`, which is what the attribute means and is
- * already the contract with assistive technology — so a host's own editor opts
- * in by being accessible rather than by knowing about this file. `aria-expanded`
- * is respected: a picker that is already showing its list is not re-activated.
- */
-const PICKER_TRIGGER_SELECTOR =
-  '[aria-haspopup="listbox"], [aria-haspopup="dialog"], [aria-haspopup="menu"], [aria-haspopup="tree"], [aria-haspopup="grid"]';
-
-/**
- * Whether this control is a picker that is still closed — i.e. whether
- * activating it is what "open the editor" means for this row.
- */
-export const isClosedPickerTrigger = (element: HTMLElement | null | undefined): boolean =>
-  !!element &&
-  typeof element.matches === 'function' &&
-  element.matches(PICKER_TRIGGER_SELECTOR) &&
-  element.getAttribute('aria-expanded') !== 'true';

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

@@ -1,159 +0,0 @@
-// 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

@@ -1,27 +0,0 @@
-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

@@ -1,63 +0,0 @@
-// 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);
-};