@astryxdesign/core 0.4.0 → 0.4.1-canary.1ce0b4c

package/src/Layer/useLayer.tsx

@@ -25,7 +25,9 @@ import React, {
 } from 'react';
 import * as stylex from '@stylexjs/stylex';
 import type {StyleXStyles} from '@stylexjs/stylex';
+import {createPortal} from 'react-dom';
 import {addAnchorName, removeAnchorName} from './anchorName';
+import {resolveLayerPortalTarget} from './layerHost';
 import {typographyVars} from '../theme/tokens.stylex';
 
 const styles = stylex.create({
@@ -149,12 +151,11 @@ export interface ContextRenderProps {
   /**
    * HTML tag to render the popover container as.
    *
-   * Defaults to `'div'`. Pass `'span'` when the layer must render inline-safe
-   * markup — e.g. a `HoverCard` wrapping inline text inside a `<p>`. A `<span>`
-   * is phrasing content, so it stays put in the DOM tree instead of being
-   * reparented out of a paragraph by the HTML parser, which keeps server and
-   * client markup identical. The Popover API and CSS anchor positioning work
-   * the same on either tag.
+   * Defaults to `'div'`. Context layers render an inert `<template>` marker at
+   * the JSX position. The marker's parent is checked before the requested
+   * container mounts there or portals outside ancestors that cannot safely
+   * contain it. The marker remains available to detect a new parent if the
+   * render call moves. With `lazyMount`, the first check waits until `show()`.
    *
    * @default 'div'
    */
@@ -222,6 +223,15 @@ interface BaseLayerOptions {
  */
 export interface ContextLayerOptions extends BaseLayerOptions {
   mode: 'context';
+  /**
+   * Defer mounting the final layer and resolving its inline/portal position
+   * until `show()` is requested. Hiding unmounts it while the inert marker
+   * remains at the JSX position. Use this when rich content must never enter
+   * an unsafe ancestor, even briefly, and does not need to exist while closed.
+   *
+   * @default false
+   */
+  lazyMount?: boolean;
 }
 
 /**
@@ -314,16 +324,51 @@ function toCssLength(value: number | string): string {
   return typeof value === 'number' ? `${value}px` : value;
 }
 
+interface ContextLayerMount {
+  /** Null means the marker's parent is safe and the layer stays inline. */
+  portalTarget: HTMLElement | null;
+  /** Logical writing context lost when moving outside an unsafe ancestor. */
+  portalStyle: React.CSSProperties;
+}
+
+function readPortalWritingContext(
+  element: HTMLElement,
+  portalTarget: HTMLElement,
+): React.CSSProperties {
+  const view = element.ownerDocument.defaultView;
+  if (!view) {
+    return {};
+  }
+  const sourceStyle = view.getComputedStyle(element);
+  const targetStyle = view.getComputedStyle(portalTarget);
+
+  // Do not snapshot custom properties here. The portal target is the closest
+  // safe ancestor, so theme variables continue to inherit and update there.
+  // These two properties can be set on the unsafe chain itself and directly
+  // affect the logical anchor-positioning keywords used by the layer. Only
+  // override values the portal would actually lose; matching values should
+  // keep inheriting from the target so later direction changes remain live.
+  return {
+    ...(sourceStyle.direction !== targetStyle.direction && {
+      direction: sourceStyle.direction as React.CSSProperties['direction'],
+    }),
+    ...(sourceStyle.writingMode !== targetStyle.writingMode && {
+      writingMode:
+        sourceStyle.writingMode as React.CSSProperties['writingMode'],
+    }),
+  };
+}
+
 /**
  * Map logical placement/alignment to a CSS position-area value.
  *
  * Uses the self-* logical keyword family: the inline axis resolves against
- * the popover's own inherited direction (the layer renders inside the
- * trigger's subtree, so it inherits `direction` and mirrors in RTL with no
- * JS). The block axis is direction-neutral but must come from the same
- * keyword family — mixing physical `top` with `self-inline-*` produces an
- * invalid position-area (computes to `none`, which pins the popover to the
- * viewport corner because styles.base zeroes the UA margins).
+ * the popover's own direction (inherited inline or preserved when portaled),
+ * so it mirrors in RTL without placement-specific JS. The block axis is
+ * direction-neutral but must come from the same keyword family — mixing
+ * physical `top` with `self-inline-*` produces an invalid position-area
+ * (computes to `none`, which pins the popover to the viewport corner because
+ * styles.base zeroes the UA margins).
  *
  * Note the plain logical family (`inline-start`, no `self-`) is NOT a
  * substitute: it resolves against the containing block — the page root for
@@ -406,39 +451,122 @@ export function useLayer(
   options: ContextLayerOptions | FixedLayerOptions,
 ): ContextLayerReturn | FixedLayerReturn {
   const {mode, onShow, onHide, lightDismiss = false} = options;
+  const lazyMount = mode === 'context' ? (options.lazyMount ?? false) : false;
   const id = useId();
   const anchorId = `--astryx-layer-${id.replace(/:/g, '')}`;
 
   const [isOpen, setIsOpen] = useState(false);
   const popoverRef = useRef<HTMLElement | null>(null);
+  // The DOM element on which the current logical open state was applied.
+  // A portal target change replaces the popover element; retaining the old
+  // reference lets the ref callback recognize and reopen its replacement.
+  const openedPopoverRef = useRef<HTMLElement | null>(null);
   const triggerRef = useRef<HTMLElement | null>(null);
+  // Context layers place a persistent inert marker at their real JSX position.
+  // Its parent tells us whether the final layer can stay inline or needs a
+  // corrective portal, including after the render call moves.
+  const sentinelRef = useRef<HTMLTemplateElement | null>(null);
+  const contextMountRef = useRef<ContextLayerMount | null>(null);
+  const [contextMount, setContextMount] = useState<ContextLayerMount | null>(
+    null,
+  );
+  // A show() that arrives before the final layer mounts is replayed when its
+  // popover ref attaches.
+  const pendingShowRef = useRef(false);
 
   // Ref mirrors isOpen for synchronous reads inside show/hide.
   // State drives re-renders; the ref lets the imperative calls avoid
   // stale-closure reads of the previous isOpen value.
   const isOpenRef = useRef(false);
 
-  const show = useCallback(() => {
-    const popover = popoverRef.current;
-    if (popover && !isOpenRef.current) {
-      // Finding infra-4: the Popover API is unsupported on Safari <17 and
-      // Firefox <125. On those browsers `showPopover` does not exist, so
-      // calling it unconditionally throws a TypeError and the layer never
-      // opens. Guard behind a feature check; when the API is missing, fall
-      // back to plain visibility (the [popover] attribute is inert there, so
-      // the element sits in normal flow) so the layer still becomes visible.
-      if (typeof popover.showPopover === 'function') {
-        popover.showPopover();
-      } else {
-        popover.style.display = 'block';
+  const showPopoverElement = useCallback((popover: HTMLElement) => {
+    // Finding infra-4: the Popover API is unsupported on Safari <17 and
+    // Firefox <125. On those browsers `showPopover` does not exist, so fall
+    // back to plain visibility instead of throwing.
+    if (typeof popover.showPopover === 'function') {
+      // The trigger is passed as the popover's invoker `source`: a layer
+      // hosted away from its trigger then still takes its sequential focus
+      // order (and its popover nesting) from the trigger rather than from its
+      // own DOM position. Browsers without the option ignore it.
+      popover.showPopover({source: triggerRef.current ?? undefined});
+    } else {
+      popover.style.display = 'block';
+    }
+    openedPopoverRef.current = popover;
+  }, []);
+
+  const isCurrentContextPopover = useCallback(
+    (popover: HTMLElement): boolean => {
+      if (mode !== 'context') {
+        return true;
       }
+      const mount = contextMountRef.current;
+      if (mount === null) {
+        return false;
+      }
+      const expectedParent =
+        mount.portalTarget ?? sentinelRef.current?.parentElement ?? null;
+      return popover.parentElement === expectedParent;
+    },
+    [mode],
+  );
+
+  const requestContextMount = useCallback(() => {
+    if (mode !== 'context') {
+      return;
+    }
+
+    const sentinel = sentinelRef.current;
+    const inlineParent = sentinel?.parentElement ?? null;
+    if (!sentinel || !inlineParent) {
+      return;
+    }
+
+    const portalTarget = resolveLayerPortalTarget(inlineParent);
+    const mount: ContextLayerMount = {
+      portalTarget,
+      portalStyle: portalTarget
+        ? readPortalWritingContext(sentinel, portalTarget)
+        : {},
+    };
+    contextMountRef.current = mount;
+    setContextMount(mount);
+  }, [mode]);
+
+  const clearContextMount = useCallback(() => {
+    if (mode !== 'context' || !lazyMount) {
+      return;
+    }
+    contextMountRef.current = null;
+    setContextMount(null);
+  }, [mode, lazyMount]);
+
+  const show = useCallback(() => {
+    // A context popover left over until React commits a previous hide must not
+    // be reopened. The synchronous mount ref is the source of truth.
+    const candidate = popoverRef.current;
+    const popover =
+      candidate && isCurrentContextPopover(candidate) ? candidate : null;
+    if (!popover) {
+      pendingShowRef.current = true;
+      requestContextMount();
+      return;
+    }
+    if (!isOpenRef.current) {
+      showPopoverElement(popover);
       isOpenRef.current = true;
       setIsOpen(true);
       onShow?.();
     }
-  }, [onShow]);
+  }, [
+    onShow,
+    requestContextMount,
+    showPopoverElement,
+    isCurrentContextPopover,
+  ]);
 
   const hide = useCallback(() => {
+    pendingShowRef.current = false;
     if (isOpenRef.current) {
       const el = popoverRef.current;
       // See finding infra-4 note in `show`: mirror the same guard on hide so
@@ -450,11 +578,13 @@ export function useLayer(
           el.style.display = 'none';
         }
       }
+      openedPopoverRef.current = null;
       isOpenRef.current = false;
       setIsOpen(false);
       onHide?.();
     }
-  }, [onHide]);
+    clearContextMount();
+  }, [onHide, clearContextMount]);
 
   // Ref for trigger element (context mode only)
   const ref: RefCallback<HTMLElement> | undefined =
@@ -488,12 +618,14 @@ export function useLayer(
     (e: Event) => {
       const toggleEvent = e as ToggleEvent;
       if (toggleEvent.newState === 'closed' && isOpenRef.current) {
+        openedPopoverRef.current = null;
         isOpenRef.current = false;
         setIsOpen(false);
         onHide?.();
+        clearContextMount();
       }
     },
-    [onHide],
+    [onHide, clearContextMount],
   );
 
   // Ref callback for popover element — sets up the `toggle` listener.
@@ -531,8 +663,40 @@ export function useLayer(
     (el: HTMLElement | null) => {
       popoverRef.current = el;
       bindToggleListener(el, handleToggle);
+      if (el && pendingShowRef.current) {
+        pendingShowRef.current = false;
+        show();
+      } else if (
+        el &&
+        isOpenRef.current &&
+        openedPopoverRef.current !== el &&
+        isCurrentContextPopover(el)
+      ) {
+        // Changing a portal target remounts the popover. Preserve the logical
+        // open state without firing onShow again for the replacement element.
+        showPopoverElement(el);
+      }
+    },
+    [
+      handleToggle,
+      bindToggleListener,
+      show,
+      showPopoverElement,
+      isCurrentContextPopover,
+    ],
+  );
+
+  const sentinelRefCallback = useCallback(
+    (el: HTMLTemplateElement | null) => {
+      sentinelRef.current = el;
+      if (el && (!lazyMount || pendingShowRef.current || isOpenRef.current)) {
+        // The render call may have moved while the hook stayed mounted.
+        // Resolve again from the newly attached marker rather than reusing a
+        // portal target from its previous JSX position.
+        requestContextMount();
+      }
     },
-    [handleToggle, bindToggleListener],
+    [lazyMount, requestContextMount],
   );
 
   // Re-bind when the handler identity changes while the element stays mounted,
@@ -556,6 +720,15 @@ export function useLayer(
   // Render function for context mode
   const renderContext = useCallback(
     (children: ReactNode, props?: ContextRenderProps) => {
+      // Keep the marker mounted after resolving the layer. Apart from giving
+      // us the real JSX parent on first show, this lets its ref report when a
+      // persistent hook's render call moves to a different host.
+      const sentinel = <template ref={sentinelRefCallback} />;
+
+      if (contextMount === null) {
+        return <>{sentinel}</>;
+      }
+
       const {
         placement = 'above',
         alignment = 'center',
@@ -598,10 +771,10 @@ export function useLayer(
         ? `${extraClassName} ${stylexResult.className ?? ''}`
         : stylexResult.className;
 
-      // Render as the requested tag. A `span` keeps the layer phrasing content
-      // so it is valid (and stays put on hydration) inside inline contexts like
-      // a `<p>`; `div` remains the default for block layers.
-      return (
+      // The marker gives us the actual JSX parent without mounting arbitrary
+      // children there. Safe positions preserve the existing DOM order and
+      // cascade; unsafe positions use the nearest corrective portal target.
+      const layer = (
         <Container
           ref={popoverRefCallback}
           id={id}
@@ -609,14 +782,35 @@ export function useLayer(
           aria-label={ariaLabel}
           popover={lightDismiss ? 'auto' : 'manual'}
           className={combinedClassName}
-          style={{...stylexResult.style, ...anchorStyle, ...extraStyle}}
+          style={{
+            ...stylexResult.style,
+            ...anchorStyle,
+            ...contextMount.portalStyle,
+            ...extraStyle,
+          }}
           onMouseEnter={onMouseEnter}
           onMouseLeave={onMouseLeave}>
           {children}
         </Container>
       );
+
+      return (
+        <>
+          {sentinel}
+          {contextMount.portalTarget
+            ? createPortal(layer, contextMount.portalTarget)
+            : layer}
+        </>
+      );
     },
-    [anchorId, id, lightDismiss, popoverRefCallback],
+    [
+      anchorId,
+      contextMount,
+      id,
+      lightDismiss,
+      popoverRefCallback,
+      sentinelRefCallback,
+    ],
   );
 
   // Render function for fixed mode

package/src/Lightbox/Lightbox.tsx

@@ -35,6 +35,7 @@ import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
 import {mergeProps, mergeRefs, rtlStyles} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
+import {focusOutlineStyles} from '../utils/focusOutline.stylex';
 import {useTranslator} from '../i18n';
 
 /**
@@ -158,16 +159,6 @@ const styles = stylex.create({
       '@media (hover: hover)': 'zoom-in',
     },
   },
-  zoomTarget: {
-    outline: {
-      default: 'none',
-      ':focus-visible': `2px solid ${colorVars['--color-accent']}`,
-    },
-    outlineOffset: {
-      default: '0',
-      ':focus-visible': '2px',
-    },
-  },
   imageWrapperZoomed: {
     cursor: 'grab',
   },
@@ -641,7 +632,7 @@ export function Lightbox({
             aria-label={isZoomTarget ? t('@astryx.lightbox.zoom') : undefined}
             {...stylex.props(
               styles.imageWrapper,
-              isZoomTarget && styles.zoomTarget,
+              isZoomTarget && focusOutlineStyles.focusVisible,
               !isVideo && hasZoom && !isZoomed && styles.imageWrapperZoomable,
               !isVideo && isZoomed && styles.imageWrapperZoomed,
               !isVideo && isDragging && styles.imageWrapperDragging,

package/src/MultiSelector/MultiSelector.doc.mjs

@@ -27,6 +27,8 @@ export const docs = {
       },
       {className: 'astryx-multi-selector-clear-icon', deprecatedFor: 'input-clear-icon'},
       {className: 'astryx-multi-selector-empty-state'},
+      {className: 'astryx-multi-selector-search'},
+      {className: 'astryx-multi-selector-section-heading'},
       {
         className: 'astryx-multi-selector-indicator-icon',
         states: ['state'],
@@ -192,6 +194,13 @@ export const docs = {
           description:
             'Custom render function for each selectable option in the dropdown. Not called for dividers, sections, or the select-all row.',
         },
+        {
+          name: 'indicatorPosition',
+          type: "'start' | 'end'",
+          description:
+            'Which edge of the option row carries the checkbox. end pushes it to the far edge of the row, including on the select-all row.',
+          default: "'start'",
+        },
         {
           name: 'width',
           type: 'SizeValue',

package/src/MultiSelector/MultiSelector.test.tsx

@@ -1774,7 +1774,134 @@ describe('MultiSelector indicator (chevron) icon theme target', () => {
   });
 });
 
+describe('MultiSelector list structure', () => {
+  it('does not draw a divider under select-all', async () => {
+    const user = userEvent.setup();
+    render(
+      <MultiSelector
+        label="Fruit"
+        options={['Apple', 'Banana', 'Orange']}
+        value={[]}
+        onChange={() => {}}
+        hasSelectAll
+      />,
+    );
+    await user.click(screen.getByRole('combobox'));
+    // Select-all is the first row of the list, not a section of its own. No
+    // option here declares a divider and there is no search row, so the panel
+    // should contain no rule at all.
+    expect(document.querySelectorAll('[role="separator"]')).toHaveLength(0);
+    const [first] = screen.getAllByRole('option', h);
+    expect(first).toHaveTextContent('Select all');
+  });
+
+  it('renders a section title as a plain heading inside the group, not a divider', async () => {
+    const user = userEvent.setup();
+    render(
+      <MultiSelector
+        label="Fruit"
+        options={[
+          {
+            type: 'section',
+            title: 'Citrus',
+            options: [
+              {value: 'orange', label: 'Orange'},
+              {value: 'lemon', label: 'Lemon'},
+            ],
+          },
+        ]}
+        value={[]}
+        onChange={() => {}}
+      />,
+    );
+    await user.click(screen.getByRole('combobox'));
+
+    // A labeled Divider used to stand in for the heading; it rendered a
+    // role="separator" as a direct child of the listbox and stacked a second
+    // rule under the search row's own.
+    expect(document.querySelectorAll('[role="separator"]')).toHaveLength(0);
+
+    const group = screen.getByRole('group', {name: 'Citrus', ...h});
+    const heading = group.querySelector(
+      '.astryx-multi-selector-section-heading',
+    );
+    expect(heading).toBeTruthy();
+    expect(heading).toHaveTextContent('Citrus');
+    // The group already carries the title as its accessible name, so the
+    // visible heading must not announce it a second time.
+    expect(heading).toHaveAttribute('aria-hidden', 'true');
+    // ...and it precedes the options it heads.
+    const [firstOption] = within(group).getAllByRole('option', h);
+    expect(
+      heading!.compareDocumentPosition(firstOption) &
+        Node.DOCUMENT_POSITION_FOLLOWING,
+    ).toBeTruthy();
+  });
+});
+
 describe('MultiSelector search affordances', () => {
+  it('renders the search row seamlessly — no nested input box, a divider under it', async () => {
+    const user = userEvent.setup();
+    render(
+      <MultiSelector
+        label="Fruit"
+        options={['Apple', 'Banana', 'Orange']}
+        value={[]}
+        onChange={() => {}}
+        hasSearch
+      />,
+    );
+    await user.click(screen.getByRole('button', {name: 'Fruit'}));
+
+    const search = screen.getByRole('combobox', h);
+    // The row is the outer gutter; the input sits inside the rounded field.
+    const row = search.closest('.astryx-multi-selector-search');
+    const field = search.parentElement;
+    if (!row || !field) {
+      throw new Error('search row not found');
+    }
+    // The panel is already a bordered surface: the field inside it must not be
+    // a second bordered box (this used to render a TextInput).
+    expect(row).not.toHaveClass('astryx-text-input');
+    expect(search.closest('.astryx-text-input')).toBeNull();
+    // The field is a rounded box inset from the panel edge, shaped like the
+    // option rows under it — not a full-bleed header strip.
+    expect(field).not.toBe(row);
+    // ...and a divider separates it from the options.
+    const separator = document.querySelector('[role="separator"]');
+    if (!separator) {
+      throw new Error('divider not found');
+    }
+    // Order: row, then divider, then the listbox.
+    expect(
+      row.compareDocumentPosition(separator) & Node.DOCUMENT_POSITION_FOLLOWING,
+    ).toBeTruthy();
+    const listbox = screen.getByRole('listbox', h);
+    expect(
+      separator.compareDocumentPosition(listbox) &
+        Node.DOCUMENT_POSITION_FOLLOWING,
+    ).toBeTruthy();
+  });
+
+  it('keeps the search row outside the scrolling option list', async () => {
+    const user = userEvent.setup();
+    render(
+      <MultiSelector
+        label="Fruit"
+        options={['Apple', 'Banana', 'Orange']}
+        value={[]}
+        onChange={() => {}}
+        hasSearch
+      />,
+    );
+    await user.click(screen.getByRole('button', {name: 'Fruit'}));
+    // The options scroll under the header rather than carrying it away, so the
+    // field stays reachable in a long list.
+    const search = screen.getByRole('combobox', h);
+    const listbox = screen.getByRole('listbox', h);
+    expect(listbox.contains(search)).toBe(false);
+  });
+
   it('renders a decorative (aria-hidden) magnifier icon whenever hasSearch is on', async () => {
     const user = userEvent.setup();
     render(
@@ -1788,8 +1915,7 @@ describe('MultiSelector search affordances', () => {
     );
     await user.click(screen.getByRole('button', {name: 'Fruit'}));
     const search = screen.getByRole('combobox', h);
-    // The search field is a TextInput; the magnifier is its startIcon, so it
-    // sits inside the input container as a sibling of the <input>.
+    // The magnifier leads the search row, as a sibling of the <input>.
     const wrapper = search.parentElement;
     const magnifier = wrapper?.querySelector('.astryx-icon');
     expect(magnifier).toBeTruthy();
@@ -2088,7 +2214,7 @@ describe('MultiSelector dropdown option theme target', () => {
 });
 
 describe('MultiSelector popup theme target', () => {
-  it('puts astryx-multi-selector-popup on the dropdown box inside the layer', async () => {
+  it('puts astryx-multi-selector-popup on the surface that paints, not the list inside it', async () => {
     const user = userEvent.setup();
     render(
       <MultiSelector
@@ -2100,13 +2226,17 @@ describe('MultiSelector popup theme target', () => {
     );
     await user.click(screen.getByRole('combobox', {name: /Fruit/}));
 
-    const layer = document.querySelector('[popover]') as HTMLElement;
     const popup = document.querySelector(
       '.astryx-multi-selector-popup',
     ) as HTMLElement;
     expect(popup).not.toBeNull();
+    expect(popup).toHaveClass('astryx-popover-surface');
+    // The scrolling list is a descendant, not the target itself.
+    expect(popup.querySelector('[role="listbox"]')).not.toBeNull();
+    expect(popup.getAttribute('role')).toBeNull();
+
+    const layer = document.querySelector('[popover]') as HTMLElement;
     expect(popup).not.toBe(layer);
     expect(layer.contains(popup)).toBe(true);
-    expect(popup.querySelector('[role="listbox"]')).not.toBeNull();
   });
 });