@qoretechnologies/reqraft 0.10.50-pr.115.gf7dfde4 → 0.10.50

package/src/components/form/engine/FormEngine.stories.tsx

@@ -2588,7 +2588,7 @@ export const CompactBasic: Story = {
     docs: {
       description: {
         story:
-          "Renders FormEngine in compact mode over the full Basic fixture — every value renders in its read-first form (templates by name, colours as hex, hashes as field-count summaries), disabled and dependency-locked rows stay non-interactive, and the dependency lock's popover navigates to blockers.",
+          "Renders FormEngine in compact mode over the full Basic fixture — every value renders in its read-first form (templates by name, colours as hex, hashes as field-count summaries), disabled and dependency-locked rows stay non-interactive, and the dependency lock's popover navigates to blockers. The play scrolls the richtext editor into view to type into it, so the captured frame sits mid-form.",
       },
     },
     chromatic: { disable: true },
@@ -3989,7 +3989,7 @@ export const CompactOverflowAndStickyHeader: Story = {
     docs: {
       description: {
         story:
-          'Renders a compact form tall enough to scroll — the group headers stick to the top of the panel as the form scrolls under them.',
+          'Renders a compact form with `compactScroll="own"` — the form caps at the host height and scrolls its own body, and its toolbar stays pinned to the top of that body.',
       },
     },
     chromatic: { disable: true },
@@ -4005,6 +4005,9 @@ export const CompactOverflowAndStickyHeader: Story = {
   ],
   args: {
     compact: true,
+    // The opt-in branch: this story is about the form owning its scroll, so it
+    // asks for it. The default is `'host'` — see CompactHostOwnedScroll.
+    compactScroll: 'own' as const,
     minColumnWidth: '300px',
     options: CompactScrollableSchema,
     groups: CompactGroups,
@@ -4044,6 +4047,170 @@ export const CompactOverflowAndStickyHeader: Story = {
   },
 };
 
+// The default branch of `compactScroll`. Two compact forms inside one scrolling
+// host is the shape that exposed this: each form used to cap at the host height
+// and scroll its own body, so a page with two of them showed three scrollbars in
+// two styles and the reader could not tell which moved what.
+export const CompactHostOwnedScroll: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders two compact forms inside one scrolling host. With the default `compactScroll="host"` neither form scrolls itself — the host owns the only scrollbar — and each form\'s toolbar still pins to the top of the host as it scrolls.',
+      },
+    },
+    chromatic: { disable: true },
+  },
+  // A COLUMN FLEX host with a definite height — the shape real consumers use
+  // (qorus-ide's ContentWrapper is exactly this). It matters: a plain block
+  // host does not exercise the flex shrink allowance, so the zero-height
+  // collapse assertion below cannot fail there and the test would be worthless.
+  decorators: [
+    (StoryComponent: React.ComponentType) => (
+      <div
+        style={{ height: 400, overflow: 'auto', display: 'flex', flexFlow: 'column' }}
+        data-testid='compact-scroll-host'
+      >
+        <StoryComponent />
+        <StoryComponent />
+      </div>
+    ),
+  ],
+  args: {
+    compact: true,
+    minColumnWidth: '300px',
+    options: CompactScrollableSchema,
+    groups: CompactGroups,
+    value: CompactValue,
+  },
+  play: async () => {
+    await _testsWaitForText('order-fulfilment');
+    const host = document.querySelector('[data-testid="compact-scroll-host"]') as HTMLElement;
+    const wraps = Array.from(
+      document.querySelectorAll('.options-readfirst-scroll')
+    ) as HTMLElement[];
+    await expect(wraps.length).toBe(2);
+
+    // (a) No form owns a scroll context — `overflow-x: clip` rather than
+    // `hidden` matters here: `hidden` would coerce `overflow-y: visible` back
+    // to `auto`, leaving each form a scroll container whose sticky toolbar
+    // silently stops pinning to the host.
+    for (const wrap of wraps) {
+      await expect(getComputedStyle(wrap).overflowY).toBe('visible');
+      await expect(wrap.scrollHeight).toBeLessThanOrEqual(wrap.clientHeight + 1);
+    }
+
+    // (b) Each form still OCCUPIES its content. Releasing the scroll without
+    // also releasing the flex shrink allowance collapses the wrap to zero
+    // height: the rows paint outside it, so it looks correct while the host
+    // sizes and scrolls to nothing. Assert the box, not just the pixels.
+    for (const wrap of wraps) {
+      const child = wrap.firstElementChild as HTMLElement;
+      await expect(wrap.getBoundingClientRect().height).toBeGreaterThan(0);
+      await expect(wrap.getBoundingClientRect().height).toBeCloseTo(
+        child.getBoundingClientRect().height,
+        0
+      );
+    }
+
+    // (c) Exactly one element on the page scrolls, and it is the host.
+    const scrollers = (Array.from(document.querySelectorAll('*')) as HTMLElement[]).filter(
+      (el) =>
+        /(auto|scroll)/.test(getComputedStyle(el).overflowY) &&
+        el.scrollHeight > el.clientHeight + 4 &&
+        el.clientHeight > 80
+    );
+    await expect(scrollers).toEqual([host]);
+
+    // (d) The toolbar still pins — the guarantee the self-scroll existed for.
+    host.scrollTop = 300;
+    await waitFor(() => {
+      const search = document.querySelector('input[placeholder="Filter fields..."]') as HTMLElement;
+      const hostTop = host.getBoundingClientRect().top;
+      expect(search.getBoundingClientRect().top).toBeGreaterThanOrEqual(hostTop - 1);
+    });
+  },
+};
+
+// The PADDED twin of CompactHostOwnedScroll. It is a separate story because the
+// unpadded one cannot fail for this: `position: sticky; top: 0` resolves against
+// a scrollport's CONTENT box, so only a host WITH padding can reveal a toolbar
+// pinning below it. Needs reqore >= 0.74.1, which measures that padding and
+// compensates the sticky line (reqore#648).
+export const CompactHostOwnedScrollPaddedHost: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "The same two compact forms in one scrolling host, but the host carries its own 24px padding. The host still owns the only scrollbar, and each form's toolbar still pins flush to the host's visible top edge rather than below its padding.",
+      },
+    },
+    chromatic: { disable: true },
+  },
+  decorators: [
+    (StoryComponent: React.ComponentType) => (
+      <div
+        style={{
+          height: 400,
+          overflow: 'auto',
+          display: 'flex',
+          flexFlow: 'column',
+          padding: 24,
+        }}
+        data-testid='compact-scroll-host'
+      >
+        <StoryComponent />
+        <StoryComponent />
+      </div>
+    ),
+  ],
+  args: {
+    compact: true,
+    minColumnWidth: '300px',
+    options: CompactScrollableSchema,
+    groups: CompactGroups,
+    value: CompactValue,
+  },
+  play: async () => {
+    await _testsWaitForText('order-fulfilment');
+    const host = document.querySelector('[data-testid="compact-scroll-host"]') as HTMLElement;
+    const wraps = Array.from(
+      document.querySelectorAll('.options-readfirst-scroll')
+    ) as HTMLElement[];
+    await expect(wraps.length).toBe(2);
+
+    // Still exactly one scroller, and no form owns one — the padding must not
+    // buy a flush toolbar back by handing the scroll to the form.
+    for (const wrap of wraps) {
+      await expect(getComputedStyle(wrap).overflowY).toBe('visible');
+      await expect(wrap.getBoundingClientRect().height).toBeGreaterThan(0);
+    }
+    const scrollers = (Array.from(document.querySelectorAll('*')) as HTMLElement[]).filter(
+      (el) =>
+        /(auto|scroll)/.test(getComputedStyle(el).overflowY) &&
+        el.scrollHeight > el.clientHeight + 4 &&
+        el.clientHeight > 80
+    );
+    await expect(scrollers).toEqual([host]);
+
+    // The toolbar pins to the host's VISIBLE top edge, not to its padding box.
+    // Measure the STICKY ELEMENT — the panel title. The "Filter fields..." input
+    // lives inside that header below the completion meter, so it sits ~69px
+    // lower by design; asserting on it measures the header's own internals and
+    // says nothing about where the header pinned.
+    const stickyHeader = wraps[0].firstElementChild!.querySelector(
+      '.reqore-panel-title'
+    ) as HTMLElement;
+    host.scrollTop = 300;
+    await waitFor(() => {
+      const line =
+        host.getBoundingClientRect().top + (parseFloat(getComputedStyle(host).borderTopWidth) || 0);
+      // Two-sided: a `>=` bound passes at +24, which is exactly the bug.
+      expect(Math.abs(stickyHeader.getBoundingClientRect().top - line)).toBeLessThanOrEqual(2);
+    });
+  },
+};
+
 // on_change/refetch + has_dependents flow through the same handleValueChange
 // as classic — the read-first editor must fire and reset the same way.
 export const CompactOnChangeAndDependents: Story = {
@@ -4616,7 +4783,7 @@ export const CompactFieldTypes: Story = {
     docs: {
       description: {
         story:
-          'Renders a compact form that exercises the full catalogue of ui_type renderers — every type (string, richtext, hash, list, file, colour, byte-size, cron, connection, enum, etc.) is present with a representative value.',
+          "Renders a compact form that exercises the full catalogue of ui_type renderers — every type (string, richtext, hash, list, file, colour, byte-size, cron, connection, enum, etc.) is present with a representative value. The play leaves the `String` row expanded with its editor focused; the form leaves scrolling to its host (`compactScroll` defaults to `'host'`), so that focus scrolls the page — the captured frame sits mid-form with the toolbar pinned over the rows, not at the top of the form.",
       },
     },
   },
@@ -5197,7 +5364,15 @@ export const CompactFieldTypesEditing: Story = {
     chromatic: { disable: true },
   },
   // multi: this story expands every row at once (single-open would collapse them).
-  args: { ...CompactFieldTypes.args, expandMode: 'multi' as const },
+  //
+  // `compactScroll: 'own'` bounds the form's height. With every editor open the
+  // document is long, and the play clicks its way down all of them — each click
+  // scrolling and hit-testing a taller page. Measured at ~8.5s bounded against
+  // ~12.5s unbounded, and this story already spent 17.2s of its 30s budget in
+  // CI, so the unbounded cost times it out. Nothing here is about scroll
+  // ownership, so bounding it loses no coverage; the default is exercised by
+  // CompactHostOwnedScroll.
+  args: { ...CompactFieldTypes.args, expandMode: 'multi' as const, compactScroll: 'own' as const },
   play: async () => {
     await _testsWaitForText('hello');
     await _compactExpandAllRows();

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

@@ -17,7 +17,6 @@ import { IReqoreCollectionProps } from '@qoretechnologies/reqore/dist/components
 import { IReqoreCollectionItemProps } from '@qoretechnologies/reqore/dist/components/Collection/item';
 import { IReqorePanelProps } from '@qoretechnologies/reqore/dist/components/Panel';
 import { IReqoreFormTemplates } from '@qoretechnologies/reqore/dist/components/Textarea';
-import { TFieldWithOwnTemplates } from './rendererTypes';
 import { TReqoreIntent } from '@qoretechnologies/reqore/dist/constants/theme';
 import {
   changeDarkness,
@@ -48,7 +47,7 @@ import reduce from 'lodash/reduce';
 import size from 'lodash/size';
 import React, { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
 import { useMeasure, useMount, useUpdateEffect } from 'react-use';
-import styled from 'styled-components';
+import styled, { css } from 'styled-components';
 import { createContext } from 'use-context-selector';
 import {
   fixOperatorValue,
@@ -234,7 +233,7 @@ const PositiveColorEffect: any = {
 // Compact (read-first) layout: flat label | value | action rows in collapsible
 // group panels; colours come in as props so the layout follows the Reqore theme.
 
-const StyledCompactWrap = styled.div<{ $flush?: boolean }>`
+const StyledCompactWrap = styled.div<{ $ownScroll?: boolean }>`
   display: flex;
   flex-flow: column;
   gap: 10px;
@@ -243,21 +242,48 @@ const StyledCompactWrap = styled.div<{ $flush?: boolean }>`
      engage instead of overflowing the container horizontally. */
   min-width: 0;
   max-width: 100%;
-  /* Own our scroll context instead of borrowing the host's. The sticky toolbar
-     pins to whatever scrolls; if that scroller carries top padding (e.g. a
-     ReqorePanel/ReqoreContent body), sticky \`top: 0\` resolves against its
-     padding box and leaves an unblurred strip above the toolbar. By scrolling
-     here — an UNPADDED box — the toolbar always pins flush and content ghosts
-     cleanly beneath it, regardless of host padding (mirrors how the IDE
-     dashboard keeps its StyledScrollBody scroller unpadded).
-     We cap at the host's available height and scroll past it, but do NOT grow
-     to fill it — short forms still hug their content. When the host height is
-     indefinite, \`max-height: 100%\` resolves to none and the box grows so the
-     host scrolls as before (graceful fallback). */
-  min-height: 0;
-  max-height: 100%;
-  overflow-y: auto;
-  overflow-x: hidden;
+
+  /* Scroll ownership — see \`compactScroll\`.
+
+     'host' (the default): the page or panel around us already scrolls, so we
+     must not cap our height and scroll our own body, or the reader gets two
+     scrollbars in two styles and cannot tell which moves what.
+
+     \`overflow-x: clip\`, NOT \`hidden\`: CSS coerces an \`overflow-y: visible\`
+     to \`auto\` whenever the other axis is neither visible nor clip, which would
+     leave this box a scroll container — the element stops scrolling only
+     because \`max-height: none\` means nothing overflows, while \`position:
+     sticky\` inside it still resolves against US instead of the host, so the
+     toolbar silently stops pinning. \`clip\` keeps the horizontal guard without
+     that coercion. */
+  ${({ $ownScroll }) =>
+    $ownScroll
+      ? css`
+          /* 'own': we are the scroller. The sticky toolbar pins to whatever
+             scrolls, so a host whose scrollport carries top padding would
+             resolve sticky \`top: 0\` against its padding box and leave an
+             unblurred strip above the toolbar. Scrolling in this unpadded box
+             pins it flush. Cap at the host's available height, but do not grow
+             to fill it — short forms still hug their content.
+
+             \`min-height: 0\` is what lets a flex item shrink below its content
+             so there is something to scroll; it belongs to this branch only. */
+          min-height: 0;
+          max-height: 100%;
+          overflow-y: auto;
+          overflow-x: hidden;
+        `
+      : css`
+          /* \`min-height: auto\` is load-bearing, not a default: inside a column
+             flex parent the shrink allowance above collapses this box to zero
+             height while its rows paint outside it, so the form looks right but
+             contributes nothing to layout — the host cannot size or scroll to
+             it and anything below it stacks against nothing. */
+          min-height: auto;
+          max-height: none;
+          overflow-y: visible;
+          overflow-x: clip;
+        `}
 
   /* Option logos (e.g. language images) render as <img> inside ReqoreIcon's
      square box; constrain them so portrait PNGs don't overflow the row. */
@@ -627,13 +653,6 @@ export interface IFormEngineProps extends Omit<IReqoreCollectionProps, 'onChange
   recordRequiresSearchOptions?: boolean;
   readOnly?: boolean;
   allowTemplates?: boolean;
-  /**
-   * The form's SHARED template vocabulary — config items, system properties —
-   * offered to every field that supports templates.
-   *
-   * A field may also declare `templates` of its own in the schema, and that
-   * narrower list wins for that field: see {@link TFieldWithOwnTemplates}.
-   */
   stringTemplates?: IReqoreFormTemplates;
   /** Opt-in: fetch global templates from `system/getContextData` for this context. */
   interfaceContext?: string;
@@ -654,6 +673,11 @@ export interface IFormEngineProps extends Omit<IReqoreCollectionProps, 'onChange
    * breathing room) so the form sits flush to its container's edges. For embeds
    * that own their own gutters — e.g. the SchemaDefinition tab body, where the
    * form should line up with the section description above it. Default `false`.
+   *
+   * @deprecated No-op. The wrap has never had the gutter this prop claims to
+   * drop — the value reached a styled template with no interpolation slot — so
+   * every form already renders flush. Kept so existing call sites keep
+   * compiling; do not add new ones.
    */
   compactFlush?: boolean;
   /**
@@ -662,8 +686,27 @@ export interface IFormEngineProps extends Omit<IReqoreCollectionProps, 'onChange
    * scroll context, so the toolbar isn't sticky and its header drops the dark
    * blurred backdrop (and the stacking context that goes with it) — it sits
    * transparently inside the parent's edit card. Default `false`.
+   *
+   * Implies `compactScroll: 'host'` — a nested sub-form never owns a scroller.
    */
   compactNested?: boolean;
+  /**
+   * Compact mode only: who owns the form's vertical scroll.
+   *
+   * - `'host'` (default) — the surrounding page, panel or drawer scrolls, and
+   *   the form grows to its content. This is right almost everywhere: a form
+   *   inside something that already scrolls must not cap its own height, or the
+   *   reader gets two scrollbars side by side in two different styles and no
+   *   way to tell which one moves what.
+   * - `'own'` — the form caps at the host's available height and scrolls its
+   *   own body. Reach for this only when the host has a definite height and is
+   *   NOT itself a scroll container (it would clip the form instead of
+   *   scrolling it), or when the host's scrollport is padded and the sticky
+   *   toolbar must pin flush against an unpadded box.
+   *
+   * Default `'host'`.
+   */
+  compactScroll?: 'own' | 'host';
   /**
    * Compact mode only: props forwarded to the read-first form's outer
    * `ReqorePanel` — the panel that carries the sticky toolbar header and holds
@@ -888,8 +931,15 @@ const FormEngineImpl = ({
   forceDropdown,
   showTypeToggle = true,
   compact,
+  // Destructured only to keep it out of `rest` (and so off the DOM). The gutter
+  // this prop documents was never implemented: it was passed to the wrap as
+  // `$flush`, whose styled template had no interpolation slot, so it has always
+  // been a no-op. Removing it from the API is a separate, breaking change —
+  // every consumer passing it today already gets the flush layout by default.
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
   compactFlush = false,
   compactNested = false,
+  compactScroll = 'host',
   compactPanelProps,
   compactCollapsedGroups = ['optional'],
   compactToolbar = true,
@@ -2391,23 +2441,7 @@ const FormEngineImpl = ({
               isFixedCompactAllowedValueOption(optionSchema) ||
               (options?.[optionName]?.supports_custom_values !== false && resolvedType !== 'any')
             }
-            // A field may declare a template list OF ITS OWN, and when it does
-            // that list is the one to offer. The engine-wide `stringTemplates`
-            // are the form's shared vocabulary - config items, system properties
-            // - and every field draws on the same set. A per-field list answers a
-            // question only that field asks: a test assertion's `$.` references
-            // are the values ITS case captured, and no other field in the form
-            // should be offering them.
-            //
-            // Passing the engine's list unconditionally overwrote the schema's,
-            // so a field that declared templates had none by the time it
-            // rendered. On a typed field that only cost the picker; on an
-            // ANY-LIKE one it changed the question, because `TemplateField`
-            // opens on the template selector only when there is something to
-            // pick and otherwise falls back to the type picker. An untyped field
-            // therefore asked the author to choose `string`/`int`/`hash` before
-            // it would let them name a value they had already captured.
-            templates={(optionSchema as TFieldWithOwnTemplates | undefined)?.templates ?? templates.value}
+            templates={templates.value}
             {...getTypeAndCanBeNull(
               // The RENDERER type picks the editor — the storage type lives on
               // the value envelope. Passing storage here rendered a `richtext`
@@ -3095,9 +3129,9 @@ const FormEngineImpl = ({
               <StyledCompactWrap
                 ref={setCompactWrap}
                 className='options-readfirst-scroll'
-                // A nested sub-form sits flush inside the parent's card — no outer
-                // gutter (the card already provides the breathing room).
-                $flush={compactFlush || compactNested}
+                // A nested sub-form is never the scroller — it sits inside the
+                // parent form's card, which is inside whatever actually scrolls.
+                $ownScroll={compactScroll === 'own' && !compactNested}
               >
                 <StyledCompactPanel
                   // Mirrors the toolbar's own search-row gate: when no search

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

@@ -1,16 +1,4 @@
 import { TQorusType } from '@qoretechnologies/ts-toolkit';
-import { IReqoreFormTemplates } from '@qoretechnologies/reqore/dist/components/Textarea';
-
-/**
- * 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 };
 
 /**
  * A schema entry carries two type-ish keys with different jobs: