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

package/dist/components/form/engine/revealRow.js

@@ -0,0 +1,120 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.revealRow = exports.isRowInView = exports.getRevealClearance = exports.getPinnedChromeHeight = exports.findScrollContainer = void 0;
+/** Selectors of the elements whose header may be pinned above a row. */
+var PINNED_HEADER_OWNERS = '.options-readfirst-group, .options-readfirst-scroll > .reqore-panel';
+var isScrollable = function (element) {
+    var overflowY = getComputedStyle(element).overflowY;
+    return ((overflowY === 'auto' || overflowY === 'scroll' || overflowY === 'overlay') &&
+        element.scrollHeight > element.clientHeight);
+};
+/** The nearest ancestor that actually scrolls; `undefined` means the viewport. */
+var findScrollContainer = function (element) {
+    for (var parent_1 = element.parentElement; parent_1; parent_1 = parent_1.parentElement) {
+        if (parent_1 === document.body || parent_1 === document.documentElement) {
+            return undefined;
+        }
+        if (isScrollable(parent_1)) {
+            return parent_1;
+        }
+    }
+    return undefined;
+};
+exports.findScrollContainer = findScrollContainer;
+/**
+ * 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.
+ */
+var getPinnedChromeHeight = function (element) {
+    var _a, _b;
+    var clearance = 0;
+    for (var owner = (_a = element.parentElement) === null || _a === void 0 ? void 0 : _a.closest(PINNED_HEADER_OWNERS); owner; owner = (_b = owner.parentElement) === null || _b === void 0 ? void 0 : _b.closest(PINNED_HEADER_OWNERS)) {
+        var header = owner.querySelector(':scope > .reqore-panel-title');
+        if (!header || header.contains(element)) {
+            continue;
+        }
+        var style = getComputedStyle(header);
+        if (style.position !== 'sticky') {
+            continue;
+        }
+        var top_1 = parseFloat(style.top) || 0;
+        clearance = Math.max(clearance, top_1 + header.getBoundingClientRect().height);
+    }
+    return clearance;
+};
+exports.getPinnedChromeHeight = getPinnedChromeHeight;
+/**
+ * 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).
+ */
+var getRevealClearance = function (element) {
+    var container = (0, exports.findScrollContainer)(element);
+    var inset = container ? parseFloat(getComputedStyle(container).paddingTop) || 0 : 0;
+    return inset + (0, exports.getPinnedChromeHeight)(element);
+};
+exports.getRevealClearance = getRevealClearance;
+/**
+ * Whether the whole of `element` is visible below `clearance` (measured from
+ * the top edge of its scrollport, see {@link getRevealClearance}).
+ */
+var isRowInView = function (element, clearance) {
+    var container = (0, exports.findScrollContainer)(element);
+    var viewTop = container ? container.getBoundingClientRect().top + container.clientTop : 0;
+    var viewBottom = container ?
+        viewTop + container.clientHeight
+        : window.innerHeight || document.documentElement.clientHeight;
+    var rect = element.getBoundingClientRect();
+    return rect.top >= viewTop + clearance && rect.bottom <= viewBottom;
+};
+exports.isRowInView = isRowInView;
+/**
+ * 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.
+ */
+var revealRow = function (element, behavior) {
+    if (behavior === void 0) { behavior = 'smooth'; }
+    // jsdom implements neither layout nor `scrollIntoView`; a missing reveal must
+    // never break a form.
+    if (typeof element.scrollIntoView !== 'function') {
+        return false;
+    }
+    var clearance = (0, exports.getRevealClearance)(element);
+    if ((0, exports.isRowInView)(element, clearance)) {
+        return false;
+    }
+    element.style.scrollMarginTop = "".concat(clearance, "px");
+    element.scrollIntoView({ block: 'nearest', inline: 'nearest', behavior: behavior });
+    return true;
+};
+exports.revealRow = revealRow;
+//# sourceMappingURL=revealRow.js.map

