@astryxdesign/core 0.4.7 → 0.5.0-canary.54bb922

package/dist/Layer/useLayerDismissal.d.ts

@@ -0,0 +1,93 @@
+import { type LayerEscapeBehavior } from './layerStack';
+export type { LayerEscapeBehavior };
+export interface UseLayerDismissalOptions {
+    /**
+     * Whether this layer is participating right now. Usually the layer's open
+     * state. A layer whose open state lags the DOM should pass `true` for its
+     * lifetime and answer `isPresent` from the DOM instead.
+     */
+    isActive: boolean;
+    /**
+     * Dismiss this layer. Called by the stack when this layer is the one that
+     * should respond to an Escape press. Not called for `escapeBehavior: 'block'`.
+     */
+    onDismiss: () => void;
+    /**
+     * What this layer does with an Escape press that reaches it.
+     * @default 'close'
+     */
+    escapeBehavior?: LayerEscapeBehavior;
+    /**
+     * This layer's container element, read lazily. Optional: supply it when the
+     * layer cannot wrap its content in `LayerDepthProvider` (a bare focus trap
+     * renders nothing), so nesting can still be recovered from the DOM.
+     */
+    getContainer?: () => HTMLElement | null;
+    /**
+     * Whether the layer is really on screen, asked at press time. Supply it when
+     * `isActive` is `true` for the layer's lifetime because its open state lags
+     * the DOM by a frame; the stack skips layers that answer `false`.
+     */
+    isPresent?: () => boolean;
+    /**
+     * Whether this layer takes part in the shared stack at all. When `false` the
+     * layer is invisible to dismissal: a press flows past it to the layer below,
+     * exactly as if it were not open.
+     *
+     * Deliberately separate from `escapeBehavior: 'block'` — `'block'` is a layer
+     * that is present and swallows the press; this is a layer that is not there
+     * at all. One case uses it: `Dialog`'s inline rendering mode, where content
+     * sits in normal flow with nothing layered over anything.
+     *
+     * A controlled layer is NOT one of these. It stays registered and takes the
+     * press like any other, answering it by calling the consumer's change
+     * handler; whether it then closes is the consumer's decision.
+     *
+     * Layers that are never Escape-dismissible (toasts) should simply not call
+     * this hook.
+     *
+     * @default true
+     */
+    isEnabled?: boolean;
+}
+export interface UseLayerDismissalReturn {
+    /**
+     * Whether a close request the browser started on its own — a `<dialog>`'s
+     * `cancel`, the Android back gesture, the platform close watcher — should
+     * dismiss this layer. As well as the top-most rule the stack applies to an
+     * Escape press, it declines a request that arrives while an IME composition
+     * is running, which no `cancel` handler can tell on its own because the
+     * event carries no composition state.
+     */
+    shouldDismissOnCloseRequest: () => boolean;
+}
+/**
+ * Join the shared layer dismissal stack for as long as this layer is active.
+ *
+ * The layer does NOT attach a key listener — the stack owns one listener and
+ * routes each Escape press to the top-most REGISTERED layer, so one press
+ * dismisses exactly one of them. Dialog (and what is built on it), Popover and
+ * the menus built on it, Tooltip, HoverCard, Lightbox and MobileNav register
+ * today; `BottomSheetSwitcher` registers through its focus trap when modal and
+ * still handles its own press when not.
+ *
+ * `BottomSheet`, `CommandPalette`, `ContextMenu`, `DropdownMenuSubMenu`,
+ * `PowerSearchEditPopover` and lab's `Drawer` still run their own Escape
+ * listener. They stay safe next to the stack only because each claims the press
+ * at element level, and the stack stands down on an already-`defaultPrevented`
+ * press — but a registered layer opened INSIDE one of them does not get the
+ * press: the host takes it and closes instead. Migrating them is the fix.
+ *
+ * Wrap the layer's own content in `LayerDepthProvider` so anything opened from
+ * inside it registers as nested.
+ *
+ * @example
+ * ```tsx
+ * useLayerDismissal({
+ *   isActive: isOpen,
+ *   onDismiss: () => onOpenChange(false),
+ * });
+ * ```
+ */
+export declare function useLayerDismissal(options: UseLayerDismissalOptions): UseLayerDismissalReturn;
+//# sourceMappingURL=useLayerDismissal.d.ts.map

