@pharos-ds/core 0.1.9

package/dist/CommandPalette/CommandPaletteList.d.ts

@@ -0,0 +1,41 @@
+import type { ReactNode } from 'react';
+import type { BaseProps } from '../BaseProps';
+export interface CommandPaletteListProps extends BaseProps<HTMLDivElement> {
+    /**
+     * Ref forwarded to the root element.
+     */
+    ref?: React.Ref<HTMLDivElement>;
+    /**
+     * Command palette items, groups, empty states, etc.
+     */
+    children: ReactNode;
+    /**
+     * Accessible label for the listbox.
+     * @default 'Commands'
+     */
+    label?: string;
+}
+/**
+ * Scrollable results container for the command palette.
+ * Renders as a listbox for ARIA compliance.
+ *
+ * When used inside CommandPalette, automatically gets the correct
+ * ID for aria-controls linking with the input.
+ *
+ * @compositionHint Place inside CommandPalette, after CommandPaletteInput.
+ *   Contains CommandPaletteItem and CommandPaletteGroup children.
+ *
+ * @example
+ * ```
+ * <CommandPaletteList>
+ *   <CommandPaletteItem value="home" onSelect={goHome}>
+ *     Go Home
+ *   </CommandPaletteItem>
+ * </CommandPaletteList>
+ * ```
+ */
+export declare function CommandPaletteList({ children, label: labelFromProps, ref, xstyle, className, style, ...props }: CommandPaletteListProps): import("react").JSX.Element;
+export declare namespace CommandPaletteList {
+    var displayName: string;
+}
+//# sourceMappingURL=CommandPaletteList.d.ts.map

package/dist/CommandPalette/CommandPaletteList.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CommandPaletteList.d.ts","sourceRoot":"","sources":["../../src/CommandPalette/CommandPaletteList.tsx"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,OAAO,CAAC;AAErC,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAmB5C,MAAM,WAAW,uBAAwB,SAAQ,SAAS,CAAC,cAAc,CAAC;IACxE;;OAEG;IACH,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAEhC;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;IAEpB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,QAAQ,EACR,KAAK,EAAE,cAAc,EACrB,GAAG,EACH,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,KAAK,EACT,EAAE,uBAAuB,+BAqBzB;yBA7Be,kBAAkB"}

package/dist/CommandPalette/CommandPaletteList.js

@@ -0,0 +1,77 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file CommandPaletteList.tsx
+ * @input Uses React, StyleX, CommandPaletteContext
+ * @output Exports CommandPaletteList component
+ * @position Sub-component; scrollable results container
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/CommandPalette/index.ts
+ * - /packages/cli/templates/blocks/components/CommandPalette/ (showcase blocks)
+ */
+
+'use client';
+
+import * as stylex from '@stylexjs/stylex';
+import { mergeProps } from "../utils/index.js";
+import "../theme/tokens.stylex.js";
+import { spacingVars } from "../theme/tokens.stylex.js";
+import { useCommandPaletteContext } from "./CommandPaletteContext.js";
+import { themeProps } from "../utils/themeProps.js";
+import { useTranslator } from "../i18n/index.js";
+import { jsx as _jsx } from "react/jsx-runtime";
+const styles = {
+  list: {
+    kORKVm: "x1odjw0f",
+    kskxy: "xmz0i5r",
+    kmVPX3: "x9epnlk",
+    kUk6DE: "x98rzlu",
+    k1xSpc: "x78zum5",
+    kXwgrk: "xdt5ytf",
+    kOIVth: "x1lsbc85",
+    $$css: true
+  }
+};
+/**
+ * Scrollable results container for the command palette.
+ * Renders as a listbox for ARIA compliance.
+ *
+ * When used inside CommandPalette, automatically gets the correct
+ * ID for aria-controls linking with the input.
+ *
+ * @compositionHint Place inside CommandPalette, after CommandPaletteInput.
+ *   Contains CommandPaletteItem and CommandPaletteGroup children.
+ *
+ * @example
+ * ```
+ * <CommandPaletteList>
+ *   <CommandPaletteItem value="home" onSelect={goHome}>
+ *     Go Home
+ *   </CommandPaletteItem>
+ * </CommandPaletteList>
+ * ```
+ */
+export function CommandPaletteList({
+  children,
+  label: labelFromProps,
+  ref,
+  xstyle,
+  className,
+  style,
+  ...props
+}) {
+  const t = useTranslator();
+  const label = labelFromProps ?? t('@pharos.commandPalette.list.label');
+  const ctx = useCommandPaletteContext();
+  return /*#__PURE__*/_jsx("div", {
+    ref: ref,
+    id: ctx?.listId,
+    role: "listbox",
+    "aria-label": label,
+    ...mergeProps(themeProps('command-palette-list'), stylex.props(styles.list, xstyle), className, style),
+    ...props,
+    children: children
+  });
+}
+CommandPaletteList.displayName = 'CommandPaletteList';

