@featherk/composables 0.15.3 → 0.15.5

package/dist/index.d.ts

@@ -13,4 +13,5 @@ export { useMaskedDateRangeInput } from "./range";
 export type { RangeChangePayload } from "./range";
 export { useMaskedTimeInput } from "./time";
 export type { ChangePayload as TimeChangePayload } from "./time";
-export { POPUP_MENU_TRAP_OPTIONS, usePopupTrap } from "./trap";
+export { DIALOG_TRAP_OPTIONS, POPUP_MENU_TRAP_OPTIONS, usePopupTrap, } from "./trap";
+export type { PopupTrapOutsideClickOptions } from "./trap";

package/dist/trap/usePopupTrap.d.ts

@@ -1,21 +1,28 @@
 import { type Ref } from "vue";
 import { useFocusTrap } from "@vueuse/integrations/useFocusTrap";
+import { type OnClickOutsideOptions } from "@vueuse/core";
 export type CloseReason = "escape" | "outside";
+export type PopupTrapOutsideClickOptions = Pick<OnClickOutsideOptions, "ignore">;
 export type InitialFocus = string | ((root: HTMLElement) => HTMLElement | null | undefined);
 /**
- * Focus-restoration options for pairing `usePopupTrap` with `usePopupMenu`.
+ * Dismissal and focus-restoration options for pairing with `usePopupMenu`.
  *
- * `usePopupMenu` owns menu-close focus restoration. These settings disable
- * both competing restoration paths in `usePopupTrap` and the underlying
+ * `usePopupMenu` owns outside dismissal and menu-close focus restoration.
+ * These settings disable the trap's outside listener and both competing
+ * restoration paths in `usePopupTrap` and the underlying
  * `focus-trap` implementation. Spread this preset last so those integration
  * settings take precedence.
  */
 export declare const POPUP_MENU_TRAP_OPTIONS: {
+    readonly outsideClick: false;
     readonly returnFocusToTrigger: false;
     readonly focusTrapOptions: {
         readonly returnFocusOnDeactivate: false;
     };
 };
