@featherk/composables 0.4.12 → 0.5.0

package/docs/range/useMaskedDateRangeInput.md

@@ -0,0 +1,213 @@
+# useMaskedDateRangeInput
+
+[← Back to Composables README](../../README.md)
+
+Composable for a masked date range input that pairs naturally with Kendo Vue `MaskedTextBox` and `Calendar`. It handles typed input in the mask `MM/DD/YYYY - MM/DD/YYYY`, keyboard steppers (ArrowUp/ArrowDown), wheel steppers, caret persistence, min/max clamping, ordered range validation, span calculation, and optional popup-close coordination when the calendar sets the value.
+
+This composable is designed to preserve the user's raw input: it does not coerce or rewrite what the user has typed in `onChange`. It only emits a parsed `SelectionRange` when the input is complete and valid.
+
+## Prerequisites
+
+- Vue 3 Composition API
+- `@progress/kendo-vue-inputs` (for `MaskedTextBox`)
+- `@progress/kendo-vue-dateinputs` (for `Calendar`, `SelectionRange`)
+- Optional: `@progress/kendo-vue-popup` for calendar popup, and a focus trap (e.g., `usePopupTrap`) if desired.
+
+## Quick Start
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { MaskedTextBox } from "@progress/kendo-vue-inputs";
+import { SvgIcon } from "@progress/kendo-vue-common";
+import { Calendar, type SelectionRange } from "@progress/kendo-vue-dateinputs";
+import { Popup } from "@progress/kendo-vue-popup";
+import { useMaskedDateRangeInput } from "@featherk/composables/range";
+
+const showCal = ref(false);
+const dateRange = ref<SelectionRange | null | undefined>();
+
+// Example bounds (customize for your app)
+const ONE_YEAR = 365 * 24 * 60 * 60 * 1000;
+const MIN_DATE = new Date(Date.now() - ONE_YEAR);
+const MAX_DATE = new Date(Date.now() + ONE_YEAR);
+
+const openCalendar = () => { showCal.value = true; };
+const closeCalendar = () => { showCal.value = false; };
+
+const range = useMaskedDateRangeInput({
+  id: "date-range-input",
+  onChange: ({ value }) => { dateRange.value = value ?? undefined; },
+  onShowCalendar: openCalendar,
+  externalValue: dateRange,
+  // Validation bounds
+  min: MIN_DATE,
+  max: MAX_DATE,
+  // Optional: cap the span length in days (uncomment to enforce)
+  // maxSpanDays: 90,
+  isOpen: showCal,
+  onRequestClose: closeCalendar,
+  closeDelay: 280,
+  debug: true,
+});
+
+// Example icon; provide your own `dateRangeIcon` or CSS mask
+const dateRangeIcon = { name: "calendar" } as any; // use @featherk/icons getCustomIcon here
+
+const rawInput = range.raw;
+const clickAdornment = () => { showCal.value ? closeCalendar() : openCalendar(); };
+</script>
+
+<template>
+  <MaskedTextBox
+    id="date-range-input"
+    v-model="rawInput"
+    :mask="'00/00/0000 - 00/00/0000'"
+    placeholder="Start Date - End Date"
+    :inputSuffix="'calendar-adornment'"
+    @change="range.handleChange"
+    @keydown="range.handleKeyDown"
+    @keyup="range.handleKeyUp"
+    @wheel.prevent="range.handleWheel"
+    @click="range.handleClick"
+  >
+    <template #calendar-adornment>
+      <SvgIcon
+        :icon="dateRangeIcon"
+        class="calendar-adornment-icon"
+        @mousedown.prevent.stop="clickAdornment"
+      />
+    </template>
+  </MaskedTextBox>
+
+  <Popup :anchor="'date-range-input'" :show="showCal" :animate="false">
+    <Calendar
+      v-model="dateRange"
+      :mode="'range'"
+      :min="MIN_DATE"
+      :max="MAX_DATE"
+      @change="range.onCalendarChange"
+    />
+  </Popup>
+
+  <!-- Example debug line showing validation info -->
+  <div style="margin-top: 0.5rem; font-size: 0.875rem;">
+    Span (days): {{ range.spanDays ?? '-' }}
+    • Valid: {{ range.valid ?? '-' }}
+    • Reason: {{ range.reason ?? '-' }}
+  </div>
+</template>
+
+<style scoped>
+.calendar-adornment-icon { cursor: pointer; }
+</style>
+```
+
+## API
+
+### `useMaskedDateRangeInput(options)`
+
+Creates a controller for a masked date range input.
+
+#### Options
+
+- **`id: string`**: The DOM id of the `MaskedTextBox` input element.
+- **`onChange: (p: { value: SelectionRange | null; event: any }) => void`**: Callback when the composable has a new parsed value to emit.
+  - Emits `value=null` if input is incomplete, invalid, outside min/max, or out of order.
+  - Does not mutate the user's raw string.
+- **`onShowCalendar: (e: KeyboardEvent) => void`**: Called when the user presses Space on the input; the composable prevents default and triggers this to open the calendar.
+- **`externalValue?: Ref<SelectionRange | null | undefined>`**: A reactive range source (e.g., the `v-model` bound to the calendar). When it updates, the composable mirrors it into `raw` without clobbering in-progress user typing.
+- **`externalValid?: Ref<boolean | undefined>`**: Optional external validity ref to mirror computed validity state into.
+- **`manageValid?: boolean`**: Defaults to `true`. When enabled, mirrors `validComputed` into `externalValid`.
+- **`min?: Date` / `max?: Date`**: Bounds for clamping and validation.
+- **`maxSpanDays?: number`**: Optional maximum allowed span between start and end (in days).
+- **`allowReverse?: boolean`**: Whether `end` may be before `start`. Defaults to `false` (requires ordered start ≤ end).
+- **`isOpen?: Ref<boolean>`**: Reactive flag for the calendar popup. If provided, the composable can coordinate closing after calendar changes.
+- **`onRequestClose?: () => void`**: Called to close the popup when `externalValue` changes due to a calendar selection.
+- **`closeDelay?: Ref<number> | number`**: Delay in ms before calling `onRequestClose` after a calendar-originated change.
+- **`debug?: boolean`**: Enables internal debug reporting (e.g., `debugLines`).
+
+#### Returns
+
+- **`raw: Ref<string>`**: The masked string `MM/DD/YYYY - MM/DD/YYYY`. Use as `v-model` for `MaskedTextBox`.
+- **`cursorPos: Ref<number | undefined>`**: Tracks caret position to restore after programmatic updates.
+- **`debugEnabled: Ref<boolean>`** and **`debugLines: Computed<Array<{label:string; value:string}>>`**: Debug info for UI display.
+- **`digitsOnly: Computed<string>`**: The raw string with non-digits removed.
+- **`valid: Ref<boolean | undefined>`**: Managed validity state (mirrored into `externalValid` when enabled).
+- **`validComputed: Readonly<ComputedRef<boolean | undefined>>`**: Derived validity considering mask completeness, min/max clamping, ordering, and span constraints.
+- **`reason: Readonly<ComputedRef<string | undefined>>`**: Explanation for invalid states; returns `'valid'` when the range passes validation.
+- **`spanDays: Readonly<ComputedRef<number | undefined>>`**: Span in days between clamped start/end; `undefined` when incomplete or invalid.
+- Readonly computed parts: **`month1`**, **`day1`**, **`year1`**, **`month2`**, **`day2`**, **`year2`** (strings). Useful for diagnostics.
+- Event handlers to wire to the input:
+  - **`handleChange(event)`**: Assigns `raw` from the input event and emits parsed range when complete and valid.
+  - **`handleKeyDown(event)`**:
+    - Space: prevents default and calls `onShowCalendar`.
+    - ArrowUp/ArrowDown: interprets as steppers for the focused date part (month/day/year) and emits parsed range or `null` accordingly.
+  - **`handleWheel(event)`**: Prevents page scroll; interprets wheel as steppers (up/down) for the focused part.
+  - **`handleKeyUp(event)`**: Maintains caret position after cursor keys/steppers.
+  - **`handleClick(event)`**: Captures caret position on click for restoring.
+  - **`onCalendarChange()`**: Marks subsequent `externalValue` updates as calendar-originated; used to optionally auto-close the popup.
+
+## Behavior Details
+
+- **Mask and parsing**: Expects `00/00/0000 - 00/00/0000`. Parsing requires both dates to be complete (10 chars each) and valid per calendar rules.
+- **Validation**:
+  - Each side must be a valid date (including month/day bounds like Feb 29).
+  - Clamped to `min`/`max` if provided; outside results in `value=null`.
+  - Ordered range required unless `allowReverse=true`.
+  - `spanDays` computes the day difference (UTC midnight aligned) between clamped `start` and `end`. If `maxSpanDays` is provided and `spanDays` exceeds it, validity fails and `reason` reflects the constraint.
+- **Steppers**:
+  - ArrowUp/ArrowDown and mouse wheel increments/decrements the focused part (`mm`, `dd`, `yyyy`) with wrapping where appropriate and day overflow correction (e.g., moving from Jan 31 to Feb adjusts day within range).
+  - If both sides are missing, steppers initialize the range to today on both ends and restore caret.
+- **Caret persistence**: After programmatic updates, caret is restored to the prior position to preserve typing flow.
+- **Space key**: The input consumes Space to open the calendar via `onShowCalendar` without inserting a space into `raw`.
+- **External sync**: When `externalValue` is set (typically by the calendar), `raw` is updated to reflect the selected range. If a popup is open and the change is marked calendar-originated, the composable calls `onRequestClose` after `closeDelay`.
+- **Raw preservation**: When external range becomes invalid/empty, the composable does not overwrite `raw`, preserving in-progress text.
+- **Styling hook**: On mount, adds `fk-daterangepicker` class to the input's parent container for theming.
+
+## Integration Pattern (Kendo + Popup)
+
+Wire the returned handlers to the `MaskedTextBox`. Use `externalValue` for syncing with the `Calendar` `v-model`. Optionally coordinate popup closing with `isOpen`/`onRequestClose`.
+
+Key event bindings:
+
+- `@change="range.handleChange"`
+- `@keydown="range.handleKeyDown"`
+- `@keyup="range.handleKeyUp"`
+- `@wheel.prevent="range.handleWheel"`
+- `@click="range.handleClick"`
+
+Calendar coordination:
+
+- Bind `v-model` on `Calendar` to the same `SelectionRange` ref passed as `externalValue`.
+- Call `@change="range.onCalendarChange"` so the composable knows the update came from the calendar.
+- Provide `isOpen`, `onRequestClose`, and `closeDelay` for smooth auto-closing after calendar selection.
+
+<!-- Example moved above into Quick Start to reduce duplication. Full reference implementation: -->
+The project’s full reference implementation is in [src/components/custom-date-range-picker/CustomDateRangePicker.vue](../src/components/custom-date-range-picker/CustomDateRangePicker.vue), which includes advanced styling, focus-trap, and accessibility tweaks.
+
+## Accessibility Notes
+
+- Consider applying a focus trap and escape/OutsideClick handling to the calendar popup (e.g., using a `usePopupTrap` composable).
+- For multi-view calendars, you may wish to ensure only one `.k-calendar-table` is tabbable (`tabIndex=0`) and set others to `-1` to improve keyboard navigation.
+
+## Limitations & Assumptions
+
+- Date format is fixed to `MM/DD/YYYY`; internationalization of the mask and parser is not yet included.
+- Built to pair with Kendo Vue inputs/dateinputs; other inputs may need minor adjustments.
+
+## Tips
+
+- Keep `min`/`max` aligned with your calendar configuration for consistent clamping.
+- Use `debug: true` and display `debugLines` during integration to verify caret, parsed values, and masks.
+- Avoid mutating `raw` externally except through `v-model`; let the composable manage its value and emit parsed ranges.
+
+## Types
+
+```ts
+export type RangeChangePayload = { value: SelectionRange | null; event: any };
+```
+
+## Example: CustomDateRangePicker Wiring
+
+The project’s `CustomDateRangePicker.vue` demonstrates full integration with calendar adornment, popup, focus trap, and Pinia store updates. Mirror that pattern and wire the composable’s handlers to the `MaskedTextBox`, pass your range ref as `externalValue`, and coordinate popup open/close via `onShowCalendar`, `isOpen`, `onRequestClose`, and `closeDelay`.

package/docs/time/useMaskedTimeInput.md

@@ -0,0 +1,197 @@
+# useMaskedTimeInput
+
+[← Back to Composables README](../../README.md)
+
+Composable for a masked single-time input that pairs naturally with Kendo Vue `MaskedTextBox`, and optionally coordinates with a `TimePicker`. It handles typed input in the mask `hh:mm AM`, keyboard steppers (ArrowUp/ArrowDown), wheel steppers, caret persistence, minute step granularity, min/max time validation, and clean emission only when the input is complete and valid.
+
+This composable preserves the user's raw input: it does not coerce or rewrite what the user has typed in `onChange` beyond lightweight conveniences (e.g., completing `AM/PM`). It emits a parsed `Date` (today's date with the chosen time) only when the input is complete and valid.
+
+## Prerequisites
+
+- Vue 3 Composition API
+- `@progress/kendo-vue-inputs` (for `MaskedTextBox`)
+- Optional: `@progress/kendo-vue-dateinputs` (for `TimePicker`) and `@progress/kendo-vue-popup` for a popup
+
+## Quick Start
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { TimePicker } from "@progress/kendo-vue-dateinputs";
+import { MaskedTextBox } from "@progress/kendo-vue-inputs";
+import { Error } from "@progress/kendo-vue-labels";
+import { useMaskedTimeInput } from "@featherk/composables/time";
+
+// Shared model for TimePicker and composable
+const selectedTime = ref<Date | null | undefined>();
+const showPicker = ref(false);
+
+// Example bounds (customize for your app)
+const minTime = ref(new Date(new Date().setHours(8, 0, 0, 0))); // 8:00 AM
+const maxTime = ref(new Date(new Date().setHours(17, 0, 0, 0))); // 5:00 PM
+
+const masked = useMaskedTimeInput({
+  id: "startTime",
+  onChange: ({ value }) => { selectedTime.value = value ?? undefined; },
+  onShowPicker: () => (showPicker.value = true), // Space opens the time menu
+  externalValue: selectedTime,                    // Mirror TimePicker selection into the mask
+  minuteStep: 5,
+  minTime,
+  maxTime,
+});
+
+// Destructure for simpler template bindings
+const {
+  raw,
+  rules,
+  placeholder,
+  isValid,
+  validationMessage,
+  debugEnabled,
+  debugLines,
+} = masked;
+</script>
+
+<template>
+  <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"
+      />
+    </template>
+  </TimePicker>
+  <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>
+```
+
+### Full Example
+
+For a complete integration including a focus trap, store sync, and UI tweaks, see the demo view referenced in this repository.
+
+## API
+
+### `useMaskedTimeInput(options)`
+
+Creates a controller for a masked single-time input.
+
+#### Options
+
+- `id: string`: DOM id of the `MaskedTextBox` input element.
+- `onChange: (p: ChangePayload) => void`: Called with `{ value, event }` when the composable has a new parsed value to emit.
+  - Emits `value = null` if input is empty, incomplete, invalid, or outside min/max.
+  - Does not mutate the user's raw string beyond minor conveniences.
+- `onShowPicker: (e: KeyboardEvent) => void`: Called when Space is pressed on the input; use this to open a time menu/popup.
+- `externalValue?: Ref<string | Date | null | undefined>`: Reactive external source for the selected time. When it updates to a valid `Date`, the composable mirrors it into `raw` without clobbering in‑progress typing.
+- `minuteStep?: 1 | 5 | 10 | 15 | 20 | 30`: Stepping granularity when ArrowUp/ArrowDown are used in the minutes segment.
+- `minuteStepRef?: Ref<1 | 5 | 10 | 15 | 20 | 30 | undefined>`: Reactive alternative to update step granularity at runtime.
+- `timeFormat?: string`: Placeholder/format hint (default: `hh:mm AM`).
+- `minTime?: Ref<Date | null | undefined>` / `maxTime?: Ref<Date | null | undefined>`: Bounds for validation.
+- `debug?: boolean`: Enables internal debug reporting (e.g., `debugLines`).
+
+#### Returns
+
+- `raw: Ref<string>`: The masked string `hh:mm AM`. Use as `v-model` for `MaskedTextBox`.
+- `rules: Record<string, RegExp>`: Relaxed mask rules for Kendo `MaskedTextBox` to allow free typing, followed by composable validation.
+- `cursorPos: Ref<number | undefined>`: Caret position for restoring after programmatic updates.
+- `placeholder: Ref<string>`: Format placeholder (defaults to `hh:mm AM`).
+- `digitsOnly: Computed<string>`: Raw string stripped of non-digits.
+- `hour`, `minute`, `period`: Readonly computed parts (numeric hour/minute, `AM`/`PM`).
+- `isComplete: Computed<boolean>`: `true` when the raw string matches `^(\d{2}):(\d{2})\s([AP]M)$`.
+- `isValid: Computed<boolean>`: Validity considering completeness, parsability, and min/max bounds.
+- `validationMessage: Computed<string>`: Human-readable message for invalid states (format or range messages).
+- Event handlers to wire to the input:
+  - `handleChange(event)` — Assigns `raw`, tracks caret, fills `AM/PM` when appropriate, emits parsed time when valid.
+  - `handleKeyDown(event)` — Space opens the picker via `onShowPicker`; ArrowUp/ArrowDown act as steppers.
+  - `handleWheel(event)` — Prevents page scroll; interprets wheel as steppers (up/down) for the focused part.
+  - `handleKeyUp(event)` — Maintains caret position after cursor keys/steppers.
+  - `handleClick(event)` — Captures caret position on click for restoring.
+
+- Debug:
+  - `debugEnabled: Ref<boolean>`
+  - `debugLines: Computed<Array<{ label: string; value: string }>>`
+
+## Behavior Details
+
+- **Mask and parsing**: Expects `00:00 AM`. Parsing requires the input to be complete and form a real time (`01–12` hours, `00–59` minutes), with `AM/PM`. Parsed output is a `Date` for today at the chosen time.
+- **AM/PM convenience**: When caret is in the AM/PM segment and a user types `A/a` or `P/p`, the composable auto-completes to `AM`/`PM`.
+- **Emission policy**: Emits `Date` only when the raw is complete, valid, and within `minTime`/`maxTime`. Otherwise emits `null`. Empty input emits `null`.
+- **Min/Max validation**: Bounds are evaluated by minutes since midnight. Times outside bounds are invalid (`isValid=false`) and produce a range `validationMessage`.
+- **Steppers**: ArrowUp/ArrowDown and mouse wheel increment/decrement the focused part (hours, minutes with `minuteStep`, or `AM/PM`). If raw is incomplete/invalid, steppers initialize to a sensible baseline before emitting.
+- **Caret persistence**: After programmatic updates (including steppers), the caret is restored to the prior position to preserve typing flow.
+- **Space key**: The input consumes Space and calls `onShowPicker` to open a time menu without inserting a space into `raw`.
+- **External sync**: When `externalValue` is set to a valid `Date`, `raw` mirrors it (e.g., from a `TimePicker` selection). If external becomes null/invalid, `raw` is preserved to avoid clobbering in-progress text.
+- **Styling hook**: On mount, adds a theming class (e.g., `fk-timepicker`) to the closest Kendo time picker container for styling.
+
+## Integration Patterns
+
+- **MaskedTextBox only**: Use the Quick Start to accept typed times with validation — no time menu required.
+- **Popup + TimePicker**: Bind a `TimePicker` to the same `timeValue` ref passed as `externalValue`. Use Space key (`onShowPicker`) to open the popup and keep bounds (`minTime`/`maxTime`) aligned.
+- **Minute step control**: Provide `minuteStep` or a reactive `minuteStepRef` to control ArrowUp/ArrowDown behavior in the minutes segment at runtime.
+
+### Important: Kendo TimePicker slot name
+
+When replacing the built‑in input inside Kendo Vue `TimePicker`, the component expects the prop/slot name `dateInput`, not `timeInput`. This is a Kendo API quirk shared with `DatePicker`.
+
+Example:
+
+```vue
+<TimePicker v-model="timeValue" dateInput="masked">
+  <template #masked="{ props }">
+    <!-- your custom MaskedTextBox here -->
+  </template>
+</TimePicker>
+```
+
+If you use `timeInput`, the slot will not render and you may waste time debugging. Our demo uses `dateInput="masked"` on `TimePicker` to align with this behavior.
+
+## Accessibility Notes
+
+- Ensure labels (e.g., Kendo `Label` with `for`) correctly reference the input `id`.
+- If using a popup time menu, consider adding a focus trap and Escape/OutsideClick handling (see `usePopupTrap`).
+- Keep tab order logical; Space opens the menu, Escape should close it.
+
+## Limitations & Assumptions
+
+- Time format is fixed to `hh:mm AM`; internationalization and 24-hour masks are not included yet.
+- Built to pair with Kendo Vue inputs/dateinputs; other inputs may need minor adjustments.
+
+## Tips
+
+- Keep `minTime`/`maxTime` aligned with your `TimePicker` configuration for consistent validation.
+- Use `debug: true` and display `debugLines` during integration to verify caret, parsed values, and masks.
+- Avoid mutating `raw` externally except through `v-model`; let the composable manage its value and emit parsed times.
+
+## Types
+
+```ts
+export type ChangePayload = { value: Date | null; event: any };
+```
+
+## Reference Implementation
+
+See the project’s full reference usage in [src/components/custom-time-picker/CustomTimePicker.vue](../src/components/custom-time-picker/CustomTimePicker.vue), which includes time menu integration, focus-trap, external store sync, and accessibility tweaks.

