@astryxdesign/core 0.1.4 → 0.1.5-canary.76e6697

package/src/CommandPalette/CommandPaletteItem.doc.mjs

@@ -50,6 +50,12 @@ export const docs = {
       description: 'StyleX styles for layout customization. Must be a stylex.create() value.',
     },
   ],
+  playground: {
+    defaults: {
+      value: 'go-home',
+      children: 'Go to Dashboard',
+    },
+  },
 };
 
 export const docsZh = {

package/src/CommandPalette/CommandPaletteList.doc.mjs

@@ -27,6 +27,15 @@ export const docs = {
       description: 'StyleX styles for layout customization. Must be a stylex.create() value.',
     },
   ],
+  playground: {
+    defaults: {
+      children: [
+        {__element: 'CommandPaletteItem', props: {value: 'home', onSelect: undefined}, children: 'Go Home'},
+        {__element: 'CommandPaletteItem', props: {value: 'settings', onSelect: undefined}, children: 'Open Settings'},
+        {__element: 'CommandPaletteItem', props: {value: 'profile', onSelect: undefined}, children: 'View Profile'},
+      ],
+    },
+  },
 };
 
 export const docsZh = {

package/src/ContextMenu/ContextMenu.doc.mjs

@@ -78,6 +78,21 @@ export const docs = {
       { guidance: false, description: 'Place more than 10–12 items in a single menu without grouping them into sections.' },
     ],
   },
+  playground: {
+    defaults: {
+      children: {
+        __element: 'Card',
+        props: {padding: 6},
+        children: {__element: 'Text', props: {color: 'secondary'}, children: 'Right-click this area'},
+      },
+      items: [
+        {label: 'Edit'},
+        {label: 'Duplicate'},
+        {type: 'divider'},
+        {label: 'Delete'},
+      ],
+    },
+  },
 };
 
 /** @type {import('../docs-types').TranslationDoc} */

package/src/ContextMenu/ContextMenu.test.tsx

@@ -172,6 +172,21 @@ describe('ContextMenu', () => {
     expect(preventDefault).toHaveBeenCalled();
   });
 
+  it('prevents default context menu on the opened menu container', () => {
+    render(
+      <ContextMenu items={[{label: 'Item 1'}]}>
+        <div>Right-click me</div>
+      </ContextMenu>,
+    );
+
+    fireEvent.contextMenu(screen.getByText('Right-click me'));
+    const menu = screen.getByRole('menu', {hidden: true});
+    const event = new MouseEvent('contextmenu', {bubbles: true});
+    const preventDefault = vi.spyOn(event, 'preventDefault');
+    menu.dispatchEvent(event);
+    expect(preventDefault).toHaveBeenCalled();
+  });
+
   it('does not open when isDisabled is true', () => {
     render(
       <ContextMenu items={[{label: 'Item 1'}]} isDisabled>
@@ -449,4 +464,76 @@ describe('ContextMenu compound mode', () => {
     ).toBeInTheDocument();
     expect(screen.getByRole('separator', {hidden: true})).toBeInTheDocument();
   });
+
+  describe('cursor anchor positioning (#3465)', () => {
+    // The menu is anchored to a zero-size element placed at the cursor point
+    // *inside the trigger*, so it is positioned relative to the trigger's
+    // context (scroll-follow + auto-flip) rather than the viewport.
+    function getCursorAnchor(trigger: HTMLElement): HTMLElement {
+      const anchor = trigger.querySelector<HTMLElement>('[aria-hidden="true"]');
+      if (!anchor) {
+        throw new Error('cursor anchor not found');
+      }
+      return anchor;
+    }
+
+    it('renders a zero-size cursor anchor inside the trigger', () => {
+      render(
+        <ContextMenu items={[{label: 'Item 1'}]} data-testid="ctx">
+          <div>Right-click me</div>
+        </ContextMenu>,
+      );
+      const anchor = getCursorAnchor(screen.getByTestId('ctx'));
+      expect(anchor.tagName).toBe('SPAN');
+      // Carries an anchor-name so the menu can be anchored to it via CSS
+      // anchor positioning (context mode), not fixed viewport coordinates.
+      expect(anchor.style.anchorName).toMatch(/^--astryx-layer-/);
+    });
+
+    it('places the cursor anchor at the pointer position relative to the trigger', () => {
+      render(
+        <ContextMenu items={[{label: 'Item 1'}]} data-testid="ctx">
+          <div>Right-click me</div>
+        </ContextMenu>,
+      );
+      const trigger = screen.getByTestId('ctx');
+      trigger.getBoundingClientRect = () =>
+        ({
+          left: 100,
+          top: 50,
+          right: 300,
+          bottom: 150,
+          width: 200,
+          height: 100,
+        }) as DOMRect;
+      // Pointer at viewport (170, 90) -> local trigger offset (70, 40).
+      fireEvent.contextMenu(trigger, {clientX: 170, clientY: 90, detail: 1});
+      const anchor = getCursorAnchor(trigger);
+      expect(anchor.style.left).toBe('70px');
+      expect(anchor.style.top).toBe('40px');
+    });
+
+    it('anchors a keyboard-invoked menu to the trigger bottom-left', () => {
+      render(
+        <ContextMenu items={[{label: 'Item 1'}]} data-testid="ctx">
+          <div>Right-click me</div>
+        </ContextMenu>,
+      );
+      const trigger = screen.getByTestId('ctx');
+      trigger.getBoundingClientRect = () =>
+        ({
+          left: 40,
+          top: 10,
+          right: 100,
+          bottom: 30,
+          width: 60,
+          height: 20,
+        }) as DOMRect;
+      // Keyboard-initiated contextmenu: coords (0,0), detail 0 -> local (0, height).
+      fireEvent.contextMenu(trigger, {clientX: 0, clientY: 0, detail: 0});
+      const anchor = getCursorAnchor(trigger);
+      expect(anchor.style.left).toBe('0px');
+      expect(anchor.style.top).toBe('20px');
+    });
+  });
 });