package/dist/components/form/engine/revealRow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"revealRow.js","sourceRoot":"","sources":["../../../../src/components/form/engine/revealRow.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qoretechnologies/reqraft",
-  "version": "0.10.59-pr.130.gf96dd6f",
+  "version": "0.10.59",
   "description": "ReQraft is a collection of React components and hooks that are used across Qore Technologies' products made using the ReQore component library from Qore.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

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

@@ -35,6 +35,7 @@ import { Description } from '../../Description';
 import { useMarkdownRenderer } from '../../Description/markdownRendererContext';
 import { FocusedEditing } from '../../FocusedEditing';
 import { CompactRowContext } from './compactRowContext';
+import { revealRow } from './revealRow';
 import {
   StyledActionSlot,
   StyledCardHeading,
@@ -931,8 +932,11 @@ export const CompactRow = memo(
         }
         const control = findRowFocusTarget(editor);
         if (!control) return false;
-        // Optional call: jsdom does not implement `scrollIntoView`.
-        rowRef.current?.scrollIntoView?.({ block: 'nearest', inline: 'nearest' });
+        // The least scroll that shows the row clear of the pinned box header,
+        // and none when it is already in view (see `revealRow`).
+        if (rowRef.current) {
+          revealRow(rowRef.current, 'auto');
+        }
         // `preventScroll`, because the reveal above has already put the row
         // where it belongs; letting focus scroll as well moves it twice.
         control.focus({ preventScroll: true });

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

@@ -147,7 +147,14 @@ export const CompactToolbar = memo((reqoreProps: Partial<IReqoreControlGroupProp
   const attentionPct = completion.total ? (attentionCount / completion.total) * 100 : 0;
 
   return (
-    <ReqoreControlGroup {...reqoreProps} vertical fluid fixed={false} gapSize='big'>
+    <ReqoreControlGroup
+      {...reqoreProps}
+      className='options-readfirst-toolbar'
+      vertical
+      fluid
+      fixed={false}
+      gapSize='big'
+    >
       {/* No completion in a read-only form. The meter answers "how much is
           left to do", and a reader can do none of it: "4/6 set · 67%" over a
           form nobody can fill in is a progress report on somebody else's

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

@@ -23,6 +23,7 @@ import {
   _testsWaitForText,
   _testsWaitForTextsCount,
   _testsWaitForTextToNotExist,
+  _testsWithViewport,
   sleep,
 } from '../../../stories/Tests/utils';
 import { mockExpressions } from '../expressions/mockExpressions';
@@ -2934,6 +2935,99 @@ export const CompactWithPanelProps: Story = {
   },
 };
 
+/**
+ * The outside-dressed panel, its toolbar and its rows all fit the width they
+ * are given: nothing scrolls sideways, the label, the host's action and the
+ * toolbar are on screen, and every row's label and value lie inside the form.
+ */
+const assertPanelPropsFitNarrowWidth = async (canvasElement: HTMLElement) => {
+  await _testsWaitForText('Connection settings');
+  await _testsWaitForText('order-fulfilment');
+  const form = canvasElement.querySelector<HTMLElement>('.options-readfirst-scroll')!;
+  await waitFor(() => expect(form.querySelector('.readfirst-narrow')).toBeTruthy());
+  const formRect = form.getBoundingClientRect();
+  // No sideways scroll: not the page, not the form.
+  expect(document.documentElement.scrollWidth).toBeLessThanOrEqual(
+    document.documentElement.clientWidth
+  );
+  expect(form.scrollWidth).toBeLessThanOrEqual(form.clientWidth + 1);
+  const inside = (element: Element | null, what: string) => {
+    expect(element, what).toBeTruthy();
+    const rect = element!.getBoundingClientRect();
+    expect(rect.width, `${what} is drawn`).toBeGreaterThan(0);
+    expect(rect.left, `${what} starts inside the form`).toBeGreaterThanOrEqual(formRect.left - 1);
+    expect(rect.right, `${what} ends inside the form`).toBeLessThanOrEqual(formRect.right + 1);
+  };
+  // The panel chrome supplied from outside, and the engine's own toolbar.
+  const panelTitle = [...canvasElement.querySelectorAll<HTMLElement>('.reqore-panel-title')].find(
+    (title) => (title.textContent || '').includes('Connection settings')
+  )!;
+  inside(panelTitle, 'the panel header');
+  // The label keeps its width: squeezed to nothing was how it went missing.
+  inside(panelTitle.querySelector('.reqore-panel-title-label-row'), 'the panel label');
+  expect(
+    panelTitle.querySelector('.reqore-panel-title-label-row')!.getBoundingClientRect().width
+  ).toBeGreaterThan(100);
+  inside(
+    [...panelTitle.querySelectorAll('.reqore-button')].find((button) =>
+      (button.textContent || '').includes('Docs')
+    ) ?? null,
+    'the Docs action'
+  );
+  inside(form.querySelector('.options-readfirst-completion'), 'the completion meter');
+  // Every row's label and value.
+  const rows = [...form.querySelectorAll<HTMLElement>('.readfirst-row')];
+  expect(rows.length).toBeGreaterThan(0);
+  for (const row of rows) {
+    inside(row, `row ${row.dataset.field}`);
+  }
+};
+
+export const CompactWithPanelPropsPhone: Story = {
+  ...CompactWithPanelProps,
+  parameters: {
+    qlip: { viewport: { width: 390, height: 844 } },
+    docs: {
+      description: {
+        story:
+          'Compact With Panel Props on a 390px phone: the dressed panel header, its Docs action, the toolbar and every row fit the screen, the rows stack their values under their names, and nothing scrolls sideways.',
+      },
+    },
+  },
+  play: async ({ canvasElement }) => {
+    // The capture is taken at 390px after the play; the play narrows the
+    // viewport itself so it asserts the layout that is captured.
+    await _testsWithViewport(390, 844, async (narrowed) => {
+      await _testsWaitForText('Connection settings');
+      if (narrowed) {
+        await assertPanelPropsFitNarrowWidth(canvasElement);
+      }
+    });
+  },
+};
+
+export const CompactWithPanelPropsNarrow: Story = {
+  ...CompactWithPanelProps,
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Compact With Panel Props in a 360px column on a wide screen (a side panel or drawer): the same narrow layout as on a phone, decided by the width the form is given rather than by the screen.',
+      },
+    },
+  },
+  decorators: [
+    (StoryComponent: React.ComponentType) => (
+      <div style={{ maxWidth: 360, margin: '0 auto', border: '1px dashed #ffffff22' }}>
+        <StoryComponent />
+      </div>
+    ),
+  ],
+  play: async ({ canvasElement }) => {
+    await assertPanelPropsFitNarrowWidth(canvasElement);
+  },
+};
+
 export const CompactReadOnly: Story = {
   parameters: {
     docs: {
@@ -9354,3 +9448,258 @@ export const AReadOnlyFormShowsWhatIsWrong: Story = {
     });
   },
 };
+
+/** A form taller than its 400px scroller: one empty required field, a required
+ *  Owner that is set, and a dozen set fields below them. */
+const MovedRowSchema: IOptionsSchema = {
+  title: { type: 'string', display_name: 'Title', required: true },
+  owner: { type: 'string', display_name: 'Owner', required: true },
+  ...Object.fromEntries(
+    Array.from({ length: 12 }, (_, index) => [
+      `detail${index + 1}`,
+      { type: 'string', display_name: `Detail ${index + 1}` },
+    ])
+  ),
+};
+const MovedRowValue: IOptions = {
+  owner: { type: 'string', value: 'ops-team' },
+  ...Object.fromEntries(
+    Array.from({ length: 12 }, (_, index) => [
+      `detail${index + 1}`,
+      { type: 'string', value: `value ${index + 1}` },
+    ])
+  ),
+};
+
+/** Renders the form with buttons that change a value from outside it, the way a
+ *  host's save or a server update does — which is what moves a collapsed row. */
+const MovedRowRender = ({ onChange, ...rest }: IFormEngineProps) => {
+  const [val, setValue] = useState<IOptions>(MovedRowValue);
+  return (
+    <>
+      <button type='button' onClick={() => setValue((v) => ({ ...v, title: { type: 'string', value: 'Quarterly report' } }))}>
+        Fill title
+      </button>
+      <button type='button' onClick={() => setValue((v) => ({ ...v, owner: { type: 'string', value: '' } }))}>
+        Clear owner
+      </button>
+      <div style={{ height: 400, overflow: 'hidden', display: 'flex', flexFlow: 'column' }}>
+        <FormEngine
+          {...rest}
+          value={val}
+          onChange={(_n, v, m) => {
+            setValue(v as IOptions);
+            onChange?.(_n, v, m);
+          }}
+        />
+      </div>
+    </>
+  );
+};
+
+/** Counts `scrollIntoView` calls on rows while a play runs. */
+const watchRowScrolls = () => {
+  const original = HTMLElement.prototype.scrollIntoView;
+  const scrolled: string[] = [];
+  HTMLElement.prototype.scrollIntoView = function (this: HTMLElement, arg?: boolean | ScrollIntoViewOptions) {
+    scrolled.push(this.getAttribute('data-field') || '');
+    return original.call(this, arg);
+  };
+  return { scrolled, restore: () => (HTMLElement.prototype.scrollIntoView = original) };
+};
+
+const movedRowScroller = () =>
+  document.querySelector<HTMLElement>('.options-readfirst-scroll')!;
+const clickHostButton = (label: string) =>
+  fireEvent.click([...document.querySelectorAll('button')].find((b) => b.textContent === label)!);
+const nextFrame = () => new Promise<void>((resolve) => requestAnimationFrame(() => resolve()));
+
+export const AMovedRowInViewIsNotScrolled: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Title is empty, so it sits under Needs attention. "Fill title" sets it from outside the form, and the row moves into Set, where it is already in plain view. The form follows the row with a flash but does not scroll, because nothing needs bringing into view.',
+      },
+    },
+  },
+  render: MovedRowRender,
+  args: {
+    compact: true,
+    compactScroll: 'own' as const,
+    minColumnWidth: '300px',
+    options: MovedRowSchema,
+  },
+  play: async () => {
+    await _testsWaitForText('Needs attention');
+    const watch = watchRowScrolls();
+    try {
+      const scroller = movedRowScroller();
+      const before = scroller.scrollTop;
+      clickHostButton('Fill title');
+      // The move is followed by a flash in the frame the reveal runs in: wait
+      // for it, then one more frame so the reveal has certainly run.
+      await waitFor(() =>
+        expect(document.querySelector('.readfirst-row-flash[data-field="title"]')).toBeTruthy()
+      );
+      await nextFrame();
+      expect(watch.scrolled).not.toContain('title');
+      expect(scroller.scrollTop).toBe(before);
+    } finally {
+      watch.restore();
+    }
+  },
+};
+
+export const AMovedRowLandsClearOfThePinnedHeader: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'The form is scrolled to its end, then "Clear owner" empties Owner, so its row moves up into Needs attention, out of view. The form scrolls the least distance that shows it, and the row stops just below the pinned "Needs attention" header instead of underneath it.',
+      },
+    },
+  },
+  render: MovedRowRender,
+  args: {
+    compact: true,
+    compactScroll: 'own' as const,
+    minColumnWidth: '300px',
+    options: MovedRowSchema,
+  },
+  play: async () => {
+    await _testsWaitForText('Detail 12');
+    const scroller = movedRowScroller();
+    const scrollEnd = () =>
+      new Promise<void>((resolve) =>
+        scroller.addEventListener('scrollend', () => resolve(), { once: true })
+      );
+    // Even an instant scroll ends with a `scrollend`; consume it here, or it
+    // would be taken for the end of the reveal below.
+    const atBottom = scrollEnd();
+    scroller.scrollTop = scroller.scrollHeight;
+    await atBottom;
+    expect(scroller.scrollTop).toBeGreaterThan(0);
+    const watch = watchRowScrolls();
+    try {
+      // The reveal is a smooth scroll; its end is the `scrollend` event, armed
+      // before the click so it cannot be missed.
+      const scrolled = scrollEnd();
+      clickHostButton('Clear owner');
+      await waitFor(() => expect(watch.scrolled).toContain('owner'));
+      await scrolled;
+      const row = document.querySelector<HTMLElement>('.readfirst-row[data-field="owner"]')!;
+      const attention = [...document.querySelectorAll<HTMLElement>('.options-readfirst-group')].find(
+        (group) => (group.textContent || '').startsWith('Needs attention')
+      )!;
+      const header = attention.querySelector<HTMLElement>(':scope > .reqore-panel-title')!;
+      const rowRect = row.getBoundingClientRect();
+      const viewRect = scroller.getBoundingClientRect();
+      // Clear of the pinned header — and right below it, the least scroll that
+      // shows the row, not centred in the scroller — and inside the scroller.
+      const headerBottom = header.getBoundingClientRect().bottom;
+      expect(rowRect.top).toBeGreaterThanOrEqual(headerBottom - 1);
+      expect(rowRect.top).toBeLessThanOrEqual(headerBottom + 2);
+      expect(rowRect.bottom).toBeLessThanOrEqual(viewRect.bottom + 1);
+    } finally {
+      watch.restore();
+    }
+  },
+};
+
+/**
+ * Scrolls the form so the end of its Needs attention box passes up through the
+ * pinned toolbar, and asserts at each step that the toolbar stays on top: the
+ * box header pinned below it is pushed up as its box scrolls away, and must
+ * slide UNDER the toolbar, never over it. Each step waits on `scrollend`.
+ */
+const assertBoxHeaderSlidesUnderToolbar = async (scroller: HTMLElement) => {
+  await _testsWaitForText('Needs attention');
+  const toolbar = document.querySelector<HTMLElement>(
+    '.options-readfirst-scroll > .reqore-panel > .reqore-panel-title'
+  )!;
+  const box = [...document.querySelectorAll<HTMLElement>('.options-readfirst-group')].find(
+    (group) => (group.textContent || '').startsWith('Needs attention')
+  )!;
+  const header = box.querySelector<HTMLElement>(':scope > .reqore-panel-title')!;
+  const scrollBy = async (delta: number) => {
+    const ended = new Promise<void>((resolve) =>
+      scroller.addEventListener('scrollend', () => resolve(), { once: true })
+    );
+    scroller.scrollTop += delta;
+    await ended;
+  };
+  // Box fully in view first: its header sits clear below the toolbar.
+  expect(header.getBoundingClientRect().top).toBeGreaterThanOrEqual(
+    toolbar.getBoundingClientRect().bottom - 1
+  );
+  // Bring the end of the box up to the toolbar's bottom edge, then past it.
+  await scrollBy(box.getBoundingClientRect().bottom - toolbar.getBoundingClientRect().bottom);
+  for (const step of [12, 12, 12]) {
+    await scrollBy(step);
+    const toolbarRect = toolbar.getBoundingClientRect();
+    const headerRect = header.getBoundingClientRect();
+    // Where the pushed-up header and the toolbar overlap, the toolbar is on top.
+    const overlapTop = Math.max(toolbarRect.top, headerRect.top);
+    const overlapBottom = Math.min(toolbarRect.bottom, headerRect.bottom);
+    expect(overlapBottom).toBeGreaterThan(overlapTop);
+    const hit = document.elementFromPoint(
+      toolbarRect.left + toolbarRect.width / 2,
+      (overlapTop + overlapBottom) / 2
+    );
+    expect(toolbar.contains(hit), 'the toolbar is painted over the box header').toBe(true);
+  }
+};
+
+const StickyBoxesSchema: IOptionsSchema = {
+  ...MovedRowSchema,
+  summary: { type: 'string', display_name: 'Summary', required: true },
+  reviewer: { type: 'string', display_name: 'Reviewer', required: true },
+};
+
+const stickyBoxesStory = (layout: 'own' | 'host' | 'padded-host'): Story => ({
+  parameters: {
+    docs: {
+      description: {
+        story: `${
+          layout === 'own' ? 'The form owns its scroller'
+          : layout === 'host' ? 'The host scrolls the form'
+          : 'A padded host scrolls the form'
+        }. Scrolling the end of the Needs attention box up past the pinned toolbar pushes the box's pinned header up with it, and the header slides under the toolbar: the toolbar stays fully visible.`,
+      },
+    },
+  },
+  render: ({ value, ...rest }: IFormEngineProps) => (
+    <div
+      data-testid='sticky-host'
+      style={{
+        height: 420,
+        overflow: layout === 'own' ? 'hidden' : 'auto',
+        padding: layout === 'padded-host' ? 20 : 0,
+        display: 'flex',
+        flexFlow: 'column',
+      }}
+    >
+      <FormEngine {...rest} value={value} />
+    </div>
+  ),
+  args: {
+    compact: true,
+    compactScroll: layout === 'own' ? 'own' : 'host',
+    minColumnWidth: '300px',
+    options: StickyBoxesSchema,
+    value: MovedRowValue,
+  },
+  play: async () => {
+    await _testsWaitForText('Detail 12');
+    const scroller =
+      layout === 'own' ?
+        document.querySelector<HTMLElement>('.options-readfirst-scroll')!
+      : document.querySelector<HTMLElement>('[data-testid="sticky-host"]')!;
+    await assertBoxHeaderSlidesUnderToolbar(scroller);
+  },
+});
+
+export const BoxHeaderSlidesUnderToolbarOwnScroll: Story = stickyBoxesStory('own');
+export const BoxHeaderSlidesUnderToolbarHostScroll: Story = stickyBoxesStory('host');
+export const BoxHeaderSlidesUnderToolbarPaddedHost: Story = stickyBoxesStory('padded-host');

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

