@featherk/composables 0.13.4 → 0.13.5

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/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/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.4",
+  "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",