package/dist/Layer/useLayerDismissal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useLayerDismissal.d.ts","sourceRoot":"","sources":["../../src/Layer/useLayerDismissal.ts"],"names":[],"mappings":"AAqBA,OAAO,EAIL,KAAK,mBAAmB,EACzB,MAAM,cAAc,CAAC;AAEtB,YAAY,EAAC,mBAAmB,EAAC,CAAC;AAElC,MAAM,WAAW,wBAAwB;IACvC;;;;OAIG;IACH,QAAQ,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,SAAS,EAAE,MAAM,IAAI,CAAC;IACtB;;;OAGG;IACH,cAAc,CAAC,EAAE,mBAAmB,CAAC;IACrC;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,WAAW,GAAG,IAAI,CAAC;IACxC;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC;IAC1B;;;;;;;;;;;;;;;;;;OAkBG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,uBAAuB;IACtC;;;;;;;OAOG;IACH,2BAA2B,EAAE,MAAM,OAAO,CAAC;CAC5C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,wBAAwB,GAChC,uBAAuB,CAiDzB"}

package/dist/Layer/useLayerDismissal.js

@@ -0,0 +1,91 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useLayerDismissal.ts
+ * @input Uses React hooks, the layer stack, and LayerDepthContext
+ * @output Exports useLayerDismissal + its option/return types
+ * @position The API overlays use to join the shared dismissal stack. Wraps
+ *   layerStack (registration + the single Escape listener) and reads nesting
+ *   depth from LayerDepthContext.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/Layer/index.ts
+ * - /packages/core/src/Layer/useLayerDismissal.test.tsx
+ * - /packages/core/src/Layer/layerStack.ts
+ */
+import { useCallback, useEffect, useRef } from 'react';
+import { useLayerDepth } from "./LayerDepthContext.js";
+import { isTextComposing, isTopmostLayer, registerLayer } from "./layerStack.js";
+/**
+ * Join the shared layer dismissal stack for as long as this layer is active.
+ *
+ * The layer does NOT attach a key listener — the stack owns one listener and
+ * routes each Escape press to the top-most REGISTERED layer, so one press
+ * dismisses exactly one of them. Dialog (and what is built on it), Popover and
+ * the menus built on it, Tooltip, HoverCard, Lightbox and MobileNav register
+ * today; `BottomSheetSwitcher` registers through its focus trap when modal and
+ * still handles its own press when not.
+ *
+ * `BottomSheet`, `CommandPalette`, `ContextMenu`, `DropdownMenuSubMenu`,
+ * `PowerSearchEditPopover` and lab's `Drawer` still run their own Escape
+ * listener. They stay safe next to the stack only because each claims the press
+ * at element level, and the stack stands down on an already-`defaultPrevented`
+ * press — but a registered layer opened INSIDE one of them does not get the
+ * press: the host takes it and closes instead. Migrating them is the fix.
+ *
+ * Wrap the layer's own content in `LayerDepthProvider` so anything opened from
+ * inside it registers as nested.
+ *
+ * @example
+ * ```tsx
+ * useLayerDismissal({
+ *   isActive: isOpen,
+ *   onDismiss: () => onOpenChange(false),
+ * });
+ * ```
+ */
+export function useLayerDismissal(options) {
+  const {
+    isActive,
+    onDismiss,
+    escapeBehavior = 'close',
+    getContainer,
+    isPresent,
+    isEnabled = true
+  } = options;
+  const depth = useLayerDepth();
+
+  // Identity for this layer's stack entry, stable across re-registration.
+  const tokenRef = useRef({});
+
+  // The stack calls these during an event, outside React's render, so they must
+  // reach the latest closures rather than the ones captured at registration.
+  const onDismissRef = useRef(onDismiss);
+  const getContainerRef = useRef(getContainer);
+  const isPresentRef = useRef(isPresent);
+  useEffect(() => {
+    onDismissRef.current = onDismiss;
+    getContainerRef.current = getContainer;
+    isPresentRef.current = isPresent;
+  });
+  const isRegistered = isActive && isEnabled;
+  useEffect(() => {
+    if (!isRegistered) {
+      return;
+    }
+    return registerLayer({
+      token: tokenRef.current,
+      depth,
+      behavior: escapeBehavior,
+      getContainer: () => getContainerRef.current?.() ?? null,
+      isPresent: () => isPresentRef.current?.() ?? true,
+      dismiss: () => onDismissRef.current()
+    });
+  }, [isRegistered, depth, escapeBehavior]);
+  const shouldDismissOnCloseRequest = useCallback(() => isRegistered && !isTextComposing() && isTopmostLayer(tokenRef.current), [isRegistered]);
+  return {
+    shouldDismissOnCloseRequest
+  };
+}