package/dist/CommandPalette/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @file index.ts
+ * @input Imports CommandPalette components and types
+ * @output Exports all CommandPalette components and types
+ * @position Component entry point; re-exported by /packages/core/src/index.ts
+ *
+ * SYNC: When modified, update this header
+ */
+export { CommandPalette } from './CommandPalette';
+export type { CommandPaletteProps } from './CommandPalette';
+export { CommandPaletteInput } from './CommandPaletteInput';
+export type { CommandPaletteInputProps } from './CommandPaletteInput';
+export { CommandPaletteList } from './CommandPaletteList';
+export type { CommandPaletteListProps } from './CommandPaletteList';
+export { CommandPaletteItem } from './CommandPaletteItem';
+export type { CommandPaletteItemProps } from './CommandPaletteItem';
+export { CommandPaletteGroup } from './CommandPaletteGroup';
+export type { CommandPaletteGroupProps } from './CommandPaletteGroup';
+export { CommandPaletteFooter } from './CommandPaletteFooter';
+export type { CommandPaletteFooterProps } from './CommandPaletteFooter';
+export { CommandPaletteEmpty } from './CommandPaletteEmpty';
+export type { CommandPaletteEmptyProps } from './CommandPaletteEmpty';
+export { useCommandPaletteContext } from './CommandPaletteContext';
+export type { CommandPaletteContextValue } from './CommandPaletteContext';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/CommandPalette/index.ts"],"names":[],"mappings":"AAIA;;;;;;;GAOG;AAEH,OAAO,EAAC,cAAc,EAAC,MAAM,kBAAkB,CAAC;AAChD,YAAY,EAAC,mBAAmB,EAAC,MAAM,kBAAkB,CAAC;AAE1D,OAAO,EAAC,mBAAmB,EAAC,MAAM,uBAAuB,CAAC;AAC1D,YAAY,EAAC,wBAAwB,EAAC,MAAM,uBAAuB,CAAC;AAEpE,OAAO,EAAC,kBAAkB,EAAC,MAAM,sBAAsB,CAAC;AACxD,YAAY,EAAC,uBAAuB,EAAC,MAAM,sBAAsB,CAAC;AAElE,OAAO,EAAC,kBAAkB,EAAC,MAAM,sBAAsB,CAAC;AACxD,YAAY,EAAC,uBAAuB,EAAC,MAAM,sBAAsB,CAAC;AAElE,OAAO,EAAC,mBAAmB,EAAC,MAAM,uBAAuB,CAAC;AAC1D,YAAY,EAAC,wBAAwB,EAAC,MAAM,uBAAuB,CAAC;AAEpE,OAAO,EAAC,oBAAoB,EAAC,MAAM,wBAAwB,CAAC;AAC5D,YAAY,EAAC,yBAAyB,EAAC,MAAM,wBAAwB,CAAC;AAEtE,OAAO,EAAC,mBAAmB,EAAC,MAAM,uBAAuB,CAAC;AAC1D,YAAY,EAAC,wBAAwB,EAAC,MAAM,uBAAuB,CAAC;AAEpE,OAAO,EAAC,wBAAwB,EAAC,MAAM,yBAAyB,CAAC;AACjE,YAAY,EAAC,0BAA0B,EAAC,MAAM,yBAAyB,CAAC"}

package/dist/CommandPalette/index.js

