@surdeddd/wmkit 0.4.0 → 0.4.2

package/README.md

@@ -2,7 +2,7 @@
 
 **Headless window manager for the web.** Draggable, resizable, snappable windows with a taskbar model, keyboard accessibility and state persistence — for vanilla JS and every major framework.
 
-[Русская версия](./README.ru.md) · [Live demo](https://wmkit.vercel.app) · [Mirror (Pages)](https://surdeddd.github.io/wmkit/) · [GitHub](https://github.com/Surdeddd/wmkit)
+[Русская версия](./README.ru.md) · [Live demo](https://wmkit.vercel.app) · [Mirror (Pages)](https://surdeddd.github.io/wmkit/) · [Docs](./docs/README.md) · [GitHub](https://github.com/Surdeddd/wmkit)
 
 [![CI](https://github.com/Surdeddd/wmkit/actions/workflows/ci.yml/badge.svg)](https://github.com/Surdeddd/wmkit/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/@surdeddd/wmkit)](https://www.npmjs.com/package/@surdeddd/wmkit)
@@ -346,6 +346,18 @@ Skip the import entirely and the library stays headless: state attributes (`data
 
 The core never touches `window`/`document` — create managers and even `hydrate()` state on the server, then call `attachDesktop` after mount. `persist` no-ops without usable storage.
 
+## Documentation
+
+This README is the tour. The reference lives in [`docs/`](./docs/README.md):
+
+| Page | What is in it |
+| --- | --- |
+| [API reference](./docs/api.md) | every export, option, method, event and type |
+| [Adapters](./docs/adapters.md) | complete React, Vue, Svelte, Solid and Angular integrations |
+| [Theming](./docs/theming.md) | `data-wm-*` contract, CSS variables, writing a theme from scratch |
+| [Recipes](./docs/recipes.md) | taskbar, modals, persistence, workspaces, SSR, testing, performance |
+| [Browser support](./docs/browser-support.md) | baselines per entry point and what degrades where |
+
 ## Comparison
 
 | | wmkit | WinBox | jsPanel4 | Dockview | Zag floating-panel |
@@ -364,7 +376,7 @@ The core never touches `window`/`document` — create managers and even `hydrate
 
 ## Quality
 
-- 216 unit tests, **100%** line/branch/function/statement coverage on the core state machine and persistence
+- 250 unit tests: **100%** line/branch/function/statement coverage on the core state machine and persistence, with enforced floors on the DOM layer and the adapters
 - 190+ Playwright scenarios on Chromium, WebKit and mobile emulation: drag, 8-way resize, snap, magnetism, workspaces, undo after drag, keyboard, touch, persistence across reloads, 50-window stress, modal traps, axe accessibility scans, visual regression screenshots
 - performance benchmarks run in CI on every push (`vitest bench`): 1 000 windows open in ~150 ms, a move among 50 windows costs ~1.2 µs, a full 100-step undo/redo sweep ~52 µs
 - `publint` + `@arethetypeswrong/cli` validate the published package, `size-limit` guards bundle budgets

package/README.ru.md

@@ -2,7 +2,7 @@
 
 **Headless оконный менеджер для веба.** Перетаскиваемые окна с ресайзом, снэпом, таскбаром, клавиатурной доступностью и персистом состояния — для vanilla JS и всех основных фреймворков.
 
-[English version](./README.md) · [Живое демо](https://wmkit.vercel.app) · [Зеркало (Pages)](https://surdeddd.github.io/wmkit/) · [GitHub](https://github.com/Surdeddd/wmkit)
+[English version](./README.md) · [Живое демо](https://wmkit.vercel.app) · [Зеркало (Pages)](https://surdeddd.github.io/wmkit/) · [Документация](./docs/README.md) · [GitHub](https://github.com/Surdeddd/wmkit)
 
 [![wmkit — живой демо-десктоп](https://raw.githubusercontent.com/Surdeddd/wmkit/main/.github/assets/hero.png)](https://surdeddd.github.io/wmkit/)
 
@@ -73,7 +73,140 @@ desktop.attachWindow(win.id, el, { removeOnClose: true })
 
 ## Адаптеры
 
-Примеры для React, Vue, Svelte, Solid и Angular — в [английском README](./README.md#react) и на [лендинге](https://surdeddd.github.io/wmkit/) (табы «Фреймворки»). Принцип один: контент окна живёт в дереве вашего фреймворка, никакого innerHTML.
+Каждый адаптер — тонкая обёртка над тем же ядром и тем же DOM-контроллером, около 60 строк. Они нужны только чтобы привязаться и отвязаться в нужный момент жизненного цикла компонента. Контент окна всегда живёт в дереве вашего фреймворка: никакого innerHTML, порталов и переноса узлов.
+
+### React
+
+```tsx
+import { useWindowManager, useDesktop, useWmState, useWmWindowRef } from '@surdeddd/wmkit/react'
+
+function Desktop() {
+  const wm = useWindowManager()
+  const { ref, binder } = useDesktop(wm)
+  const state = useWmState(wm)
+
+  return (
+    <div ref={ref} style={{ position: 'relative', height: '100vh' }}>
+      <button type="button" onClick={() => wm.open({ title: 'Окно' })}>открыть</button>
+      {state.order.map((id) => (
+        <Win key={id} binder={binder} win={state.windows[id]} />
+      ))}
+    </div>
+  )
+}
+
+function Win({ binder, win }) {
+  const ref = useWmWindowRef(binder, win.id, { removeOnClose: true })
+  return (
+    <section ref={ref}>
+      <header data-wm-drag><span data-wm-title>{win.title}</span></header>
+      <div data-wm-content>ваше дерево компонентов</div>
+    </section>
+  )
+}
+```
+
+### Vue
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { useWindowManager, useDesktop, useWmWindowEl } from '@surdeddd/wmkit/vue'
+
+const host = ref<HTMLElement>()
+const panel = ref<HTMLElement>()
+const wm = useWindowManager()
+const binder = useDesktop(wm, host)
+useWmWindowEl(binder, 'notes', panel)
+wm.open({ id: 'notes', title: 'Заметки' })
+</script>
+
+<template>
+  <div ref="host" style="position: relative; height: 100vh">
+    <section ref="panel">
+      <header data-wm-drag><span data-wm-title>Заметки</span></header>
+      <div data-wm-content>композаблы</div>
+    </section>
+  </div>
+</template>
+```
+
+### Svelte
+
+```svelte
+<script lang="ts">
+  import { createManager, createDesktop, wmWindowStore } from '@surdeddd/wmkit/svelte'
+
+  const wm = createManager()
+  const dk = createDesktop(wm)
+  wm.open({ id: 'notes', title: 'Заметки' })
+  const notes = wmWindowStore(wm, 'notes')
+</script>
+
+<div use:dk.desktop style="position: relative; height: 100vh">
+  <section use:dk.window={{ id: 'notes' }}>
+    <header data-wm-drag><span data-wm-title>{$notes?.title}</span></header>
+    <div data-wm-content>сторы и экшены</div>
+  </section>
+</div>
+```
+
+### Solid
+
+```tsx
+import { useWindowManager, createDesktop, useWmState } from '@surdeddd/wmkit/solid'
+
+function Desktop() {
+  const wm = useWindowManager()
+  const dk = createDesktop(wm)
+  const state = useWmState(wm)
+  wm.open({ id: 'notes', title: 'Заметки' })
+
+  return (
+    <div ref={dk.desktop} style={{ position: 'relative', height: '100vh' }}>
+      <section ref={dk.window('notes')}>
+        <header data-wm-drag><span data-wm-title>Заметки</span></header>
+        <div data-wm-content>{state().order.length} окон</div>
+      </section>
+    </div>
+  )
+}
+```
+
+### Angular
+
+```ts
+import { Component, ElementRef, afterNextRender, viewChild } from '@angular/core'
+import { useWindowManager, createDesktop, useWmState } from '@surdeddd/wmkit/angular'
+
+@Component({
+  selector: 'app-desktop',
+  template: `
+    <div #host style="position: relative; height: 100vh">
+      <section #panel>
+        <header data-wm-drag><span data-wm-title>Заметки</span></header>
+        <div data-wm-content>{{ state().order.length }} окон</div>
+      </section>
+    </div>`,
+})
+export class DesktopComponent {
+  private host = viewChild.required<ElementRef>('host')
+  private panel = viewChild.required<ElementRef>('panel')
+  wm = useWindowManager()
+  state = useWmState(this.wm)
+
+  constructor() {
+    const dk = createDesktop(this.wm)
+    afterNextRender(() => {
+      dk.desktop(this.host().nativeElement)
+      this.wm.open({ id: 'notes', title: 'Заметки' })
+      dk.window('notes')(this.panel().nativeElement)
+    })
+  }
+}
+```
+
+Полные примеры с таскбаром, модалками и сигнатурами всех хуков — в [docs/adapters.md](./docs/adapters.md).
 
 ## API ядра — кратко
 
@@ -140,7 +273,7 @@ if (isPopoutSupported()) await popout(wm, 'docs', contentElement)
 
 ## Качество
 
-- 216 юнит-тестов, **100%** покрытие стейт-машины и persist по строкам/веткам/функциям
+- 250 юнит-тестов: **100%** покрытие стейт-машины и persist по строкам/веткам/функциям, плюс обязательные пороги на DOM-слой и адаптеры
 - 190+ Playwright-сценариев на Chromium, WebKit и мобильной эмуляции: drag, ресайз во все стороны, снэп, магнетизм, рабочие столы, undo после drag, клавиатура, touch, персист через перезагрузку, стресс на 50 окон, модальные ловушки, axe-аудиты доступности, визуальная регрессия по скриншотам
 - перф-бенчмарки в CI на каждый push (`vitest bench`): 1 000 окон открываются за ~150 мс, move среди 50 окон ~1.2 мкс, полный undo/redo-проход на 100 шагов ~52 мкс
 - `publint` + `@arethetypeswrong/cli` проверяют валидность пакета, `size-limit` следит за бюджетами

package/dist/angular.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-var chunk3KZZOLHW_cjs = require('./chunk-3KZZOLHW.cjs');
+var chunkGLBVT4AQ_cjs = require('./chunk-GLBVT4AQ.cjs');
 var core = require('@angular/core');
 
 function onDestroy(dispose) {
@@ -13,7 +13,7 @@ function onDestroy(dispose) {
   destroyRef?.onDestroy(dispose);
 }
 function useWindowManager(options) {
-  const wm = chunk3KZZOLHW_cjs.createWindowManager(options);
+  const wm = chunkGLBVT4AQ_cjs.createWindowManager(options);
   onDestroy(() => wm.destroy());
   return wm;
 }
@@ -28,7 +28,7 @@ function useWmWindow(wm, id) {
   return core.computed(() => state().windows[id]);
 }
 function createDesktop(wm, options) {
-  const binder = chunk3KZZOLHW_cjs.createDesktopBinder(wm, options);
+  const binder = chunkGLBVT4AQ_cjs.createDesktopBinder(wm, options);
   onDestroy(() => binder.destroy());
   return {
     binder,

package/dist/angular.js

@@ -1,4 +1,4 @@
-import { createWindowManager, createDesktopBinder } from './chunk-FPZDAKNP.js';
+import { createWindowManager, createDesktopBinder } from './chunk-GGDF2EWV.js';
 import { signal, computed, inject, DestroyRef } from '@angular/core';
 
 function onDestroy(dispose) {

package/dist/{chunk-FPZDAKNP.js → chunk-GGDF2EWV.js}

@@ -209,6 +209,7 @@ function createWindowManager(options = {}) {
   let future = [];
   let interactionDepth = 0;
   let interactionRecorded = false;
+  let interactionMark = null;
   let skipNextHistory = false;
   let pendingHistory = null;
   const layouts = /* @__PURE__ */ new Map();
@@ -319,7 +320,13 @@ function createWindowManager(options = {}) {
       width: init.width ?? defaultSize.width,
       height: init.height ?? defaultSize.height
     };
-    const size = aspectRatio === null ? clampSize(requested, minSize, maxSize) : applyAspect(requested, aspectRatio, minSize, maxSize, "width");
+    const size = aspectRatio === null ? clampSize(requested, minSize, maxSize) : applyAspect(
+      requested,
+      aspectRatio,
+      minSize,
+      maxSize,
+      init.width === void 0 && init.height !== void 0 ? "height" : "width"
+    );
     const position = positionForOpen(init);
     let bounds = { ...position, ...size };
     if (keepInViewport) bounds = clampToViewport(bounds, viewport, minVisible);
@@ -435,7 +442,13 @@ function createWindowManager(options = {}) {
   }
   function snapBounds(win, zone) {
     const rect = zoneBounds(zone, viewport);
-    return { x: rect.x, y: rect.y, ...normalizeSize(rect, win) };
+    const byWidth = normalizeSize(rect, win);
+    const size = byWidth.height > rect.height ? normalizeSize(rect, win, "height") : byWidth;
+    return {
+      x: Math.max(0, Math.min(rect.x, viewport.width - size.width)),
+      y: Math.max(0, Math.min(rect.y, viewport.height - size.height)),
+      ...size
+    };
   }
   function focusUnlessBlocked(id) {
     const modal = topModalId();
@@ -600,7 +613,7 @@ function createWindowManager(options = {}) {
       snappable: patch.snappable ?? win.snappable,
       meta: patch.meta ? { ...win.meta, ...patch.meta } : win.meta
     };
-    const size = normalizeSize(next.bounds, next);
+    const size = next.stage === "maximized" ? next.bounds : normalizeSize(next.bounds, next);
     const resized = size.width !== next.bounds.width || size.height !== next.bounds.height;
     const finalWin = resized ? { ...next, bounds: { ...next.bounds, ...size } } : next;
     setWindow(finalWin);
@@ -648,6 +661,10 @@ function createWindowManager(options = {}) {
     if (!onActiveWorkspace(updated) && focusedId === id) {
       focusTop();
       if (focusedId) emitFocus(windows[focusedId], id);
+    } else if (onActiveWorkspace(updated) && topModalId() === id && focusedId !== id) {
+      const previous = focusedId;
+      focusedId = id;
+      emitFocus(updated, previous);
     }
     queueEvent(() => emitter.emit("update", { window: updated }));
     commit();
@@ -775,14 +792,20 @@ function createWindowManager(options = {}) {
   }
   function beginInteraction() {
     interactionDepth += 1;
-    if (interactionDepth === 1) interactionRecorded = false;
+    if (interactionDepth === 1) {
+      interactionRecorded = false;
+      interactionMark = { past: [...past], future };
+    }
   }
   function endInteraction() {
     if (interactionDepth > 0) interactionDepth -= 1;
+    if (interactionDepth === 0) interactionMark = null;
   }
   function abortInteraction() {
-    if (interactionDepth > 0 && interactionRecorded) {
-      past.pop();
+    if (interactionDepth > 0 && interactionMark) {
+      past.length = 0;
+      past.push(...interactionMark.past);
+      future = interactionMark.future;
       interactionRecorded = false;
     }
     endInteraction();
@@ -1130,10 +1153,8 @@ function createAnnouncer(wm, container, messages = {}) {
   element.style.cssText = "position:absolute;width:1px;height:1px;margin:-1px;padding:0;overflow:hidden;clip:rect(0 0 0 0);white-space:nowrap;border:0";
   container.append(element);
   let clearTimer;
-  let lastMessage = "";
   let detailed = false;
   function announce(message) {
-    lastMessage = message;
     element.textContent = message;
     if (clearTimer !== void 0) clearTimeout(clearTimer);
     clearTimer = setTimeout(() => {
@@ -1141,8 +1162,14 @@ function createAnnouncer(wm, container, messages = {}) {
     }, 2e3);
   }
   const unsubscribers = [
-    wm.on("open", ({ window: win }) => announce(dict.opened(win.title))),
-    wm.on("close", ({ window: win }) => announce(dict.closed(win.title))),
+    wm.on("open", ({ window: win }) => {
+      announce(dict.opened(win.title));
+      detailed = true;
+    }),
+    wm.on("close", ({ window: win }) => {
+      announce(dict.closed(win.title));
+      detailed = true;
+    }),
     wm.on("stage", ({ window: win, previous }) => {
       if (win.stage === "minimized") announce(dict.minimized(win.title));
       else if (win.stage === "maximized") announce(dict.maximized(win.title));
@@ -1153,7 +1180,7 @@ function createAnnouncer(wm, container, messages = {}) {
       detailed = true;
     }),
     wm.on("focus", ({ window: win, previous }) => {
-      if (detailed || previous === null || lastMessage === dict.opened(win.title)) return;
+      if (detailed || previous === null) return;
       announce(dict.focused(win.title));
     }),
     wm.on("workspace", ({ workspace }) => {
@@ -1400,6 +1427,7 @@ function createResizeStarter(ctx) {
     let pendingX = 0;
     let pendingY = 0;
     let hasPending = false;
+    let applied = false;
     const el = ctx.windowElement(id);
     if (el) el.dataset.wmResizing = direction;
     function flush() {
@@ -1408,18 +1436,24 @@ function createResizeStarter(ctx) {
       raf = 0;
       const dx = pendingX - startPoint.x;
       const dy = pendingY - startPoint.y;
-      const top = direction.includes("n") ? Math.max(0, start.y + dy) : start.y;
+      const floor = Math.min(0, start.y);
+      const top = direction.includes("n") ? Math.max(floor, start.y + dy) : start.y;
       const raw = {
         width: direction.includes("e") ? start.width + dx : direction.includes("w") ? start.width - dx : start.width,
         height: direction.includes("s") ? start.height + dy : direction.includes("n") ? start.y + start.height - top : start.height
       };
-      const size = aspect === null ? clampSize(raw, minSize, maxSize) : applyAspect(raw, aspect, minSize, maxSize, drive);
+      let size = aspect === null ? clampSize(raw, minSize, maxSize) : applyAspect(raw, aspect, minSize, maxSize, drive);
+      const available = start.y + start.height - floor;
+      if (direction.includes("n") && size.height > available) {
+        size = applyAspect({ ...size, height: available }, aspect ?? 0, minSize, maxSize, "height");
+      }
       const next = {
         x: direction.includes("w") ? start.x + start.width - size.width : start.x,
         y: direction.includes("n") ? start.y + start.height - size.height : start.y,
         ...size
       };
       wm.resize(id, next);
+      applied = true;
     }
     function onMove(moveEvent) {
       if (moveEvent.pointerId !== event.pointerId) return;
@@ -1434,7 +1468,7 @@ function createResizeStarter(ctx) {
       try {
         if (raf !== 0) view.cancelAnimationFrame(raf);
         if (hasPending && !cancelled) flush();
-        if (cancelled) {
+        if (cancelled && applied) {
           if (startStage === "snapped" && startZone) {
             wm.restoreTo(id, startRestore ?? start);
             wm.snap(id, startZone);
@@ -1504,6 +1538,7 @@ var SNAP_SHORTCUTS = {
   ArrowLeft: "left",
   ArrowRight: "right"
 };
+var LANDMARK_TAGS = /* @__PURE__ */ new Set(["header", "footer", "aside", "nav"]);
 var FOCUSABLE_SELECTOR = 'button:not([disabled]), [href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
 function attachDesktop(wm, element, options = {}) {
   const doc = element.ownerDocument;
@@ -1635,6 +1670,11 @@ function attachDesktop(wm, element, options = {}) {
       if (hide && !el.hidden && el.contains(doc.activeElement)) {
         element.focus({ preventScroll: true });
       }
+      if (!hide && el.hidden && wm.getState().focusedId === win.id) {
+        queueMicrotask(() => {
+          if (!el.hidden && !el.contains(doc.activeElement)) el.focus({ preventScroll: true });
+        });
+      }
       el.hidden = hide;
       el.setAttribute("aria-label", win.title);
       if (win.layer === "modal") el.setAttribute("aria-modal", "true");
@@ -1683,6 +1723,7 @@ function attachDesktop(wm, element, options = {}) {
     wm.on("focus", ({ window: win }) => {
       const attached = registry.get(win.id);
       if (!attached) return;
+      if (attached.element.hidden) syncAll();
       if (!attached.element.contains(doc.activeElement)) {
         attached.element.focus({ preventScroll: true });
       }
@@ -1718,6 +1759,7 @@ function attachDesktop(wm, element, options = {}) {
         return;
       }
       if (!event.ctrlKey && !event.metaKey) return;
+      if (drag) return;
       const target = event.target;
       if (target?.closest(INTERACTIVE_SELECTOR)) return;
       if (historyShortcuts && (event.key === "z" || event.key === "Z")) {
@@ -1778,6 +1820,9 @@ function attachDesktop(wm, element, options = {}) {
     }
     const handle = typeof windowOptions.handle === "string" ? windowElement.querySelector(windowOptions.handle) : windowOptions.handle ?? windowElement.querySelector("[data-wm-drag]");
     attached.handle = handle;
+    if (handle && !handle.hasAttribute("role") && LANDMARK_TAGS.has(handle.localName)) {
+      handle.setAttribute("role", "presentation");
+    }
     const onPointerDownFocus = () => {
       wm.focus(id);
     };
@@ -1983,5 +2028,5 @@ function createDesktopBinder(wm, options = {}) {
 }
 
 export { applyAspect, attachDesktop, boundsEqual, clamp, clampSize, clampToViewport, createAnnouncer, createDesktopBinder, createEmitter, createWindowManager, defaultMessages, detectSnapZone, flipFromTarget, flipToTarget, magnetize, prefersReducedMotion, zoneBounds };
-//# sourceMappingURL=chunk-FPZDAKNP.js.map
-//# sourceMappingURL=chunk-FPZDAKNP.js.map
+//# sourceMappingURL=chunk-GGDF2EWV.js.map
+//# sourceMappingURL=chunk-GGDF2EWV.js.map