@readme/markdown 13.8.0 → 13.8.2

package/README.md

@@ -125,9 +125,29 @@ To make changes to the RDMD engine locally, run the local development server. Cl
 
 If you make changes to the docs or how the markdown is rendered, you may need to update the visual regression snapshots by running `make updateSnapshot`. Running these browser tests requires `docker`. Follow the docker [install instructions for mac](https://docs.docker.com/docker-for-mac/install/). You may want to increase the [memory usage](https://docs.docker.com/docker-for-mac/#resources). If you have not already, you'll need to create an account for `docker hub` and [sign-in locally](https://docs.docker.com/docker-for-mac/#docker-hub).
 
+### Linking Changes to the Main Repo
+
+To test local changes in the main readme app, use `npm pack` (not `npm link`) and clear the webpack cache:
+
+**In this repo, run:**
+
+```
+npm run build && npm pack
+```
+
+**In the main app repo, run:**
+
+```
+npm install ../markdown/readme-markdown-<version>.tgz
+rm -rf webpack-cache
+make start
+```
+
+> **Note:** You must clear `webpack-cache` after every reinstall or the app will serve the old version.
+
 ### Linking Changes to Storybook
 
-There's currently some `babel` issues that prevent `npm link`ing to our main repo. `npm link`ing does work with our storybook app.
+`npm link` works with the storybook app:
 
 **In this repo, run:**
 

package/components/TableOfContents/index.tsx

@@ -17,6 +17,26 @@ function buildLinkMap(nav: HTMLElement) {
   return map;
 }
 
+const VISIBLE_RATIO = 0.4;
+/** Tolerance for subpixel rounding when checking if scrolled to the bottom. */
+const SCROLL_BOTTOM_TOLERANCE = 1;
+
+/**
+ * Walk up the DOM to find the nearest scrollable ancestor.
+ * Falls back to `window` when the page itself scrolls.
+ */
+function getScrollParent(el: HTMLElement): HTMLElement | Window {
+  let parent = el.parentElement;
+  while (parent) {
+    const { overflow, overflowY } = getComputedStyle(parent);
+    if (/(auto|scroll)/.test(overflow + overflowY) && parent.scrollHeight > parent.clientHeight) {
+      return parent;
+    }
+    parent = parent.parentElement;
+  }
+  return window;
+}
+
 /**
  * Watches headings in the viewport and toggles `active` on the
  * corresponding TOC links so the reader always knows where they are.
@@ -44,7 +64,16 @@ function useScrollHighlight(navRef: React.RefObject<HTMLElement | null>) {
     if (headings.length === 0) return undefined;
 
     let activeId: string | null = null;
+    let clickLocked = false;
     const visible = new Set<string>();
+    const scrollParent = getScrollParent(headings[0]);
+
+    const isAtBottom = () => {
+      if (scrollParent instanceof Window) {
+        return window.innerHeight + window.scrollY >= document.documentElement.scrollHeight - SCROLL_BOTTOM_TOLERANCE;
+      }
+      return scrollParent.scrollTop + scrollParent.clientHeight >= scrollParent.scrollHeight - SCROLL_BOTTOM_TOLERANCE;
+    };
 
     const activate = (id: string | null) => {
       if (id === activeId) return;
@@ -66,22 +95,69 @@ function useScrollHighlight(navRef: React.RefObject<HTMLElement | null>) {
       }
     };
 
+    const updateActive = () => {
+      if (clickLocked) return;
+
+      if (isAtBottom()) {
+        activate(headings[headings.length - 1].id);
+        return;
+      }
+
+      const topmost = headings.find(el => visible.has(el.id));
+      if (topmost) activate(topmost.id);
+    };
+
     const observer = new IntersectionObserver(
       entries => {
         entries.forEach(e => {
           if (e.isIntersecting) visible.add(e.target.id);
           else visible.delete(e.target.id);
         });
-        // Highlight the topmost visible heading; if none are visible,
-        // keep the last active one so the user still has context.
-        const topmost = headings.find(el => visible.has(el.id));
-        if (topmost) activate(topmost.id);
+        updateActive();
       },
-      { rootMargin: '0px 0px -60% 0px', threshold: 0 },
+      { rootMargin: `0px 0px -${(1 - VISIBLE_RATIO) * 100}% 0px`, threshold: 0 },
     );
 
+    // Check on scroll so bottom-of-page detection works even when
+    // no headings are crossing the intersection boundary.
+    const scrollTarget = scrollParent instanceof Window ? window : scrollParent;
+    const onScroll = () => { updateActive(); };
+
+    // Click a ToC link → immediately activate it, suppress the observer
+    // until the smooth scroll finishes, then hand control back.
+    const onClick = (e: MouseEvent) => {
+      const anchor = (e.target as HTMLElement).closest?.('a[href^="#"]');
+      if (!anchor) return;
+      const id = decodeURIComponent(anchor.getAttribute('href')!.slice(1));
+      if (!linkMap.has(id)) return;
+
+      e.preventDefault();
+      activate(id);
+      clickLocked = true;
+
+      const unlock = () => { clickLocked = false; };
+      scrollTarget.addEventListener('scrollend', unlock, { once: true });
+
+      document.getElementById(id)?.scrollIntoView({ behavior: 'smooth' });
+    };
+
     headings.forEach(el => { observer.observe(el); });
-    return () => { observer.disconnect(); };
+    scrollTarget.addEventListener('scroll', onScroll, { passive: true });
+    nav.addEventListener('click', onClick);
+
+    // Set initial active state for the first heading visible in the viewport,
+    // falling back to the first heading if none is in the observation zone yet.
+    const initialHeading = headings.find(el => {
+      const rect = el.getBoundingClientRect();
+      return rect.top >= 0 && rect.top < window.innerHeight * VISIBLE_RATIO;
+    }) || headings[0];
+    activate(initialHeading.id);
+
+    return () => {
+      observer.disconnect();
+      scrollTarget.removeEventListener('scroll', onScroll);
+      nav.removeEventListener('click', onClick);
+    };
   }, [navRef, linkCount]);
 }
 

package/dist/main.js

@@ -12087,6 +12087,24 @@ function buildLinkMap(nav) {
     });
     return map;
 }
+const VISIBLE_RATIO = 0.4;
+/** Tolerance for subpixel rounding when checking if scrolled to the bottom. */
+const SCROLL_BOTTOM_TOLERANCE = 1;
+/**
+ * Walk up the DOM to find the nearest scrollable ancestor.
+ * Falls back to `window` when the page itself scrolls.
+ */
+function getScrollParent(el) {
+    let parent = el.parentElement;
+    while (parent) {
+        const { overflow, overflowY } = getComputedStyle(parent);
+        if (/(auto|scroll)/.test(overflow + overflowY) && parent.scrollHeight > parent.clientHeight) {
+            return parent;
+        }
+        parent = parent.parentElement;
+    }
+    return window;
+}
 /**
  * Watches headings in the viewport and toggles `active` on the
  * corresponding TOC links so the reader always knows where they are.
@@ -12113,7 +12131,15 @@ function useScrollHighlight(navRef) {
         if (headings.length === 0)
             return undefined;
         let activeId = null;
+        let clickLocked = false;
         const visible = new Set();
+        const scrollParent = getScrollParent(headings[0]);
+        const isAtBottom = () => {
+            if (scrollParent instanceof Window) {
+                return window.innerHeight + window.scrollY >= document.documentElement.scrollHeight - SCROLL_BOTTOM_TOLERANCE;
+            }
+            return scrollParent.scrollTop + scrollParent.clientHeight >= scrollParent.scrollHeight - SCROLL_BOTTOM_TOLERANCE;
+        };
         const activate = (id) => {
             if (id === activeId)
                 return;
@@ -12133,6 +12159,17 @@ function useScrollHighlight(navRef) {
                 }
             }
         };
+        const updateActive = () => {
+            if (clickLocked)
+                return;
+            if (isAtBottom()) {
+                activate(headings[headings.length - 1].id);
+                return;
+            }
+            const topmost = headings.find(el => visible.has(el.id));
+            if (topmost)
+                activate(topmost.id);
+        };
         const observer = new IntersectionObserver(entries => {
             entries.forEach(e => {
                 if (e.isIntersecting)
@@ -12140,14 +12177,43 @@ function useScrollHighlight(navRef) {
                 else
                     visible.delete(e.target.id);
             });
-            // Highlight the topmost visible heading; if none are visible,
-            // keep the last active one so the user still has context.
-            const topmost = headings.find(el => visible.has(el.id));
-            if (topmost)
-                activate(topmost.id);
-        }, { rootMargin: '0px 0px -60% 0px', threshold: 0 });
+            updateActive();
+        }, { rootMargin: `0px 0px -${(1 - VISIBLE_RATIO) * 100}% 0px`, threshold: 0 });
+        // Check on scroll so bottom-of-page detection works even when
+        // no headings are crossing the intersection boundary.
+        const scrollTarget = scrollParent instanceof Window ? window : scrollParent;
+        const onScroll = () => { updateActive(); };
+        // Click a ToC link → immediately activate it, suppress the observer
+        // until the smooth scroll finishes, then hand control back.
+        const onClick = (e) => {
+            const anchor = e.target.closest?.('a[href^="#"]');
+            if (!anchor)
+                return;
+            const id = decodeURIComponent(anchor.getAttribute('href').slice(1));
+            if (!linkMap.has(id))
+                return;
+            e.preventDefault();
+            activate(id);
+            clickLocked = true;
+            const unlock = () => { clickLocked = false; };
+            scrollTarget.addEventListener('scrollend', unlock, { once: true });
+            document.getElementById(id)?.scrollIntoView({ behavior: 'smooth' });
+        };
         headings.forEach(el => { observer.observe(el); });
-        return () => { observer.disconnect(); };
+        scrollTarget.addEventListener('scroll', onScroll, { passive: true });
+        nav.addEventListener('click', onClick);
+        // Set initial active state for the first heading visible in the viewport,
+        // falling back to the first heading if none is in the observation zone yet.
+        const initialHeading = headings.find(el => {
+            const rect = el.getBoundingClientRect();
+            return rect.top >= 0 && rect.top < window.innerHeight * VISIBLE_RATIO;
+        }) || headings[0];
+        activate(initialHeading.id);
+        return () => {
+            observer.disconnect();
+            scrollTarget.removeEventListener('scroll', onScroll);
+            nav.removeEventListener('click', onClick);
+        };
     }, [navRef, linkCount]);
 }
 function TableOfContents({ children }) {
@@ -98719,25 +98785,31 @@ function makeVariableNode(varName, rawValue) {
 }
 /**
  * A remark plugin that parses {user.<field>} patterns from text nodes and
- * mdxTextExpression nodes, creating Variable nodes for runtime resolution.
+ * mdx expression nodes, creating Variable nodes for runtime resolution.
  *
- * Handles both:
+ * Handles:
  * - `text` nodes: when safeMode is true or after expression evaluation
  * - `mdxTextExpression` nodes: when mdxExpression has parsed {user.*} before evaluation
+ * - `mdxFlowExpression` nodes: when {user.*} appears on its own line (e.g. inside JSX table cells)
  *
  * Supports any user field: name, email, email_verified, exp, iat, etc.
  */
+function visitExpressionNode(node, index, parent) {
+    if (index === undefined || !parent)
+        return;
+    const wrapped = `{${(node.value ?? '').trim()}}`;
+    const matches = [...wrapped.matchAll(USER_VAR_REGEX)];
+    if (matches.length !== 1)
+        return;
+    const varName = matches[0][1] || matches[0][2];
+    parent.children.splice(index, 1, makeVariableNode(varName, wrapped));
+}
 const variablesTextTransformer = () => tree => {
-    // Handle mdxTextExpression nodes (e.g. {user.name} parsed by mdxExpression)
     visit(tree, 'mdxTextExpression', (node, index, parent) => {
-        if (index === undefined || !parent)
-            return;
-        const wrapped = `{${(node.value ?? '').trim()}}`; // Wrap the expression value in {} to match the USER_VAR_REGEX pattern
-        const matches = [...wrapped.matchAll(USER_VAR_REGEX)];
-        if (matches.length !== 1)
-            return;
-        const varName = matches[0][1] || matches[0][2];
-        parent.children.splice(index, 1, makeVariableNode(varName, wrapped));
+        visitExpressionNode(node, index, parent);
+    });
+    visit(tree, 'mdxFlowExpression', (node, index, parent) => {
+        visitExpressionNode(node, index, parent);
     });
     visit(tree, 'text', (node, index, parent) => {
         if (index === undefined || !parent)

package/dist/main.node.js

@@ -19670,14 +19670,14 @@ function getWindowScrollBarX(element) {
 }
 ;// ./node_modules/@popperjs/core/lib/dom-utils/getComputedStyle.js
 
-function getComputedStyle(element) {
+function getComputedStyle_getComputedStyle(element) {
   return getWindow(element).getComputedStyle(element);
 }
 ;// ./node_modules/@popperjs/core/lib/dom-utils/isScrollParent.js
 
 function isScrollParent(element) {
   // Firefox wants us to check `-x` and `-y` variations as well
-  var _getComputedStyle = getComputedStyle(element),
+  var _getComputedStyle = getComputedStyle_getComputedStyle(element),
       overflow = _getComputedStyle.overflow,
       overflowX = _getComputedStyle.overflowX,
       overflowY = _getComputedStyle.overflowY;
@@ -19849,7 +19849,7 @@ function isTableElement(element) {
 
 function getTrueOffsetParent(element) {
   if (!isHTMLElement(element) || // https://github.com/popperjs/popper-core/issues/837
-  getComputedStyle(element).position === 'fixed') {
+  getComputedStyle_getComputedStyle(element).position === 'fixed') {
     return null;
   }
 
@@ -19864,7 +19864,7 @@ function getContainingBlock(element) {
 
   if (isIE && isHTMLElement(element)) {
     // In IE 9, 10 and 11 fixed elements containing block is always established by the viewport
-    var elementCss = getComputedStyle(element);
+    var elementCss = getComputedStyle_getComputedStyle(element);
 
     if (elementCss.position === 'fixed') {
       return null;
@@ -19878,7 +19878,7 @@ function getContainingBlock(element) {
   }
 
   while (isHTMLElement(currentNode) && ['html', 'body'].indexOf(getNodeName(currentNode)) < 0) {
-    var css = getComputedStyle(currentNode); // This is non-exhaustive but covers the most common CSS properties that
+    var css = getComputedStyle_getComputedStyle(currentNode); // This is non-exhaustive but covers the most common CSS properties that
     // create a containing block.
     // https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block#identifying_the_containing_block
 
@@ -19898,11 +19898,11 @@ function getOffsetParent(element) {
   var window = getWindow(element);
   var offsetParent = getTrueOffsetParent(element);
 
-  while (offsetParent && isTableElement(offsetParent) && getComputedStyle(offsetParent).position === 'static') {
+  while (offsetParent && isTableElement(offsetParent) && getComputedStyle_getComputedStyle(offsetParent).position === 'static') {
     offsetParent = getTrueOffsetParent(offsetParent);
   }
 
-  if (offsetParent && (getNodeName(offsetParent) === 'html' || getNodeName(offsetParent) === 'body' && getComputedStyle(offsetParent).position === 'static')) {
+  if (offsetParent && (getNodeName(offsetParent) === 'html' || getNodeName(offsetParent) === 'body' && getComputedStyle_getComputedStyle(offsetParent).position === 'static')) {
     return window;
   }
 
@@ -20447,7 +20447,7 @@ function mapToStyles(_ref2) {
     if (offsetParent === getWindow(popper)) {
       offsetParent = getDocumentElement(popper);
 
-      if (getComputedStyle(offsetParent).position !== 'static' && position === 'absolute') {
+      if (getComputedStyle_getComputedStyle(offsetParent).position !== 'static' && position === 'absolute') {
         heightProp = 'scrollHeight';
         widthProp = 'scrollWidth';
       }
@@ -20759,7 +20759,7 @@ function getDocumentRect(element) {
   var x = -winScroll.scrollLeft + getWindowScrollBarX(element);
   var y = -winScroll.scrollTop;
 
-  if (getComputedStyle(body || html).direction === 'rtl') {
+  if (getComputedStyle_getComputedStyle(body || html).direction === 'rtl') {
     x += math_max(html.clientWidth, body ? body.clientWidth : 0) - width;
   }
 
@@ -20841,7 +20841,7 @@ function getClientRectFromMixedType(element, clippingParent, strategy) {
 
 function getClippingParents(element) {
   var clippingParents = listScrollParents(getParentNode(element));
-  var canEscapeClipping = ['absolute', 'fixed'].indexOf(getComputedStyle(element).position) >= 0;
+  var canEscapeClipping = ['absolute', 'fixed'].indexOf(getComputedStyle_getComputedStyle(element).position) >= 0;
   var clipperElement = canEscapeClipping && isHTMLElement(element) ? getOffsetParent(element) : element;
 
   if (!isElement(clipperElement)) {
@@ -24683,6 +24683,24 @@ function buildLinkMap(nav) {
     });
     return map;
 }
+const VISIBLE_RATIO = 0.4;
+/** Tolerance for subpixel rounding when checking if scrolled to the bottom. */
+const SCROLL_BOTTOM_TOLERANCE = 1;
+/**
+ * Walk up the DOM to find the nearest scrollable ancestor.
+ * Falls back to `window` when the page itself scrolls.
+ */
+function TableOfContents_getScrollParent(el) {
+    let parent = el.parentElement;
+    while (parent) {
+        const { overflow, overflowY } = getComputedStyle(parent);
+        if (/(auto|scroll)/.test(overflow + overflowY) && parent.scrollHeight > parent.clientHeight) {
+            return parent;
+        }
+        parent = parent.parentElement;
+    }
+    return window;
+}
 /**
  * Watches headings in the viewport and toggles `active` on the
  * corresponding TOC links so the reader always knows where they are.
@@ -24709,7 +24727,15 @@ function useScrollHighlight(navRef) {
         if (headings.length === 0)
             return undefined;
         let activeId = null;
+        let clickLocked = false;
         const visible = new Set();
+        const scrollParent = TableOfContents_getScrollParent(headings[0]);
+        const isAtBottom = () => {
+            if (scrollParent instanceof Window) {
+                return window.innerHeight + window.scrollY >= document.documentElement.scrollHeight - SCROLL_BOTTOM_TOLERANCE;
+            }
+            return scrollParent.scrollTop + scrollParent.clientHeight >= scrollParent.scrollHeight - SCROLL_BOTTOM_TOLERANCE;
+        };
         const activate = (id) => {
             if (id === activeId)
                 return;
@@ -24729,6 +24755,17 @@ function useScrollHighlight(navRef) {
                 }
             }
         };
+        const updateActive = () => {
+            if (clickLocked)
+                return;
+            if (isAtBottom()) {
+                activate(headings[headings.length - 1].id);
+                return;
+            }
+            const topmost = headings.find(el => visible.has(el.id));
+            if (topmost)
+                activate(topmost.id);
+        };
         const observer = new IntersectionObserver(entries => {
             entries.forEach(e => {
                 if (e.isIntersecting)
@@ -24736,14 +24773,43 @@ function useScrollHighlight(navRef) {
                 else
                     visible.delete(e.target.id);
             });
-            // Highlight the topmost visible heading; if none are visible,
-            // keep the last active one so the user still has context.
-            const topmost = headings.find(el => visible.has(el.id));
-            if (topmost)
-                activate(topmost.id);
-        }, { rootMargin: '0px 0px -60% 0px', threshold: 0 });
+            updateActive();
+        }, { rootMargin: `0px 0px -${(1 - VISIBLE_RATIO) * 100}% 0px`, threshold: 0 });
+        // Check on scroll so bottom-of-page detection works even when
+        // no headings are crossing the intersection boundary.
+        const scrollTarget = scrollParent instanceof Window ? window : scrollParent;
+        const onScroll = () => { updateActive(); };
+        // Click a ToC link → immediately activate it, suppress the observer
+        // until the smooth scroll finishes, then hand control back.
+        const onClick = (e) => {
+            const anchor = e.target.closest?.('a[href^="#"]');
+            if (!anchor)
+                return;
+            const id = decodeURIComponent(anchor.getAttribute('href').slice(1));
+            if (!linkMap.has(id))
+                return;
+            e.preventDefault();
+            activate(id);
+            clickLocked = true;
+            const unlock = () => { clickLocked = false; };
+            scrollTarget.addEventListener('scrollend', unlock, { once: true });
+            document.getElementById(id)?.scrollIntoView({ behavior: 'smooth' });
+        };
         headings.forEach(el => { observer.observe(el); });
-        return () => { observer.disconnect(); };
+        scrollTarget.addEventListener('scroll', onScroll, { passive: true });
+        nav.addEventListener('click', onClick);
+        // Set initial active state for the first heading visible in the viewport,
+        // falling back to the first heading if none is in the observation zone yet.
+        const initialHeading = headings.find(el => {
+            const rect = el.getBoundingClientRect();
+            return rect.top >= 0 && rect.top < window.innerHeight * VISIBLE_RATIO;
+        }) || headings[0];
+        activate(initialHeading.id);
+        return () => {
+            observer.disconnect();
+            scrollTarget.removeEventListener('scroll', onScroll);
+            nav.removeEventListener('click', onClick);
+        };
     }, [navRef, linkCount]);
 }
 function TableOfContents({ children }) {
@@ -118913,25 +118979,31 @@ function makeVariableNode(varName, rawValue) {
 }
 /**
  * A remark plugin that parses {user.<field>} patterns from text nodes and
- * mdxTextExpression nodes, creating Variable nodes for runtime resolution.
+ * mdx expression nodes, creating Variable nodes for runtime resolution.
  *
- * Handles both:
+ * Handles:
  * - `text` nodes: when safeMode is true or after expression evaluation
  * - `mdxTextExpression` nodes: when mdxExpression has parsed {user.*} before evaluation
+ * - `mdxFlowExpression` nodes: when {user.*} appears on its own line (e.g. inside JSX table cells)
  *
  * Supports any user field: name, email, email_verified, exp, iat, etc.
  */
+function visitExpressionNode(node, index, parent) {
+    if (index === undefined || !parent)
+        return;
+    const wrapped = `{${(node.value ?? '').trim()}}`;
+    const matches = [...wrapped.matchAll(USER_VAR_REGEX)];
+    if (matches.length !== 1)
+        return;
+    const varName = matches[0][1] || matches[0][2];
+    parent.children.splice(index, 1, makeVariableNode(varName, wrapped));
+}
 const variablesTextTransformer = () => tree => {
-    // Handle mdxTextExpression nodes (e.g. {user.name} parsed by mdxExpression)
     visit(tree, 'mdxTextExpression', (node, index, parent) => {
-        if (index === undefined || !parent)
-            return;
-        const wrapped = `{${(node.value ?? '').trim()}}`; // Wrap the expression value in {} to match the USER_VAR_REGEX pattern
-        const matches = [...wrapped.matchAll(USER_VAR_REGEX)];
-        if (matches.length !== 1)
-            return;
-        const varName = matches[0][1] || matches[0][2];
-        parent.children.splice(index, 1, makeVariableNode(varName, wrapped));
+        visitExpressionNode(node, index, parent);
+    });
+    visit(tree, 'mdxFlowExpression', (node, index, parent) => {
+        visitExpressionNode(node, index, parent);
     });
     visit(tree, 'text', (node, index, parent) => {
         if (index === undefined || !parent)