@@ -0,0 +1,20 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file index.ts
+ * @input Imports CommandPalette components and types
+ * @output Exports all CommandPalette components and types
+ * @position Component entry point; re-exported by /packages/core/src/index.ts
+ *
+ * SYNC: When modified, update this header
+ */
+export { CommandPalette } from "./CommandPalette.js";
+export { CommandPaletteInput } from "./CommandPaletteInput.js";
+export { CommandPaletteList } from "./CommandPaletteList.js";
+export { CommandPaletteItem } from "./CommandPaletteItem.js";
+export { CommandPaletteGroup } from "./CommandPaletteGroup.js";
+export { CommandPaletteFooter } from "./CommandPaletteFooter.js";
+export { CommandPaletteEmpty } from "./CommandPaletteEmpty.js";
+export { useCommandPaletteContext } from "./CommandPaletteContext.js";

package/dist/ContextMenu/ContextMenu.d.ts

@@ -0,0 +1,104 @@
+/**
+ * @file ContextMenu.tsx
+ * @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 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:
+ * - **Data-driven**: pass `items` array (converted to components internally)
+ * - **Compound-component**: pass `menuContent` JSX directly
+ *
+ * Both modes use useListFocus for DOM-based keyboard navigation.
+ * Open state is managed internally — right-click opens, click-outside/Escape closes.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/ContextMenu/ContextMenu.doc.mjs
+ * - /packages/core/src/ContextMenu/ContextMenu.test.tsx
+ * - /packages/core/src/ContextMenu/index.ts
+ * - /apps/storybook/stories/ContextMenu.stories.tsx
+ * - /packages/cli/templates/blocks/components/ContextMenu/ (showcase blocks)
+ */
+import React from 'react';
+import type { ReactNode } from 'react';
+import type { BaseProps } from '../BaseProps';
+import type { StyleXStyles } from '../theme/types';
+import type { DropdownMenuOption, DropdownMenuItemData, DropdownMenuDivider, DropdownMenuSection } from '../DropdownMenu/DropdownMenu';
+export type ContextMenuItemData = DropdownMenuItemData;
+export type ContextMenuDivider = DropdownMenuDivider;
+export type ContextMenuSection = DropdownMenuSection;
+export type ContextMenuOption = DropdownMenuOption;
+interface ContextMenuBaseProps extends BaseProps {
+    /** Ref forwarded to the trigger wrapper element. */
+    ref?: React.Ref<HTMLDivElement>;
+    /**
+     * Styles applied to the trigger wrapper element (the right-click target).
+     * By default the trigger is a plain block that hugs its content — pass a
+     * fill style (e.g. `width/height: 100%`) when the whole parent area should
+     * be right-clickable (as the Table does for full-cell context menus).
+     */
+    triggerXstyle?: StyleXStyles | StyleXStyles[];
+    /** The trigger area — right-click on this to open the menu. */
+    children: ReactNode;
+    /** Custom menu width. @default '160px' */
+    menuWidth?: number | string;
+    /** Size of menu items. @default 'md' */
+    size?: 'sm' | 'md' | 'lg';
+    /**
+     * Accessible name for the menu surface, announced when it opens.
+     * @default 'Context menu'
+     */
+    label?: string;
+    /** When true, right-click shows the native browser context menu instead. */
+    isDisabled?: boolean;
+    /** Called when the menu opens or closes. */
+    onOpenChange?: (isOpen: boolean) => void;
+    'data-testid'?: string;
+}
+interface ContextMenuDataProps extends ContextMenuBaseProps {
+    /** Array of menu entries (data-driven mode). */
+    items: ContextMenuOption[];
+    menuContent?: undefined;
+}
+interface ContextMenuCompoundProps extends ContextMenuBaseProps {
+    items?: undefined;
+    /** Custom JSX menu content (compound mode). */
+    menuContent: ReactNode;
+}
+export type ContextMenuProps = ContextMenuDataProps | ContextMenuCompoundProps;
+/**
+ * A context menu component that appears on right-click at cursor position.
+ *
+ * Supports two modes:
+ * - **Data-driven**: pass `items` for static menus
+ * - **Compound-component**: pass `menuContent` JSX for dynamic menus
+ *
+ * Both modes share the same DOM-based keyboard navigation via useListFocus.
+ *
+ * @example
+ * ```
+ * <ContextMenu
+ *   items={[
+ *     { label: 'Cut', onClick: () => handleCut() },
+ *     { label: 'Copy', onClick: () => handleCopy() },
+ *     { type: 'divider' },
+ *     { label: 'Paste', onClick: () => handlePaste() },
+ *   ]}
+ * >
+ *   <div>Right-click this area</div>
+ * </ContextMenu>
+ * ```
+ */
+export declare function ContextMenu({ children, menuWidth, size, label: labelFromProps, isDisabled, onOpenChange, ref, className, style, xstyle, triggerXstyle, 'data-testid': testId, ...props }: ContextMenuProps): React.JSX.Element;
+export declare namespace ContextMenu {
+    var displayName: string;
+}
+export {};
+//# sourceMappingURL=ContextMenu.d.ts.map

