@featherk/composables 0.13.2 → 0.13.4

package/dist/geometry/{computeFlippedOffset.d.ts → computeCollisionOffset.d.ts}

@@ -10,7 +10,12 @@ export type GeometryBounds = {
     right: number;
     bottom: number;
 };
-export type ComputeFlippedOffsetInput = {
+export type GeometryCollisionType = "fit" | "flip";
+export type GeometryCollision = {
+    horizontal: GeometryCollisionType;
+    vertical: GeometryCollisionType;
+};
+export type ComputeCollisionOffsetInput = {
     /** 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. */
@@ -21,20 +26,19 @@ export type ComputeFlippedOffsetInput = {
     popupAlign: GeometryAlign;
     /** Clipping bounds checked for overflow; same coordinate space as `anchor`. */
     bounds: GeometryBounds;
+    /** Per-axis collision behavior applied when the preferred corner overflows. */
+    collision: GeometryCollision;
 };
 /**
  * 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.
+ * then applies Kendo-style `fit` or `flip` collision behavior independently
+ * on each axis. Fit shifts the popup within bounds without changing sides;
+ * flip moves it to the anchor's opposite side only when that reduces overflow.
  *
- * 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.
+ * Returns the preferred position when `popup` is `null`, since collision
+ * behavior cannot be calculated before the popup has been measured.
  */
-export declare const computeFlippedOffset: ({ anchor, popup, anchorAlign, popupAlign, bounds, }: ComputeFlippedOffsetInput) => {
+export declare const computeCollisionOffset: ({ anchor, popup, anchorAlign, popupAlign, bounds, collision, }: ComputeCollisionOffsetInput) => {
     left: number;
     top: number;
 };

package/dist/geometry/index.d.ts

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

package/dist/menu/usePopupMenu.d.ts

@@ -1,5 +1,5 @@
 import { type ComponentPublicInstance, type ComputedRef, type MaybeRefOrGetter, type Ref } from "vue";
-import { type GeometryAlign } from "../geometry";
+import { type GeometryAlign, type GeometryCollision } 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";
@@ -9,6 +9,8 @@ export type PopupMenuOffset = {
 };
 /** Mirrors Kendo Popup's `anchorAlign`/`popupAlign` point shape. */
 export type PopupMenuAlign = GeometryAlign;
+/** Per-axis viewport collision behavior for offset-positioned popups. */
+export type PopupMenuCollision = GeometryCollision;
 export type PopupMenuAnchorActivation = {
     triggerType: "click" | "keyboard";
     coordinates?: {
@@ -35,6 +37,8 @@ type PopupMenuAnchorBaseOptions = {
     hideWhenAnchorClipped?: boolean;
     /** Intersection ratio required to keep the anchor considered visible. */
     intersectionThreshold?: number | number[];
+    /** Per-axis collision behavior. Defaults to `flip` on both axes. */
+    collision?: PopupMenuCollision;
     /**
      * Point on the anchor rect that `offset` is computed from. Mirrors Kendo
      * Popup's `anchorAlign` semantics. Defaults to `{ vertical: "bottom",
@@ -49,9 +53,8 @@ type PopupMenuAnchorBaseOptions = {
      * 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".
+     * border box; until it has a size (e.g. the first open frame), non-"left"/
+     * "top" alignments briefly fall back to "left"/"top".
      */
     popupAlign?: PopupMenuAlign;
 };
@@ -101,12 +104,10 @@ export type UsePopupMenuOptions = {
     /** 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`.
+     * Optional measurement source for custom popup markup. The source is
+     * promoted to its nearest Kendo `.k-popup` so alignment and collision use
+     * the complete border box. Defaults to `menuRef`; outside-click detection
+     * always uses `menuRef` directly.
      */
     popupContentRef?: PopupMenuElementRef;
     /** Ref to the trigger button element or component. Ignored by outside-click detection. */

package/docs/menu/usePopupMenu.md

@@ -11,7 +11,7 @@ Composable for accessible Kendo UI for Vue `Popup` + `Menu` action menus. It man
 1. Add static `aria-haspopup="menu"` and baseline `aria-expanded="false"` to the trigger element in your template. The composable never sets `aria-haspopup` and never removes `aria-expanded`; the consumer owns both as the closed-state baseline.
 2. Create parent-owned refs for `isOpen`, `triggerRef`, `menuRef`, and an optional keyboard focus target.
 3. Call `usePopupMenu(...)` with `requestShow`, `requestHide`, and an explicit `triggerMode: "button"` (or `"row"`).
-4. Route Kendo Menu `@select` through `handleMenuSelect(event, onAction)` so your business action runs while the active menu context is still available, before the composable closes the popup.
+4. Route Kendo Menu `@select` through `handleMenuSelect(event, onAction)` so the composable closes the popup before running your business action synchronously.
 5. Bind trigger button `@click` and `@keydown` to the composable handlers.
 6. Bind Popup `@close` and Menu `@keydown.escape` so keyboard and mouse close paths restore focus correctly.
 
@@ -70,7 +70,7 @@ const menu = usePopupMenu({
   requestHide: () => (isOpen.value = false),
 });
 
-// Step 4: act while the active context is available; usePopupMenu closes afterward
+// Step 4: usePopupMenu closes before running the business action synchronously
 const onSelect = (event: KendoMenuSelectEvent) => {
   menu.handleMenuSelect(event, (selected) => {
     // Keep application-specific actions in the consuming component.
@@ -89,7 +89,7 @@ For a virtualized Kendo Grid, use `focusTargetContainerSelector` to restore keyb
 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 `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.
+6. Route menu selection through `handleMenuSelect(event, onAction)` so the popup closes before row action logic runs synchronously.
 
 ```ts
 <script setup lang="ts">
@@ -124,7 +124,7 @@ const menu = usePopupMenu({
   focusTargetContainerSelector: ".k-table-row[data-grid-row-index]",
 });
 
-// Step 6: run row-specific business action before usePopupMenu closes
+// Step 6: usePopupMenu closes before running the row-specific business action
 const onSelect = (event: KendoMenuSelectEvent) => {
   menu.handleMenuSelect(event, (selected) => {
     // Row-specific action logic remains here.
@@ -315,7 +315,7 @@ usePopupTrap({
 
 - `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.
+- `popupContentRef?: PopupMenuElementRef`: Optional measurement source for custom popup markup. The composable measures its nearest Kendo `.k-popup` border box, falling back to the source element itself. 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.
@@ -326,7 +326,7 @@ usePopupTrap({
 - `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. `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.
+- `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` configure the computed corner, while `collision` configures per-axis `fit` or `flip` behavior.
 
 `PopupMenuElementRef` accepts a normal `HTMLElement` ref or a Vue/Kendo component ref that exposes `$el`.
 
@@ -355,6 +355,10 @@ export type PopupMenuAlign = {
   horizontal: "left" | "center" | "right";
   vertical: "top" | "center" | "bottom";
 };
+export type PopupMenuCollision = {
+  horizontal: "fit" | "flip";
+  vertical: "fit" | "flip";
+};
 export type KendoMenuSelectEvent = {
   item?: { text?: string };
   event?: { type?: string } | null;
@@ -366,17 +370,14 @@ export type KendoMenuSelectEvent = {
 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.
+- `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, 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`: Optional measurement source for custom popup markup. The composable promotes it (or `menuRef` by default) to the nearest Kendo `.k-popup`, ensuring titles, sibling content, and popup borders are included in alignment and collision calculations.
 
 ```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" },
@@ -389,24 +390,29 @@ const buttonMenu = usePopupMenu({
 
 ```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>
+  <strong v-if="activeTitle">{{ activeTitle }}</strong>
+  <Menu ref="menuRef" :items="activeMenuItems" />
 </Popup>
 ```
 
-## Flipping the Popup on Viewport Collision
+## Handling 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.
+Whenever `anchor` is configured, `usePopupMenu` applies collision behavior if the preferred `anchorAlign`/`popupAlign` corner would render outside the viewport or configured `clipRoot`. Configure each axis independently with `anchor.collision`; both axes default to `"flip"`, preserving the original behavior.
 
-- Each axis is flipped independently: a popup can flip horizontally, vertically, both, or neither, depending on which edges it would overflow.
+- `"flip"` moves the popup to the opposite side of the anchor when that reduces overflow.
+- `"fit"` shifts the popup just far enough to remain within bounds without changing anchor sides. If the popup is larger than the available space, that axis is pinned to the bounds' starting edge.
+- Mixed strategies are supported, for example `{ horizontal: "fit", vertical: "flip" }`.
 - 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.
+- Collision detection requires measuring the popup's real size, so `popupRect` is measured via `ResizeObserver` whenever `anchor` is configured.
 - `"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.
+- Bounds default to the viewport (`window.innerWidth`/`innerHeight`); pass `anchor.clipRoot` to constrain collision handling to a scrollable ancestor instead (the same container used for `hideWhenAnchorClipped`).
+- The underlying math is a pure, stateless function - `computeCollisionOffset` in `@featherk/composables/geometry` - reusable outside `usePopupMenu` for any anchor/popup positioning problem.
+
+```ts
+anchor: {
+  collision: { horizontal: "fit", vertical: "flip" },
+}
+```
 
 ## Behavior
 
@@ -417,7 +423,7 @@ Whenever `anchor` is configured, `usePopupMenu` automatically flips the popup to
 - Trigger replacement and virtualization are handled by re-resolving the ref. The previous trigger is demoted to `aria-expanded="false"`, not stripped of attributes, so a shared instance can move between many rows (e.g. a grid) without losing each row's `aria-haspopup` baseline. Set `manageMenuTriggerAria` to `false` when the consumer owns `aria-expanded` too.
 - Opening focuses the first enabled Kendo Menu item after Vue renders it.
 - Outside clicks close the menu, while the trigger is ignored to prevent a close/reopen race.
-- Menu selection runs the optional business callback while the active state is still available, then records modality and closes the popup.
+- Menu selection records modality and requests close before running the optional business callback synchronously. Registry-backed consumers must snapshot business context before calling `handleMenuSelect`; `useActionCellMenu` does this internally.
 - `Escape` on the trigger or inside the menu uses the keyboard close path.
 - Keyboard-driven closes focus `resolveFocusTarget()` or `focusTargetRef`, then fall back to the trigger.
 - Mouse selection closes restore focus to the trigger.

package/docs/menu/usePopupMenuGridOrchestration.md

@@ -340,17 +340,19 @@ const handleGridKeydown = (event: KeyboardEvent) => {
 };
 
 const handleRowMenuSelect = (event: KendoMenuSelectEvent) => {
+  const record = activeRowRecord.value;
   rowMenu.handleMenuSelect(event, (selection) => {
-    if (selection.item && activeRowRecord.value) {
-      console.log(selection.item.id, activeRowRecord.value);
+    if (selection.item && record) {
+      console.log(selection.item.id, record);
     }
   });
 };
 
 const handleButtonMenuSelect = (event: KendoMenuSelectEvent) => {
+  const record = activeButtonRecord.value;
   buttonMenu.handleMenuSelect(event, (selection) => {
-    if (selection.item && activeButtonRecord.value) {
-      console.log(selection.item.id, activeButtonRecord.value);
+    if (selection.item && record) {
+      console.log(selection.item.id, record);
     }
   });
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@featherk/composables",
-  "version": "0.13.2",
+  "version": "0.13.4",
   "main": "dist/featherk-composables.umd.js",
   "module": "dist/featherk-composables.es.js",
   "types": "dist/index.d.ts",