@astryxdesign/core 0.5.0 → 0.5.1-canary.70169cd

package/src/Layer/useLayer.tsx

@@ -5,7 +5,7 @@
 /**
  * @file useLayer.tsx
  * @input Uses React hooks, Popover API, CSS anchor positioning, typography tokens
- * @output Exports useLayer hook for layer positioning and visibility
+ * @output Exports the public useLayer hook plus internal trigger helpers.
  * @position Core layer utility; used by useHoverCard, useTooltip, etc.
  *
  * SYNC: When modified, update:
@@ -18,6 +18,7 @@ import React, {
   useCallback,
   useEffect,
   useId,
+  useMemo,
   useRef,
   useState,
   type ReactNode,
@@ -27,6 +28,7 @@ import * as stylex from '@stylexjs/stylex';
 import type {StyleXStyles} from '@stylexjs/stylex';
 import {createPortal} from 'react-dom';
 import {addAnchorName, removeAnchorName} from './anchorName';
+import {currentGesture, currentGestureHasClicked} from './gestureCounter';
 import {resolveLayerPortalTarget} from './layerHost';
 import {typeScaleVars, typographyVars} from '../theme/tokens.stylex';
 import {overlayPaddingReset} from '../Layout/padding.stylex';
@@ -72,6 +74,18 @@ const styles = stylex.create({
   }),
 });
 
+/**
+ * Props for a control that sits on the trigger but must not dismiss the layer.
+ */
+interface KeepLayerOpenProps {
+  onPointerDown: React.PointerEventHandler<HTMLElement>;
+  /**
+   * Capture phase, so spreading these props never collides with the control's
+   * own `onClick`.
+   */
+  onClickCapture: React.MouseEventHandler<HTMLElement>;
+}
+
 /**
  * Position placement relative to anchor.
  * Logical: start/end resolve against the popover's own inherited direction
@@ -326,6 +340,13 @@ export interface FixedLayerReturn {
   render: (children: ReactNode, props: FixedRenderProps) => ReactNode;
 }
 
+interface InternalLayerFields {
+  wasJustDismissed: () => boolean;
+}
+
+type InternalContextLayerReturn = ContextLayerReturn & InternalLayerFields;
+type InternalFixedLayerReturn = FixedLayerReturn & InternalLayerFields;
+
 function toCssLength(value: number | string): string {
   return typeof value === 'number' ? `${value}px` : value;
 }
@@ -437,6 +458,51 @@ export function getPositionTryFallbacks(
   return `${flips}, ${same} span-top, ${same} span-bottom, ${opposite} span-top, ${opposite} span-bottom`;
 }
 
+/**
+ * Internal props for controls that sit beside an open layer. This stays out of
+ * the public useLayer/usePopover return types until the input family adopts it.
+ */
+export function useKeepLayerOpenProps(
+  id: string,
+  isOpen: boolean,
+): KeepLayerOpenProps {
+  const isOpenRef = useRef(isOpen);
+  isOpenRef.current = isOpen;
+
+  return useMemo(
+    () => ({
+      onPointerDown: (event: React.PointerEvent<HTMLElement>) => {
+        if (!isOpenRef.current) {
+          return;
+        }
+        // The browser reads the invoker relationship at both ends of the press.
+        const control = event.currentTarget;
+        const doc = control.ownerDocument;
+        control.setAttribute('popovertarget', id);
+        const onPressEnd = () => {
+          doc.removeEventListener('pointerup', onPressEnd);
+          doc.removeEventListener('pointercancel', onPressEnd);
+          // Light dismiss runs as the pointerup default action after listeners.
+          doc.defaultView?.setTimeout(() => {
+            control.removeAttribute('popovertarget');
+          }, 0);
+        };
+        doc.addEventListener('pointerup', onPressEnd);
+        doc.addEventListener('pointercancel', onPressEnd);
+      },
+      onClickCapture: (event: React.MouseEvent<HTMLElement>) => {
+        const control = event.currentTarget;
+        if (control.hasAttribute('popovertarget')) {
+          // Being an invoker would otherwise toggle the layer shut.
+          event.preventDefault();
+          control.removeAttribute('popovertarget');
+        }
+      },
+    }),
+    [id],
+  );
+}
+
 /**
  * Core layer hook that handles popover behavior and positioning.
  *
@@ -451,11 +517,9 @@ export function getPositionTryFallbacks(
  * {layer.render(<Content />, { placement: 'above', alignment: 'center' })}
  * ```
  */