package/dist/Lightbox/Lightbox.d.ts

@@ -8,6 +8,7 @@
  * - /packages/core/src/Lightbox/Lightbox.doc.mjs (props table, features, implementation notes)
  * - /packages/core/src/Lightbox/Lightbox.test.tsx (tests for new/changed behavior)
  * - /packages/core/src/Lightbox/index.ts (exports if types change)
+ * - /packages/core/src/Layer/useLayerDismissal.ts (dismissal stack)
  * - /apps/storybook/stories/Lightbox.stories.tsx (storybook stories)
  * - /packages/cli/assets/templates/blocks/components/Lightbox/ (showcase blocks)
  */

package/dist/Lightbox/Lightbox.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Lightbox.d.ts","sourceRoot":"","sources":["../../src/Lightbox/Lightbox.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAOL,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AASf,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAM5C;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,OAAO,CAAC;AAElD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,uBAAuB;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,gEAAgE;IAChE,GAAG,EAAE,MAAM,CAAC;IACZ,iDAAiD;IACjD,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB;;;OAGG;IACH,IAAI,CAAC,EAAE,iBAAiB,CAAC;CAC1B;AAED,MAAM,WAAW,aAAc,SAAQ,SAAS,CAAC,iBAAiB,CAAC;IACjE,+CAA+C;IAC/C,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;IACnC;;OAEG;IACH,MAAM,EAAE,OAAO,CAAC;IAChB;;;OAGG;IACH,YAAY,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IACxC;;;OAGG;IACH,KAAK,EAAE,aAAa,GAAG,aAAa,EAAE,CAAC;IACvC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;OAEG;IACH,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AA+JD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,QAAQ,CAAC,EACvB,MAAM,EACN,YAAY,EACZ,KAAK,EACL,KAAK,EAAE,eAAe,EACtB,YAAgB,EAChB,aAAa,EACb,OAAe,EACf,WAAmB,EACnB,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,OAAO,EAAE,WAAW,EACpB,SAAS,EAAE,aAAa,EACxB,GAAG,KAAK,EACT,EAAE,aAAa,sCA6Yf;yBA7Ze,QAAQ"}
+{"version":3,"file":"Lightbox.d.ts","sourceRoot":"","sources":["../../src/Lightbox/Lightbox.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAOL,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AASf,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAS5C;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,OAAO,CAAC;AAElD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,uBAAuB;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,gEAAgE;IAChE,GAAG,EAAE,MAAM,CAAC;IACZ,iDAAiD;IACjD,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB;;;OAGG;IACH,IAAI,CAAC,EAAE,iBAAiB,CAAC;CAC1B;AAED,MAAM,WAAW,aAAc,SAAQ,SAAS,CAAC,iBAAiB,CAAC;IACjE,+CAA+C;IAC/C,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;IACnC;;OAEG;IACH,MAAM,EAAE,OAAO,CAAC;IAChB;;;OAGG;IACH,YAAY,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IACxC;;;OAGG;IACH,KAAK,EAAE,aAAa,GAAG,aAAa,EAAE,CAAC;IACvC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;OAEG;IACH,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AA+JD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,QAAQ,CAAC,EACvB,MAAM,EACN,YAAY,EACZ,KAAK,EACL,KAAK,EAAE,eAAe,EACtB,YAAgB,EAChB,aAAa,EACb,OAAe,EACf,WAAmB,EACnB,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,OAAO,EAAE,WAAW,EACpB,SAAS,EAAE,aAAa,EACxB,GAAG,KAAK,EACT,EAAE,aAAa,sCA+Zf;yBA/ae,QAAQ"}

package/dist/Lightbox/Lightbox.js

@@ -12,6 +12,7 @@
  * - /packages/core/src/Lightbox/Lightbox.doc.mjs (props table, features, implementation notes)
  * - /packages/core/src/Lightbox/Lightbox.test.tsx (tests for new/changed behavior)
  * - /packages/core/src/Lightbox/index.ts (exports if types change)
+ * - /packages/core/src/Layer/useLayerDismissal.ts (dismissal stack)
  * - /apps/storybook/stories/Lightbox.stories.tsx (storybook stories)
  * - /packages/cli/assets/templates/blocks/components/Lightbox/ (showcase blocks)
  */
@@ -24,12 +25,14 @@ import { IconButton } from "../IconButton/index.js";
 import { useAnnounce } from "../hooks/useAnnounce.js";
 import { useScrollLock } from "../hooks/useScrollLock.js";
 import { useIsomorphicLayoutEffect } from "../hooks/useIsomorphicLayoutEffect.js";
-import { mergeProps, mergeRefs, rtlStyles } from "../utils/index.js";
+import { mergeProps, rtlStyles } from "../utils/index.js";
 import { themeProps } from "../utils/themeProps.js";
 import { focusOutlineStyles } from "../utils/focusOutline.stylex.js";
 import { overlayPaddingReset } from "../Layout/padding.stylex.js";
+import { LayerDepthProvider } from "../Layer/LayerDepthContext.js";
+import { useLayerDismissal } from "../Layer/useLayerDismissal.js";
 import { useTranslator } from "../i18n/index.js";
-
+import { useMergedRefs } from "../hooks/useMergedRefs.js";
 /**
  * Media type for lightbox items.
  */
@@ -198,6 +201,7 @@ export function Lightbox({
 }) {
   const t = useTranslator();
   const dialogRef = useRef(null);
+  const mergedDialogRef = useMergedRefs(ref, dialogRef);
   const containerRef = useRef(null);
   const imageWrapperRef = useRef(null);
   const triggerElementRef = useRef(null);
@@ -299,12 +303,28 @@ export function Lightbox({
   const handleClose = useCallback(() => {
     onOpenChange(false);
   }, [onOpenChange]);
+  const {
+    shouldDismissOnCloseRequest
+  } = useLayerDismissal({
+    isActive: isOpen,
+    onDismiss: handleClose
+  });
 
-  // Escape key
+  // The native `cancel` event is the browser's own close-watcher firing: an
+  // Android back gesture, or a close request the stack never saw a press for.
+  // Escape presses the stack owns never arrive here — it preventDefault()s
+  // those, which suppresses the close watcher.
+  //
+  // Always preventDefault so the browser cannot close a controlled <dialog>
+  // behind React's back, then answer with the stack's own rules: top-most
+  // only, and never while an IME composition is in progress.
   const handleCancel = useCallback(e => {
     e.preventDefault();
+    if (!shouldDismissOnCloseRequest()) {
+      return;
+    }
     handleClose();
-  }, [handleClose]);
+  }, [handleClose, shouldDismissOnCloseRequest]);
 
   // Backdrop click. The layout container fills the whole transparent dialog,
   // so clicks on the visual backdrop (the dark area around the media) land on
@@ -438,7 +458,7 @@ export function Lightbox({
     return null;
   }
   return /*#__PURE__*/_jsx("dialog", {
-    ref: mergeRefs(ref, dialogRef),
+    ref: mergedDialogRef,
     onCancel: handleCancel,
     onClick: e => {
       handleBackdropClick(e);
@@ -451,88 +471,90 @@ export function Lightbox({
     "aria-label": currentItem.alt || t('@astryx.lightbox.mediaViewer'),
     ...mergeProps(themeProps('lightbox'), stylex.props(styles.dialog, overlayPaddingReset.reset, xstyle), className, style),
     ...props,
-    children: /*#__PURE__*/_jsxs("div", {
-      ref: containerRef,
-      ...{
-        className: "x78zum5 xdt5ytf x6s0dn4 xl56j7k xh8yej3 x5yr21d x1n2onr6"
-      },
-      children: [/*#__PURE__*/_jsx(IconButton, {
-        icon: /*#__PURE__*/_jsx(Icon, {
-          icon: "close",
-          size: "sm",
-          color: "inherit"
-        }),
-        label: t('@astryx.lightbox.close'),
-        variant: "ghost",
-        onClick: handleClose,
-        xstyle: [styles.closeButton, styles.controlButton]
-      }), isGallery && /*#__PURE__*/_jsx(IconButton, {
-        icon: /*#__PURE__*/_jsx(Icon, {
-          icon: "chevronLeft",
-          size: "sm",
-          color: "inherit",
-          xstyle: rtlStyles.mirror
-        }),
-        label: t('@astryx.lightbox.previous'),
-        variant: "ghost",
-        isDisabled: !canPrev,
-        onClick: goToPrev,
-        xstyle: [styles.navButton, styles.navPrev, styles.controlButton]
-      }), /*#__PURE__*/_jsxs("div", {
+    children: /*#__PURE__*/_jsx(LayerDepthProvider, {
+      children: /*#__PURE__*/_jsxs("div", {
+        ref: containerRef,
         ...{
-          className: "x78zum5 xdt5ytf x6s0dn4 x193iq5w xmz0i5r xb3r6kr"
+          className: "x78zum5 xdt5ytf x6s0dn4 xl56j7k xh8yej3 x5yr21d x1n2onr6"
         },
-        children: [/*#__PURE__*/_jsx("div", {
-          ref: imageWrapperRef
-          // The wrapper is a keyboard-operable zoom toggle when zoom is
-          // enabled: Enter/Space toggles, aria-pressed reflects state.
-          ,
-          role: isZoomTarget ? 'button' : undefined,
-          tabIndex: isZoomTarget ? 0 : undefined,
-          "aria-pressed": isZoomTarget ? isZoomed : undefined,
-          "aria-label": isZoomTarget ? t('@astryx.lightbox.zoom') : undefined,
-          ...stylex.props(styles.imageWrapper, isZoomTarget && focusOutlineStyles.focusVisible, !isVideo && hasZoom && !isZoomed && styles.imageWrapperZoomable, !isVideo && isZoomed && styles.imageWrapperZoomed, !isVideo && isDragging && styles.imageWrapperDragging),
-          onDoubleClick: isVideo ? undefined : handleDoubleClick,
-          onKeyDown: isZoomTarget ? handleImageKeyDown : undefined,
-          onPointerDown: isVideo ? undefined : handlePointerDown,
-          children: isVideo ? /*#__PURE__*/_jsx("video", {
-            src: currentItem.src,
-            "aria-label": currentItem.alt,
-            controls: true,
-            autoPlay: hasAutoPlay,
+        children: [/*#__PURE__*/_jsx(IconButton, {
+          icon: /*#__PURE__*/_jsx(Icon, {
+            icon: "close",
+            size: "sm",
+            color: "inherit"
+          }),
+          label: t('@astryx.lightbox.close'),
+          variant: "ghost",
+          onClick: handleClose,
+          xstyle: [styles.closeButton, styles.controlButton]
+        }), isGallery && /*#__PURE__*/_jsx(IconButton, {
+          icon: /*#__PURE__*/_jsx(Icon, {
+            icon: "chevronLeft",
+            size: "sm",
+            color: "inherit",
+            xstyle: rtlStyles.mirror
+          }),
+          label: t('@astryx.lightbox.previous'),
+          variant: "ghost",
+          isDisabled: !canPrev,
+          onClick: goToPrev,
+          xstyle: [styles.navButton, styles.navPrev, styles.controlButton]
+        }), /*#__PURE__*/_jsxs("div", {
+          ...{
+            className: "x78zum5 xdt5ytf x6s0dn4 x193iq5w xmz0i5r xb3r6kr"
+          },
+          children: [/*#__PURE__*/_jsx("div", {
+            ref: imageWrapperRef
+            // The wrapper is a keyboard-operable zoom toggle when zoom is
+            // enabled: Enter/Space toggles, aria-pressed reflects state.
+            ,
+            role: isZoomTarget ? 'button' : undefined,
+            tabIndex: isZoomTarget ? 0 : undefined,
+            "aria-pressed": isZoomTarget ? isZoomed : undefined,
+            "aria-label": isZoomTarget ? t('@astryx.lightbox.zoom') : undefined,
+            ...stylex.props(styles.imageWrapper, isZoomTarget && focusOutlineStyles.focusVisible, !isVideo && hasZoom && !isZoomed && styles.imageWrapperZoomable, !isVideo && isZoomed && styles.imageWrapperZoomed, !isVideo && isDragging && styles.imageWrapperDragging),
+            onDoubleClick: isVideo ? undefined : handleDoubleClick,
+            onKeyDown: isZoomTarget ? handleImageKeyDown : undefined,
+            onPointerDown: isVideo ? undefined : handlePointerDown,
+            children: isVideo ? /*#__PURE__*/_jsx("video", {
+              src: currentItem.src,
+              "aria-label": currentItem.alt,
+              controls: true,
+              autoPlay: hasAutoPlay,
+              ...{
+                className: "x193iq5w xmz0i5r x19kjcj4 x1a2a7pz"
+              }
+            }) : /*#__PURE__*/_jsx("img", {
+              src: currentItem.src,
+              alt: currentItem.alt,
+              draggable: false,
+              ...stylex.props(styles.image, isDragging && styles.imageDragging, imageTransform != null && dynamicStyles.imageTransform(imageTransform))
+            })
+          }), currentItem.caption && /*#__PURE__*/_jsx("div", {
             ...{
-              className: "x193iq5w xmz0i5r x19kjcj4 x1a2a7pz"
-            }
-          }) : /*#__PURE__*/_jsx("img", {
-            src: currentItem.src,
-            alt: currentItem.alt,
-            draggable: false,
-            ...stylex.props(styles.image, isDragging && styles.imageDragging, imageTransform != null && dynamicStyles.imageTransform(imageTransform))
-          })
-        }), currentItem.caption && /*#__PURE__*/_jsx("div", {
+              className: "x9e3rv5 x18juvz8 xf74fhv x2b8uid x1xye8es x18d9i69 xrrkdod xrlsmeg x2lah0s"
+            },
+            children: currentItem.caption
+          })]
+        }), isGallery && /*#__PURE__*/_jsx(IconButton, {
+          icon: /*#__PURE__*/_jsx(Icon, {
+            icon: "chevronRight",
+            size: "sm",
+            color: "inherit",
+            xstyle: rtlStyles.mirror
+          }),
+          label: t('@astryx.lightbox.next'),
+          variant: "ghost",
+          isDisabled: !canNext,
+          onClick: goToNext,
+          xstyle: [styles.navButton, styles.navNext, styles.controlButton]
+        }), isGallery && mediaArray.length > 1 && /*#__PURE__*/_jsxs("div", {
           ...{
-            className: "x9e3rv5 x18juvz8 xf74fhv x2b8uid x1xye8es x18d9i69 xrrkdod xrlsmeg x2lah0s"
+            className: "x10l6tqk xyx6v2t x1ybfrjj x9e3rv5 xjm74w1 xw6l6zx x1vjfegm"
           },
-          children: currentItem.caption
+          children: [index + 1, " / ", mediaArray.length]
         })]
-      }), isGallery && /*#__PURE__*/_jsx(IconButton, {
-        icon: /*#__PURE__*/_jsx(Icon, {
-          icon: "chevronRight",
-          size: "sm",
-          color: "inherit",
-          xstyle: rtlStyles.mirror
-        }),
-        label: t('@astryx.lightbox.next'),
-        variant: "ghost",
-        isDisabled: !canNext,
-        onClick: goToNext,
-        xstyle: [styles.navButton, styles.navNext, styles.controlButton]
-      }), isGallery && mediaArray.length > 1 && /*#__PURE__*/_jsxs("div", {
-        ...{
-          className: "x10l6tqk xyx6v2t x1ybfrjj x9e3rv5 xjm74w1 xw6l6zx x1vjfegm"
-        },
-        children: [index + 1, " / ", mediaArray.length]
-      })]
+      })
     })
   });
 }

package/dist/Markdown/index.d.ts

@@ -6,5 +6,5 @@
 export { Markdown } from './Markdown';
 export type { MarkdownProps, MarkdownSource, MarkdownComponents, MarkdownInlinePlugin, } from './Markdown';
 export { parseMarkdown, parseMarkdownIncremental, createIncrementalState, parseInline, } from './parser';
-export type { BlockNode, InlineNode, ListItemNode, TableCellNode, TableAlignment, IncrementalState as IncrementalParseState, } from './parser';
+export type { BlockNode, InlineNode, SourceRange, ListItemNode, TableCellNode, TableAlignment, IncrementalState as IncrementalParseState, } from './parser';
 //# sourceMappingURL=index.d.ts.map

package/dist/Markdown/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/Markdown/index.ts"],"names":[],"mappings":"AAIA;;;;GAIG;AAEH,OAAO,EAAC,QAAQ,EAAC,MAAM,YAAY,CAAC;AACpC,YAAY,EACV,aAAa,EACb,cAAc,EACd,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,aAAa,EACb,wBAAwB,EACxB,sBAAsB,EACtB,WAAW,GACZ,MAAM,UAAU,CAAC;AAClB,YAAY,EACV,SAAS,EACT,UAAU,EACV,YAAY,EACZ,aAAa,EACb,cAAc,EACd,gBAAgB,IAAI,qBAAqB,GAC1C,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/Markdown/index.ts"],"names":[],"mappings":"AAIA;;;;GAIG;AAEH,OAAO,EAAC,QAAQ,EAAC,MAAM,YAAY,CAAC;AACpC,YAAY,EACV,aAAa,EACb,cAAc,EACd,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,aAAa,EACb,wBAAwB,EACxB,sBAAsB,EACtB,WAAW,GACZ,MAAM,UAAU,CAAC;AAClB,YAAY,EACV,SAAS,EACT,UAAU,EACV,WAAW,EACX,YAAY,EACZ,aAAa,EACb,cAAc,EACd,gBAAgB,IAAI,qBAAqB,GAC1C,MAAM,UAAU,CAAC"}

package/dist/Markdown/parser.d.ts

@@ -35,7 +35,14 @@ export type InlineNode = {
 } | {
     type: 'break';
 };
-export type BlockNode = {
+export type BlockNode = BlockNodeKind & {
+    /**
+     * Where this block came from in the source, when parsed with the
+     * `sourceRanges` option. Top-level blocks only.
+     */
+    range?: SourceRange;
+};
+type BlockNodeKind = {
     type: 'heading';
     level: 1 | 2 | 3 | 4 | 5 | 6;
     children: InlineNode[];
@@ -69,6 +76,19 @@ export type BlockNode = {
     src: string;
     alt: string;
 };
+/**
+ * Where a block sits in the source string handed to `parseMarkdown`:
+ * `source.slice(start, end)` is the block, and `end` excludes the block's
+ * trailing blank lines.
+ *
+ * An object rather than a `[start, end]` tuple so a second way of addressing
+ * the same block — line numbers, once a consumer needs them — can be added as
+ * optional fields without breaking anyone.
+ */
+export type SourceRange = {
+    readonly start: number;
+    readonly end: number;
+};
 export type ListItemNode = {
     checked?: boolean;
     children: BlockNode[];
@@ -100,6 +120,16 @@ export type ParseOptions = {
      * suffix is not rejected (Astryx accepts any plausible TLD shape).
      */
     autolink?: 'gfm';
+    /**
+     * When true, every top-level block carries a `range` — the offsets it
+     * occupies in the string passed in. Lets a consumer that still holds the
+     * source slice the original markdown for a block instead of reconstructing
+     * it from the parsed node (or from the rendered DOM). Off by default: the
+     * field is absent unless asked for, so nothing that compares nodes changes.
+     *
+     * Blocks nested inside a list item or a blockquote do not carry one.
+     */
+    sourceRanges?: boolean;
 };
 export declare function parseInline(text: string, sourceIds?: ReadonlySet<string>): InlineNode[];
 export declare function parseInline(text: string, options: ParseOptions): InlineNode[];
@@ -117,6 +147,12 @@ export interface IncrementalState {
      * with newly-arriving content.
      */
     autolink?: 'gfm';
+    /**
+     * The `sourceRanges` option the cached `settledBlocks` were parsed with.
+     * Flipping it invalidates them the same way `autolink` does: they either
+     * lack the ranges the caller now asks for, or carry ones it did not.
+     */
+    sourceRanges?: boolean;
     /**
      * Signature of the link reference definitions the cached `settledBlocks`
      * were parsed with. Definitions are document-global and typically arrive
@@ -143,4 +179,5 @@ export declare function slugify(value: string): string;
  * document shares a single numbering sequence.
  */
 export declare function uniqueSlug(baseSlug: string, counts: Map<string, number>): string;
+export {};
 //# sourceMappingURL=parser.d.ts.map

package/dist/Markdown/parser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/Markdown/parser.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/Markdown/parser.ts"],"names":[],"mappings":"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"}