package/dist/ContextMenu/ContextMenu.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ContextMenu.d.ts","sourceRoot":"","sources":["../../src/ContextMenu/ContextMenu.tsx"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAON,MAAM,OAAO,CAAC;AACf,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,OAAO,CAAC;AA0BrC,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAGjD,OAAO,KAAK,EACV,kBAAkB,EAClB,oBAAoB,EACpB,mBAAmB,EACnB,mBAAmB,EACpB,MAAM,8BAA8B,CAAC;AAqDtC,MAAM,MAAM,mBAAmB,GAAG,oBAAoB,CAAC;AAEvD,MAAM,MAAM,kBAAkB,GAAG,mBAAmB,CAAC;AAErD,MAAM,MAAM,kBAAkB,GAAG,mBAAmB,CAAC;AAErD,MAAM,MAAM,iBAAiB,GAAG,kBAAkB,CAAC;AAMnD,UAAU,oBAAqB,SAAQ,SAAS;IAC9C,oDAAoD;IACpD,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;;;;OAKG;IACH,aAAa,CAAC,EAAE,YAAY,GAAG,YAAY,EAAE,CAAC;IAC9C,+DAA+D;IAC/D,QAAQ,EAAE,SAAS,CAAC;IACpB,0CAA0C;IAC1C,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5B,wCAAwC;IACxC,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;IAC1B;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,4CAA4C;IAC5C,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IACzC,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,UAAU,oBAAqB,SAAQ,oBAAoB;IACzD,gDAAgD;IAChD,KAAK,EAAE,iBAAiB,EAAE,CAAC;IAC3B,WAAW,CAAC,EAAE,SAAS,CAAC;CACzB;AAED,UAAU,wBAAyB,SAAQ,oBAAoB;IAC7D,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,+CAA+C;IAC/C,WAAW,EAAE,SAAS,CAAC;CACxB;AAED,MAAM,MAAM,gBAAgB,GAAG,oBAAoB,GAAG,wBAAwB,CAAC;AAM/E;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,WAAW,CAAC,EAC1B,QAAQ,EACR,SAAS,EACT,IAAW,EACX,KAAK,EAAE,cAAc,EACrB,UAAkB,EAClB,YAAY,EACZ,GAAG,EACH,SAAS,EACT,KAAK,EACL,MAAM,EACN,aAAa,EACb,aAAa,EAAE,MAAM,EACrB,GAAG,KAAK,EACT,EAAE,gBAAgB,qBAmRlB;yBAjSe,WAAW"}

package/dist/ContextMenu/ContextMenu.js

