@featherk/composables 0.12.5 → 0.13.1

package/dist/geometry/computeFlippedOffset.d.ts

@@ -0,0 +1,40 @@
+/** A corner/center alignment pair, independent of any specific composable. */
+export type GeometryAlign = {
+    horizontal: "left" | "center" | "right";
+    vertical: "top" | "center" | "bottom";
+};
+/** A rectangular clipping region (viewport or a scrollable container's rect). */
+export type GeometryBounds = {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+};
+export type ComputeFlippedOffsetInput = {
+    /** The anchor rect (or a zero-size point rect for a click/keyboard activation). */
+    anchor: DOMRect;
+    /** The popup's own measured size, or `null` before it has been measured. */
+    popup: DOMRect | null;
+    /** Point on the anchor that the popup is positioned from. */
+    anchorAlign: GeometryAlign;
+    /** Point on the popup that is placed at the computed anchor point. */
+    popupAlign: GeometryAlign;
+    /** Clipping bounds checked for overflow; same coordinate space as `anchor`. */
+    bounds: GeometryBounds;
+};
+/**
+ * Computes a popup's top-left corner from an anchor rect and alignment pair,
+ * flipping either axis to the anchor's opposite side when the preferred
+ * position would overflow `bounds` and flipping actually reduces the
+ * overflow. Mirrors Kendo Popup's own `anchorAlign`/`popupAlign`/`collision:
+ * "flip"` semantics, which only run when Kendo positions via a real `anchor`
+ * DOM ref - this reproduces them for offset-based positioning.
+ *
+ * A `center` alignment on an axis never flips (there is no opposite side).
+ * Returns the un-flipped position when `popup` is `null` (not yet measured)
+ * or `bounds` cannot be checked - there is nothing to compare against yet.
+ */
+export declare const computeFlippedOffset: ({ anchor, popup, anchorAlign, popupAlign, bounds, }: ComputeFlippedOffsetInput) => {
+    left: number;
+    top: number;
+};

package/dist/geometry/computeFlippedOffset.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/geometry/index.d.ts

@@ -0,0 +1 @@
+export * from "./computeFlippedOffset";

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export * from "./grid";
 export * from "./address";
 export * from "./form";
+export * from "./geometry";
 export * from "./id";
 export * from "./menu";
 export * from "./observer";

package/dist/menu/usePopupMenu.d.ts

@@ -1,4 +1,5 @@
 import { type ComponentPublicInstance, type ComputedRef, type MaybeRefOrGetter, type Ref } from "vue";
+import { type GeometryAlign } from "../geometry";
 /** A template ref that may point to an element or a Vue/Kendo component. */
 export type PopupMenuElementRef = Ref<HTMLElement | ComponentPublicInstance | null>;
 export type PopupMenuTriggerMode = "button" | "row";
@@ -6,17 +7,64 @@ export type PopupMenuOffset = {
     left: number;
     top: number;
 };