@@ -42,6 +42,7 @@ import { shouldMarkAsExpression } from '../expressions/argumentPresence';
 import { offersTypeChoices } from './typeChoices';
 import { optionRowActions, resolveOptionActions, TOptionActions } from './optionActions';
 import { createRendererOnlyUiTypeCheck, isRendererOnlyUiType } from './rendererTypes';
+import { revealRow } from './revealRow';
 import { cloneDeep, findKey, flatten, forEach, isEqual, isPlainObject, last, uniq } from 'lodash';
 import map from 'lodash/map';
 import reduce from 'lodash/reduce';
@@ -1520,8 +1521,15 @@ const FormEngineImpl = ({
         const target = compactWrapNodeRef.current?.querySelector<HTMLElement>(
           `.readfirst-row[data-field="${optionNames[0]}"]`
         );
-        if (typeof target?.scrollIntoView === 'function') {
-          target.scrollIntoView({ block: 'center', behavior: 'smooth' });
+        // Only when it is not already in view, and never under a pinned box
+        // header: `block: 'center'` scrolled a row that was in plain sight and
+        // centred it against the whole scrollport, so the header pinned at the
+        // top was drawn over it (see `revealRow`).
+        if (target) {
+          revealRow(
+            target,
+            window.matchMedia?.('(prefers-reduced-motion: reduce)')?.matches ? 'auto' : 'smooth'
+          );
         }
       });
     }
@@ -3826,6 +3834,16 @@ const FormEngineImpl = ({
                   // Keeps the wrapper from clipping, which is what a pinned box
                   // header inside it needs — see StyledCompactPanel.
                   $stickyBoxes={compactStickyBoxHeaders && !compactNested}
+                  // A narrow header the consumer dressed stacks its toolbar
+                  // under the label and actions (see StyledCompactPanel).
+                  $stackHeader={
+                    compactNarrow &&
+                    !!(
+                      compactPanelProps?.label ||
+                      compactPanelProps?.icon ||
+                      compactPanelProps?.actions?.length
+                    )
+                  }
                   flat
                   raised
                   minimal

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