package/docs/trap/usePopupTrap.md

@@ -0,0 +1,138 @@
+# usePopupTrap
+
+[← Back to Composables README](../../README.md)
+
+Composable for managing focus trapping and close behavior for popup UIs (e.g., Kendo `Popup`, `DatePicker`, `TimePicker` dropdowns). It provides focus trapping via `@vueuse/integrations/useFocusTrap`, Escape/OutsideClick to close, automatic popup element discovery, and optional return-to-trigger focus.
+
+## Prerequisites
+
+- Vue 3 Composition API
+- `@vueuse/integrations` (`useFocusTrap`)
+- `@vueuse/core` (`onClickOutside`)
+- Optional: Kendo Vue components (`Popup`, `DatePicker`, `TimePicker`) or any popup-like UI
+
+## Quick Start
+
+```ts
+<script setup lang="ts">
+import { ref, shallowRef } from "vue";
+import { DatePicker } from "@progress/kendo-vue-dateinputs";
+import { usePopupTrap } from "@featherk/composables/trap";
+
+const open = ref(false);
+const datePickerRef = shallowRef<HTMLElement | null>(null);
+
+usePopupTrap({
+  isOpen: open,
+  onRequestClose: () => (open.value = false),
+  triggerEl: datePickerRef,
+  // 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>
+```
+
+### TimePicker example (custom selectors)
+
+```ts
+<script setup lang="ts">
+import { ref, useTemplateRef } from "vue";
+import { TimePicker } from "@progress/kendo-vue-dateinputs";
+import { usePopupTrap } from "@featherk/composables/trap";
+
+const showPicker = ref(false);
+const timePickerRef = useTemplateRef("timePickerRef");
+
+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
+
+### `usePopupTrap(options)`
+
+Sets up focus trap and close behaviors for a discovered popup element.
+
+#### Options
+
+- `isOpen: Ref<boolean>`: Reactive flag indicating whether the popup is open.
+- `onRequestClose?: (reason: CloseReason, ev?: Event) => void`: Callback to request closing the popup. Reasons: `'escape' | 'outside'`.
+- `popupSelector?: string | string[]`: CSS selector(s) used to locate the popup element. Defaults target common Kendo popup containers.
+- `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`.
+- `focusTrapOptions?: Parameters<typeof useFocusTrap>[1]`: Options forwarded to `useFocusTrap`.
+- `returnFocusToTrigger?: boolean`: When closing, return focus to `triggerEl`. Defaults to `true`.
+
+#### Returns
+
+- `popupRef: Ref<HTMLElement | null>`: The active 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.
+
+#### Types
+
+```ts
+export type CloseReason = "escape" | "outside";
+export type InitialFocus = string | ((root: HTMLElement) => HTMLElement | null | undefined);
+```
+
+## Behavior Details
+
+- **Discovery**: Attempts to find the popup near `triggerEl` within its closest `.k-animation-container` or `document.body`. Default selectors:
+  - `.k-animation-container .k-popup`
+  - `.k-popup`
+  - `.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.
+- **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`.
+
+## 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.
+  - 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).
+
+## Accessibility Notes
+
+- Trap focus while the popup is open and ensure Escape closes it.
+- Return focus to the trigger after closing (or handle focus yourself by setting `returnFocusToTrigger: false`).
+- Provide an accessible label for the trigger and ensure tab order is logical.
+
+## Limitations & Assumptions
+
+- Discovery relies on stable CSS selectors; customize `popupSelector` or use `resolvePopupEl` if your UI differs.
+- Focus guard behavior is tuned for Kendo popups; other libraries may require selector adjustments.
+
+## Tips
+
+- Keep `onRequestClose` idempotent; it can be called by Escape and outside click.
+- When combining with masked inputs, consider focusing the custom input after closing (disable `returnFocusToTrigger` and handle focus yourself).
+- If multiple popups can be open, ensure selectors narrow to the correct one or provide `resolvePopupEl`.
+
+## Reference Implementations
+
+- Date example: [src/components/custom-date-picker/CustomDatePicker.vue](../src/components/custom-date-picker/CustomDatePicker.vue)
+- Time example: [src/components/custom-time-picker/CustomTimePicker.vue](../src/components/custom-time-picker/CustomTimePicker.vue)

package/package.json

@@ -1,11 +1,44 @@
 {
   "name": "@featherk/composables",
-  "version": "0.4.12",
+  "version": "0.5.0",
   "main": "dist/featherk-composables.umd.js",
   "module": "dist/featherk-composables.es.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/featherk-composables.es.js",
+      "require": "./dist/featherk-composables.umd.js"
+    },
+    "./grid": {
+      "types": "./dist/grid/index.d.ts",
+      "import": "./dist/featherk-composables.es.js",
+      "require": "./dist/featherk-composables.umd.js"
+    },
+    "./date": {
+      "types": "./dist/date/index.d.ts",
+      "import": "./dist/featherk-composables.es.js",
+      "require": "./dist/featherk-composables.umd.js"
+    },
+    "./range": {
+      "types": "./dist/range/index.d.ts",
+      "import": "./dist/featherk-composables.es.js",
+      "require": "./dist/featherk-composables.umd.js"
+    },
+    "./time": {
+      "types": "./dist/time/index.d.ts",
+      "import": "./dist/featherk-composables.es.js",
+      "require": "./dist/featherk-composables.umd.js"
+    },
+    "./trap": {
+      "types": "./dist/trap/index.d.ts",
+      "import": "./dist/featherk-composables.es.js",
+      "require": "./dist/featherk-composables.umd.js"
+    }
+  },
   "files": [
-    "dist"
+    "dist",
+    "docs"
   ],
   "scripts": {
     "build": "vite build && npm run build:types",
@@ -15,11 +48,28 @@
     "prepublishOnly": "npm run build"
   },
   "peerDependencies": {
-    "vue": ">=3.0.0"
+    "vue": ">=3.0.0",
+    "@vueuse/core": ">=10.0.0",
+    "@vueuse/integrations": ">=10.0.0",
+    "focus-trap": ">=7.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@vueuse/core": {
+      "optional": true
+    },
+    "@vueuse/integrations": {
+      "optional": true
+    },
+    "focus-trap": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@types/node": "^24.5.2",
     "@vitejs/plugin-vue": "^6.0.1",
+    "@vueuse/core": "^13.5.0",
+    "@vueuse/integrations": "^13.5.0",
+    "focus-trap": "^7.6.0",
     "typescript": "~5.8.3",
     "vite": "^7.1.7",
     "vitest": "^3.2.4",

package/dist/useGridComposableEx.d.ts

@@ -1,11 +0,0 @@
-interface GridAccessibilityOptions {
-    activeByDefault?: boolean;
-    autoActivateDelay?: number;
-}
-export declare function useGridComposableEx(options?: GridAccessibilityOptions): {
-    isGridActive: import("vue").Ref<boolean, boolean>;
-    activateGrid: () => void;
-    deactivateGrid: () => void;
-    toggleGrid: () => void;
-};
-export {};