@@ -0,0 +1,358 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+'use client';
+
+/**
+ * @file ContextMenu.tsx
+ * @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 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:
+ * - **Data-driven**: pass `items` array (converted to components internally)
+ * - **Compound-component**: pass `menuContent` JSX directly
+ *
+ * Both modes use useListFocus for DOM-based keyboard navigation.
+ * Open state is managed internally — right-click opens, click-outside/Escape closes.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/ContextMenu/ContextMenu.doc.mjs
+ * - /packages/core/src/ContextMenu/ContextMenu.test.tsx
+ * - /packages/core/src/ContextMenu/index.ts
+ * - /apps/storybook/stories/ContextMenu.stories.tsx
+ * - /packages/cli/templates/blocks/components/ContextMenu/ (showcase blocks)
+ */
+import React, { useCallback, useEffect, useId, useMemo, useRef, useState } from 'react';
+import * as stylex from '@stylexjs/stylex';
+import { useLayer } from "../Layer/useLayer.js";
+import { renderDropdownItems } from "../DropdownMenu/renderDropdownItems.js";
+import { DropdownMenuContext } from "../DropdownMenu/DropdownMenuContext.js";
+import { MENU_ITEM_ROLES, MENU_ITEM_SELECTOR, MENU_BOUNDARY_SELECTOR } from "../DropdownMenu/menuItemRoles.js";
+import { useListFocus } from "../hooks/useListFocus.js";
+import { useTypeahead } from "../hooks/useTypeahead.js";
+import { useLongPress } from "../hooks/useLongPress.js";
+import { layerAnimations } from "../Layer/layerAnimations.stylex.js";
+import "../theme/tokens.stylex.js";
+import { colorVars, spacingVars, radiusVars, durationVars, easeVars, shadowVars } from "../theme/tokens.stylex.js";
+import { mergeProps, mergeRefs } from "../utils/index.js";
+import { themeProps } from "../utils/themeProps.js";
+import { useTranslator } from "../i18n/index.js";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+const styles = {
+  trigger: {
+    kVAEAm: "x1n2onr6",
+    k7VYTy: "xpdipgo",
+    $$css: true
+  },
+  menu: {
+    kB7OPa: "x9f619",
+    k1xSpc: "x78zum5",
+    kXwgrk: "xdt5ytf",
+    kOIVth: "x1lsbc85",
+    kskxy: "xuyqlj2",
+    kORKVm: "x1odjw0f",
+    "--_dropdown-menu-radius": "x1fcsqxe",
+    "--_dropdown-menu-padding": "xgory14",
+    kmVPX3: "x9epnlk",
+    kaIpWk: "x1n97fys",
+    kWkggS: "x1prclbq",
+    kGVxlE: "x1i5ehqx",
+    kSiTet: "x1hc1fzr",
+    k1ekBW: "x19991ni",
+    kIyJzY: "xuedmi6",
+    kAMwcw: "xlr8y92",
+    kfSwDN: "x87ps6o",
+    $$css: true
+  },
+  popover: {
+    k7Eaqz: "x5w4yej",
+    $$css: true
+  },
+  popoverCustomWidth: width => [{
+    k7Eaqz: (typeof width === 'number' ? `${width}px` : width) != null ? "xkj4a21" : typeof width === 'number' ? `${width}px` : width,
+    $$css: true
+  }, {
+    "--x-minWidth": (val => typeof val === "number" ? val + "px" : val != null ? val : undefined)(typeof width === 'number' ? `${width}px` : width)
+  }]
+};
+
+// =============================================================================
+// Types
+// =============================================================================
+
+// =============================================================================
+// Props
+// =============================================================================
+
+// =============================================================================
+// ContextMenu
+// =============================================================================
+
+/**
+ * A context menu component that appears on right-click at cursor position.
+ *
+ * Supports two modes:
+ * - **Data-driven**: pass `items` for static menus
+ * - **Compound-component**: pass `menuContent` JSX for dynamic menus
+ *
+ * Both modes share the same DOM-based keyboard navigation via useListFocus.
+ *
+ * @example
+ * ```
+ * <ContextMenu
+ *   items={[
+ *     { label: 'Cut', onClick: () => handleCut() },
+ *     { label: 'Copy', onClick: () => handleCopy() },
+ *     { type: 'divider' },
+ *     { label: 'Paste', onClick: () => handlePaste() },
+ *   ]}
+ * >
+ *   <div>Right-click this area</div>
+ * </ContextMenu>
+ * ```
+ */
+export function ContextMenu({
+  children,
+  menuWidth,
+  size = 'md',
+  label: labelFromProps,
+  isDisabled = false,
+  onOpenChange,
+  ref,
+  className,
+  style,
+  xstyle,
+  triggerXstyle,
+  'data-testid': testId,
+  ...props
+}) {
+  const t = useTranslator();
+  const label = labelFromProps ?? t('@pharos.contextMenu.label');
+  const items = ('items' in props ? props.items : undefined) ?? [];
+  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(null);
+  const triggerRef = useRef(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(null);
+  const [isOpen, setIsOpen] = useState(false);
+  const layer = useLayer({
+    mode: 'context',
+    onHide: useCallback(() => {
+      setIsOpen(false);
+      onOpenChange?.(false);
+      // Restore focus to the element that was focused before opening.
+      const toRestore = triggerFocusRef.current;
+      triggerFocusRef.current = null;
+      if (toRestore && document.contains(toRestore)) {
+        toRestore.focus();
+      }
+    }, [onOpenChange]),
+    onShow: useCallback(() => {
+      setIsOpen(true);
+      onOpenChange?.(true);
+    }, [onOpenChange]),
+    lightDismiss: false
+  });
+  const closeMenu = useCallback(() => {
+    layer.hide();
+  }, [layer]);
+  const {
+    listRef,
+    handleKeyDown: listNavKeyDown,
+    focusFirst,
+    focusItem,
+    ownsEvent,
+    getItems: getMenuItems
+  } = useListFocus({
+    itemSelector: MENU_ITEM_SELECTOR,
+    boundarySelector: MENU_BOUNDARY_SELECTOR,
+    wrap: false,
+    onEscape: closeMenu
+  });
+
+  // First-character typeahead over the enabled menu items (menus-11). Reuses
+  // the hook's scoped item collection so an inline submenu flyout's items
+  // aren't swept in.
+  const typeahead = useTypeahead({
+    getItemLabels: () => getMenuItems().map(el => el.textContent),
+    onMatch: focusItem,
+    getCurrentIndex: () => getMenuItems().findIndex(el => el === document.activeElement || el.contains(document.activeElement))
+  });
+
+  // Dismiss on any click outside the menu. We use popover="manual" (not
+  // "auto") because the native light-dismiss treats the mouseup from the
+  // opening right-click as a dismiss event. Handling it ourselves via
+  // mousedown avoids that race.
+  useEffect(() => {
+    if (!isOpen) {
+      return;
+    }
+    const handleClickOutside = e => {
+      const menu = listRef.current;
+      if (menu && !menu.contains(e.target)) {
+        closeMenu();
+      }
+    };
+    document.addEventListener('mousedown', handleClickOutside);
+    return () => {
+      document.removeEventListener('mousedown', handleClickOutside);
+    };
+  }, [isOpen, closeMenu, listRef]);
+
+  // Dismiss on Escape from anywhere while open. The menu div's own onKeyDown
+  // only fires when focus is inside the menu; a document-level listener is
+  // kept as a reliable fallback Escape path (e.g. if focus has moved out of
+  // the menu). Guards against IME composition-cancel.
+  useEffect(() => {
+    if (!isOpen) {
+      return;
+    }
+    const handleEscape = e => {
+      if (e.key !== 'Escape') {
+        return;
+      }
+      if (e.isComposing || e.keyCode === 229) {
+        return;
+      }
+      e.preventDefault();
+      closeMenu();
+    };
+    document.addEventListener('keydown', handleEscape);
+    return () => {
+      document.removeEventListener('keydown', handleEscape);
+    };
+  }, [isOpen, closeMenu]);
+  const listKeyDown = useCallback(e => {
+    // A submenu flyout renders inline inside this menu; its key events bubble
+    // up here. Let that level own them — only handle events from this level.
+    if (!ownsEvent(e)) {
+      return;
+    }
+    if (e.key === 'Enter' || e.key === ' ') {
+      e.preventDefault();
+      const focused = document.activeElement;
+      if (focused && MENU_ITEM_ROLES.has(focused.getAttribute('role') ?? '')) {
+        focused.click();
+      }
+      return;
+    }
+    if (typeahead.onKeyDown(e)) {
+      e.preventDefault();
+      return;
+    }
+    listNavKeyDown(e);
+  }, [listNavKeyDown, typeahead, ownsEvent]);
+
+  // 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, localY, focusEl) => {
+    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 => {
+    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 bottom-left instead,
+    // so the menu is reachable without a pointer (menus-8).
+    const isKeyboardInvoked = e.clientX === 0 && e.clientY === 0 && e.detail === 0;
+    // 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);
+  }, [isDisabled, openAtLocalPoint]);
+
+  // Touch long-press invocation (menus-8). iOS Safari never synthesizes a
+  // `contextmenu` event on long-press, so a context menu is otherwise
+  // unreachable on touch. Open the menu at the touch point once the press is
+  // held long enough (see useLongPress for timer/move-cancel/cleanup logic).
+  const longPressHandlers = useLongPress({
+    disabled: isDisabled,
+    onLongPress: useCallback(point => {
+      const rect = triggerRef.current?.getBoundingClientRect();
+      openAtLocalPoint(rect ? point.x - rect.left : point.x, rect ? point.y - rect.top : point.y, triggerRef.current);
+    }, [openAtLocalPoint])
+  });
+  const popoverXstyle = menuWidth ? styles.popoverCustomWidth(menuWidth) : styles.popover;
+  const contextValue = useMemo(() => ({
+    closeMenu,
+    menuSize: size
+  }), [closeMenu, size]);
+  const resolvedMenuContent = props.items !== undefined ? renderDropdownItems(items) : menuContent;
+  return /*#__PURE__*/_jsxs(_Fragment, {
+    children: [/*#__PURE__*/_jsxs("div", {
+      ref: mergeRefs(ref, triggerRef),
+      onContextMenu: handleContextMenu,
+      ...longPressHandlers,
+      "data-testid": testId,
+      ...stylex.props(styles.trigger, ...(triggerXstyle ? Array.isArray(triggerXstyle) ? triggerXstyle : [triggerXstyle] : [])),
+      children: [children, /*#__PURE__*/_jsx("span", {
+        ref: mergeRefs(cursorAnchorRef, layer.ref),
+        "aria-hidden": "true",
+        ...mergeProps({
+          className: "x10l6tqk xnalus7 xqtp20y x47corl"
+        }, {
+          style: {
+            left: `${positionRef.current.x}px`,
+            top: `${positionRef.current.y}px`
+          }
+        })
+      })]
+    }), layer.render(/*#__PURE__*/_jsx("div", {
+      ref: listRef,
+      id: menuId,
+      role: "menu",
+      "aria-label": label,
+      onKeyDown: listKeyDown,
+      onContextMenu: e => e.preventDefault(),
+      ...mergeProps(themeProps('context-menu'), stylex.props(styles.menu, xstyle), className, style),
+      children: /*#__PURE__*/_jsx(DropdownMenuContext, {
+        value: contextValue,
+        children: resolvedMenuContent
+      })
+    }), {
+      placement: 'below',
+      alignment: 'start',
+      xstyle: [popoverXstyle, layerAnimations.below]
+    })]
+  });
+}
+ContextMenu.displayName = 'ContextMenu';