-export function useLayer(options: ContextLayerOptions): ContextLayerReturn;
-export function useLayer(options: FixedLayerOptions): FixedLayerReturn;
-export function useLayer(
+function useLayerImplementation(
   options: ContextLayerOptions | FixedLayerOptions,
-): ContextLayerReturn | FixedLayerReturn {
+): InternalContextLayerReturn | InternalFixedLayerReturn {
   const {mode, onShow, onHide, lightDismiss = false} = options;
   const lazyMount = mode === 'context' ? (options.lazyMount ?? false) : false;
   const id = useId();
@@ -485,6 +549,17 @@ export function useLayer(
   // stale-closure reads of the previous isOpen value.
   const isOpenRef = useRef(false);
 
+  // The gesture during which the browser last closed this layer on its own.
+  // Read through wasJustDismissed by triggers deciding whether a click is
+  // theirs to act on.
+  const dismissedByGestureRef = useRef<number | null>(null);
+  const forgetDismissalRef = useRef<(() => void) | null>(null);
+
+  const wasJustDismissed = useCallback(() => {
+    const gesture = currentGesture();
+    return dismissedByGestureRef.current === gesture;
+  }, []);
+
   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
@@ -548,6 +623,11 @@ export function useLayer(
   }, [mode, lazyMount]);
 
   const show = useCallback(() => {
+    // Every caller lands here, so this is where the dismissing press is
+    // absorbed: opening now would reopen the popup that same press closed.
+    if (wasJustDismissed()) {
+      return;
+    }
     // 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;
@@ -569,12 +649,18 @@ export function useLayer(
     requestContextMount,
     showPopoverElement,
     isCurrentContextPopover,
+    wasJustDismissed,
   ]);
 
   const hide = useCallback(() => {
     pendingShowRef.current = false;
     if (isOpenRef.current) {
       const el = popoverRef.current;
+      // Clear the open state BEFORE hiding: hidePopover fires `toggle`, and
+      // the reconciler below reads this ref to tell the browser's own
+      // dismissals from ours.
+      openedPopoverRef.current = null;
+      isOpenRef.current = false;
       // See finding infra-4 note in `show`: mirror the same guard on hide so
       // unsupported browsers degrade gracefully instead of throwing.
       if (el) {
@@ -584,31 +670,74 @@ export function useLayer(
           el.style.display = 'none';
         }
       }
-      openedPopoverRef.current = null;
-      isOpenRef.current = false;
       setIsOpen(false);
       onHide?.();
     }
     clearContextMount();
   }, [onHide, clearContextMount]);
 
-  // Ref for trigger element (context mode only)
-  const ref: RefCallback<HTMLElement> | undefined =
-    mode === 'context'
-      ? (el: HTMLElement | null) => {
-          // Remove only THIS layer's anchor name from the previous element so
-          // other layers sharing the same trigger keep their anchors.
-          if (triggerRef.current && triggerRef.current !== el) {
-            removeAnchorName(triggerRef.current, anchorId);
-          }
+  // Stable ref for the trigger element (context mode only).
+  const contextRef = useCallback(
+    (el: HTMLElement | null) => {
+      // Remove only THIS layer's anchor name from the previous element so
+      // other layers sharing the same trigger keep their anchors.
+      if (triggerRef.current && triggerRef.current !== el) {
+        removeAnchorName(triggerRef.current, anchorId);
+      }
+
+      if (el) {
+        addAnchorName(el, anchorId);
+      }
 
-          if (el) {
-            addAnchorName(el, anchorId);
+      triggerRef.current = el;
+    },
+    [anchorId],
+  );
+
+  // Arm only when the dismissing gesture's click is still ahead of us. Some
+  // engines deliver click first; in that order there is nothing left to absorb.
+  const rememberDismissal = useCallback((doc: Document) => {
+    forgetDismissalRef.current?.();
+    if (currentGestureHasClicked()) {
+      return;
+    }
+    dismissedByGestureRef.current = currentGesture();
+    const view = doc.defaultView;
+    let forgetTimer: number | null = null;
+    const forget = () => {
+      dismissedByGestureRef.current = null;
+      doc.removeEventListener('click', scheduleForget, true);
+      if (forgetTimer !== null) {
+        view?.clearTimeout(forgetTimer);
+        forgetTimer = null;
+      }
+      if (forgetDismissalRef.current === forget) {
+        forgetDismissalRef.current = null;
+      }
+    };
+    const scheduleForget = () => {
+      doc.removeEventListener('click', scheduleForget, true);
+      // The next task keeps the dismissal armed through React's click handler.
+      if (view) {
+        forgetTimer = view.setTimeout(() => {
+          forgetTimer = null;
+          if (forgetDismissalRef.current === forget) {
+            forget();
           }
+        }, 0);
+      } else {
+        forget();
+      }
+    };
+    doc.addEventListener('click', scheduleForget, true);
+    forgetDismissalRef.current = forget;
+  }, []);
 
-          triggerRef.current = el;
-        }
-      : undefined;
+  useEffect(() => {
+    // Install capture-phase gesture tracking before the first interaction.
+    currentGesture();
+    return () => forgetDismissalRef.current?.();
+  }, []);
 
   // Reconcile browser-initiated closes (light-dismiss, popover="auto" stack
   // eviction). These are the only cases where the DOM mutates without going
@@ -626,12 +755,15 @@ export function useLayer(
       if (toggleEvent.newState === 'closed' && isOpenRef.current) {
         openedPopoverRef.current = null;
         isOpenRef.current = false;
+        rememberDismissal(
+          (e.currentTarget as HTMLElement | null)?.ownerDocument ?? document,
+        );
         setIsOpen(false);
         onHide?.();
         clearContextMount();
       }
     },
-    [onHide, clearContextMount],
+    [onHide, clearContextMount, rememberDismissal],
   );
 
   // Ref callback for popover element — sets up the `toggle` listener.
@@ -865,24 +997,65 @@ export function useLayer(
     [popoverRefCallback, id, lightDismiss],
   );
 
-  if (mode === 'context') {
-    return {
-      ref: ref as RefCallback<HTMLElement>,
+  const contextResult = useMemo<InternalContextLayerReturn>(
+    () => ({
+      ref: contextRef,
       anchorId,
       show,
       hide,
       isOpen,
+      wasJustDismissed,
       id,
       render: renderContext,
-    };
-  }
+    }),
+    [
+      contextRef,
+      anchorId,
+      show,
+      hide,
+      isOpen,
+      wasJustDismissed,
+      id,
+      renderContext,
+    ],
+  );
+  const fixedResult = useMemo<InternalFixedLayerReturn>(
+    () => ({
+      ref: undefined,
+      show,
+      hide,
+      isOpen,
+      wasJustDismissed,
+      id,
+      render: renderFixed,
+    }),
+    [show, hide, isOpen, wasJustDismissed, id, renderFixed],
+  );
 
-  return {
-    ref: undefined,
-    show,
-    hide,
-    isOpen,
-    id,
-    render: renderFixed,
-  };
+  return mode === 'context' ? contextResult : fixedResult;
+}
+
+export function useLayer(options: ContextLayerOptions): ContextLayerReturn;
+export function useLayer(options: FixedLayerOptions): FixedLayerReturn;
+export function useLayer(
+  options: ContextLayerOptions | FixedLayerOptions,
+): ContextLayerReturn | FixedLayerReturn {
+  const internalLayer = useLayerImplementation(options);
+  return useMemo(() => {
+    const {wasJustDismissed: _, ...layer} = internalLayer;
+    return layer;
+  }, [internalLayer]);
+}
+
+/** @internal Shared with usePopover; not exported from the package barrel. */
+export function useLayerInternal(
+  options: ContextLayerOptions,
+): InternalContextLayerReturn;
+export function useLayerInternal(
+  options: FixedLayerOptions,
+): InternalFixedLayerReturn;
+export function useLayerInternal(
+  options: ContextLayerOptions | FixedLayerOptions,
+): InternalContextLayerReturn | InternalFixedLayerReturn {
+  return useLayerImplementation(options);
 }

package/src/Layout/__tests__/edgeCompensation.test.tsx

@@ -112,7 +112,7 @@ describe('Edge Compensation', () => {
   describe('Banner container compensation', () => {
     it('renders dismissable banner with ghost dismiss button', () => {
       render(<Banner status="info" title="Test" isDismissable />);
-      const dismissButton = screen.getByRole('button', {name: 'Dismiss'});
+      const dismissButton = screen.getByRole('button', {name: 'Dismiss Test'});
       expect(dismissButton).toHaveAttribute(EDGE_COMP_ATTR);
     });
   });

package/src/List/List.test.tsx

@@ -681,6 +681,44 @@ describe('List', () => {
     expect(screen.getByText('Simple text')).toBeInTheDocument();
   });
 
+  it('forwards data and aria attributes onto the list element', () => {
+    // BaseProps keeps data-*/aria-*; the list element dropped them.
+    const {container} = render(
+      <List listStyle="decimal" data-delimiter=")" aria-label="Steps">
+        <ListItem label="First" />
+      </List>,
+    );
+    const list = container.querySelector('ol')!;
+    expect(list.getAttribute('data-delimiter')).toBe(')');
+    expect(list.getAttribute('aria-label')).toBe('Steps');
+  });
+
+  it('keeps an aria-labelledby pointing outside the component', () => {
+    // With no header of its own there is nothing to associate, so the
+    // consumer's label must survive.
+    const {container} = render(
+      <List aria-labelledby="external-heading">
+        <ListItem label="First" />
+      </List>,
+    );
+    expect(container.querySelector('ul')!.getAttribute('aria-labelledby')).toBe(
+      'external-heading',
+    );
+  });
+
+  it('keeps its own list role and header association', () => {
+    // The rest spread comes first so a consumer prop cannot drop the
+    // Safari/VoiceOver role workaround or the generated header association.
+    const {container} = render(
+      <List header="Steps" role="presentation" aria-labelledby="elsewhere">
+        <ListItem label="First" />
+      </List>,
+    );
+    const list = container.querySelector('ul')!;
+    expect(list.getAttribute('role')).toBe('list');
+    expect(list.getAttribute('aria-labelledby')).not.toBe('elsewhere');
+  });
+
   it('accepts number as description (ReactNode)', () => {
     render(
       <List>

package/src/List/List.tsx

@@ -152,6 +152,7 @@ export function List({
   style,
   'data-testid': testId,
   ref,
+  ...props
 }: ListProps) {
   const headerId = useId();
   const isOrdered = listStyle === 'decimal';
@@ -165,8 +166,14 @@ export function List({
   const listElement = (
     <Tag
       ref={ref as React.Ref<HTMLUListElement & HTMLOListElement>}
+      // Consumer props first: everything the component sets for itself below
+      // is part of its contract and wins on conflict.
+      {...props}
       data-testid={testId}
-      aria-labelledby={header != null ? headerId : undefined}
+      // Only when this component renders the header — writing `undefined`
+      // unconditionally would erase a label a consumer pointed at their own
+      // heading.
+      {...(header != null ? {'aria-labelledby': headerId} : null)}
       {...(isOrdered && start != null && start !== 1 ? {start} : {})}
       // The base list style always sets list-style-type: none (markers are
       // custom-rendered by ListItem), and Safari/VoiceOver drops implicit

package/src/Markdown/Markdown.test.tsx

@@ -124,6 +124,43 @@ describe('Markdown', () => {
     expect(second.className).toContain('astryx-markdown-paragraph');
   });
 
+  describe('base props', () => {
+    // BaseProps documents that data-*, aria-* and role are kept; the root
+    // dropped everything but data-testid.
+    it('forwards data and aria attributes to the block root', () => {
+      const {container} = render(
+        <Markdown data-source="turn-7" aria-label="Answer">
+          Hello
+        </Markdown>,
+      );
+      const root = container.firstElementChild!;
+      expect(root.getAttribute('data-source')).toBe('turn-7');
+      expect(root.getAttribute('aria-label')).toBe('Answer');
+    });
+
+    it('keeps its own role when a consumer passes one', () => {
+      // The rest spread comes first precisely so the component's own
+      // semantics survive a consumer prop.
+      const {container} = render(
+        <Markdown role="presentation">Hello</Markdown>,
+      );
+      expect(container.firstElementChild!.getAttribute('role')).toBe(
+        'document',
+      );
+    });
+
+    it('forwards them on the inline root too', () => {
+      const {container} = render(
+        <Markdown display="inline" data-source="turn-7">
+          Hello
+        </Markdown>,
+      );
+      expect(container.firstElementChild!.getAttribute('data-source')).toBe(
+        'turn-7',
+      );
+    });
+  });
+
   describe('block spacing theme targets', () => {
     // Every block type renders a stable astryx-markdown-<block> class so a
     // theme can tune the gap around it (marginBlockStart/marginBlockEnd) via

package/src/Markdown/Markdown.tsx

@@ -561,14 +561,19 @@ const headingStyles = {
 const DANGEROUS_URL_PATTERN = /^(javascript|data|vbscript):/i;
 
 function sanitizeUrl(url: string): string | null {
-  const trimmed = url.trim();
-  if (trimmed.length === 0) {
+  // Strip control characters before testing, the same normalization the
+  // parser's isSafeUrl applies — the anchored pattern must see the URL the
+  // way a browser will. Return the normalized value so the stripped
+  // characters don't ride along into an attribute or component override.
+  // eslint-disable-next-line no-control-regex -- control chars are the bypass
+  const normalized = url.replace(/[\x00-\x1f\x7f]/g, '').trim();
+  if (normalized.length === 0) {
     return null;
   }
-  if (DANGEROUS_URL_PATTERN.test(trimmed)) {
+  if (DANGEROUS_URL_PATTERN.test(normalized)) {
     return null;
   }
-  return trimmed;
+  return normalized;
 }
 
 // ---------------------------------------------------------------------------
@@ -1622,6 +1627,7 @@ export function Markdown({
   className,
   style,
   'data-testid': testId,
+  ...props
 }: MarkdownProps): React.ReactElement {
   const t = useTranslator();
   const LinkComponent = useLinkComponent();
@@ -1744,6 +1750,8 @@ export function Markdown({
     const renderedInline = (
       <span
         ref={ref}
+        // Consumer props first: what the component sets for itself wins.
+        {...props}
         data-testid={testId}
         {...mergeProps(
           themeProps('markdown', {density}),
@@ -1775,8 +1783,11 @@ export function Markdown({
 
   const rendered = (
     <div
-      role="document"
       ref={ref as React.Ref<HTMLDivElement>}
+      // Consumer props first: what the component sets for itself — the
+      // document role included — wins.
+      {...props}
+      role="document"
       data-testid={testId}
       {...mergeProps(
         themeProps('markdown', {density}),

package/src/Markdown/parser.test.ts

@@ -454,6 +454,14 @@ describe('parseMarkdown', () => {
     }
   });
 
+  it('rejects a standalone image with an unsafe scheme as literal text (XSS prevention)', () => {
+    // Same rule as inline images: the line falls through to the paragraph
+    // path and stays literal text instead of becoming an image node.
+    const result = parseMarkdown('![alt](vbscript:msgbox)');
+    expect(result[0].type).toBe('paragraph');
+    expect(JSON.stringify(result)).not.toContain('"type":"image"');
+  });
+
   it('parses complex AI response', () => {
     const input = [
       '# Analysis',
@@ -1150,6 +1158,31 @@ describe('link reference definitions', () => {
     expect(links).toEqual([{type: 'image', src: '/logo.png', text: 'logo'}]);
   });
 
+  it('rejects a reference image whose definition has an unsafe scheme (XSS prevention)', () => {
+    const {links} = paragraphLinks('![logo][l]\n\n[l]: <javascript:alert(1)>');
+    expect(links).toEqual([]);
+  });
+
+  it('rejects a shortcut reference image with an unsafe definition (XSS prevention)', () => {
+    const {links} = paragraphLinks('![logo]\n\n[logo]: <javascript:alert(1)>');
+    expect(links).toEqual([]);
+  });
+
+  it('rejects definitions that hide the scheme behind control chars (XSS prevention)', () => {
+    // isSafeUrl strips control characters before testing; the angle-bracket
+    // destination form is the only definition shape that can contain them.
+    // Both consumers of a definition — reference images and reference links —
+    // must apply it.
+    const {links: imageLinks} = paragraphLinks(
+      '![logo][l]\n\n[l]: <java\tscript:alert(1)>',
+    );
+    expect(imageLinks).toEqual([]);
+    const {links: refLinks} = paragraphLinks(
+      '[click][l]\n\n[l]: <java\tscript:alert(1)>',
+    );
+    expect(refLinks).toEqual([]);
+  });
+
   it('does not treat a whitespace-only second label as collapsed', () => {
     // `[foo][ ]` is a full reference to the empty (normalized) label and matches
     // nothing; `[foo]` still resolves as a shortcut and `[ ]` stays literal.

package/src/Markdown/parser.ts

@@ -369,7 +369,7 @@ function matchReferenceImage(
       const rawLabel = text.slice(altClose + 2, labelClose);
       const label = rawLabel === '' ? alt : rawLabel;
       const src = linkDefs.get(normalizeLinkLabel(label));
-      if (src != null) {
+      if (src != null && isSafeUrl(src)) {
         return {node: {type: 'image', src, alt}, end: labelClose + 1};
       }
       // No match — fall back to a shortcut `![alt]`.
@@ -379,7 +379,7 @@ function matchReferenceImage(
     return null;
   }
   const src = linkDefs.get(normalizeLinkLabel(alt));
-  if (src == null) {
+  if (src == null || !isSafeUrl(src)) {
     return null;
   }
   return {node: {type: 'image', src, alt}, end: altClose + 1};
@@ -1416,8 +1416,14 @@ function parseMarkdownImpl(
     }
 
     // --- Standalone image ---
+    // An unsafe src falls through to the paragraph path and renders as
+    // literal text, the same rule the inline image path applies.
     const imageMatch = line.match(/^!\[([^\]]*)\]\(([^)]+)\)/);
-    if (imageMatch && line.trim() === imageMatch[0]) {
+    if (
+      imageMatch &&
+      line.trim() === imageMatch[0] &&
+      isSafeUrl(imageMatch[2])
+    ) {
       pushBlock({type: 'image', alt: imageMatch[1], src: imageMatch[2]});
       index++;
       continue;