@featherk/composables 0.13.3 → 0.13.5

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/index.d.ts

@@ -6,6 +6,7 @@ export * from "./id";
 export * from "./menu";
 export * from "./observer";
 export * from "./registry";
+export * from "./window";
 export { useMaskedDateInput } from "./date";
 export type { ChangePayload as DateChangePayload } from "./date";
 export { useMaskedDateRangeInput } from "./range";

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/dist/window/index.d.ts

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

package/dist/window/useWindow.d.ts

@@ -0,0 +1,100 @@
+import { type ComponentPublicInstance, type ComputedRef, type Ref } from "vue";
+/** Kendo Window's stage values. Distinct from browser fullscreen APIs. */
+export type WindowStage = "DEFAULT" | "MINIMIZED" | "FULLSCREEN";
+export interface WindowMoveEventPayload {
+    drag: boolean;
+    end: boolean;
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+export type WindowResizeEventPayload = WindowMoveEventPayload;
+export interface WindowSettings {
+    title: string;
+    draggable: boolean;
+    resizable: boolean;
+    /** Hidden via `windowClass`, not a real Kendo prop - see docs "Inert Props". */
+    closable: boolean;
+    fixed: boolean;
+    /** Hidden via `windowClass`, not a real Kendo prop - see docs "Inert Props". */
+    minimizeButton: boolean;
+    /** Hidden via `windowClass`, not a real Kendo prop - see docs "Inert Props". */
+    maximizeButton: boolean;
+    initialWidth: number;
+    initialHeight: number;
+    width?: number;
+    height?: number;
+    left?: number;
+    top?: number;
+}
+export declare const WINDOW_SETTINGS_DEFAULTS: WindowSettings;
+export interface UseWindowOptions {
+    /**
+     * Overrides for one or more settings; any field you omit falls back to
+     * `WINDOW_SETTINGS_DEFAULTS`, merged internally - you never need to spread
+     * the defaults yourself. Pass a `Ref` (e.g. one already wired to your own
+     * persistence layer) to have `useWindow` read and mutate it directly
+     * instead of creating its own internal ref; missing fields on that ref are
+     * filled in from the defaults once, in place, at setup time.
+     */
+    settings?: Partial<WindowSettings> | Ref<Partial<WindowSettings>>;
+    initialStage?: WindowStage;
+    onMove?: (payload: WindowMoveEventPayload) => void;
+    onResize?: (payload: WindowResizeEventPayload) => void;
+    onStageChange?: (stage: WindowStage) => void;
+    onOpen?: () => void;
+    onClose?: () => void;
+}
+/** The subset of Kendo `Window` props useWindow keeps functional - see docs "Inert Props". */
+export interface WindowBindableProps {
+    title: string;
+    draggable: boolean;
+    resizable: boolean;
+    left?: number;
+    top?: number;
+    initialLeft: number;
+    initialTop: number;
+    initialWidth: number;
+    initialHeight: number;
+    width?: number;
+    height?: number;
+    stage: WindowStage;
+    windowClass: string;
+}
+export interface WindowEvents {
+    move: (...args: unknown[]) => void;
+    resize: (...args: unknown[]) => void;
+    stagechange: (...args: unknown[]) => void;
+    close: (...args: unknown[]) => void;
+}
+export interface UseWindowOpenOptions {
+    /**
+     * Discards any existing left/top/width/height (including one restored from
+     * an externally-persisted `settings` ref) and recomputes the initial inset
+     * position and `initialWidth`/`initialHeight` size. Defaults to `false`, so
+     * a previously dragged/resized/persisted position survives close + reopen.
+     */
+    resetPosition?: boolean;
+}
+export interface UseWindowReturn {
+    windowRef: Ref<ComponentPublicInstance | null>;
+    settings: Ref<WindowSettings>;
+    visible: Ref<boolean>;
+    stage: Ref<WindowStage>;
+    isDragging: Ref<boolean>;
+    isResizing: Ref<boolean>;
+    /** Spread via `v-bind` onto `<Window>`. */
+    props: ComputedRef<WindowBindableProps>;
+    /** Spread via `v-on` onto `<Window>`. */
+    events: WindowEvents;
+    open: (openOptions?: UseWindowOpenOptions) => Promise<void>;
+    close: () => void;
+}
+/**
+ * Wraps Kendo UI for Vue's `Window` component (not the browser `window`
+ * object) with zero-config defaults, viewport-clamped dragging, and the
+ * pointerdown-capture resize/text-selection workaround from
+ * docs/design/composable-native-event-listener-tactic.md.
+ */
+export declare function useWindow(options?: UseWindowOptions): UseWindowReturn;

package/dist/window/useWindow.test.d.ts

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

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/docs/window/useWindow.md

@@ -0,0 +1,107 @@
+# useWindow
+
+[Back to Composables README](https://github.com/NantHealth/featherk/blob/integration/packages/composables/README.md)
+
+> Wraps Kendo UI for Vue's `Window` component - not the browser `window` object. If you were expecting something like VueUse's `useWindowSize`/`useWindowScroll`, this is unrelated to those.
+
+Composable for a zero/low-config Kendo `Window`: viewport-clamped dragging, resize tracking, stage transitions, and the pointerdown-capture resize/text-selection workaround are all handled internally. Every setting has a sensible default, so `useWindow()` with no arguments is a complete, working Window.
+
+## Quick Start
+
+1. Import `useWindow` and Kendo's `Window` component.
+2. Call `useWindow()` - accept every default setting.
+3. Wire a trigger (e.g. a Button) to `open()`.
+4. Bind `<Window>` via `v-if`, `ref`, `v-bind`, and `v-on` - never wire individual Window props by hand.
+
+```vue
+<template>
+  <!-- Step 3: trigger opens the Window using its defaults -->
+  <Button @click="open">Open Window</Button>
+
+  <!-- Step 4: v-if/ref/v-bind/v-on is the entire binding surface -->
+  <Window v-if="visible" ref="windowRef" v-bind="props" v-on="events">
+    <p>This is the content of the window.</p>
+  </Window>
+</template>
+
+<script setup lang="ts">
+// Step 1: import the composable and the Kendo component it augments
+import { useWindow } from "@featherk/composables/window";
+import { Window } from "@progress/kendo-vue-dialogs";
+import { Button } from "@progress/kendo-vue-buttons";
+
+// Step 2: no options - every setting uses useWindow's built-in defaults
+const { windowRef, visible, props, events, open } = useWindow();
+</script>
+```
+
+## Overriding Defaults
+
+Pass `settings` with only the fields you want to change; `useWindow` merges it over `WINDOW_SETTINGS_DEFAULTS` internally, so you never spread the defaults yourself.
+
+```ts
+const { windowRef, visible, props, events, open } = useWindow({
+  settings: {
+    title: "Preferences",
+    initialWidth: 600,
+    initialHeight: 400,
+    resizable: false,
+  },
+});
+```
+
+## Persisting Settings Externally
+
+Pass an existing `Ref` (for example, one already wired to your own persistence layer) as `settings` instead of a plain object. `useWindow` fills in any missing fields from `WINDOW_SETTINGS_DEFAULTS` once, in place, then reads and mutates that same ref directly (position/size updates from dragging and resizing land on it) - persistence stays entirely your concern, `useWindow` has no knowledge of how or whether you persist it.
+
+```ts
+const persistedSettings = ref<Partial<WindowSettings>>({ ...myLoadedSettings });
+const win = useWindow({ settings: persistedSettings });
+```
+
+A partially-populated ref is fine - any field `myLoadedSettings` doesn't have falls back to the built-in default, exactly like the plain-object form above.
+
+`open()` respects this: by default it reopens at whatever `left`/`top`/`width`/`height` are already on `settings` (a prior drag/resize, or a value you restored from persistence), rather than recomputing the initial inset position. Pass `open({ resetPosition: true })` to force the Window back to its computed initial position/size instead - see `UseWindowReturn.open` in the API table below.
+
+## API
+
+### `UseWindowOptions`
+
+| Option          | Type                                                      | Description                                                                                                        |
+| --------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `settings`      | `Partial<WindowSettings> \| Ref<Partial<WindowSettings>>` | Overrides merged over `WINDOW_SETTINGS_DEFAULTS` internally. Pass a `Ref` for externally-owned/persisted settings. |
+| `initialStage`  | `WindowStage`                                             | Initial `stage` value. Defaults to `"DEFAULT"`.                                                                    |
+| `onMove`        | `(payload) => void`                                       | Called after internal move handling.                                                                               |
+| `onResize`      | `(payload) => void`                                       | Called after internal resize handling.                                                                             |
+| `onStageChange` | `(stage) => void`                                         | Called after a valid stage transition.                                                                             |
+| `onOpen`        | `() => void`                                              | Called after `open()` finishes sizing the Window.                                                                  |
+| `onClose`       | `() => void`                                              | Called after `close()` hides the Window.                                                                           |
+
+### `UseWindowReturn`
+
+| Member                      | Type                                                           | Description                                                                                                                                                         |
+| --------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `windowRef`                 | `Ref<ComponentPublicInstance \| null>`                         | Bind via `ref="windowRef"`.                                                                                                                                         |
+| `settings`                  | `Ref<WindowSettings>`                                          | Reactive settings - bind checkboxes/inputs directly for a settings panel.                                                                                           |
+| `visible`                   | `Ref<boolean>`                                                 | Bind via `v-if="visible"`.                                                                                                                                          |
+| `stage`                     | `Ref<WindowStage>`                                             | Current `"DEFAULT" \| "MINIMIZED" \| "FULLSCREEN"` stage.                                                                                                           |
+| `isDragging` / `isResizing` | `Ref<boolean>`                                                 | Live drag/resize state, already folded into `windowClass`.                                                                                                          |
+| `props`                     | `ComputedRef<WindowBindableProps>`                             | Spread via `v-bind="props"` onto `<Window>`.                                                                                                                        |
+| `events`                    | `WindowEvents`                                                 | Spread via `v-on="events"` onto `<Window>`.                                                                                                                         |
+| `open`                      | `(openOptions?: { resetPosition?: boolean }) => Promise<void>` | Shows the Window. By default, reopens at the current `settings` position/size; pass `{ resetPosition: true }` to recompute the initial inset position/size instead. |
+| `close`                     | `() => void`                                                   | Resets `stage` to `"DEFAULT"` and hides the Window.                                                                                                                 |
+
+## Inert Props
+
+`props` only contains Kendo `Window` props that actually work: `title`, `draggable`, `resizable`, `left`, `top`, `initialLeft`, `initialTop`, `initialWidth`, `initialHeight`, `width`, `height`, `stage`, and `windowClass`. `settings.closable`, `settings.minimizeButton`, and `settings.maximizeButton` are deliberately **not** included in `props`.
+
+If you hand-wire raw Kendo props like `closeButton`/`minimizeButton`/`maximizeButton` directly on `<Window>` alongside `v-bind="props"`, they are **inert** - they will not hide the corresponding titlebar button. `useWindow` only ever suppresses those buttons via CSS (`fk-window-hide-minimize`/`fk-window-hide-maximize`/`fk-window-hide-close` classes folded into `windowClass`), never through Kendo's own button props. Toggle `settings.minimizeButton`/`settings.maximizeButton`/`settings.closable` instead.
+
+## Kendo Defects Worked Around
+
+- **Titlebar button props are non-functional.** Kendo's `Window` types `minimizeButton`/`maximizeButton`/`closeButton`/`restoreButton` as `[String, Function]`, but the child `WindowTitlebar` that actually renders them types the same props `[String, Function, Object, Boolean]` and renders each button unconditionally regardless of value. There is no supported way to hide these buttons through Kendo's own props - see "Inert Props" above for the CSS-class workaround `useWindow` uses instead.
+- **Resize-handle drag vs. text-selection race.** Kendo Window's resize handles use Kendo's own draggable implementation, which does not prevent the native browser default until after pointer movement begins. If text inside the Window is already selected, native selection-dragging can compete with a resize started from an inward-overlapping handle. `useWindow` prevents this internally with a capture-phase `pointerdown` listener scoped to `.k-resize-handle` elements - see [docs/design/composable-native-event-listener-tactic.md](https://github.com/NantHealth/featherk/blob/integration/docs/design/composable-native-event-listener-tactic.md) for the general pattern. This is fully internal; no `@pointerdown.capture` binding is needed (or exposed) in consumer templates.
+
+## Styling
+
+All `windowClass` output (`fk-window`, `fk-window-can-drag`, `fk-window-is-dragging`, `fk-window-is-resizing`, `fk-window-fixed`, `fk-window-hide-minimize`, `fk-window-hide-maximize`, `fk-window-hide-close`) is styled in `@featherk/styles` - consumers do not need to write any Window CSS themselves. The titlebar button-hiding workaround, the Kendo defect fixes, and drag/resize motion are all shipped as part of the external stylesheet; header background, text color, icon color, and padding are configured through ThemeBuilder's Window component panel. Just make sure the app includes `@featherk/styles`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@featherk/composables",
-  "version": "0.13.3",
+  "version": "0.13.5",
   "main": "dist/featherk-composables.umd.js",
   "module": "dist/featherk-composables.es.js",
   "types": "dist/index.d.ts",
@@ -70,6 +70,11 @@
       "import": "./dist/featherk-composables.es.js",
       "require": "./dist/featherk-composables.umd.js"
     },
+    "./window": {
+      "types": "./dist/window/index.d.ts",
+      "import": "./dist/featherk-composables.es.js",
+      "require": "./dist/featherk-composables.umd.js"
+    },
     "./docs-manifest": {
       "types": "./dist/docs-manifest.d.ts",
       "import": "./dist/docs-manifest.js",