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

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

@@ -1,6 +1,6 @@
 import { ReqoreP, ReqorePanel } from '@qoretechnologies/reqore';
 import { GAP_FROM_SIZE, TSizes } from '@qoretechnologies/reqore/dist/constants/sizes';
-import styled from 'styled-components';
+import styled, { css } from 'styled-components';
 
 // Styled primitives for the compact (read-first) rows and their editor cards.
 // Shared between FormEngine and the extracted CompactRow component.
@@ -64,7 +64,31 @@ export const StyledCompactPanel = styled(ReqorePanel)<{
   /** True when the toolbar renders no search row (hidden via `compactToolbar`,
    *  self-hidden on a single-option form, or no toolbar at all). */
   $tightHeader?: boolean;
+  /** True when the status boxes inside pin their headers. */
+  $stickyBoxes?: boolean;
 }>`
+  /* The wrapper must not clip, or nothing INSIDE it can pin.
+  
+     ReqorePanel sets its wrapper to \`overflow: hidden\` unless its own header
+     is sticky — and a clipping box is a scrollport, so a status box header
+     inside it resolves against the wrapper instead of the page and stops
+     pinning. That coupling is right for the panel's own header and wrong for
+     its descendants': a host that turns this form's toolbar off (a two-field
+     form inside a longer page, where a pinned search bar is the biggest thing
+     on screen and the least useful) was silently turning the box headers off
+     with it.
+  
+     The clip is the panel's rounded corners, and this panel is transparent and
+     border-less — \`flat raised minimal\`, no background of its own — so there
+     is nothing for it to clip. */
+  ${({ $stickyBoxes }) =>
+    $stickyBoxes ?
+      css`
+        &&& {
+          overflow: visible;
+        }
+      `
+    : ''}
   > .reqore-panel-title {
     /* The blur + translateZ exist only to make the STICKY top-level toolbar ghost
        content beneath it; a nested sub-form's header isn't sticky, so skip them
@@ -154,7 +178,12 @@ export const StyledGroupHeaderLine = styled.span<{ $color: string }>`
 // a barely-there accent border + a ~5%-opacity tint, NOT the loud intent border a
 // stock ReqorePanel draws. `$accent` is the box's theme colour (warning/success/
 // muted).
