@qoretechnologies/reqraft 0.10.59-pr.130.gff5fd49 → 0.10.59

package/src/components/form/engine/OptionFieldMessages.tsx

@@ -327,20 +327,13 @@ export interface IOptionFieldMessagesProps {
   name: string;
   getType: (type: string) => string;
   /**
-   * The reader has not edited this field in this session.
+   * Whether a `ui_type` names a bespoke editor, the consumer's own included.
    *
-   * An error is a report that something went WRONG. "This field is required"
-   * under a field nobody has been in yet reports nothing: the form is empty
-   * because it is new. The requirement is already carried three other ways —
-   * the asterisk on the label, the Needs-attention box the row sits in, and the
-   * completion meter — so the message waits until the reader has been in the
-   * field and left it empty, which IS a thing that went wrong.
-   *
-   * Only the plain required message is held back. A value that fails
-   * validation, an unmet required GROUP and a locked dependency are all facts
-   * about what the form currently holds, and they show immediately.
+   * Such a field's `allowed_values` are not fixed choices (the editor decides
+   * what a value means), so a value is not judged against them. Without it only
+   * reqraft's built-in editors are known.
    */
-  untouched?: boolean;
+  isRendererOnly?: (type?: any) => boolean;
 }
 
 /**
@@ -354,7 +347,7 @@ export const getOptionFieldMessages = ({
   name,
   allOptions,
   getType,
-  untouched,
+  isRendererOnly,
 }: IOptionFieldMessagesProps): IReqoreTagProps[] => {
   const optionSchema = schema[name];
   const result: IReqoreTagProps[] = [];
@@ -386,6 +379,7 @@ export const getOptionFieldMessages = ({
         // config never reached the validator.
         ...(optionSchema as object),
         optionSchema: schema,
+        hasOwnEditor: !!isRendererOnly?.(optionSchema?.ui_type),
       }
     );
     if (!validationData.isValid) {
@@ -395,9 +389,10 @@ export const getOptionFieldMessages = ({
       });
     }
   } else {
-    // A locked field is not asked for: the dependency message below says what
+    // An empty required field says so from the start, on a new form too. A
+    // locked field is not asked for: the dependency message below says what
     // unlocks it, and until then there is nothing to fill in.
-    if (optionSchema?.required && !untouched && !locked) {
+    if (optionSchema?.required && !locked) {
       result.push({ label: 'This field is required', intent: 'danger' });
     }
 
@@ -442,11 +437,25 @@ export const OptionFieldMessages = ({
   name,
   allOptions,
   getType,
-  untouched,
+  isRendererOnly,
 }: IOptionFieldMessagesProps) => {
   const messages: IReqoreTagProps[] = useMemo(
-    () => getOptionFieldMessages({ schema, option, name, allOptions, getType, untouched }),
-    [JSON.stringify(schema), JSON.stringify(option), JSON.stringify(allOptions), name, untouched]
+    () =>
+      getOptionFieldMessages({
+        schema,
+        option,
+        name,
+        allOptions,
+        getType,
+        isRendererOnly,
+      }),
+    [
+      JSON.stringify(schema),
+      JSON.stringify(option),
+      JSON.stringify(allOptions),
+      name,
+      isRendererOnly,
+    ]
   );
 
   if (!size(messages)) {

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

@@ -98,6 +98,8 @@ export interface ICompactRowContext {
   handleOptionLabelClick: (optionName: string) => void;
   removeSelectedOption: (optionName: string) => void;
   getTypeForOption: (type: string) => string;
+  /** Whether a `ui_type` names a bespoke editor, reqraft's or the consumer's own. */
+  isRendererOnly?: (type?: any) => boolean;
   isOptionValid: (optionName: string, type: any, optionValue: any) => boolean;
   confirmAction: ReturnType<typeof useReqoreProperty<'confirmAction'>>;
 

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

@@ -66,6 +66,9 @@ export const StyledCompactPanel = styled(ReqorePanel)<{
   $tightHeader?: boolean;
   /** True when the status boxes inside pin their headers. */
   $stickyBoxes?: boolean;
+  /** True when a narrow form's header carries a consumer's label, icon or
+   *  actions beside the toolbar, which then has to take a line of its own. */
+  $stackHeader?: boolean;
 }>`
   /* The wrapper must not clip, or nothing INSIDE it can pin.
   
@@ -89,6 +92,37 @@ export const StyledCompactPanel = styled(ReqorePanel)<{
         }
       `
     : ''}
+  /* A NARROW header dressed by the consumer (\`compactPanelProps\` label, icon
+     or actions) stacks: the label and the consumer's actions share the first
+     line, and the toolbar takes the whole second line.
+
+     ReqorePanel lays its header out as one unwrapping row — the label, then an
+     action group that never shrinks. The toolbar is one of those actions and
+     is as wide as the form, so at phone width the label was squeezed to
+     nothing and the consumer's own action was pushed past the panel's edge and
+     clipped. Flattening the action group (\`display: contents\`) lets its
+     members wrap with the label, and \`order\` moves the toolbar after them. */
+  ${({ $stackHeader }) =>
+    $stackHeader ?
+      css`
+        && > .reqore-panel-title {
+          flex-wrap: wrap;
+          row-gap: ${GAP_FROM_SIZE.normal}px;
+        }
+        && > .reqore-panel-title > .reqore-panel-title-header {
+          flex: 1 1 0;
+          min-width: 0;
+        }
+        && > .reqore-panel-title > .reqore-control-group {
+          display: contents;
+        }
+        && > .reqore-panel-title .options-readfirst-toolbar {
+          order: 1;
+          flex: 1 1 100%;
+          min-width: 0;
+        }
+      `
+    : ''}
   > .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
