@deseteral/biurko 0.0.0-stage → 0.1.0

package/dist/window-manager-X3GN3wrq.d.ts

@@ -0,0 +1,524 @@
+/**
+ * Unique window identifier.
+ */
+type WindowHandle = string & {
+  readonly __brand: unique symbol;
+};
+/**
+ * Configuration for creating a new window.
+ */
+interface CreateWindowOptions {
+  /** The display title for the window. */
+  title: string;
+  /**
+   * Initial horizontal position (in pixels) in desktop coordinate space.
+   * Both `x` and `y` must be supplied to use explicit coordinates. If either is omitted,
+   * the configured {@link WindowPositionStrategy} determines both coordinates.
+   */
+  x?: number;
+  /**
+   * Initial vertical position (in pixels) in desktop coordinate space.
+   * Both `x` and `y` must be supplied to use explicit coordinates. If either is omitted,
+   * the configured {@link WindowPositionStrategy} determines both coordinates.
+   */
+  y?: number;
+  /** Initial width of the window in pixels. */
+  width: number;
+  /** Initial height of the window in pixels. */
+  height: number;
+  /** Minimum width constraint enforced during resize. Defaults to `0`. */
+  minWidth?: number;
+  /** Minimum height constraint enforced during resize. Defaults to `0`. */
+  minHeight?: number;
+}
+/**
+ * Represents the position and dimensions of a window.
+ */
+interface WindowRect {
+  /** Horizontal position in pixels in desktop coordinate space. */
+  x: number;
+  /** Vertical position in pixels in desktop coordinate space. */
+  y: number;
+  /** Width of the window in pixels. */
+  width: number;
+  /** Height of the window in pixels. */
+  height: number;
+}
+/**
+ * Determines how the {@link WindowManager} positions new windows when explicit coordinates are not provided.
+ *
+ * - `"required"` - The caller must always provide `x` and `y`.
+ * - `"offset-from-focused"` - The new window is placed at an offset from the currently focused window.
+ *   If no window is focused, the offset is applied to the desktop origin `(0, 0)`.
+ */
+type WindowPositionStrategy = {
+  readonly type: "required";
+} | {
+  readonly type: "offset-from-focused";
+  readonly offsetX: number;
+  readonly offsetY: number;
+};
+/**
+ * Determines how the {@link WindowManager} desktop behaves.
+ *
+ * - `"static"` - The desktop has no wheel-driven panning or zooming. Moving and resizing windows
+ *   clamps their position to keep a small portion visible, not the entire window. Initial placement
+ *   is not clamped, and descendants moved with a parent may overflow the desktop bounds.
+ * - `"infinite-canvas"` - The desktop acts as an infinite canvas. Windows live inside a translatable
+ *   world layer that can be moved with the mouse wheel or the viewport translate API, and window
+ *   placement is not clamped to the viewport.
+ */
+type DesktopMode = {
+  readonly type: "static";
+} | {
+  readonly type: "infinite-canvas";
+};
+/**
+ * Determines which window content surfaces can receive pointer input events.
+ *
+ * - `"all"` - All window surfaces are interactive.
+ * - `"focused-only"` - Only the currently focused window's surface is interactive.
+ *
+ * Drag regions (`data-biurko-drag-region`) and resize handles remain interactive in both modes.
+ */
+type WindowInteractivity = {
+  readonly type: "all";
+} | {
+  readonly type: "focused-only";
+};
+/**
+ * Configuration for a parent-child window relationship
+ * (see {@link WindowManager.attachWindowToParent}).
+ */
+interface WindowParentOptions {
+  /**
+   * Determines whether dragging a window tears it off its parent.
+   *
+   * @defaultValue `false`
+   */
+  detachOnDrag?: boolean;
+}
+/** Event detail emitted when a new window is created. */
+interface WindowOpenedEventDetail {
+  /** The handle of the newly created window. */
+  handle: WindowHandle;
+}
+/** Event detail emitted when a window is closed. */
+interface WindowClosedEventDetail {
+  /** The handle of the closed window. */
+  handle: WindowHandle;
+}
+/** Event detail emitted by a successful focus call, even if the window was already focused. */
+interface WindowFocusedEventDetail {
+  /** The handle of the focused window. */
+  handle: WindowHandle;
+}
+/**
+ * Event detail emitted when a window drag gesture completes, even if its position did not change.
+ * Only the dragged window emits this event, not descendants moved with it.
+ * Programmatic calls to `moveWindow` do not emit this event.
+ */
+interface WindowMovedEventDetail {
+  /** The handle of the moved window. */
+  handle: WindowHandle;
+  /** The horizontal position after the drag, in pixels in desktop coordinate space. */
+  x: number;
+  /** The vertical position after the drag, in pixels in desktop coordinate space. */
+  y: number;
+}
+/**
+ * Event detail emitted when a window resize gesture completes, even if its size did not change.
+ * Programmatic calls to `resizeWindow` do not emit this event.
+ */
+interface WindowResizedEventDetail {
+  /** The handle of the resized window. */
+  handle: WindowHandle;
+  /** The horizontal position after the resize, in pixels in desktop coordinate space. */
+  x: number;
+  /** The vertical position after the resize, in pixels in desktop coordinate space. */
+  y: number;
+  /** The width after the resize, in pixels. */
+  width: number;
+  /** The height after the resize, in pixels. */
+  height: number;
+}
+/** Event detail emitted when a window's parent relationship changes. */
+interface WindowParentChangedEventDetail {
+  /** The handle of the window whose parent changed. */
+  handle: WindowHandle;
+  /** The previous parent handle, or `null` if the window was a root. */
+  previousParent: WindowHandle | null;
+  /** The new parent handle, or `null` if the window has become a root. */
+  parent: WindowHandle | null;
+}
+/**
+ * Event detail emitted when the stored viewport translation changes.
+ * Offsets are the requested values and may differ from the browser-clamped scroll position.
+ */
+interface ViewportTranslatedEventDetail {
+  /** New horizontal translate offset of the world layer, in pixels. */
+  x: number;
+  /** New vertical translate offset of the world layer, in pixels. */
+  y: number;
+}
+/** Maps window manager event names to their custom event payloads. */
+interface WindowManagerEventMap {
+  "window-opened": CustomEvent<WindowOpenedEventDetail>;
+  "window-closed": CustomEvent<WindowClosedEventDetail>;
+  "window-focused": CustomEvent<WindowFocusedEventDetail>;
+  "window-moved": CustomEvent<WindowMovedEventDetail>;
+  "window-resized": CustomEvent<WindowResizedEventDetail>;
+  "window-parent-changed": CustomEvent<WindowParentChangedEventDetail>;
+  "viewport-translated": CustomEvent<ViewportTranslatedEventDetail>;
+}
+type NoAttachedData = ReturnType<() => void>;
+/** Configuration options for the {@link WindowManager} constructor. */
+interface WindowManagerOptions {
+  /**
+   * Distance (in pixels) that invisible resize hit regions extend inside and outside each window edge.
+   * Edge hit regions are twice this value in thickness; corner regions are squares of that size.
+   * A larger value makes it easier for users to grab the resize handles.
+   *
+   * @defaultValue `6`
+   */
+  resizeRegionSize?: number;
+  /**
+   * Strategy used to determine window position.
+   *
+   * @defaultValue `{ type: "required" }`
+   */
+  positionStrategy?: WindowPositionStrategy;
+  /**
+   * Determines how the desktop behaves (see {@link DesktopMode}).
+   *
+   * @defaultValue `{ type: "static" }`
+   */
+  mode?: DesktopMode;
+  /**
+   * Determines which windows can receive mouse input events.
+   *
+   * @defaultValue `{ type: "all" }`
+   */
+  windowInteractivity?: WindowInteractivity;
+}
+/**
+ * Core window management class that handles window lifecycle and actions such as drag, resize, focus, and ordering.
+ *
+ * Dispatches typed events (see {@link WindowManagerEventMap}).
+ *
+ * @typeParam AttachedDataT - Optional data type attached to each window. Use `void` (default) if no
+ *   data is needed.
+ */
+declare class WindowManager<AttachedDataT = NoAttachedData> extends EventTarget {
+  private readonly desktopElement;
+  private readonly scrollerElement;
+  private readonly worldElement;
+  private readonly windows;
+  private readonly dragState;
+  private readonly resizeState;
+  private readonly resizeRegionSize;
+  private readonly positionStrategy;
+  private readonly mode;
+  private readonly windowInteractivity;
+  private translateX;
+  private translateY;
+  private zoomLevel;
+  /**
+   * Creates a new WindowManager bound to the given container element.
+   * The container acts as the "desktop" area where windows are positioned. Its `data-biurko-type`
+   * attribute is set to `"desktop"`, its position is set to `relative`, and the `biurko-desktop`
+   * CSS class is added automatically.
+   *
+   * Windows are placed inside an inner layer with `data-biurko-type="world"`.
+   * In `"infinite-canvas"` mode, scrolling the desktop background pans the canvas and
+   * Shift+wheel zooms around the pointer. Holding Alt also enables these gestures over windows.
+   * Panning is also available through {@link setViewportTranslate}.
+   *
+   * @param container - The DOM element that serves as the desktop area.
+   * @param options - Optional configuration details.
+   */
+  constructor(container: HTMLElement, options?: WindowManagerOptions);
+  /**
+   * Creates a new window and appends it to the desktop's world layer.
+   * The window is automatically focused (brought to front) upon creation.
+   * Dispatches `"window-focused"` before `"window-opened"`.
+   * Initial position and size are not clamped to desktop bounds or minimum size constraints.
+   *
+   * @param options - Configuration details (see {@link CreateWindowOptions}).
+   * @param args - If `AttachedDataT` is not `void`, the attached data must be passed as the second argument.
+   * @returns A unique {@link WindowHandle} identifying the created window.
+   * @throws Error if either coordinate is missing when the position strategy is `"required"`.
+   */
+  createWindow(options: CreateWindowOptions, ...args: AttachedDataT extends NoAttachedData ? [] : [data: AttachedDataT]): WindowHandle;
+  /**
+   * Brings the specified window to front.
+   * No-op if the handle is invalid.
+   * Dispatches a `"window-focused"` event even if the window is already focused.
+   *
+   * @param handle - The handle of the window to focus.
+   */
+  focusWindow(handle: WindowHandle): void;
+  /**
+   * Returns the handle of the currently focused window.
+   *
+   * @returns The {@link WindowHandle} of the focused window, or `null` if no windows are open.
+   */
+  getFocusedWindow(): WindowHandle | null;
+  /**
+   * Closes and removes the window together with its complete descendant subtree.
+   * The windows' DOM elements are removed and their internal state is cleaned up.
+   * One `"window-closed"` event is dispatched per removed window, descendants first.
+   * No-op if the handle is invalid or its window is no longer open.
+   *
+   * @param handle - The handle of the window to close.
+   */
+  closeWindow(handle: WindowHandle): void;
+  /**
+   * Attaches a window to another window, forming a parent-child relationship.
+   * Moving the parent moves the complete child subtree (see {@link moveWindow}),
+   * and closing the parent closes the complete child subtree (see {@link closeWindow}).
+   * Attachment does not affect position, size, focus, z-order, or DOM structure.
+   *
+   * Attaching a window to itself or to one of its descendants is rejected.
+   * Attaching a window that already has a parent reparents it with the given options.
+   * No-op if either handle is invalid or the relationship already exists.
+   * Dispatches a `"window-parent-changed"` event on success.
+   *
+   * @param child - The handle of the window to attach.
+   * @param parent - The handle of the window to attach to.
+   * @param options - Configuration of the relationship (see {@link WindowParentOptions}).
+   *   To change the options of an existing relationship, detach the window and attach it again.
+   */
+  attachWindowToParent(child: WindowHandle, parent: WindowHandle, options?: WindowParentOptions): void;
+  /**
+   * Detaches a window from its parent, turning the window together with its
+   * descendants into an independent root tree. Descendant relationships are preserved.
+   * Relationship options are reset to defaults.
+   * No-op if the handle is invalid or the window has no parent.
+   * Dispatches a `"window-parent-changed"` event on success.
+   *
+   * @param child - The handle of the window to detach.
+   */
+  detachWindowFromParent(child: WindowHandle): void;
+  /**
+   * Returns the parent of the given window.
+   *
+   * @param child - The window handle.
+   * @returns The parent handle, or `null` if the window is a root or the handle is invalid.
+   */
+  getWindowParent(child: WindowHandle): WindowHandle | null;
+  /**
+   * Returns the direct children of the given window.
+   *
+   * @param parent - The window handle.
+   * @returns The handles of direct children in creation order. Empty if the window has no children.
+   */
+  getChildren(parent: WindowHandle): WindowHandle[];
+  /**
+   * Returns the options of the parent-child relationship of the given window
+   * (see {@link attachWindowToParent}).
+   *
+   * @param child - The window handle.
+   * @returns The relationship options with defaults applied. Defaults are returned
+   *   if the window is a root or the handle is invalid.
+   */
+  getWindowParentOptions(child: WindowHandle): Required<WindowParentOptions>;
+  /**
+   * Returns the surface element (content container) for the given window.
+   * This is the `HTMLDivElement` where you should render your window content.
+   * It has the CSS class `biurko-surface`.
+   *
+   * @param handle - The window handle.
+   * @returns The surface element, or `null` if the handle is invalid.
+   */
+  getWindowSurface(handle: WindowHandle): HTMLDivElement | null;
+  /**
+   * Returns the current title of the window.
+   *
+   * @param handle - The window handle.
+   * @returns The title string, or `null` if the handle is invalid.
+   */
+  getWindowTitle(handle: WindowHandle): string | null;
+  /**
+   * Updates the title of the window.
+   * This only updates the internal state (see {@link getWindowTitle}).
+   *
+   * @param handle - The window handle.
+   * @param title - The new title string.
+   */
+  setWindowTitle(handle: WindowHandle, title: string): void;
+  /**
+   * Returns the attached data for the given window.
+   * The data type is determined by the `AttachedDataT` generic parameter.
+   *
+   * @param handle - The window handle.
+   * @returns The attached data, or `null` if the handle is invalid or the stored data is falsy
+   *   (including when no data was provided).
+   */
+  getWindowData(handle: WindowHandle): AttachedDataT | null;
+  /**
+   * Returns the current position and dimensions of the window.
+   *
+   * @param handle - The window handle.
+   * @returns A {@link WindowRect}, or `null` if the handle is invalid.
+   */
+  getWindowRect(handle: WindowHandle): WindowRect | null;
+  /**
+   * Returns the minimum size constraints for the window.
+   *
+   * @param handle - The window handle.
+   * @returns An object with `minWidth` and `minHeight`, or `null` if the handle is invalid.
+   */
+  getMinSize(handle: WindowHandle): {
+    minWidth: number;
+    minHeight: number;
+  } | null;
+  /**
+   * Returns the container element containing windows that represents the desktop.
+   */
+  getDesktopElement(): HTMLElement;
+  /** Offset between logical world coordinates and physical offsets inside the world layer. */
+  private get worldOriginOffset();
+  /**
+   * Returns the stored viewport translation, initially `{ x: 0, y: 0 }`.
+   * This is the requested offset, which may differ from the actual scroll position
+   * when the browser clamps scrolling at the world bounds.
+   *
+   * @returns The horizontal and vertical translate offsets in pixels.
+   */
+  getViewportTranslate(): {
+    x: number;
+    y: number;
+  };
+  /**
+   * Stores a viewport translation and updates the inner container's scroll position.
+   * Intended for `"infinite-canvas"` mode, where positive offsets pan the world right and down.
+   * The stored offsets are not clamped, but the browser limits the actual scroll position
+   * to the scrollable world bounds. Static mode does not ignore or reset these offsets.
+   * Dispatches a `"viewport-translated"` event when the stored offset changes.
+   *
+   * @param x - New horizontal offset in pixels.
+   * @param y - New vertical offset in pixels.
+   */
+  setViewportTranslate(x: number, y: number): void;
+  /**
+   * Translates the world layer by a relative offset (see {@link setViewportTranslate}).
+   *
+   * @param dx - Horizontal offset delta in pixels.
+   * @param dy - Vertical offset delta in pixels.
+   */
+  translateViewport(dx: number, dy: number): void;
+  /**
+   * Sets the scale of the world layer.
+   * Values below `0.1` are clamped to `0.1`; there is no maximum.
+   * Applies in both desktop modes and does not adjust the viewport translation.
+   *
+   * @param level - The scale applied to the world layer.
+   */
+  setZoomLevel(level: number): void;
+  /**
+   * Adds `delta` to the current zoom level (see {@link setZoomLevel}).
+   * This is an additive change, not a multiplication of the scale.
+   *
+   * @param delta - The delta applied to the world layer scale.
+   */
+  zoomBy(delta: number): void;
+  /** Resets the world layer's zoom level to `1` without changing the viewport translation. */
+  resetZoomLevel(): void;
+  /**
+   * Returns the scale of the world layer.
+   *
+   * @returns The current zoom level, initially `1` and at least `0.1`.
+   */
+  getZoomLevel(): number;
+  private setZoomLevelAtPoint;
+  /**
+   * Converts viewport (client) coordinates to desktop world coordinates,
+   * taking the desktop's position, actual scroll offsets, and zoom level into account.
+   *
+   * @param clientX - Horizontal position in client (viewport) coordinates.
+   * @param clientY - Vertical position in client (viewport) coordinates.
+   * @returns The corresponding position in desktop coordinate space.
+   */
+  clientToWorld(clientX: number, clientY: number): {
+    x: number;
+    y: number;
+  };
+  private onWheel;
+  /**
+   * Moves the window to the specified position in desktop coordinate space.
+   * The window's complete descendant subtree (see {@link attachWindowToParent}) is moved
+   * by the same delta, preserving relative positions inside the subtree.
+   * In `"static"` mode only the moved root is clamped to keep a small portion visible
+   * within the desktop bounds; descendants follow rigidly and may overflow the bounds.
+   * In `"infinite-canvas"` mode positions are not clamped.
+   * No-op if the handle is invalid. Does not dispatch `"window-moved"`;
+   * that event is dispatched only when a drag gesture completes, for the dragged window.
+   *
+   * @param handle - The window handle.
+   * @param x - New horizontal position in pixels.
+   * @param y - New vertical position in pixels.
+   */
+  moveWindow(handle: WindowHandle, x: number, y: number): void;
+  /**
+   * Resizes and repositions the window.
+   * The size is clamped to the minimum constraints (`minWidth`/`minHeight`).
+   * In `"static"` mode the position is clamped to keep a small portion of the window visible;
+   * in `"infinite-canvas"` mode the position is not clamped.
+   * Descendant windows are not moved or resized.
+   * No-op if the handle is invalid. Does not dispatch `"window-resized"`;
+   * that event is dispatched only when a resize gesture completes.
+   *
+   * @param handle - The window handle.
+   * @param x - New horizontal position in pixels in desktop coordinate space.
+   * @param y - New vertical position in pixels in desktop coordinate space.
+   * @param width - New width in pixels (will be clamped to `minWidth`).
+   * @param height - New height in pixels (will be clamped to `minHeight`).
+   */
+  resizeWindow(handle: WindowHandle, x: number, y: number, width: number, height: number): void;
+  /** Clamp position so that at least `margin` pixels of the window remain visible within the container. */
+  private clampWindowPositionWithinDesktop;
+  private resolveInitialPosition;
+  /**
+   * Stabilize orderIdx (make them continuous, remove duplicate indices).
+   * Apply order to z-index for all windows.
+   * This method must be called everytime any orderIdx is changed.
+   */
+  private applyWindowOrdering;
+  private getWindowRectInWorldCoords;
+  private buildChildrenIndex;
+  private collectWindowSubtree;
+  /**
+   * Registers a listener for a window manager event with a typed event payload.
+   *
+   * @param type - The window manager event name.
+   * @param listener - Callback receiving the event and its detail payload.
+   * @param options - Standard DOM listener options or the capture flag.
+   */
+  addEventListener<K extends keyof WindowManagerEventMap>(type: K, listener: (event: WindowManagerEventMap[K]) => void, options?: boolean | AddEventListenerOptions): void;
+  /**
+   * Registers a listener for any event using the standard {@link EventTarget} API.
+   *
+   * @param type - The event name.
+   * @param listener - Callback or object whose `handleEvent` method receives the event.
+   * @param options - Standard DOM listener options or the capture flag.
+   */
+  addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+  /**
+   * Removes a listener for a typed window manager event.
+   *
+   * @param type - The window manager event name used during registration.
+   * @param listener - The same callback passed to {@link addEventListener}.
+   * @param options - Listener options; the capture flag must match the registration.
+   */
+  removeEventListener<K extends keyof WindowManagerEventMap>(type: K, listener: (event: WindowManagerEventMap[K]) => void, options?: boolean | EventListenerOptions): void;
+  /**
+   * Removes a listener using the standard {@link EventTarget} API.
+   *
+   * @param type - The event name used during registration.
+   * @param listener - The same callback or listener object used during registration.
+   * @param options - Listener options; the capture flag must match the registration.
+   */
+  removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
+}
+export { WindowFocusedEventDetail as a, WindowOpenedEventDetail as c, CreateWindowOptions as d, DesktopMode as f, WindowRect as g, WindowPositionStrategy as h, WindowClosedEventDetail as i, WindowParentChangedEventDetail as l, WindowParentOptions as m, WindowManagerOptions as n, WindowManagerEventMap as o, WindowHandle as p, ViewportTranslatedEventDetail as r, WindowMovedEventDetail as s, WindowManager as t, WindowResizedEventDetail as u };

