@featherk/composables 0.13.8 → 0.14.0

package/dist/window/useWindow.d.ts

@@ -29,6 +29,10 @@ export interface WindowSettings {
     height?: number;
     left?: number;
     top?: number;
+    /** Minimum resize width in px. Unset/`null` falls back to Kendo's default (120). */
+    minWidth?: number | null;
+    /** Minimum resize height in px. Unset/`null` falls back to Kendo's default (100). */
+    minHeight?: number | null;
 }
 export declare const WINDOW_SETTINGS_DEFAULTS: WindowSettings;
 export interface UseWindowOptions {
@@ -63,6 +67,8 @@ export interface WindowBindableProps {
     initialHeight: number;
     width?: number;
     height?: number;
+    minWidth: number;
+    minHeight: number;
     stage: WindowStage;
     windowClass: string;
 }

package/docs/window/useWindow.md

@@ -4,7 +4,7 @@
 
 > 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.
+Composable for a zero/low-config Kendo `Window`: viewport-clamped dragging and resizing, 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
 
@@ -67,6 +67,23 @@ A partially-populated ref is fine - any field `myLoadedSettings` doesn't have fa
 
 Set `settings.initialLeft` and/or `settings.initialTop` to override the default 16px right/top inset on the first open and whenever `resetPosition` is true. Each coordinate can be overridden independently; an omitted coordinate keeps its computed inset default.
 
+## Resizing Bounds
+
+Resizing is clamped to the viewport (the scrolled document viewport when `settings.fixed` is `false`):
+
+- The dragged edge stops at the viewport edge; the opposite edge stays anchored, so dragging the top or left edge past the viewport never grows the Window down or right.
+- An edge that is already outside the viewport (for example, a bottom edge dragged below the fold) is never snapped back - it just cannot be pushed further out.
+- The Window cannot shrink below `settings.minWidth`/`settings.minHeight`. Both are optional; unset or `null` falls back to Kendo's defaults (120px/100px).
+- Keyboard resizing (Ctrl+Arrow) follows the same viewport and minimum-size limits.
+
+`settings.left`/`top`/`width`/`height` and the `onResize` payload always hold these clamped values, not Kendo's raw resize geometry.
+
+```ts
+const win = useWindow({
+  settings: { minWidth: 320, minHeight: 200 },
+});
+```
+
 ## Extending Window Behavior
 
 Use the `UseWindowOptions` callbacks when application code needs to react to Window behavior. These callbacks are extension hooks: they run after `useWindow` completes its internal handling, and they do not replace Kendo's event handlers.
@@ -74,7 +91,7 @@ Use the `UseWindowOptions` callbacks when application code needs to react to Win
 This applies to every callback option:
 
 - `onMove` runs after viewport clamping and position updates.
-- `onResize` runs after size/position updates and resize-state tracking.
+- `onResize` runs after viewport clamping, size/position updates, and resize-state tracking.
 - `onStageChange` runs after a valid controlled stage transition.
 - `onOpen` runs after `open()` has shown and sized the Window.
 - `onClose` runs after `close()` has reset the stage and hidden the Window.
@@ -99,7 +116,7 @@ the titlebar toggles between `DEFAULT` and `FULLSCREEN`. Set `titlebarDoubleClic
 disable both transitions. This option is independent of `settings.maximizeButton`; disabling the
 maximize button does not automatically disable titlebar double-click behavior.
 
-Keep binding `v-on="events"` on `<Window>` so viewport clamping, resize tracking, stage handling, and Kendo workarounds remain active:
+Keep binding `v-on="events"` on `<Window>` so viewport clamping (drag and resize), stage handling, and Kendo workarounds remain active:
 
 ```vue
 <Window
@@ -122,7 +139,7 @@ Do not replace entries on `events` unless you intentionally opt out of the corre
 | `initialStage`  | `WindowStage`                                             | Initial `stage` value. Defaults to `"DEFAULT"`.                                                                    |
 | `titlebarDoubleClick` | `MaybeRefOrGetter<boolean>`                         | Enables titlebar double-click stage changes. Defaults to `true`; pass `false` or a reactive ref/getter returning `false` to disable both maximize and restore transitions. |
 | `onMove`        | `(payload) => void`                                       | Called after internal move handling.                                                                               |
-| `onResize`      | `(payload) => void`                                       | Called after internal resize handling.                                                                             |
+| `onResize`      | `(payload) => void`                                       | Called after internal resize handling, with the viewport-clamped `left`/`top`/`width`/`height`.                     |
 | `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.                                                                           |
@@ -143,7 +160,7 @@ Do not replace entries on `events` unless you intentionally opt out of the corre
 
 ## 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`.
+`props` only contains Kendo `Window` props that actually work: `title`, `draggable`, `resizable`, `left`, `top`, `initialLeft`, `initialTop`, `initialWidth`, `initialHeight`, `width`, `height`, `minWidth`, `minHeight`, `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.
 
@@ -151,6 +168,36 @@ If you hand-wire raw Kendo props like `closeButton`/`minimizeButton`/`maximizeBu
 
 - **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.
+- **Resize geometry is unbounded and self-compounding.** See "Kendo Window Resize Math Defect" below.
+
+### Kendo Window Resize Math Defect
+
+Observed in `@progress/kendo-vue-dialogs` 6.4.1 (`Window.mjs`, `handleResize`). Because of this, `useWindow` computes resize geometry itself rather than trusting the values Kendo emits on `resize`.
+
+**Symptoms (without the workaround)**
+
+- Dragging the right or bottom edge past the browser window keeps growing the Window indefinitely.
+- After that, the left edge can be dragged offscreen too, leaving the whole Window offscreen and unrecoverable.
+- Dragging the top edge up past the viewport makes the Window grow **down**; dragging the left edge past the viewport makes it grow **right**. Corner handles show both behaviors.
+
+**Root cause**
+
+- Kendo sets the dragged edge to the pointer's absolute `pageX`/`pageY` with no viewport bounds. Pointer capture keeps reporting coordinates beyond the browser window, so right/bottom edges follow indefinitely.
+- For `n`/`w` handles Kendo sets `top = pageY` (negative past the viewport) and adds `computedTop - pageY` to the height. `computedTop` is `Math.max(top, 0)`, so the Window renders at `0` while the height grows again on every pointer move - growth leaks out the opposite edge. Same for `left`/width.
+- The emitted `left`/`top`/`width`/`height` come from Kendo's internal state, not the controlled props: values for the axis not being resized can be stale (including unclamped values from a prior drag).
+- Kendo mixes coordinate spaces: `pageX`/`pageY` are document coordinates, while a `position: fixed` Window's `top`/`left` are viewport coordinates, so resizing is off by the scroll offset on a scrolled page.
+- Kendo reads `props.top || currentTop`, so a controlled `top`/`left` of `0` is treated as unset and falls back to internal state.
+
+**Workaround in `useWindow`**
+
+- The existing capture-phase `pointerdown` listener on `.k-resize-handle` also records the handle direction (from its `k-resize-<dir>` class), the starting rect, and the starting pointer position, then tracks the pointer with a capture-phase `window` `pointermove` listener.
+- On each Kendo `resize` event, geometry is computed from the pointer delta and clamped per edge (viewport bounds, anchored opposite edge, `minWidth`/`minHeight`); Kendo's emitted geometry is ignored. Kendo's event still drives timing (`drag`/`end`).
+- Keyboard resizing (Ctrl+Arrow) has no pointer, so it applies the change in Kendo's emitted size as a delta to the clamped size.
+- See "Resizing Bounds" above for the resulting behavior.
+
+**Removal criteria**
+
+Revisit when upgrading `@progress/kendo-vue-dialogs`. The workaround can be dropped once Kendo's `handleResize` bounds edges to the viewport, anchors the opposite edge at the viewport, and emits geometry consistent with the controlled props. The `useWindow` resize tests (`useWindow.test.ts`) describe the expected behavior and can be used to verify.
 
 ## Styling
 

package/package.json

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