-/** Offset-positioning options for a Popup with a dynamically changing trigger. */
-export type PopupMenuAnchorOptions = {
+/** Mirrors Kendo Popup's `anchorAlign`/`popupAlign` point shape. */
+export type PopupMenuAlign = GeometryAlign;
+export type PopupMenuAnchorActivation = {
+    triggerType: "click" | "keyboard";
+    coordinates?: {
+        clientX: number;
+        clientY: number;
+    };
+};
+export type PopupMenuActivationPointOptions = {
+    /** Added to pointer coordinates after they are made trigger-relative. */
+    pointerOffset?: {
+        x?: number;
+        y?: number;
+    };
+    /** Trigger-relative keyboard position. Defaults to 8px from the left and vertically centered. */
+    keyboardPosition?: {
+        x?: number;
+        y?: number | "top" | "center" | "bottom";
+    };
+};
+type PopupMenuAnchorBaseOptions = {
     /** Scrollable/clipping container used for out-of-view dismissal. */
     clipRoot?: MaybeRefOrGetter<Element | null>;
     /** Closes the menu after its trigger leaves the clipping container. */
     hideWhenAnchorClipped?: boolean;
-    /** Intersection ratio required to keep the anchor considered visible. Defaults to `0.5`. */
+    /** Intersection ratio required to keep the anchor considered visible. */
     intersectionThreshold?: number | number[];
-    /** Overrides the trigger rect for pointer-positioned menus. */
-    getRect?: () => DOMRect | null;
+    /**
+     * Point on the anchor rect that `offset` is computed from. Mirrors Kendo
+     * Popup's `anchorAlign` semantics. Defaults to `{ vertical: "bottom",
+     * horizontal: "left" }`, matching Kendo's own default. Passing `anchorAlign`/
+     * `popupAlign` directly to `<Popup>` has no effect when positioning via
+     * `offset` (no `anchor` DOM ref) - Kendo's own alignment engine only runs
+     * against a real anchor element - so these options exist to reproduce that
+     * alignment ourselves in the computed `offset`.
+     */
+    anchorAlign?: PopupMenuAlign;
+    /**
+     * Point on the popup itself that is placed at the computed anchor point.
+     * Mirrors Kendo Popup's `popupAlign` semantics. Defaults to `{ vertical:
+     * "top", horizontal: "left" }`. Requires measuring the rendered popup
+     * content (`popupContentRef`, falling back to `menuRef`); until it has a
+     * size (e.g. the first open frame), non-"left"/"top" alignments briefly
+     * fall back to "left"/"top".
+     */
+    popupAlign?: PopupMenuAlign;
 };
+/** Offset-positioning options for a Popup with a dynamically changing trigger. */
+export type PopupMenuAnchorOptions = PopupMenuAnchorBaseOptions & ({
+    /** Tracks a pointer or keyboard activation point relative to the trigger. */
+    activationPoint: true | PopupMenuActivationPointOptions;
+    getRect?: never;
+} | {
+    activationPoint?: never;
+    /** Resolves a custom anchor rect from the current trigger element. */
+    getRect?: (trigger: HTMLElement) => DOMRect | null;
+});
 /** Why the popup was closed, including the focus policy for mouse paths. */
 export type PopupMenuCloseReason = 
 /** Keyboard-driven menu selection (Enter/Space on a menu item); restores the configured focus target. */
@@ -48,10 +96,19 @@ export type KendoMenuSelectEvent<TItem = {
 };
 /** Options for configuring {@link usePopupMenu}. */
 export type UsePopupMenuOptions = {
-    /** Reactive flag reflecting whether the popup menu is currently open. */
-    isOpen: Ref<boolean>;
+    /** Read-only reactive flag reflecting whether the popup menu is currently open. */
+    isOpen: Readonly<Ref<boolean>>;
     /** Ref to the popup menu element or component. Used for outside-click detection. */
     menuRef: PopupMenuElementRef;
+    /**
+     * Ref to the full rendered popup content (e.g. a wrapper containing both a
+     * title and the Menu) used to measure size for a non-"left"/"top"
+     * `anchor.popupAlign`. Defaults to `menuRef` when omitted - which
+     * under-measures the popup whenever it renders anything besides the Menu
+     * (e.g. a title), throwing off `popupAlign`'s corner calculation. Not read
+     * for outside-click detection; that always uses `menuRef`.
+     */
+    popupContentRef?: PopupMenuElementRef;
     /** Ref to the trigger button element or component. Ignored by outside-click detection. */
     triggerRef: PopupMenuElementRef;
     /** Called to open the popup menu. Kendo passes its event args as a rest tuple. */
@@ -68,6 +125,12 @@ export type UsePopupMenuOptions = {
      * Takes precedence over `focusTargetRef`.
      */
     resolveFocusTarget?: () => HTMLElement | null;
+    /**
+     * Resolves the closest matching ancestor of the trigger as the configured
+     * keyboard-close focus target. Used after `resolveFocusTarget` and
+     * `focusTargetRef`.
+     */
+    focusTargetContainerSelector?: string;
     /**
      * Resolves a fallback focus target for Escape closes when no `focusTargetRef`/
      * `resolveFocusTarget` is configured, e.g. the trigger's containing grid row so
@@ -110,15 +173,17 @@ export type UsePopupMenuOptions = {
 };
 /** Functions returned by {@link usePopupMenu} for the action menu. */
 export type UsePopupMenuReturn = {
+    /** Captures an activation relative to a trigger for activation-point anchoring. */
+    setAnchorActivation: (trigger: HTMLElement | ComponentPublicInstance | null, activation: PopupMenuAnchorActivation) => boolean;
     /** Opens the menu, or closes it when it is already open. */
-    handleActionButtonClick: (...args: unknown[]) => void;
+    handleTriggerClick: (...args: unknown[]) => void;
     /**
-     * Handles keyboard input on the action button. Enter and Space open or close
+     * Handles keyboard input on the trigger. Enter and Space open or close
      * the menu. Escape closes an open menu or moves focus to the configured target.
      */
-    handleActionButtonKeydown: (...args: unknown[]) => void;
+    handleTriggerKeydown: (...args: unknown[]) => void;
     /** Closes the menu when Escape is pressed while using the menu. */
-    handleActionMenuEscape: (event: KeyboardEvent) => void;
+    handleMenuEscape: (event: KeyboardEvent) => void;
     /**
      * Closes the menu after an item is chosen, then runs the optional action
      * provided by the consuming component.
@@ -143,3 +208,4 @@ export type UsePopupMenuReturn = {
  * @returns Template event handlers for the action trigger, Kendo Menu, and Popup.
  */
 export declare const usePopupMenu: (options: UsePopupMenuOptions) => UsePopupMenuReturn;
+export {};

package/docs/menu/usePopupMenu.md

@@ -2,6 +2,8 @@
 
 [Back to Composables README](https://github.com/NantHealth/featherk/blob/integration/packages/composables/README.md)
 
+New to coordinating row and button menus in a Kendo Grid? Start with [Grid Popup Menu Orchestration](https://github.com/NantHealth/featherk/blob/integration/packages/composables/docs/menu/usePopupMenuGridOrchestration.md).
+
 Composable for accessible Kendo UI for Vue `Popup` + `Menu` action menus. It manages trigger toggling, first-item focus, outside clicks, input-modality tracking, and focus restoration. It does not trap focus or own popup state; keep `usePopupTrap` separate when focus trapping or generic popup lifecycle behavior is needed.
 
 ## Quick Start
@@ -22,8 +24,8 @@ Composable for accessible Kendo UI for Vue `Popup` + `Menu` action menus. It man
       type="button"
       aria-haspopup="menu"
       aria-expanded="false"
-      @click="menu.handleActionButtonClick"
-      @keydown="menu.handleActionButtonKeydown"
+      @click="menu.handleTriggerClick"
+      @keydown="menu.handleTriggerKeydown"
     >
       Actions
     </button>
@@ -35,7 +37,7 @@ Composable for accessible Kendo UI for Vue `Popup` + `Menu` action menus. It man
       </strong>
       <Menu
         ref="menuRef"
-        @keydown.escape="menu.handleActionMenuEscape"
+        @keydown.escape="menu.handleMenuEscape"
         @select="onSelect"
       />
     </Popup>
@@ -80,13 +82,13 @@ const onSelect = (event: KendoMenuSelectEvent) => {
 
 ## Grid Action Cell
 
-For a virtualized Kendo Grid, use `resolveFocusTarget` to locate the current row when the popup closes by keyboard. The resolver is evaluated at focus time, after the grid and popup have settled.
+For a virtualized Kendo Grid, use `focusTargetContainerSelector` to restore keyboard focus to the trigger's current row without reaching through a registry.
 
 1. Add static `aria-haspopup="menu"` and `aria-expanded="false"` to the row's trigger button template.
 2. Read `showMenu` from the row item and keep open/close state parent-owned.
 3. Create trigger and menu refs as component refs (`ComponentPublicInstance`) for Kendo wrappers.
 4. Call `usePopupMenu(...)` with an explicit `triggerMode: "button"` and map `requestShow`/`requestHide` to row-specific emits.
-5. Provide `resolveFocusTarget` so keyboard close restores focus to the current virtualized row.
+5. Provide `focusTargetContainerSelector` so keyboard close restores focus to the current virtualized row.
 6. Route menu selection through `handleMenuSelect(event, onAction)` so row action logic can use its active state before the popup closes.
 
 ```ts
@@ -118,13 +120,8 @@ const menu = usePopupMenu({
   triggerMode: "button",
   requestShow: () => emit("update:showMenu", props.dataItem.id),
   requestHide: () => emit("update:hideMenu", props.dataItem.id),
-  // Step 5: keyboard close restores focus to current virtualized grid row
-  resolveFocusTarget: () => {
-    const trigger = triggerRef.value?.$el as HTMLElement | undefined;
-    return (
-      trigger?.closest(".k-table-row[data-grid-row-index]") ?? null
-    ) as HTMLElement | null;
-  },
+  // Step 5: keyboard close restores focus to the trigger's current row
+  focusTargetContainerSelector: ".k-table-row[data-grid-row-index]",
 });
 
 // Step 6: run row-specific business action before usePopupMenu closes
@@ -149,7 +146,9 @@ A grid row can have both a row-level context menu (`triggerMode: "row"`) and a n
 
 ```ts
 // Step 2-4: independent instances, independent triggerRef, explicit triggerMode
-const rowTriggerRef = computed(() => cellRef.value?.closest(".k-table-row") as HTMLElement | null);
+const rowTriggerRef = computed(
+  () => cellRef.value?.closest(".k-table-row") as HTMLElement | null,
+);
 
 const buttonMenu = usePopupMenu({
   isOpen: computed(() => props.dataItem.showButtonMenu),
@@ -170,7 +169,15 @@ const rowMenu = usePopupMenu({
 });
 ```
 
-See [UsePopupMenu.vue](https://github.com/NantHealth/featherk/blob/integration/demos/src/views/composables/UsePopupMenu.vue) for the full reference implementation: exactly two shared instances (one row-mode, one button-mode) for the whole grid, with per-row/button trigger registries and offset-positioned Popups instead of per-row `usePopupMenu` calls.
+For a complete shared-instance implementation, see [Shared Instance Menus](https://github.com/NantHealth/featherk/blob/integration/packages/composables/docs/menu/usePopupMenuSharedInstance.md).
+
+## Row vs. Button Trigger Differences
+
+`triggerMode: "row"` and `triggerMode: "button"` share the same `handleTriggerClick`/`handleTriggerKeydown`/`handleMenuSelect` code paths - opening, closing, and selection logic is identical either way. What actually differs:
+
+- **Anchor positioning convention (not enforced, just the natural fit).** A row spans the full grid width with no single natural corner to anchor to, and the same row can be clicked at a different point every time - so row triggers conventionally use `anchor.activationPoint` (dynamic, positioned at the click/keyboard point). A button is a small, fixed-size element with an obvious anchor corner, so button triggers conventionally use plain rect-based anchoring (`anchor: true`, or `anchor` omitted) - the menu simply drops below the button every time, in the same spot. Nothing stops flipping this (e.g. `activationPoint` on a right-click-anywhere button, or a fixed rect anchor for a row menu that should always appear in one corner) - but for a shared/registry-driven trigger, `activationPoint` always requires the consumer to call `setAnchorActivation(trigger, activation)` with real coordinates before activating (see "Cursor-Positioned Row Menus" above), regardless of which mode it's paired with. `usePopupMenu` cannot capture this automatically for a shared instance, because it only ever sees the *currently active* trigger, never the one about to become active.
+- **ARIA element matching is enforced, not just conventional.** `triggerMode: "row"` only manages an element matching `tr.k-table-row`; `triggerMode: "button"` only manages an element that does **not** match `tr.k-table-row`. If the resolved `triggerRef` doesn't match the declared mode (e.g. `triggerMode: "button"` resolves to a `tr`), the composable logs a `console.warn` and skips ARIA management entirely for that resolution, rather than silently managing the wrong element shape.
+- **Escape fallback target differs.** `triggerMode: "button"` defaults `escapeFocusContainerSelector` to `.k-table-row` - pressing Escape with no closer configured focus target walks up from the button to its containing row and focuses that, keeping keyboard users in the grid's row navigation instead of stranding them on a small nested cell. `triggerMode: "row"` has no such default: the trigger *is* the row already, so Escape with no configured target simply refocuses it directly - there's nothing to "walk up" to.
 
 ## Sharing One Instance Across Many Triggers (Grid-Wide)
 
@@ -179,8 +186,8 @@ A single `usePopupMenu` instance can manage an entire list of same-mode triggers
 1. Track exactly one "active id" for the whole list, instead of a boolean per row item, via `useActiveIdRegistry<Id>()`. Only one trigger in the list can be open at a time. It exposes a read-only `activeId`, a reactive `isActive`/`activeElement` pair, and `register`/`resolve`/`activate`/`deactivate`/`isIdActive` helpers.
 2. Register each row/button element into the registry as it mounts (e.g. a `row-render` ref callback, or a component `:ref` callback) via `registry.register(id, el)`. The registry's internal element map is reactive, so `activeElement` stays correct even if a keyed/virtualized re-render swaps out the active id's underlying DOM node.
 3. Feed `isOpen: registry.isActive` and `triggerRef: registry.activeElement` straight into `usePopupMenu`, rather than deriving them from a per-row prop.
-4. Enable `anchor: true` and bind the shared `Popup` to `:offset="menu.offset"`, not `:anchor`. Kendo's `Popup.anchor` only resolves a static template-ref name once at mount; it cannot dynamically retarget a different element after the popup is already mounted. Use Kendo's `anchorAlign` and `popupAlign` props when the popup should align to a specific edge of its button. Use `anchor: { getRect: () => ... }` for cursor-positioned menus.
-5. Drive show/hide through `registry.activate(id)` / `registry.deactivate()` rather than binding `handleActionButtonClick` directly to every trigger's `@click`. A single instance's `isOpen` is one shared boolean, so `handleActionButtonClick()` cannot tell "close this trigger" apart from "open a different trigger" — calling it while another id is active will close the wrong thing.
+4. Enable `anchor: true` and bind the shared `Popup` to `:offset="menu.offset"`, not `:anchor`. Kendo's `Popup.anchor` only resolves a static template-ref name once at mount; it cannot dynamically retarget a different element after the popup is already mounted. Use `anchor.activationPoint` for pointer/keyboard context menus and `getRect(trigger)` only for custom geometry.
+5. Drive show/hide through `registry.activate(id)` / `registry.deactivate()` rather than binding `handleTriggerClick` directly to every shared trigger. A single instance's `isOpen` is one shared boolean, so the generic toggle handler cannot distinguish closing the current id from opening another id.
 
 ```ts
 // Step 1: one registry tracks the active id and resolves it to its DOM element
@@ -212,23 +219,74 @@ const toggleRowMenu = (id: number) => {
 };
 ```
 
-For a second shared instance driven by a real `@click` handler on each trigger (e.g. a per-row action button, where `handleActionButtonClick` toggle semantics would otherwise misfire on a different trigger), close the currently active trigger explicitly through the composable before switching the active id, so its `triggerRef` still resolves to the correct element at close time:
+### Cursor-Positioned Row Menus That Follow Scrolling
+
+Enable `anchor.activationPoint`, call `setAnchorActivation(row, context)` before activating the shared row id, and bind `offset` to the Popup. The composable owns trigger-relative coordinate conversion, keyboard placement, scroll reconstruction, clipping, and cleanup.
+
+```ts
+const rowMenu = usePopupMenu({
+  isOpen: rowRegistry.isActive,
+  triggerRef: rowRegistry.activeElement,
+  menuRef: rowMenuRef,
+  triggerMode: "row",
+  anchor: {
+    activationPoint: { pointerOffset: { x: -20, y: -20 } },
+  },
+  requestShow: () => {},
+  requestHide: () => rowRegistry.deactivate(),
+});
+
+const openRowMenu = (id: number, context: RowActionContext) => {
+  const row = rowRegistry.resolve(id);
+  if (!row || !rowMenu.setAnchorActivation(row, context)) return;
+  rowRegistry.activate(id);
+};
+```
+
+See [Activation-Point Anchors](https://github.com/NantHealth/featherk/blob/integration/packages/composables/docs/menu/usePopupMenuActivationAnchor.md) for the complete standalone setup and custom keyboard placement.
+
+For a second shared instance driven by a real `@click` handler on each trigger, close the currently active trigger explicitly before switching the active id, so its `triggerRef` still resolves to the correct element at close time:
 
 ```ts
 const toggleButtonMenu = (id: number) => {
   if (buttonRegistry.isIdActive(id)) {
-    buttonMenu.handleActionButtonClick(); // closes: triggerRef still matches this id
+    buttonMenu.handleTriggerClick(); // closes: triggerRef still matches this id
     return;
   }
   if (buttonRegistry.isActive.value) {
-    buttonMenu.handleActionButtonClick(); // closes the OTHER trigger correctly, before switching
+    buttonMenu.handleTriggerClick(); // closes the OTHER trigger correctly, before switching
   }
   buttonRegistry.activate(id); // the reactive watcher promotes the new trigger's aria-expanded
   nextTick(focusFirstMenuItem); // reproduce first-item focus manually; the "open" branch never ran
 };
 ```
 
-See [UsePopupMenu.vue](https://github.com/NantHealth/featherk/blob/integration/demos/src/views/composables/UsePopupMenu.vue) for the complete working version of both patterns, including the registry-building `row-render` function and composable-owned offset tracking. `useActiveIdRegistry` is now part of `@featherk/composables`, so shared-instance consumers can import it directly instead of keeping a demo-local copy.
+See [Focus and Exclusivity](https://github.com/NantHealth/featherk/blob/integration/packages/composables/docs/menu/usePopupMenuFocusAndExclusivity.md) for complete focus precedence and multi-menu coordination examples.
+
+## Pairing with `usePopupTrap`
+
+`usePopupMenu` deliberately does not trap focus (see the intro above) - a real menu should let `Tab` move on to the next element in the page, not cycle inside it. If a specific popup genuinely needs `Tab` trapped (behaving more like a modal than a menu), compose `usePopupTrap` alongside it rather than fighting its own close/focus-restoration logic:
+
+1. Pass the same `isOpen` and the resolved trigger element (`triggerEl`) that you gave `usePopupMenu`.
+2. Omit `onRequestClose` entirely. `usePopupTrap` has its own outside-click/Escape detection, but without `onRequestClose` it never acts on it - `usePopupMenu` remains the sole decision-maker for when the popup closes. Passing `onRequestClose` here would let two composables independently decide to close on the same interaction.
+3. Set `initialFocus: () => document.activeElement`. `usePopupMenu` already focuses the first enabled menu item on open; this preserves that instead of refocusing a possibly different element.
+4. Set `returnFocusToTrigger: false`. This only disables `usePopupTrap`'s own hand-rolled Escape-focus logic.
+5. **Also set `focusTrapOptions: { returnFocusOnDeactivate: false }`.** This is a separate, easy-to-miss setting: the underlying `focus-trap` library has its own independent `returnFocusOnDeactivate` option that defaults to `true` and fires on every `deactivate()`, restoring focus to whatever it captured as "previously focused" - completely bypassing step 4 and racing `usePopupMenu`'s own (correct) restoration target. Skipping this leaves focus landing on the wrong element after close, even though everything else is wired correctly.
+6. If more than one `<Popup>` is rendered in the same template (e.g. a shared row menu and a shared button menu, both permanently mounted with only `:show` toggling visibility), pass `resolvePopupEl` pointing at that specific `<Popup>` by a stable `id`. Without it, `usePopupTrap`'s default class-based lookup can't reliably tell multiple `.k-popup` elements apart and may bind the wrong one.
+
+`usePopupTrap` already defaults `allowOutsideClick` to `true` internally - no consumer action needed for that one, but see [usePopupTrap](https://github.com/NantHealth/featherk/blob/integration/packages/composables/docs/trap/usePopupTrap.md) for why it matters: without it, a genuinely active trap swallows every outside click (e.g. a second trigger in the same grid row), not just ones that would close it.
+
+```ts
+usePopupTrap({
+  isOpen: registry.isActive,
+  triggerEl: registry.activeElement,
+  // Step 6: only required when this popup coexists with another in the template.
+  resolvePopupEl: () => document.getElementById("my-shared-popup"),
+  initialFocus: () => document.activeElement as HTMLElement | null,
+  returnFocusToTrigger: false,
+  focusTrapOptions: { returnFocusOnDeactivate: false },
+});
+```
 
 ## API
 
@@ -236,26 +294,29 @@ See [UsePopupMenu.vue](https://github.com/NantHealth/featherk/blob/integration/d
 
 #### Options
 
-- `isOpen: Ref<boolean>`: Parent-owned popup visibility state.
+- `isOpen: Readonly<Ref<boolean>>`: Parent-owned popup visibility state observed, but never mutated, by the composable.
 - `menuRef: PopupMenuElementRef`: Ref to the Kendo `Menu` element or component.
+- `popupContentRef?: PopupMenuElementRef`: What a non-default `anchor.popupAlign` measures for the popup's own size. Defaults to `menuRef`; see "Aligning the Popup to the Anchor" below.
 - `triggerRef: PopupMenuElementRef`: Ref to the action trigger element or component.
 - `requestShow(): void`: Opens the parent-owned popup state.
 - `requestHide(): void`: Closes the parent-owned popup state.
 - `focusTargetRef?: PopupMenuElementRef`: Optional element/component to focus after a keyboard-driven close.
 - `resolveFocusTarget?: () => HTMLElement | null`: Dynamic focus-target resolver. It takes precedence over `focusTargetRef` and is useful for virtualized grid rows.
+- `focusTargetContainerSelector?: string`: Closest trigger ancestor to focus after any keyboard-driven close. Used after `resolveFocusTarget` and `focusTargetRef`.
 - `menuItemSelector?: string`: Selector for the first enabled item. Defaults to `.k-menu-item:not(.k-disabled)`.
 - `manageMenuTriggerAria?: boolean`: Keeps `aria-expanded` in sync with `isOpen` on the resolved `triggerRef` element. Defaults to `true`. The consumer always owns the static `aria-haspopup="menu"` attribute and the baseline `aria-expanded="false"`; the composable only ever writes `aria-expanded` and never removes it. Set to `false` to own `aria-expanded` yourself too.
 - `menuLabel?: MaybeRefOrGetter<string | null | undefined>`: Optional accessible name applied as `aria-label` to the rendered `ul[role="menubar"]`. Empty labels remove the managed attribute.
 - `triggerMode: "button" | "row"`: Required. Declares the trigger semantics so a misrouted `triggerRef` (e.g. one that unexpectedly resolves to a `tr.k-table-row` while `triggerMode: "button"` is set) is never silently managed; a mismatch logs a `console.warn` and skips ARIA management for that resolution. Use `"row"` only when a `tr.k-table-row` owns the menu trigger. Neither mode adds `role`, `tabindex`, or keyboard behavior.
-- `anchor?: true | PopupMenuAnchorOptions`: Enables document-relative `offset` tracking for dynamically retargeted Popups. `true` uses the resolved trigger's rectangle and nearest scrollable ancestor. `PopupMenuAnchorOptions` accepts `clipRoot`, `hideWhenAnchorClipped`, `intersectionThreshold`, and `getRect` for pointer-positioned menus. The threshold defaults to `0.5`; use `intersectionThreshold: 0` when any partially visible trigger should remain open. A fully clipped trigger closes with `"anchor-hidden"` without restoring focus.
+- `anchor?: true | PopupMenuAnchorOptions`: Enables document-relative offset tracking. `true` follows the trigger's bottom-left corner. `activationPoint` captures pointer/keyboard positions relative to the trigger and defaults its clipping threshold to `0`; `getRect(trigger)` remains the mutually exclusive custom-geometry escape hatch. Without `clipRoot`, the composable prefers the nearest overflow-enabled ancestor that can actually scroll, skipping styled wrappers with no overflow. Other anchors default to threshold `0.5`. A fully clipped trigger closes with `"anchor-hidden"` without restoring focus. `anchorAlign`/`popupAlign` (see below) configure the computed corner.
 
 `PopupMenuElementRef` accepts a normal `HTMLElement` ref or a Vue/Kendo component ref that exposes `$el`.
 
 #### Returns
 
-- `handleActionButtonClick()`: Toggles the menu and focuses the first enabled item after opening.
-- `handleActionButtonKeydown(event)`: `Enter` and `Space` toggle; `Escape` closes, or focuses the configured target when already closed.
-- `handleActionMenuEscape(event)`: Closes an open menu with keyboard modality.
+- `setAnchorActivation(trigger, activation)`: Captures a pointer or keyboard activation for `anchor.activationPoint`; returns `false` when activation anchoring or a trigger is unavailable.
+- `handleTriggerClick()`: Toggles the menu and focuses the first enabled item after opening.
+- `handleTriggerKeydown(event)`: `Enter` and `Space` toggle; `Escape` closes, or focuses the configured target when already closed.
+- `handleMenuEscape(event)`: Closes an open menu with keyboard modality.
 - `handleMenuSelect(event, onAction?)`: Records the selection modality, requests close, then invokes optional business logic.
 - `handlePopupClose()`: Restores focus after Kendo Popup has closed.
 - `offset`: A computed `{ left, top }` value for Kendo Popup's `:offset`; it is `{ left: 0, top: 0 }` while closed.
@@ -271,12 +332,63 @@ export type PopupMenuCloseReason =
   | "anchor-hidden"
   | null;
 export type PopupMenuCloseTrigger = Exclude<PopupMenuCloseReason, null>;
+export type PopupMenuAlign = {
+  horizontal: "left" | "center" | "right";
+  vertical: "top" | "center" | "bottom";
+};
 export type KendoMenuSelectEvent = {
   item?: { text?: string };
   event?: { type?: string } | null;
 };
 ```
 
+## Aligning the Popup to the Anchor (`anchorAlign` / `popupAlign`)
+
+Kendo's `<Popup>` only runs its own `anchorAlign`/`popupAlign` alignment engine when it is positioned via a real `anchor` DOM ref. `usePopupMenu` always positions through `:offset` instead - because Kendo's `anchor` prop resolves a static template-ref name once at mount and cannot retarget a different element per open (see the shared-instance section above) - so passing `anchor-align`/`popup-align` directly to `<Popup>` is a silent no-op when using `usePopupMenu`. Configure alignment through `anchor.anchorAlign`/`anchor.popupAlign` instead; `usePopupMenu` computes the aligned `offset` itself.
+
+- `anchorAlign?: PopupMenuAlign`: The point on the anchor rect that `offset` is computed from. Defaults to `{ horizontal: "left", vertical: "bottom" }`, matching Kendo's own default. Meaningless (a no-op) against an `activationPoint` anchor, since that anchor is already a single point with no width/height.
+- `popupAlign?: PopupMenuAlign`: The point on the popup itself that lands at the computed anchor point. Defaults to `{ horizontal: "left", vertical: "top" }`. A `"center"`/`"right"`/`"bottom"` value requires measuring the rendered popup content (via `popupContentRef`, falling back to `menuRef`), so on the very first open there can be a one-frame snap from the top-left default to the final aligned position while that measurement completes.
+- `popupContentRef?: PopupMenuElementRef`: What `popupAlign` measures for the popup's own size. Defaults to `menuRef`, which **under-measures** the popup whenever it renders anything besides the Menu - e.g. a title `<strong>` above it, as in the Grid Action Cell example - throwing off the computed corner (especially when that extra content is wider or taller than the Menu itself). Point this at a wrapper element containing everything rendered inside the `<Popup>` whenever `popupAlign` is not `{ horizontal: "left", vertical: "top" }` and the popup renders more than just the Menu.
+
+```ts
+const buttonMenu = usePopupMenu({
+  isOpen: registry.isActive,
+  triggerRef: registry.activeElement,
+  menuRef: menuRef,
+  // Only needed because the template below renders a title above the Menu -
+  // without it, popupAlign would measure just the Menu and mis-align the popup.
+  popupContentRef: popupContentRef,
+  triggerMode: "button",
+  anchor: {
+    anchorAlign: { horizontal: "right", vertical: "bottom" },
+    popupAlign: { horizontal: "right", vertical: "top" },
+  },
+  requestShow: () => {},
+  requestHide: () => registry.deactivate(),
+});
+```
+
+```vue
+<Popup :show="isOpen" :offset="buttonMenu.offset.value">
+  <!-- popupContentRef wraps everything the Popup renders, not just the Menu. -->
+  <div ref="popupContentRef">
+    <strong v-if="activeTitle">{{ activeTitle }}</strong>
+    <Menu ref="menuRef" :items="activeMenuItems" />
+  </div>
+</Popup>
+```
+
+## Flipping the Popup on Viewport Collision
+
+Whenever `anchor` is configured, `usePopupMenu` automatically flips the popup to the opposite side of the anchor, per axis, if the preferred `anchorAlign`/`popupAlign` corner would render outside the viewport (or the configured `clipRoot`, when set). This is always on and requires no configuration - it exists because Kendo's own collision-avoidance engine, like its alignment engine, only runs against a real `anchor` DOM ref and is a no-op against `usePopupMenu`'s `:offset`-based positioning.
+
+- Each axis is flipped independently: a popup can flip horizontally, vertically, both, or neither, depending on which edges it would overflow.
+- A flip is only committed if it actually reduces the overflow on that axis; a popup wider or taller than the available space is left at its preferred position rather than flipped back and forth.
+- Flip detection requires measuring the popup's real size, so `popupRect` is now measured (via `ResizeObserver`) whenever `anchor` is configured, not only when `popupAlign` is non-default.
+- `"center"` alignment on either axis never flips - flipping center to center is a no-op by definition.
+- Bounds default to the viewport (`window.innerWidth`/`innerHeight`); pass `anchor.clipRoot` to constrain flipping to a scrollable ancestor instead (the same container used for `hideWhenAnchorClipped`).
+- The underlying math is a pure, stateless function - `computeFlippedOffset` in `@featherk/composables/geometry` - reusable outside `usePopupMenu` for any anchor/popup positioning problem.
+
 ## Behavior
 
 - Pointer click, `Enter`, and `Space` toggle the menu.

package/docs/menu/usePopupMenuActivationAnchor.md

@@ -0,0 +1,132 @@
+# usePopupMenu Activation-Point Anchors
+
+[Back to usePopupMenu](https://github.com/NantHealth/featherk/blob/integration/packages/composables/docs/menu/usePopupMenu.md)
+
+Use an activation-point anchor when a context menu must open near a pointer or at a predictable keyboard position and continue following its trigger during scrolling.
+
+## Quick Start
+
+1. Register each trigger element by id.
+2. Enable `anchor.activationPoint` and bind `menu.offset` to the Popup.
+3. Capture the activation against the trigger before activating its id.
+4. Keep visibility parent-owned through the registry.
+
+```vue
+<template>
+  <table>
+    <tbody>
+      <tr
+        v-for="row in rows"
+        :key="row.id"
+        :ref="(element) => registerRow(row.id, element)"
+        class="k-table-row"
+        tabindex="0"
+        aria-haspopup="menu"
+        aria-expanded="false"
+        @click="openFromPointer(row.id, $event)"
+        @keydown.enter.prevent="openFromKeyboard(row.id)"
+        @keydown.space.prevent="openFromKeyboard(row.id)"
+      >
+        <td>{{ row.name }}</td>
+      </tr>
+    </tbody>
+  </table>
+
+  <Popup
+    :show="rowRegistry.isActive.value"
+    :offset="menu.offset.value"
+    @close="menu.handlePopupClose"
+  >
+    <Menu
+      ref="menuRef"
+      :items="items"
+      :vertical="true"
+      @keydown.escape="menu.handleMenuEscape"
+      @select="menu.handleMenuSelect"
+    />
+  </Popup>
+</template>
+
+<script setup lang="ts">
+import { ref, type ComponentPublicInstance } from "vue";
+import { Popup } from "@progress/kendo-vue-popup";
+import { Menu } from "@progress/kendo-vue-layout";
+import { usePopupMenu } from "@featherk/composables/menu";
+import { useActiveIdRegistry } from "@featherk/composables/registry";
+
+const rows = [
+  { id: 1, name: "Alpha" },
+  { id: 2, name: "Beta" },
+];
+const items = [{ text: "Open" }, { text: "Archive" }];
+const rowRegistry = useActiveIdRegistry<number>();
+const menuRef = ref<ComponentPublicInstance | null>(null);
+
+// Step 2: pointer coordinates receive 12px of visual clearance. Keyboard
+// activation defaults to x=8 and the trigger's vertical center.
+const menu = usePopupMenu({
+  isOpen: rowRegistry.isActive,
+  triggerRef: rowRegistry.activeElement,
+  menuRef,
+  triggerMode: "row",
+  anchor: {
+    activationPoint: { pointerOffset: { x: -12, y: -12 } },
+  },
+  requestShow: () => {},
+  requestHide: () => rowRegistry.deactivate(),
+});
+
+// Step 1: the registry resolves an id to the current DOM element, including
+// after keyed or virtualized rendering replaces it.
+const registerRow = (id: number, element: unknown) => {
+  rowRegistry.register(id, element as HTMLElement | null);
+};
+
+const activate = (
+  id: number,
+  activation: Parameters<typeof menu.setAnchorActivation>[1],
+) => {
+  const row = rowRegistry.resolve(id);
+  // Step 3: capture before activation because triggerRef is still null or may
+  // still resolve to the previously active row.
+  if (!row || !menu.setAnchorActivation(row, activation)) return;
+
+  // Step 4: the registry remains the owner of open state.
+  rowRegistry.activate(id);
+};
+
+const openFromPointer = (id: number, event: MouseEvent) => {
+  activate(id, {
+    triggerType: "click",
+    coordinates: { clientX: event.clientX, clientY: event.clientY },
+  });
+};
+
+const openFromKeyboard = (id: number) => {
+  activate(id, { triggerType: "keyboard" });
+};
+</script>
+```
+
+## Keyboard Position
+
+The default keyboard point is 8px inside the trigger's left edge and vertically centered. Override it when needed:
+
+```ts
+anchor: {
+  activationPoint: {
+    keyboardPosition: { x: 12, y: "bottom" },
+  },
+}
+```
+
+`y` accepts a number or `"top"`, `"center"`, or `"bottom"`.
+
+## Behavior
+
+- Pointer coordinates are converted to a trigger-relative point once.
+- Scroll and resize measurements reconstruct that point from the trigger's current rectangle.
+- The clipping threshold defaults to `0`; the menu stays open while any part of the trigger remains visible.
+- A fully clipped trigger closes with `"anchor-hidden"` without restoring focus.
+- Activation metadata is cleared whenever `isOpen` becomes false.
+- Use custom `getRect(trigger)` instead when positioning does not originate from a pointer or keyboard activation.