+export declare const DIALOG_TRAP_OPTIONS: {
+    readonly outsideClick: false;
+};
 export declare function usePopupTrap(opts: {
     isOpen: Ref<boolean>;
     onRequestClose?: (reason: CloseReason, ev?: Event) => void;
@@ -23,6 +30,7 @@ export declare function usePopupTrap(opts: {
     triggerEl?: Ref<HTMLElement | null>;
     resolvePopupEl?: () => HTMLElement | null;
     initialFocus?: InitialFocus;
+    outsideClick?: false | PopupTrapOutsideClickOptions;
     focusTrapOptions?: Parameters<typeof useFocusTrap>[1];
     returnFocusToTrigger?: boolean;
 }): {

package/docs/menu/usePopupMenu.md

@@ -268,7 +268,7 @@ See [Focus and Exclusivity](https://github.com/NantHealth/featherk/blob/integrat
 `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.
+2. Spread `POPUP_MENU_TRAP_OPTIONS` and omit `onRequestClose` entirely. The preset includes `outsideClick: false`, preventing a competing outside-click listener; the trap's independent Escape listener can still record a reason, but dismissal stays with the menu's handlers. Passing `onRequestClose` here would introduce another close-request owner.
 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.
@@ -293,8 +293,9 @@ usePopupTrap({
 ```
 
 `POPUP_MENU_TRAP_OPTIONS` is an optional convenience preset for this pairing.
-It disables the trap's competing focus restoration paths so `usePopupMenu`
-remains the sole owner of focus restoration. `initialFocus` stays explicit
+It disables the trap's outside listener and competing focus restoration paths
+so `usePopupMenu` remains the sole owner of outside dismissal and focus
+restoration. `initialFocus` stays explicit
 because it should preserve the focus behavior chosen by each menu. Spread the
 preset last in the options object so these required integration settings win
 over conflicting trap options:
@@ -307,6 +308,12 @@ usePopupTrap({
 });
 ```
 
+The preset does not change the menu's own trigger-ignore or Escape policies.
+It is intended for a companion trap, not standalone popups. Previously it
+disabled focus restoration only; callers deliberately relying on the trap's
+outside callback can place `outsideClick: {}` after the preset to retain that
+behavior, accepting responsibility for dismissal ownership.
+
 ## API
 
 ### `usePopupMenu(options)`

package/docs/menu/usePopupMenuGridOrchestration.md

@@ -485,7 +485,8 @@ this composite-id orchestration.
 
 Neither `rowMenu` nor `buttonMenu` above traps `Tab` inside its Popup - that's
 intentional (see `usePopupMenu.md`'s intro). If a specific shared popup needs
-it anyway, pair it with `usePopupTrap` using the same registry, and disable
+it anyway, pair it with `usePopupTrap` using the same registry and spread
+`POPUP_MENU_TRAP_OPTIONS` to delegate outside dismissal to the menu and disable
 both its own Escape-focus logic and the underlying `focus-trap` library's
 independent `returnFocusOnDeactivate` default, so `usePopupMenu` remains the
 sole owner of close/focus-restoration decisions. Both shared Popups above stay

package/docs/time/useMaskedTimeInput.md

@@ -14,7 +14,51 @@ This composable preserves the user's raw input: it does not coerce or rewrite wh
 
 ## Quick Start
 
+1. Create the time value, popup visibility, and DOM-wrapper refs.
+2. Configure `useMaskedTimeInput` with a unique input ID and shared value.
+3. Connect `usePopupTrap` to the time popup's state and wrapper.
+4. Replace the built-in input with a wrapped `MaskedTextBox`; wire input handlers and TimePicker popup actions.
+
 ```vue
+<template>
+  <!-- Step 4: replace TimePicker's input through dateInput, not timeInput. -->
+  <div ref="timePickerRef">
+    <TimePicker
+      v-model="selectedTime"
+      dateInput="masked"
+      :format="'hh:mm a'"
+      :min="minTime"
+      :max="maxTime"
+      :valid="isValid"
+      :validationMessage="validationMessage"
+      :show="showPicker"
+      @change="masked.handleChange"
+      @open="showPicker = true"
+      @close="showPicker = false"
+    >
+      <template #masked="{}">
+        <div class="custom-time-input">
+          <MaskedTextBox
+            id="startTime"
+            :mask="'Hh:Mm Aa'"
+            :rules="rules"
+            :value="raw"
+            :placeholder="placeholder"
+            :showClearButton="false"
+            @change="masked.handleChange"
+            @keydown="masked.handleKeyDown"
+            @keyup="masked.handleKeyUp"
+            @click="masked.handleClick"
+            @wheel="masked.handleWheel"
+            @blur="masked.handleBlur"
+          />
+        </div>
+      </template>
+    </TimePicker>
+  </div>
+  <Error for="startTime">{{ validationMessage }}</Error>
+</template>
+
 <script setup lang="ts">
 import { ref } from "vue";
 import { TimePicker } from "@progress/kendo-vue-dateinputs";
@@ -23,7 +67,7 @@ import { Error } from "@progress/kendo-vue-labels";
 import { useMaskedTimeInput } from "@featherk/composables/time";
 import { usePopupTrap } from "@featherk/composables/trap";
 
-// Shared model for TimePicker and composable
+// Step 1: shared model for this TimePicker and its own controller.
 const selectedTime = ref<Date | null | undefined>();
 const showPicker = ref(false);
 const timePickerRef = ref<HTMLElement | null>(null);
@@ -32,6 +76,7 @@ const timePickerRef = ref<HTMLElement | null>(null);
 const minTime = new Date(new Date().setHours(8, 0, 0, 0)); // 8:00 AM
 const maxTime = new Date(new Date().setHours(17, 0, 0, 0)); // 5:00 PM
 
+// Step 2: synchronize typed values and popup selections.
 const masked = useMaskedTimeInput({
   id: "startTime",
   onChange: ({ value }) => { selectedTime.value = value ?? undefined; },
@@ -40,7 +85,6 @@ const masked = useMaskedTimeInput({
   minuteStep: 5,
   min: minTime,
   max: maxTime,
-  required: true,
 });
 
 // Destructure for simpler template bindings
@@ -57,7 +101,7 @@ const {
   debugLines,
 } = masked;
 
-// Integrate focus trap for the TimePicker popup
+// Step 3: trap the popup using its DOM-wrapper ref.
 usePopupTrap({
   isOpen: showPicker,
   onRequestClose: () => (showPicker.value = false),
@@ -65,47 +109,20 @@ usePopupTrap({
   popupSelector: [".k-timeselector", ".k-popup"],
 });
 </script>
-
-<template>
-  <div ref="timePickerRef">
-    <TimePicker
-      v-model="selectedTime"
-      dateInput="masked"
-      :format="'hh:mm a'"
-      :show="showPicker"
-      @open="showPicker = true"
-      @close="showPicker = false"
-      :style="{ width: 'fit-content' }"
-    >
-      <template #masked="{ props }">
-        <MaskedTextBox
-          id="startTime"
-          :mask="'Hh:Mm Aa'"
-          :rules="rules"
-          :value="raw"
-          :placeholder="placeholder"
-          :showClearButton="false"
-          @change="masked.handleChange"
-          @keydown="masked.handleKeyDown"
-          @keyup="masked.handleKeyUp"
-          @click="masked.handleClick"
-          @wheel="masked.handleWheel"
-          @blur="masked.handleBlur"
-        />
-      </template>
-    </TimePicker>
-  </div>
-  <Error for="startTime">{{ validationMessage }}</Error>
-
-  <!-- Optional: show internal debug lines during integration -->
-  <div v-if="debugEnabled" style="margin-top: 8px; color: #475467;">
-    <div v-for="(row, idx) in debugLines" :key="idx">
-      <strong>{{ row[0] }}:</strong> {{ row[1] }}
-    </div>
-  </div>
-  </template>
 ```
 
+Like the date and date-range examples, this integration uses a custom
+`MaskedTextBox`, not Kendo's built-in date/time input. DatePicker and TimePicker
+both expose the `dateInput` slot; the range example uses a separate
+`MaskedTextBox` with a `Calendar`/`Popup`. Each picker needs its own controller,
+input ID, value, and visibility state. For a picker inside a dialog, apply
+`DIALOG_TRAP_OPTIONS` to the parent dialog trap, not the time popup trap; the
+time popup keeps its own outside dismissal.
+
+When enabling `required`, the composable can write an empty string into its
+`externalValue` on blank blur. Keep that validation state separate from the
+TimePicker's model, or normalize its binding to `Date | null | undefined`.
+
 ### Full Example
 
 For a complete integration including a focus trap, store sync, and UI tweaks, see the demo view referenced in this repository.

package/docs/trap/usePopupTrap.md

@@ -12,15 +12,141 @@ Composable for managing focus trapping and close behavior for popup UIs (e.g., K
 
 ## Quick Start
 
-```ts
+1. Create the menu visibility, trigger, and Menu component refs.
+2. Configure `usePopupMenu` to own dismissal and focus restoration.
+3. Add `usePopupTrap` with `POPUP_MENU_TRAP_OPTIONS` for focus containment only.
+4. Bind the trigger, Popup, and Menu to the menu controller's handlers.
+
+```vue
+<template>
+  <!-- Step 4: route interactions through the menu controller. -->
+  <button
+    ref="triggerRef"
+    type="button"
+    aria-haspopup="menu"
+    aria-expanded="false"
+    @click="popupMenu.handleTriggerClick"
+    @keydown="popupMenu.handleTriggerKeydown"
+  >
+    Actions
+  </button>
+  <Popup
+    :show="open"
+    :anchor="'triggerRef'"
+    @close="popupMenu.handlePopupClose()"
+  >
+    <Menu
+      ref="menuRef"
+      :items="items"
+      :vertical="true"
+      @keydown.escape="popupMenu.handleMenuEscape"
+      @select="popupMenu.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 { POPUP_MENU_TRAP_OPTIONS, usePopupTrap } from "@featherk/composables/trap";
+
+// Step 1: create consumer-owned visibility and the DOM/component refs.
+const open = ref(false);
+const triggerRef = ref<HTMLElement | null>(null);
+const menuRef = ref<ComponentPublicInstance | null>(null);
+const items = [{ text: "Edit" }, { text: "Archive" }];
+
+// Step 2: the menu owns close requests, ARIA state, and focus restoration.
+const popupMenu = usePopupMenu({
+  isOpen: open,
+  triggerRef,
+  menuRef,
+  triggerMode: "button",
+  requestShow: () => { open.value = true; },
+  requestHide: () => { open.value = false; },
+});
+
+// Step 3: preserve menu focus and delegate dismissal through the preset.
+usePopupTrap({
+  isOpen: open,
+  triggerEl: triggerRef,
+  initialFocus: () => document.activeElement as HTMLElement | null,
+  ...POPUP_MENU_TRAP_OPTIONS,
+});
+</script>
+```
+
+This pairing intentionally traps Tab inside the popup. For ordinary menus that
+let Tab move on, use `usePopupMenu` without the companion trap. The preset
+disables the trap's outside listener and competing focus restoration; outside
+clicks still close through `usePopupMenu`. Do not add `onRequestClose` to this
+trap: the menu's handlers remain the dismissal owner.
+
+### DatePicker With a Custom Masked Input
+
+1. Create independent visibility, value, input ID, and trigger refs for this picker.
+2. Configure `useMaskedDateInput` to synchronize the value and open the calendar.
+3. Connect `usePopupTrap` to the visibility and trigger refs.
+4. Replace the DatePicker input with a wrapped `MaskedTextBox` and wire its handlers.
+
+```vue
+<template>
+  <!-- Step 4: use the controller's custom input, not Kendo's built-in DateInput. -->
+  <div ref="datePickerRef">
+    <DatePicker
+      v-model="selectedDate"
+      dateInput="masked"
+      :valid="isValid"
+      :validationMessage="validationMessage"
+      :show="open"
+      @open="open = true"
+      @close="open = false"
+    >
+      <template #masked="{}">
+        <div class="custom-date-input">
+          <MaskedTextBox
+            id="popup-date"
+            :mask="'00/00/0000'"
+            :value="raw"
+            :placeholder="placeholder"
+            :showClearButton="false"
+            @change="masked.handleChange"
+            @keydown="masked.handleKeyDown"
+            @keyup="masked.handleKeyUp"
+            @click="masked.handleClick"
+            @wheel="masked.handleWheel"
+            @blur="masked.handleBlur"
+          />
+        </div>
+      </template>
+    </DatePicker>
+  </div>
+</template>
+
 <script setup lang="ts">
 import { ref, shallowRef } from "vue";
 import { DatePicker } from "@progress/kendo-vue-dateinputs";
+import { MaskedTextBox } from "@progress/kendo-vue-inputs";
+import { useMaskedDateInput } from "@featherk/composables/date";
 import { usePopupTrap } from "@featherk/composables/trap";
 
+// Step 1: create consumer-owned state and the trigger ref.
 const open = ref(false);
+const selectedDate = ref<Date | undefined>();
 const datePickerRef = shallowRef<HTMLElement | null>(null);
 
+// Step 2: give this input its own masked controller and value.
+const masked = useMaskedDateInput({
+  id: "popup-date",
+  externalValue: selectedDate,
+  onChange: ({ value }) => { selectedDate.value = value ?? undefined; },
+  onShowCalendar: () => { open.value = true; },
+});
+const { raw, placeholder, isValid, validationMessage } = masked;
+
+// Step 3: accept the trap's close requests by updating visibility.
 usePopupTrap({
   isOpen: open,
   onRequestClose: () => (open.value = false),
@@ -28,63 +154,173 @@ usePopupTrap({
   // Use defaults: finds .k-popup near the trigger within .k-animation-container
 });
 </script>
-
-<template>
-  <div ref="datePickerRef">
-    <DatePicker v-model="/* your value */" :show="open" @open="open=true" @close="open=false" />
-  </div>
-</template>
 ```
 
-When pairing this composable with `usePopupMenu`, the optional
-`POPUP_MENU_TRAP_OPTIONS` export disables the trap's competing focus
-restoration paths:
+The picker examples here use a custom `MaskedTextBox`, not Kendo's built-in
+date/time input. `DatePicker` and `TimePicker` both use `dateInput="masked"`
+with a `#masked` slot. Date ranges use a `MaskedTextBox` alongside a separate
+`Calendar`/`Popup`, rather than a date-input slot. Keep input IDs, controller
+instances, values, and visibility refs independent when multiple pickers share
+a page or a dialog.
+
+For complete picker wiring, see
+[useMaskedDateInput](https://github.com/NantHealth/featherk/blob/integration/packages/composables/docs/date/useMaskedDateInput.md),
+[useMaskedDateRangeInput](https://github.com/NantHealth/featherk/blob/integration/packages/composables/docs/range/useMaskedDateRangeInput.md), and
+[useMaskedTimeInput](https://github.com/NantHealth/featherk/blob/integration/packages/composables/docs/time/useMaskedTimeInput.md).
+
+### Pairing With usePopupMenu
+
+See [Quick Start](#quick-start) for the complete pairing. `usePopupMenu` owns
+dismissal and focus restoration; `usePopupTrap` adds focus containment.
+
+Spread `POPUP_MENU_TRAP_OPTIONS` last to disable the trap's outside listener
+and both competing focus-restoration paths. No separate `outsideClick: false`
+flag is needed. Keep `initialFocus` explicit to preserve the focus chosen by
+the menu, and omit `onRequestClose` so Escape and dismissal stay with the menu's
+handlers. `allowOutsideClick` already defaults to `true`.
+
+This preset is only for traps paired with `usePopupMenu`, not every popup.
+Standalone popups and pickers retain outside dismissal by default.
+
+### Dialog With a Teleported Calendar
+
+Dialogs should stay open on all outside clicks, including backdrop clicks and
+clicks in a teleported DatePicker calendar. Spread `DIALOG_TRAP_OPTIONS` first
+to disable the dialog trap's outside listener while preserving Escape and focus
+trapping. Close, Cancel, and confirmation buttons continue to update visibility
+through their existing handlers.
 
 ```ts
-import {
-  POPUP_MENU_TRAP_OPTIONS,
-  usePopupTrap,
-} from "@featherk/composables/trap";
+import { DIALOG_TRAP_OPTIONS, usePopupTrap } from "@featherk/composables/trap";
 
 usePopupTrap({
-  isOpen,
-  triggerEl,
-  initialFocus: () => document.activeElement as HTMLElement | null,
-  ...POPUP_MENU_TRAP_OPTIONS,
+  ...DIALOG_TRAP_OPTIONS,
+  isOpen: dialogIsVisible,
+  triggerEl: dialogTriggerRef,
+  resolvePopupEl: resolveDialogElement,
+  onRequestClose: (reason) => {
+    if (reason === "escape" && showPicker.value) return;
+    dialogIsVisible.value = false;
+  },
+});
+
+usePopupTrap({
+  isOpen: showPicker,
+  triggerEl: datePickerRef,
+  onRequestClose: () => { showPicker.value = false; },
 });
 ```
 
-Keep `initialFocus` explicit because the correct focus target is specific to
-the popup and its owning composable. `allowOutsideClick` is already `true` by
-default and is not repeated in this preset. Spread this preset last when using
-it with `usePopupMenu`; its focus-restoration settings are required for that
-integration and should take precedence over conflicting options.
+The parent guard preserves the nested keyboard policy: the first Escape closes
+only the calendar; the next closes the dialog. Focus-trap stacking alone does
+not coordinate FeatherK's independent Escape or outside-click listeners.
+Neither the preset nor `escapeDeactivates: false` disables FeatherK's Escape
+requests. No calendar-specific outside-click ignore list is needed for a dialog.
 
-### TimePicker example (custom selectors)
+### Dismissible Parent With Related Popups
+
+For a parent that intentionally dismisses on outside clicks, ignore its exact
+owned child popup rather than using a broad global calendar selector. Create the
+child trap first so its ref can be passed directly:
 
 ```ts
+const calendarTrap = usePopupTrap({
+  isOpen: showPicker,
+  triggerEl: datePickerRef,
+  onRequestClose: () => { showPicker.value = false; },
+});
+
+usePopupTrap({
+  isOpen: parentIsVisible,
+  resolvePopupEl: resolveParentElement,
+  outsideClick: { ignore: [calendarTrap.popupRef] },
+  onRequestClose: (reason) => {
+    if (reason === "escape" && showPicker.value) return;
+    parentIsVisible.value = false;
+  },
+});
+```
+
+VueUse handles ignore matching and pointerdown/click semantics. Element refs can
+start null and later mount or retarget; selectors and reactive/getter ignore
+lists are supported with the installed VueUse types. Ignoring a child affects
+dismissal only: it does not add the child to the parent's focus trap. Teleported
+children still need their own working focus containment and keyboard behavior.
+
+### TimePicker With a Custom Masked Input
+
+1. Create the time value, visibility, and DOM-wrapper refs.
+2. Configure `useMaskedTimeInput` with its own input ID and value.
+3. Connect `usePopupTrap` using the TimePicker popup selectors.
+4. Render the wrapped `MaskedTextBox` in the `dateInput` slot and wire both input and picker changes.
+
+```vue
+<template>
+  <!-- Step 4: TimePicker uses dateInput, not timeInput, for its custom input. -->
+  <div ref="timePickerRef">
+    <TimePicker
+      v-model="selectedTime"
+      dateInput="masked"
+      :format="'hh:mm a'"
+      :valid="isValid"
+      :validationMessage="validationMessage"
+      :show="showPicker"
+      @change="masked.handleChange"
+      @open="showPicker = true"
+      @close="showPicker = false"
+    >
+      <template #masked="{}">
+        <div class="custom-time-input">
+          <MaskedTextBox
+            id="popup-time"
+            :mask="'Hh:Mm Aa'"
+            :rules="rules"
+            :value="raw"
+            :placeholder="placeholder"
+            :showClearButton="false"
+            @change="masked.handleChange"
+            @keydown="masked.handleKeyDown"
+            @keyup="masked.handleKeyUp"
+            @click="masked.handleClick"
+            @wheel="masked.handleWheel"
+            @blur="masked.handleBlur"
+          />
+        </div>
+      </template>
+    </TimePicker>
+  </div>
+</template>
+
 <script setup lang="ts">
-import { ref, useTemplateRef } from "vue";
+import { ref } from "vue";
 import { TimePicker } from "@progress/kendo-vue-dateinputs";
+import { MaskedTextBox } from "@progress/kendo-vue-inputs";
+import { useMaskedTimeInput } from "@featherk/composables/time";
 import { usePopupTrap } from "@featherk/composables/trap";
 
+// Step 1: keep this picker's state separate from other examples.
+const selectedTime = ref<Date | undefined>();
 const showPicker = ref(false);
-const timePickerRef = useTemplateRef("timePickerRef");
+const timePickerRef = ref<HTMLElement | null>(null);
+
+// Step 2: synchronize typed input and popup selections through one controller.
+const masked = useMaskedTimeInput({
+  id: "popup-time",
+  externalValue: selectedTime,
+  onChange: ({ value }) => { selectedTime.value = value ?? undefined; },
+  onShowPicker: () => { showPicker.value = true; },
+  minuteStep: 5,
+});
+const { raw, rules, placeholder, isValid, validationMessage } = masked;
 
+// Step 3: trap the popup using its DOM-wrapper ref.
 usePopupTrap({
   isOpen: showPicker,
   onRequestClose: () => (showPicker.value = false),
   triggerEl: timePickerRef,
   popupSelector: [".k-timeselector", ".k-popup"],
-  returnFocusToTrigger: false, // parent will refocus the custom input
 });
 </script>
-
-<template>
-  <div ref="timePickerRef">
-    <TimePicker :show="showPicker" @open="showPicker=true" @close="showPicker=false" />
-  </div>
-</template>
 ```
 
 ## API
@@ -101,6 +337,7 @@ Sets up focus trap and close behaviors for a discovered popup element.
 - `triggerEl?: Ref<HTMLElement | null>`: The trigger/root element used as a scope to discover the popup.
 - `resolvePopupEl?: () => HTMLElement | null`: Provide your own resolver when direct selection is needed.
 - `initialFocus?: InitialFocus`: The initial focus target inside the popup: a CSS selector string or function `(root) => HTMLElement | null`.
+- `outsideClick?: false | PopupTrapOutsideClickOptions`: Omitted or `{}` preserves outside dismissal; `false` registers no outside listener; `{ ignore }` forwards VueUse's typed ignore configuration. Enablement is fixed at setup time; ignore entries remain reactive. The trigger is not automatically ignored. Escape, containment, and focus-restoration defaults are unchanged.
 - `focusTrapOptions?: Parameters<typeof useFocusTrap>[1]`: Options forwarded to `useFocusTrap`.
 - `returnFocusToTrigger?: boolean`: When closing, return focus to `triggerEl`. Defaults to `true`.
 
@@ -110,11 +347,28 @@ Sets up focus trap and close behaviors for a discovered popup element.
 - `activate(): void`: Manually activate the focus trap.
 - `deactivate(): void`: Manually deactivate the focus trap.
 - `setPopupEl(el: HTMLElement | null): void`: Override the discovered popup element.
+- `lastCloseReason: Readonly<Ref<CloseReason | null>>`: Last close-request reason, not necessarily an accepted closure. Resets to `null` on open and is preserved while closed. Disabled or ignored outside interactions do not update it; button-driven closure does not assign a new reason.
+
+#### Presets
+
+- `DIALOG_TRAP_OPTIONS = { outsideClick: false } as const`: Disables all outside-click dismissal, retaining Escape and existing focus-restoration defaults. Spread first to allow deliberate overrides.
+- `POPUP_MENU_TRAP_OPTIONS`: Includes `outsideClick: false` and disables competing focus restoration when paired with `usePopupMenu`. The menu retains its own outside listener and trigger-ignore policy.
+
+Previously, the menu preset disabled focus restoration only. Callers that
+intentionally relied on the trap's outside-close callback must override with
+`outsideClick: {}` after spreading the preset. Normal `usePopupMenu` pairings
+continue to dismiss outside through the menu's listener.
+
+The presets and `PopupTrapOutsideClickOptions` are exported from both
+`@featherk/composables/trap` and `@featherk/composables`.
 
 #### Types
 
 ```ts
+import type { OnClickOutsideOptions } from "@vueuse/core";
+
 export type CloseReason = "escape" | "outside";
+export type PopupTrapOutsideClickOptions = Pick<OnClickOutsideOptions, "ignore">;
 export type InitialFocus = string | ((root: HTMLElement) => HTMLElement | null | undefined);
 ```
 
@@ -126,14 +380,16 @@ export type InitialFocus = string | ((root: HTMLElement) => HTMLElement | null |
   - `.k-timepicker-popup`
   - `.k-menu-popup`
 - **Focus trap**: Uses `useFocusTrap(popupRef)` with a fallback/initial focus inside the popup. `escapeDeactivates` and `clickOutsideDeactivates` are disabled; closing is managed explicitly. `allowOutsideClick` defaults to `true` - without it, `focus-trap`'s own default (`false`) `preventDefault()`s and swallows *every* outside pointerdown/click while the trap is active, not just ones that would close it, blocking interaction with anything else on the page (e.g. a second trigger in the same grid row) until the trap deactivates. Override via `focusTrapOptions` only if a specific popup genuinely needs that stricter modal-style behavior.
-- **Escape to close**: Adds a `keydown` listener on the popup when opened; pressing Escape calls `onRequestClose('escape', event)` and stops propagation.
-- **Outside click to close**: Uses `onClickOutside(popupRef, ...)` to call `onRequestClose('outside', event)` when open.
-- **Open/close lifecycle**: When `isOpen` becomes true, discovers the popup, sets `popupRef`, and activates the focus trap. When it becomes false, deactivates, removes listeners, clears `popupRef`, and optionally returns focus to `triggerEl`.
+- **Escape to close**: Adds a capture-phase `keydown` listener on `document` when opened; pressing Escape calls `onRequestClose('escape', event)`. The composable does not stop propagation; consumers retain ownership of nested Escape policy.
+- **Outside click to close**: Unless disabled, uses `onClickOutside(popupRef, ...)` with VueUse's capture default to request closure when open. There should be one outside-dismissal owner per popup. Focus-trap stacking pauses containment, not this independent listener.
+- **Separate policies**: `allowOutsideClick` permits interactions and `clickOutsideDeactivates` controls containment; neither configures FeatherK's independent close requests. Do not set `allowOutsideClick: false` to prevent dialog dismissal: it can block teleported child interactions. Modal background isolation remains the dialog component's responsibility.
+- **Open/close lifecycle**: When `isOpen` becomes true, discovers the popup, sets `popupRef`, and activates the focus trap. When false, deactivates, removes the Escape listener, clears `popupRef`, and restores focus according to the configured policy. The outside listener is registered once at setup, guarded while closed, and removed by VueUse on component-scope disposal.
 
 ## Integration Patterns
 
-- **Kendo DatePicker/Popup**: Use defaults; pass `triggerEl` pointing to the DatePicker wrapper and `isOpen` from the component’s open state.
-- **Kendo TimePicker**: Provide `popupSelector` like `[".k-timeselector", ".k-popup"]` to target the menu container reliably.
+- **Kendo DatePicker**: Use `useMaskedDateInput` with a wrapped custom `MaskedTextBox` in the `dateInput` slot; pass `triggerEl` pointing to the DatePicker's DOM wrapper and `isOpen` from its open state.
+- **Date range calendar**: Use `useMaskedDateRangeInput` with its own `MaskedTextBox`, value, and popup state; trap the separate `Calendar`/`Popup` using its owned popup selector or resolver.
+- **Kendo TimePicker**: Use `useMaskedTimeInput` with a wrapped custom `MaskedTextBox`, including its `rules`, and provide `popupSelector` like `[".k-timeselector", ".k-popup"]`. Wire the TimePicker's `@change` to `masked.handleChange` as well as the custom input's `@change` so Now/Set actions use the composable's value and focus handling.
   - Note: Kendo Vue `TimePicker` uses the `dateInput` slot/prop to replace its internal input (same as `DatePicker`). Use `dateInput="masked"` and define the `#masked` slot; `timeInput` will not work.
 - **Manual resolution**: When a popup is outside the default scope, set `resolvePopupEl` to return the element directly.
 - **Initial focus**: Use `initialFocus` to direct focus to a primary interactive element inside the popup (e.g., first calendar cell or button).

package/package.json

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