-export const StyledStatusBox = styled(ReqorePanel)<{ $accent: string; $bg?: string }>`
+export const StyledStatusBox = styled(ReqorePanel)<{
+  $accent: string;
+  $bg?: string;
+  /** The page's own background, for the PINNED header — see below. */
+  $surface?: string;
+}>`
   &&& {
     border: 1px solid ${({ $accent }) => `${$accent}33`};
     /* $bg lets the muted "Optional" box opt into a darker, recessed surface
@@ -162,6 +191,31 @@ export const StyledStatusBox = styled(ReqorePanel)<{ $accent: string; $bg?: stri
     background: ${({ $accent, $bg }) => $bg || `${$accent}1f`};
     border-radius: 10px;
   }
+
+  /* A PINNED header needs a surface of its own.
+  
+     The box's tint lives on the wrapper, behind the header, and a \`minimal\`
+     panel header is transparent — which is right while the header sits in the
+     flow over its own box, and wrong the moment it pins, because the rows then
+     scroll THROUGH it. Reqore's backdrop blur softens them but a 12% tint over
+     moving text still reads as two overlaid labels.
+  
+     So repaint the pinned header as the box looks at rest: an opaque layer of
+     the page background with the box's own translucent tint composited on top,
+     which is exactly what the eye sees where the box meets the page. The
+     Optional box already carries an opaque \`$bg\`, so that is used as-is.
+  
+     Only when \`$surface\` is supplied — i.e. only on a form that pins at all —
+     so an unpinned box is pixel-identical to before. */
+  ${({ $surface, $accent, $bg }) =>
+    $surface ?
+      css`
+        &&& > .reqore-panel-title {
+          background-color: ${$bg || $surface};
+          ${$bg ? '' : `background-image: linear-gradient(${$accent}1f, ${$accent}1f);`}
+        }
+      `
+    : ''}
 `;
 
 // "One of the below is required" cluster box — wraps the members of an unmet

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

@@ -35,7 +35,7 @@ export interface ICompactToolbarContext {
   // Completion meter
   invalidCount: number;
   attentionCount: number;
-  completion: { set: number; total: number; pct: number };
+  completion: { set: number; done: number; total: number; pct: number };
   // Invalid-fields banner (pinned in the sticky header)
   showInvalidOnly: boolean;
   onToggleInvalidOnly: () => void;

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

@@ -1,4 +1,8 @@
-import { IReqorePanelAction } from '@qoretechnologies/reqore/dist/components/Panel';
+import { IReqoreDropdownItem } from '@qoretechnologies/reqore/dist/components/Dropdown/list';
+import {
+  IReqorePanelAction,
+  IReqorePanelSubAction,
+} from '@qoretechnologies/reqore/dist/components/Panel';
 import { IQorusFormField, IQorusFormSchema } from '@qoretechnologies/ts-toolkit';
 
 /**
@@ -38,3 +42,87 @@ export const resolveOptionActions = (
 
   return (actions ?? []).filter((action): action is IReqorePanelAction => !!action);
 };
+
+/** How many injected actions a row shows as buttons before the rest go into its menu. */
+export const MAX_INLINE_OPTION_ACTIONS = 2;
+
+/**
+ * Which injected actions stay as buttons, and which move into the row's menu.
+ *
+ * Everything moves on touch and on narrow viewports (`collapse`) — a button
+ * that waits for a hover is unreachable without one — and anything past the
+ * inline cap moves regardless, so a consumer injecting ten actions can never
+ * push the row's value out of view. Both render paths decide it here.
+ */
+export const splitOptionActions = (
+  actions: IReqorePanelAction[],
+  collapse: boolean
+): [IReqorePanelAction[], IReqorePanelAction[]] =>
+  collapse ?
+    [[], actions]
+  : [actions.slice(0, MAX_INLINE_OPTION_ACTIONS), actions.slice(MAX_INLINE_OPTION_ACTIONS)];
+
+/**
+ * An injected action as a row in a menu.
+ *
+ * A panel action labels itself with `label`, but an icon-only one (the IDE's
+ * AI-assist button) carries its name in the tooltip — and a menu row has no
+ * hover to fall back on.
+ */
+export const optionActionAsMenuItem = (
+  action: IReqorePanelAction,
+  index: number
+): IReqoreDropdownItem => ({
+  /* A menu row's label has to be text. `tooltip` may be a tooltip OBJECT
+     (`IReqoreTooltip`), which is why this was cast before — an action with a
+     configured tooltip and no label put that object where a string belongs. */
+  label:
+    action.label ??
+    (typeof action.tooltip === 'string' ? action.tooltip : undefined) ??
+    `Action ${index + 1}`,
+  icon: action.icon,
+  intent: action.intent,
+  disabled: action.disabled,
+  className: action.className,
+  onClick: () => action.onClick?.(),
+});
+
+export interface IOptionRowActionsInput {
+  /** The consumer's actions for this option, already resolved. */
+  injected: IReqorePanelAction[];
+  /** Move every injected action into the menu (touch, narrow viewport). */
+  collapse: boolean;
+  /** The row's own secondary actions; a falsy entry is one that does not apply. */
+  menu: (IReqorePanelSubAction | false | null | undefined | 0 | '')[];
+}
+
+/**
+ * A classic form row's header actions.
+ *
+ * Injected actions stay as buttons up to the inline cap; the rest, and the
+ * row's own secondary actions, go into ONE ⋯ menu that is always drawn, so
+ * nothing the row offers is reachable only by hovering it.
+ */
+export const optionRowActions = ({
+  injected,
+  collapse,
+  menu,
+}: IOptionRowActionsInput): IReqorePanelAction[] => {
+  const [inline, overflow] = splitOptionActions(injected, collapse);
+  const items: IReqorePanelSubAction[] = [
+    ...overflow.map(optionActionAsMenuItem),
+    ...menu.filter((item): item is IReqorePanelSubAction => !!item),
+  ];
+
+  const more: IReqorePanelAction = {
+    icon: 'More2Fill',
+    size: 'tiny',
+    minimal: true,
+    flat: true,
+    className: 'options-item-more',
+    tooltip: 'More actions',
+    actions: items,
+  };
+
+  return [...inline, ...(items.length ? [more] : [])];
+};

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

@@ -0,0 +1,24 @@
+import { IQorusFormSchema, TQorusForm } from '@qoretechnologies/ts-toolkit';
+import { createContext } from 'use-context-selector';
+
+/** The form a field is standing in: what it declares, and what it currently holds. */
+export interface IOptionsContext {
+  schema?: IQorusFormSchema;
+  value?: TQorusForm;
+}
+
+/**
+ * The surrounding form, for a renderer that has to judge one field against its
+ * SIBLINGS — an allowed value gated on another field's answer, for instance.
+ *
+ * It lives in a module of its own rather than in `FormEngine`, which imports
+ * the field renderers that read it: a renderer importing the engine back would
+ * close a cycle around a value created at module scope, and the context would
+ * be `undefined` for whichever module happened to be evaluated first.
+ *
+ * An empty default is load-bearing. `value` is `undefined` only when there is
+ * no form around the renderer at all — a picker mounted on its own, a story, a
+ * test — and a predicate about siblings has nothing to say there. Inside a form
+ * it is always an object, empty or not.
+ */
+export const OptionsContext = createContext<IOptionsContext>({});

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

@@ -10,6 +10,7 @@ import { renderExpressionToText } from '../expressions/renderExpressionToText';
 import { IExpressionValue } from '../expressions/types';
 import yaml from 'js-yaml';
 import { formatTimeoutValue, richtextToString } from '../../../helpers/common';
+import { firstDeclaredType } from '../../../helpers/optionUiTypes';
 
 /** "N noun" with naive pluralisation ("1 item", "2 items"). */
 const pluralize = (count: number, noun: string): string =>
@@ -224,7 +225,7 @@ export const shouldAutoCollapseCompactAllowedValueOption = (
  * user chooses either boolean value in compact mode, the choice is complete
  * and the inline editor can close without a separate confirmation. */
 export const isCompactBooleanOption = (schema: TQorusFormFieldSchema | undefined): boolean => {
-  const type = (schema?.ui_type || schema?.type)?.toLowerCase();
+  const type = firstDeclaredType(schema?.ui_type || schema?.type)?.toLowerCase();
   return type === 'bool' || type === 'boolean';
 };
 
@@ -316,6 +317,31 @@ export const getAllowedValueImage = (
   return (match?.image as string) || undefined;
 };
 
+/**
+ * The selected option's ICON, when it carries one and no logo — for the value
+ * cell.
+ *
+ * The same idea as {@link getAllowedValueImage} and read for the same reason:
+ * an option's mark belongs beside the value it names. Only images were rendered,
+ * so a picker whose entries are distinguished by ICON — an interface-kind list
+ * where every entry is a bare word, `Service`, `Job`, `Qog` — showed each mark
+ * while choosing and then dropped it the moment the row went read-only, which is
+ * the surface a reader spends the most time on.
+ *
+ * The image wins where an option has both: a logo is the more specific mark, and
+ * an icon standing behind it is a fallback rather than a second thing to draw.
+ */
+export const getAllowedValueIcon = (
+  value: unknown,
+  schema?: TQorusFormFieldSchema
+): string | undefined => {
+  const match = findAllowedOption(value, schema);
+  if (!match || match.image) {
+    return undefined;
+  }
+  return (match.icon as string) || undefined;
+};
+
 /** Clamp an RGB channel to a 0–255 integer. */
 const clampChannel = (n: number): number => Math.max(0, Math.min(255, Math.round(n)));
 const toHexPart = (n: number): string => clampChannel(n).toString(16).padStart(2, '0');
@@ -556,6 +582,36 @@ export const summariseMarkdown = (value: unknown): string => {
   return capSummary(prose);
 };
 
+/**
+ * The expression AST a field holds, whichever shape it arrived in.
+ *
+ * An expression arrives in TWO shapes, and only the flat one used to be
+ * checked. At runtime the editor writes the flag onto the option
+ * (`{ is_expression: true, value: ast }`); a value read back from a saved draft
+ * carries the envelope NESTED (`{ value: { is_expression: true, value: ast } }`)
+ * with no flag on the option at all. Missing the nested shape sent a reloaded
+ * expression to the generic formatter, which printed the AST — the row showed
+ * `is_expression true / value / exp + / args 1 2` where the expression should
+ * be.
+ *
+ * Exported because the SUMMARY is not the only place that has to know. The AST
+ * is how an expression is stored, not what it is, so nothing may draw it as
+ * data: `CompactRow` asks this before deciding a hash-shaped value has earned a
+ * structured inset. Answering it in one place is what keeps the row's two
+ * halves — the line and the inset under it — talking about the same value.
+ */
+export const getExpressionAst = (option?: {
+  is_expression?: boolean;
+  value?: unknown;
+}): IExpressionValue | undefined =>
+  option?.is_expression ? (option?.value as IExpressionValue | undefined)
+  : (
+    (option?.value as { is_expression?: boolean; value?: IExpressionValue } | undefined)
+      ?.is_expression
+  ) ?
+    (option?.value as { value?: IExpressionValue }).value
+  : undefined;
+
 export const formatOptionValue = (
   option?: IQorusFormField,
   schema?: TQorusFormFieldSchema
@@ -572,11 +628,13 @@ export const formatOptionValue = (
     return '••••••';
   }
 
-  if (option?.is_expression) {
+  const expressionAst = getExpressionAst(option);
+
+  if (expressionAst !== undefined) {
     // Offline summary of the {exp,args} AST already in the form value — the
     // same client-side renderer the editor's "Explain" seam falls back to when
     // the LSP is unreachable. The drill-in editor shows the canonical DPQL.
-    return renderExpressionToText(option?.value as IExpressionValue | undefined) || 'Expression';
+    return renderExpressionToText(expressionAst) || 'Expression';
   }
 
   // schema-definition is stored as a hash envelope; summarise it as the schema
@@ -792,7 +850,10 @@ export const getOptionGroupLabel = (
 /** Completion summary for the read-first progress meter. */
 export interface IReadFirstCompletion {
   total: number;
+  /** Fields holding a value, whether or not anything is wrong with it. */
   set: number;
+  /** Fields holding a value that nothing is flagging — what the meter fills. */
+  done: number;
   pct: number;
 }
 
@@ -831,14 +892,33 @@ export const getReadFirstBucket = (status: TReadFirstStatus): 'attention' | 'set
 
 /** Count how many of the shown options have a value set, for the progress meter. */
 export const getReadFirstCompletion = (
-  shownOptions: Record<string, IQorusFormField | undefined> = {}
+  shownOptions: Record<string, IQorusFormField | undefined> = {},
+  /**
+   * Whether the form flags this field as needing attention. Optional: without
+   * it the meter falls back to counting values alone, which is what a caller
+   * with no bucketing of its own can honestly say.
+   */
+  needsAttention?: (name: string) => boolean
 ): IReadFirstCompletion => {
   const names = Object.keys(shownOptions);
   const total = names.length;
-  const set = names.filter((name) => !isOptionValueEmpty(shownOptions[name]?.value)).length;
-  const pct = total ? Math.round((set / total) * 100) : 0;
-
-  return { total, set, pct };
+  const hasValue = (name: string) => !isOptionValueEmpty(shownOptions[name]?.value);
+  const set = names.filter(hasValue).length;
+  /* "Set" and "needs attention" are not opposites. A field can hold a value and
+     still be wrong — one that fails validation, or one the host has flagged
+     because something INSIDE it is unfinished — and counting those as progress
+     is how a form comes to report 100% while the box beneath it says a field
+     needs attention.
+
+     It also cost the meter its amber run: the bar draws attention from `set%`
+     onward, so a field counted in both pushed that run past the right edge,
+     where `overflow: hidden` swallowed it. The one visual signal that something
+     was outstanding was the one thing the double-count hid. */
+  const done =
+    needsAttention ? names.filter((name) => hasValue(name) && !needsAttention(name)).length : set;
+  const pct = total ? Math.round((done / total) * 100) : 0;
+
+  return { total, set, done, pct };
 };
 
 /** What the "first field to fix" selector needs to know about one field.

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

@@ -1,4 +1,37 @@
-import { TQorusType } from '@qoretechnologies/ts-toolkit';
+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:
@@ -41,6 +74,15 @@ export const BUILT_IN_RENDERER_ONLY_UI_TYPES: readonly string[] = [
   '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.
  *
@@ -52,11 +94,13 @@ export const BUILT_IN_RENDERER_ONLY_UI_TYPES: readonly string[] = [
  */
 export const createRendererOnlyUiTypeCheck = (
   extraTypes?: readonly string[]
-): ((type?: TQorusType | TQorusType[]) => boolean) => {
+): ((type?: TRendererTypeName) => boolean) => {
   const known = new Set<string>([...BUILT_IN_RENDERER_ONLY_UI_TYPES, ...(extraTypes ?? [])]);
 
-  return (type?: TQorusType | TQorusType[]): boolean =>
-    typeof type === 'string' && known.has(type);
+  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. */

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

@@ -0,0 +1,101 @@
+/**
+ * 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';