package/package.json

@@ -1,6 +1,81 @@
 {
   "name": "@deseteral/biurko",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "A browser window manager with React and SolidJS adapters.",
+  "homepage": "https://github.com/Deseteral/biurko#readme",
+  "bugs": {
+    "url": "https://github.com/Deseteral/biurko/issues"
+  },
+  "license": "MIT",
+  "author": "Deseteral",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Deseteral/biurko.git"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./adapters/solid-js": {
+      "types": "./dist/adapters/solid-js/index.d.ts",
+      "import": "./dist/adapters/solid-js/index.js"
+    },
+    "./adapters/react": {
+      "types": "./dist/adapters/react/index.d.ts",
+      "import": "./dist/adapters/react/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "build:demo": "vp build demo/",
+    "prepack": "npm run typecheck && npm run build",
+    "typecheck": "tsc --noEmit",
+    "lint": "vp lint",
+    "check": "vp check",
+    "format": "vp fmt",
+    "format:check": "vp fmt --check",
+    "demo": "vp dev demo/"
+  },
+  "devDependencies": {
+    "@types/node": "26.6.3",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "@vitejs/plugin-react": "6.1.1",
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
+    "solid-js": "1.9.15",
+    "typescript": "7.0.2",
+    "vite": "npm:@voidzero-dev/vite-plus-core@1.4.0",
+    "vite-plugin-solid": "2.11.14",
+    "vite-plus": "1.4.0"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0",
+    "solid-js": ">=1.8.0"
+  },
+  "peerDependenciesMeta": {
+    "solid-js": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "overrides": {
+    "vite": "npm:@voidzero-dev/vite-plus-core@1.4.0"
+  },
+  "packageManager": "npm@11.20.0"
+}