@@ -97,6 +131,14 @@ export const StyledCompactPanel = styled(ReqorePanel)<{
       $nested ? '' : (
         'backdrop-filter: blur(6px); -webkit-backdrop-filter: blur(6px); transform: translateZ(0);'
       )}
+    /* Above the status-box headers, which pin just below this toolbar. A
+       pinned header cannot leave its own box, so when the end of a box
+       scrolls up past the toolbar it pushes the header up with it — and with
+       both at ReqorePanel's sticky z-index the header, later in the
+       document, slid OVER the toolbar and covered the search and the
+       meter. One step higher and it slides under the toolbar's blur
+       instead. Nested sub-forms pin nothing, so they keep the default. */
+    ${({ $nested }) => ($nested ? '' : 'z-index: 3;')}
     padding-top: ${GAP_FROM_SIZE[HEADER_GAP]}px;
     /* A header with a SEARCH ROW keeps the \`big\` gap below it — a tall
        interactive control earns separation from the content it filters. A

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

@@ -0,0 +1,123 @@
+/**
+ * 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/helpers/allowedValues.ts

@@ -9,6 +9,7 @@
  */
 import { TQorusFormFieldSchema } from '@qoretechnologies/ts-toolkit';
 import isEqual from 'lodash/isEqual';
+import { isRendererOnlyUiType } from '../components/form/engine/rendererTypes';
 import { richtextHasTag, richtextToString } from './common';
 import { getListElementValue } from './options';
 import { isValueTemplate } from './templates';
@@ -109,8 +110,32 @@ export interface IChoiceFieldSchema {
   /** Set when the value is an expression, which is resolved at run time. */
   isFunction?: boolean;
   is_expression?: boolean;
+  /** The editor the field is drawn with; see {@link hasOwnEditor}. */
+  ui_type?: string | readonly string[];
+  /**
+   * Set by a form that knows the field is drawn by a bespoke editor of the
+   * consumer's own (one it declared in `rendererOnlyUiTypes`), which reqraft's
+   * built-in list cannot name.
+   */
+  hasOwnEditor?: boolean;
 }
 
+/**
+ * Does a bespoke editor, rather than reqraft's choice picker, draw this field?
+ *
+ * Then the editor alone decides what a value means, and `allowed_values` is not
+ * a closed set of values the field may hold. The AI endpoint's Tools field is
+ * the case that proved it: its `tool-catalog` editor stores SELECTORS -- `*` for
+ * every tool, `system:*`, a connection name, `connection/tool` -- and the host
+ * hangs the tool catalogue's SOURCES on `allowed_values` for the editor to
+ * browse. Judging the selectors against the sources flagged the server's own
+ * default, `["*"]`, as "not one of the choices", so no chat endpoint could be
+ * published with it. The server says the same: a custom `ui_type` "defines its
+ * own value shape".
+ */
+const hasOwnEditor = (field: IChoiceFieldSchema): boolean =>
+  !!field.hasOwnEditor || isRendererOnlyUiType(field.ui_type);
+
 /**
  * The parts of a stored value that are not among the field's fixed choices.
  *
@@ -121,14 +146,22 @@ export interface IChoiceFieldSchema {
  *   all of which are resolved when the interface runs;
  * - `allowed_values: []` — the server has no choices to offer right now, which
  *   is "unknown", not "nothing is allowed";
- * - creatable choices, where any value may be added.
+ * - creatable choices, where any value may be added;
+ * - a field drawn by a bespoke editor (a renderer-only `ui_type` such as
+ *   `tool-catalog`), whose values are whatever that editor says they are.
  *
  * A single-valued field is judged as a whole. A multi-select field, and a list
  * whose elements are constrained by `element_allowed_values`, are judged per
  * element, so the answer names exactly the elements that are not choices.
  */
 export const getUnlistedChoices = (value: unknown, field?: IChoiceFieldSchema): unknown[] => {
-  if (!field || isEmptyChoiceValue(value) || field.isFunction || field.is_expression) {
+  if (
+    !field ||
+    isEmptyChoiceValue(value) ||
+    field.isFunction ||
+    field.is_expression ||
+    hasOwnEditor(field)
+  ) {
     return [];
   }
 

package/src/stories/Tests/utils.ts

@@ -282,3 +282,39 @@ export async function _testsDoubleClickButton({
   }
   console.log('Clicked button:', label, selector, nth, wait);
 }
+
+/**
+ * Run `body` with the story's own viewport narrowed to `width` x `height`, then
+ * put it back.
+ *
+ * qlip's `parameters.qlip.viewport` sizes the CAPTURE, which happens after the
+ * play has finished — the play itself runs at the test browser's width. A play
+ * that asserts the phone layout has to narrow the viewport itself, with the
+ * same `page.viewport` call qlip makes. It is a DYNAMIC import: `vitest/browser`
+ * throws on import outside Browser Mode, so a static one would take the
+ * Storybook dev server down. Where the call is unavailable, `body` runs at the
+ * width it already had and is told so (`narrowed` is false).
+ */
+export const _testsWithViewport = async (
+  width: number,
+  height: number,
+  body: (narrowed: boolean) => Promise<void>
+) => {
+  let resize: ((w: number, h: number) => Promise<void>) | undefined;
+  try {
+    ({
+      page: { viewport: resize },
+    } = (await import('vitest/browser')) as never);
+  } catch {
+    resize = undefined;
+  }
+
+  const was = { width: window.innerWidth, height: window.innerHeight };
+  await resize?.(width, height);
+  try {
+    await body(!!resize && window.innerWidth === width);
+  } finally {
+    // Unconditional: a viewport left narrowed would narrow every later story.
+    await resize?.(was.width, was.height);
+  }
+};