package/dist/ContextMenu/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @file index.ts
+ * @output Exports ContextMenu, ContextMenuItem and related types
+ * @position Public API entry point
+ */
+export { ContextMenu, type ContextMenuProps, type ContextMenuItemData, type ContextMenuDivider, type ContextMenuSection, type ContextMenuOption, } from './ContextMenu';
+export { DropdownMenuItem as ContextMenuItem, type DropdownMenuItemProps as ContextMenuItemProps, } from '../DropdownMenu/DropdownMenuItem';
+export { DropdownMenuCheckboxItem as ContextMenuCheckboxItem, type DropdownMenuCheckboxItemProps as ContextMenuCheckboxItemProps, } from '../DropdownMenu/DropdownMenuCheckboxItem';
+export { DropdownMenuRadioGroup as ContextMenuRadioGroup, type DropdownMenuRadioGroupProps as ContextMenuRadioGroupProps, } from '../DropdownMenu/DropdownMenuRadioGroup';
+export { DropdownMenuRadioItem as ContextMenuRadioItem, type DropdownMenuRadioItemProps as ContextMenuRadioItemProps, } from '../DropdownMenu/DropdownMenuRadioItem';
+export { DropdownMenuSubMenu as ContextMenuSubMenu, type DropdownMenuSubMenuProps as ContextMenuSubMenuProps, } from '../DropdownMenu/DropdownMenuSubMenu';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ContextMenu/index.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AAEH,OAAO,EACL,WAAW,EACX,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,GACvB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,gBAAgB,IAAI,eAAe,EACnC,KAAK,qBAAqB,IAAI,oBAAoB,GACnD,MAAM,kCAAkC,CAAC;AAI1C,OAAO,EACL,wBAAwB,IAAI,uBAAuB,EACnD,KAAK,6BAA6B,IAAI,4BAA4B,GACnE,MAAM,0CAA0C,CAAC;AAClD,OAAO,EACL,sBAAsB,IAAI,qBAAqB,EAC/C,KAAK,2BAA2B,IAAI,0BAA0B,GAC/D,MAAM,wCAAwC,CAAC;AAChD,OAAO,EACL,qBAAqB,IAAI,oBAAoB,EAC7C,KAAK,0BAA0B,IAAI,yBAAyB,GAC7D,MAAM,uCAAuC,CAAC;AAE/C,OAAO,EACL,mBAAmB,IAAI,kBAAkB,EACzC,KAAK,wBAAwB,IAAI,uBAAuB,GACzD,MAAM,qCAAqC,CAAC"}