package/src/ContextMenu/ContextMenu.tsx

@@ -3,11 +3,16 @@
 
 /**
  * @file ContextMenu.tsx
- * @input Uses React, StyleX, useLayer (fixed mode), useListFocus
+ * @input Uses React, StyleX, useLayer (context mode), useListFocus
  * @output Exports ContextMenu component
  * @position Core implementation; consumed by index.ts
  *
- * Right-click context menu positioned at cursor coordinates.
+ * Right-click context menu positioned at the cursor. The cursor point is
+ * captured as an offset *inside the trigger* and materialized as a zero-size
+ * anchor element, so the menu is positioned relative to the trigger's context
+ * (via CSS anchor positioning) rather than the viewport. It therefore follows
+ * the content on scroll and auto-flips at viewport edges, while still appearing
+ * under the cursor.
  * Reuses DropdownMenu item rendering and keyboard navigation.
  *
  * Supports two content modes with a single keyboard/focus path:
@@ -53,7 +58,7 @@ import {
   easeVars,
   shadowVars,
 } from '../theme/tokens.stylex';
-import {mergeProps} from '../utils';
+import {mergeProps, mergeRefs} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import type {StyleXStyles} from '../theme/types';
 import {themeProps} from '../utils/themeProps';
@@ -67,9 +72,23 @@ import type {
 const styles = stylex.create({
   // Trigger wrapper: suppress the iOS long-press callout/selection so the
   // long-press opens our context menu instead of the native text/callout UI.
+  // `position: relative` establishes the containing block for the absolutely
+  // positioned cursor anchor below, so the anchor point tracks the trigger
+  // (and scrolls with it) instead of the page.
   trigger: {
+    position: 'relative',
     WebkitTouchCallout: 'none',
   },
+  // Zero-size anchor placed at the cursor point within the trigger. The menu
+  // is anchored to this element, so it sits under the cursor yet is positioned
+  // relative to the trigger's context — it follows the content on scroll and
+  // the browser can auto-flip it against the viewport edges.
+  cursorAnchor: {
+    position: 'absolute',
+    width: 0,
+    height: 0,
+    pointerEvents: 'none',
+  },
   menu: {
     boxSizing: 'border-box',
     display: 'flex',
@@ -87,6 +106,7 @@ const styles = stylex.create({
     transitionProperty: 'opacity',
     transitionDuration: durationVars['--duration-fast'],
     transitionTimingFunction: easeVars['--ease-standard'],
+    userSelect: 'none',
   },
   popover: {
     minWidth: '160px',
@@ -200,7 +220,13 @@ export function ContextMenu({
   const menuContent = 'menuContent' in props ? props.menuContent : undefined;
 
   const menuId = useId();
+  // Cursor point in the trigger's local coordinate space (offset from the
+  // trigger's top-left, in-flow). Stored here and written to the zero-size
+  // anchor element so the menu is positioned relative to the trigger context
+  // — it scrolls with the content instead of sitting at a fixed viewport point.
   const positionRef = useRef({x: 0, y: 0});
+  const cursorAnchorRef = useRef<HTMLSpanElement>(null);
+  const triggerRef = useRef<HTMLDivElement>(null);
   // Element focused before the menu opened, restored when it closes so focus
   // does not fall to <body> after Escape or outside-click dismissal.
   const triggerFocusRef = useRef<HTMLElement | null>(null);
@@ -208,7 +234,7 @@ export function ContextMenu({
   const [isOpen, setIsOpen] = useState(false);
 
   const layer = useLayer({
-    mode: 'fixed',
+    mode: 'context',
     onHide: useCallback(() => {
       setIsOpen(false);
       onOpenChange?.(false);
@@ -326,34 +352,53 @@ export function ContextMenu({
     [listNavKeyDown, typeahead],
   );
 
+  // Place the zero-size cursor anchor at a point in the trigger's local
+  // coordinate space and open the menu. Positioning the anchor inside the
+  // trigger (rather than storing viewport coordinates on the menu itself) is
+  // what makes the menu context-relative: it scrolls with the content and the
+  // browser auto-flips it against the viewport edges via CSS anchor positioning.
+  const openAtLocalPoint = useCallback(
+    (localX: number, localY: number, focusEl: HTMLElement | null) => {
+      positionRef.current = {x: localX, y: localY};
+      const anchorEl = cursorAnchorRef.current;
+      if (anchorEl) {
+        anchorEl.style.left = `${localX}px`;
+        anchorEl.style.top = `${localY}px`;
+      }
+      // Remember the element focused before opening so we can restore it on
+      // close (Escape or outside-click), instead of dropping focus to <body>.
+      triggerFocusRef.current =
+        document.activeElement instanceof HTMLElement
+          ? document.activeElement
+          : focusEl;
+      layer.show();
+      requestAnimationFrame(() => focusFirst());
+    },
+    [layer, focusFirst],
+  );
+
   const handleContextMenu = useCallback(
     (e: React.MouseEvent) => {
       if (isDisabled) {
         return;
       }
       e.preventDefault();
+      const trigger = triggerRef.current;
+      const rect = trigger?.getBoundingClientRect();
       // A keyboard-initiated contextmenu (Shift+F10 / the Menu key) fires a
       // `contextmenu` event whose coordinates are (0, 0) in several browsers.
-      // Detect that and anchor the menu to the trigger's box instead, so the
-      // menu is reachable without a pointer (menus-8).
+      // Detect that and anchor the menu to the trigger's bottom-left instead,
+      // so the menu is reachable without a pointer (menus-8).
       const isKeyboardInvoked =
         e.clientX === 0 && e.clientY === 0 && e.detail === 0;
-      if (isKeyboardInvoked && e.currentTarget instanceof HTMLElement) {
-        const rect = e.currentTarget.getBoundingClientRect();
-        positionRef.current = {x: rect.left, y: rect.bottom};
-      } else {
-        positionRef.current = {x: e.clientX, y: e.clientY};
-      }
-      // Remember the element focused before opening so we can restore it on
-      // close (Escape or outside-click), instead of dropping focus to <body>.
-      triggerFocusRef.current =
-        document.activeElement instanceof HTMLElement
-          ? document.activeElement
-          : (e.currentTarget as HTMLElement);
-      layer.show();
-      requestAnimationFrame(() => focusFirst());
+      // Convert the viewport cursor point into the trigger's local space so
+      // the anchor lives inside the (scrollable) trigger context.
+      const localX = isKeyboardInvoked || !rect ? 0 : e.clientX - rect.left;
+      const localY =
+        isKeyboardInvoked || !rect ? (rect?.height ?? 0) : e.clientY - rect.top;
+      openAtLocalPoint(localX, localY, e.currentTarget as HTMLElement);
     },
-    [isDisabled, layer, focusFirst],
+    [isDisabled, openAtLocalPoint],
   );
 
   // Touch long-press invocation (menus-8). iOS Safari never synthesizes a
@@ -364,11 +409,14 @@ export function ContextMenu({
     disabled: isDisabled,
     onLongPress: useCallback(
       (point: {x: number; y: number}) => {
-        positionRef.current = {x: point.x, y: point.y};
-        layer.show();
-        requestAnimationFrame(() => focusFirst());
+        const rect = triggerRef.current?.getBoundingClientRect();
+        openAtLocalPoint(
+          rect ? point.x - rect.left : point.x,
+          rect ? point.y - rect.top : point.y,
+          triggerRef.current,
+        );
       },
-      [layer, focusFirst],
+      [openAtLocalPoint],
     ),
   });
 
@@ -387,7 +435,7 @@ export function ContextMenu({
   return (
     <>
       <div
-        ref={ref}
+        ref={mergeRefs(ref, triggerRef)}
         onContextMenu={handleContextMenu}
         {...longPressHandlers}
         data-testid={testId}
@@ -400,6 +448,16 @@ export function ContextMenu({
             : []),
         )}>
         {children}
+        <span
+          ref={mergeRefs(cursorAnchorRef, layer.ref)}
+          aria-hidden="true"
+          {...mergeProps(stylex.props(styles.cursorAnchor), {
+            style: {
+              left: `${positionRef.current.x}px`,
+              top: `${positionRef.current.y}px`,
+            },
+          })}
+        />
       </div>
 
       {layer.render(
@@ -409,6 +467,7 @@ export function ContextMenu({
           role="menu"
           aria-label={label}
           onKeyDown={listKeyDown}
+          onContextMenu={e => e.preventDefault()}
           {...mergeProps(
             themeProps('context-menu'),
             stylex.props(styles.menu, xstyle),
@@ -420,8 +479,8 @@ export function ContextMenu({
           </DropdownMenuContext>
         </div>,
         {
-          x: positionRef.current.x,
-          y: positionRef.current.y,
+          placement: 'below',
+          alignment: 'start',
           xstyle: [popoverXstyle, layerAnimations.below],
         },
       )}

package/src/ContextMenu/ContextMenuItem.doc.mjs

@@ -35,6 +35,12 @@ export const docs = {
       description: 'StyleX styles for layout customization.',
     },
   ],
+  playground: {
+    defaults: {
+      label: 'Edit',
+      description: 'Modify this item',
+    },
+  },
 };
 
 export const docsZh = {

package/src/DateInput/DateInput.test.tsx

@@ -12,6 +12,7 @@
 import {describe, it, expect, vi, beforeEach} from 'vitest';
 import {render, screen, fireEvent, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
+import {getButton, queryButton} from '../__tests__/fastRoleQueries';
 import {DateInput} from './DateInput';
 import {InputGroup} from '../InputGroup';
 import {InputGroupText} from '../InputGroup/InputGroupText';
@@ -92,14 +93,14 @@ describe('DateInput', () => {
 
   it('calendar button is focusable and clickable', () => {
     render(<DateInput label="Date" onChange={() => {}} />);
-    const button = screen.getByRole('button', {name: 'Open calendar'});
+    const button = getButton('Open calendar');
     expect(button).toBeInTheDocument();
     expect(button).not.toBeDisabled();
   });
 
   it('calendar button is disabled when isDisabled is true', () => {
     render(<DateInput label="Date" isDisabled onChange={() => {}} />);
-    const button = screen.getByRole('button', {name: 'Open calendar'});
+    const button = getButton('Open calendar');
     expect(button).toBeDisabled();
   });
 
@@ -282,7 +283,7 @@ describe('DateInput', () => {
   it('disables input and button when isLoading is true', () => {
     render(<DateInput label="Date" isLoading onChange={() => {}} />);
     expect(screen.getByRole('combobox')).toBeDisabled();
-    expect(screen.getByRole('button', {name: 'Open calendar'})).toBeDisabled();
+    expect(getButton('Open calendar')).toBeDisabled();
   });
 
   it('shows spinner when isLoading is true', () => {
@@ -475,7 +476,7 @@ describe('DateInput', () => {
 
   it('does not open popover when clicking calendar button while disabled', () => {
     render(<DateInput label="Date" isDisabled onChange={() => {}} />);
-    const button = screen.getByRole('button', {name: 'Open calendar'});
+    const button = getButton('Open calendar');
     fireEvent.click(button);
     expect(screen.getByRole('combobox')).toHaveAttribute(
       'aria-expanded',
@@ -513,23 +514,17 @@ describe('DateInput', () => {
           hasClear
         />,
       );
-      expect(
-        screen.getByRole('button', {name: 'Clear Date'}),
-      ).toBeInTheDocument();
+      expect(getButton('Clear Date')).toBeInTheDocument();
     });
 
     it('does not show clear button when value is undefined', () => {
       render(<DateInput label="Date" onChange={() => {}} hasClear />);
-      expect(
-        screen.queryByRole('button', {name: 'Clear Date'}),
-      ).not.toBeInTheDocument();
+      expect(queryButton('Clear Date')).not.toBeInTheDocument();
     });
 
     it('does not show clear button when hasClear is false', () => {
       render(<DateInput label="Date" value="2026-01-15" onChange={() => {}} />);
-      expect(
-        screen.queryByRole('button', {name: 'Clear Date'}),
-      ).not.toBeInTheDocument();
+      expect(queryButton('Clear Date')).not.toBeInTheDocument();
     });
 
     it('does not show clear button when disabled', () => {
@@ -542,9 +537,7 @@ describe('DateInput', () => {
           isDisabled
         />,
       );
-      expect(
-        screen.queryByRole('button', {name: 'Clear Date'}),
-      ).not.toBeInTheDocument();
+      expect(queryButton('Clear Date')).not.toBeInTheDocument();
     });
 
     it('calls onChange with undefined when clear is clicked', () => {
@@ -557,7 +550,7 @@ describe('DateInput', () => {
           hasClear
         />,
       );
-      fireEvent.click(screen.getByRole('button', {name: 'Clear Date'}));
+      fireEvent.click(getButton('Clear Date'));
       expect(onChange).toHaveBeenCalledWith(undefined);
     });
   });
@@ -699,9 +692,7 @@ describe('DateInput', () => {
       expect(input).toHaveAttribute('aria-disabled', 'true');
       expect(input.getAttribute('aria-describedby')).toContain(tooltip.id);
       expect(tooltip).toHaveTextContent('Scheduling is locked');
-      expect(
-        screen.getByRole('button', {name: 'Open calendar'}),
-      ).toBeDisabled();
+      expect(getButton('Open calendar')).toBeDisabled();
     });
   });
 

package/src/DateRangeInput/DateRangeInput.doc.mjs

@@ -57,7 +57,8 @@ export const docs = {
     {
       name: 'value',
       type: 'DateRange | null',
-      description: 'Selected date range ({start, end} in ISO format), or null.',
+      description:
+        'Selected date range or null. Import the `DateRange` type from `@astryxdesign/core/DateRangeInput` — it is `{start: ISODateString, end: ISODateString}`. Do NOT redeclare your own DateRange type; use the exported one so TypeScript structurally matches.',
       required: true,
     },
     {
@@ -83,12 +84,14 @@ export const docs = {
     {
       name: 'min',
       type: 'ISODateString',
-      description: 'Minimum selectable date.',
+      description:
+        'Minimum selectable date. `ISODateString` is a template literal type (`\\`${number}${number}${number}${number}-${number}${number}-${number}${number}\\``) — pass a string literal like `"2026-01-28"`, not a runtime string variable. Import it from `@astryxdesign/core/Calendar` or use `as ISODateString` if computing the value dynamically.',
     },
     {
       name: 'max',
       type: 'ISODateString',
-      description: 'Maximum selectable date.',
+      description:
+        'Maximum selectable date. Same template literal type as `min` — use a YYYY-MM-DD string literal or cast with `as ISODateString`.',
     },
     {
       name: 'dateConstraints',
@@ -283,10 +286,10 @@ export const docsDense = {
     isDisabled: 'disable trigger+picker',
     disabledMessage:
       'reason shown in a tooltip on hover/focus when disabled; keeps trigger focusable via aria-disabled',
-    value: 'selected range {start, end} or null',
+    value: 'selected range {start, end} or null — import DateRange type from @astryxdesign/core/DateRangeInput (do not redeclare)',
     onChange: 'callback on range change; null on clear',
-    min: 'min selectable date',
-    max: 'max selectable date',
+    min: 'min selectable date — ISODateString template literal type (YYYY-MM-DD); use string literal or cast `as ISODateString`',
+    max: 'max selectable date — ISODateString template literal type (YYYY-MM-DD); use string literal or cast `as ISODateString`',
     dateConstraints: 'custom constraint fns to disable dates',
     presets: 'preset ranges as quick-select options',
     hasClear: 'clear button when range is set (default true)',