@featherk/composables 0.13.3 → 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

@@ -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
 

package/package.json

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