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

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/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);
+  }
+};