winui-svelte 0.0.2 → 0.0.4

package/src/window/anchor.ts

@@ -0,0 +1,156 @@
+/**
+ * A corner of a window or of a display's work area. A window that changes
+ * size keeps its anchor corner where it is; a window docked to an anchor sits
+ * against that corner.
+ */
+export const WindowAnchor = {
+  topLeft: "topLeft",
+  topRight: "topRight",
+  bottomLeft: "bottomLeft",
+  bottomRight: "bottomRight"
+} as const;
+
+/** One of `WindowAnchor`'s values. */
+export type WindowAnchor = (typeof WindowAnchor)[keyof typeof WindowAnchor];
+
+/**
+ * Which of a window's sides follow its content: the width, the height, both,
+ * or neither (the window keeps the size its props and its user give it).
+ */
+export const SizeToContent = {
+  none: "none",
+  width: "width",
+  height: "height",
+  both: "both"
+} as const;
+
+/** One of `SizeToContent`'s values. */
+export type SizeToContent = (typeof SizeToContent)[keyof typeof SizeToContent];
+
+/** A position and a size in device pixels, as AppWindow and DisplayArea have them. */
+export interface WindowBounds {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/** A size in device pixels. */
+export interface WindowSize {
+  width: number;
+  height: number;
+}
+
+/** The least and the most a window may be, in device pixels; `Infinity` is no most. */
+export interface WindowLimits {
+  minWidth: number;
+  minHeight: number;
+  maxWidth: number;
+  maxHeight: number;
+}
+
+const ANCHOR_SIDES = {
+  [WindowAnchor.topLeft]: {
+    isRight: false,
+    isBottom: false
+  },
+  [WindowAnchor.topRight]: {
+    isRight: true,
+    isBottom: false
+  },
+  [WindowAnchor.bottomLeft]: {
+    isRight: false,
+    isBottom: true
+  },
+  [WindowAnchor.bottomRight]: {
+    isRight: true,
+    isBottom: true
+  }
+} as const satisfies Record<WindowAnchor, {
+  isRight: boolean;
+  isBottom: boolean;
+}>;
+
+/**
+ * The window `bounds` at `size` with its `anchor` corner where it was: a
+ * window anchored bottom-right that grows taller grows upward.
+ */
+export function anchoredBounds({ bounds, size, anchor }: {
+  bounds: WindowBounds;
+  size: WindowSize;
+  anchor: WindowAnchor;
+}) {
+  const { isRight, isBottom } = ANCHOR_SIDES[anchor];
+  return {
+    x: isRight ? bounds.x + bounds.width - size.width : bounds.x,
+    y: isBottom ? bounds.y + bounds.height - size.height : bounds.y,
+    width: size.width,
+    height: size.height
+  };
+}
+
+/**
+ * Where a window of `size` sits against the `anchor` corner of `area` (a
+ * display's work area), `inset` device pixels in from both of its edges.
+ */
+export function dockedBounds({ area, size, anchor, inset }: {
+  area: WindowBounds;
+  size: WindowSize;
+  anchor: WindowAnchor;
+  inset: number;
+}) {
+  const { isRight, isBottom } = ANCHOR_SIDES[anchor];
+  return {
+    x: isRight ? area.x + area.width - size.width - inset : area.x + inset,
+    y: isBottom ? area.y + area.height - size.height - inset : area.y + inset,
+    width: size.width,
+    height: size.height
+  };
+}
+
+function clamp({ value, least, most }: {
+  value: number;
+  least: number;
+  most: number;
+}) {
+  return Math.min(Math.max(value, least), most);
+}
+
+/**
+ * The bounds a window sized to its content takes: the sides `mode` names go to
+ * `desired` (what the content asks for, frame included) within `limits`, and
+ * the `anchor` corner stays. null when the window is already that size, so a
+ * caller makes no call for it.
+ */
+export function fittedBounds({ bounds, desired, mode, anchor, limits }: {
+  bounds: WindowBounds;
+  desired: WindowSize;
+  mode: SizeToContent;
+  anchor: WindowAnchor;
+  limits: WindowLimits;
+}) {
+  const isWidthFitted = mode === SizeToContent.width || mode === SizeToContent.both;
+  const isHeightFitted = mode === SizeToContent.height || mode === SizeToContent.both;
+  const size = {
+    width: isWidthFitted ? clamp({
+      value: desired.width,
+      least: limits.minWidth,
+      most: limits.maxWidth
+    }) : bounds.width,
+    height: isHeightFitted ? clamp({
+      value: desired.height,
+      least: limits.minHeight,
+      most: limits.maxHeight
+    }) : bounds.height
+  };
+  const isUnchanged = size.width === bounds.width && size.height === bounds.height;
+  if (isUnchanged) {
+    return null;
+  }
+
+  return anchoredBounds({
+    bounds,
+    size,
+    anchor
+  });
+}

package/src/window/backdrop.ts

@@ -1,4 +1,5 @@
 import { AcrylicVariant, attachAcrylic } from "./acrylic-controller.ts";
+import { attachTransparentBackdrop } from "./transparent-backdrop.ts";
 import { write } from "#src/renderer/host/reflect.js";
 import type { FrameworkElement, Window } from "#src/winui.js";
 import { DesktopAcrylicBackdrop, MicaBackdrop, MicaKind } from "#src/winui.js";
@@ -7,7 +8,9 @@ import { DesktopAcrylicBackdrop, MicaBackdrop, MicaKind } from "#src/winui.js";
  * The material behind a window's content. Acrylic blurs and tints what is
  * behind the window (`acrylicBase` and `acrylicThin` are its other two
  * variants, made by the system backdrop controller); Mica tints with the desktop wallpaper (Mica Alt more
- * strongly, as a tabbed title bar has it); none leaves the theme's solid color.
+ * strongly, as a tabbed title bar has it); transparent shows the desktop
+ * through every pixel the content leaves clear (with per-pixel alpha; pair it
+ * with `isBorderless`); none leaves the theme's solid color.
  */
 export const Backdrop = {
   acrylic: "acrylic",
@@ -15,7 +18,8 @@ export const Backdrop = {
   acrylicThin: "acrylicThin",
   mica: "mica",
   micaAlt: "micaAlt",
-  none: "none"
+  none: "none",
+  transparent: "transparent"
 } as const;
 
 /** One of `Backdrop`'s values. */
@@ -64,6 +68,7 @@ export function applyBackdrop({ window, content, backdrop }: {
 }) {
   const variant = controllerVariants.get(backdrop);
   const isControlled = variant !== undefined;
+  const isTransparent = backdrop === Backdrop.transparent;
   const systemBackdrop = isControlled ? null : systemBackdropFor(backdrop);
   const isRemoved = systemBackdrop === null;
   if (isRemoved) {
@@ -74,6 +79,10 @@ export function applyBackdrop({ window, content, backdrop }: {
     window.systemBackdrop = systemBackdrop;
   }
 
+  if (isTransparent) {
+    return attachTransparentBackdrop(window);
+  }
+
   if (isControlled) {
     return attachAcrylic({
       window,

package/src/window/create-window.ts

@@ -21,6 +21,8 @@ interface WindowChrome extends Pick<
   | "isShownInSwitchers"
   | "isToolWindow"
   | "owner"
+  | "anchor"
+  | "sizeToContent"
   | "title"
 > {
   /** In device pixels. */
@@ -123,7 +125,9 @@ export function createWindow<Props extends object>(options: WindowOptions<Props>
       isExcludedFromCapture: options.isExcludedFromCapture,
       isHidden: options.isHidden,
       isShownInSwitchers: options.isShownInSwitchers,
-      isToolWindow: options.isToolWindow
+      isToolWindow: options.isToolWindow,
+      sizeToContent: options.sizeToContent,
+      anchor: options.anchor
     },
     titleBar: () => null,
     size: options.size

package/src/window/css-pixels.ts

@@ -0,0 +1,18 @@
+/**
+ * Device-independent pixels (what the web calls CSS pixels) as device pixels,
+ * at `scale` device pixels per device-independent pixel.
+ */
+export function toDevicePixels({ value, scale }: {
+  value: number;
+  scale: number;
+}) {
+  return Math.round(value * scale);
+}
+
+/** Device pixels as device-independent (CSS) pixels, at `scale` device pixels per one. */
+export function toCssPixels({ value, scale }: {
+  value: number;
+  scale: number;
+}) {
+  return Math.round(value / scale);
+}

package/src/window/dock.ts

@@ -0,0 +1,99 @@
+import type { WindowAnchor } from "./anchor.ts";
+import { dockedBounds } from "./anchor.ts";
+import { foregroundWindowHandle } from "./native.ts";
+import type { AppWindow } from "#src/winui.js";
+import { DisplayArea, DisplayAreaFallback } from "#src/winui.js";
+
+/**
+ * Which display a window is docked to: the one the user is working on (the
+ * foreground window's), the one the window is on, or the primary one.
+ */
+export const DockDisplay = {
+  active: "active",
+  current: "current",
+  primary: "primary"
+} as const;
+
+/** One of `DockDisplay`'s values. */
+export type DockDisplay = (typeof DockDisplay)[keyof typeof DockDisplay];
+
+const NO_WINDOW = 0n;
+
+function activeDisplayArea(appWindow: AppWindow) {
+  const foreground = foregroundWindowHandle();
+  const hasForeground = foreground !== NO_WINDOW;
+  const windowId = hasForeground ? { value: foreground } : appWindow.id;
+  return DisplayArea.getFromWindowId(windowId, DisplayAreaFallback.Nearest);
+}
+
+const DISPLAY_FINDERS = {
+  [DockDisplay.active]: activeDisplayArea,
+  [DockDisplay.current]: appWindow => DisplayArea.getFromWindowId(appWindow.id, DisplayAreaFallback.Nearest),
+  [DockDisplay.primary]: () => DisplayArea.primary
+} as const satisfies Record<DockDisplay, (appWindow: AppWindow) => DisplayArea>;
+
+/**
+ * The display area `display` names for `appWindow`. The `active` one is the
+ * display of the foreground window, so an overlay that shows up while the user
+ * works on a second monitor lands there.
+ *
+ * @param options - The window and which display to find.
+ * @returns The WinUI `DisplayArea`: `workArea` is its desktop minus the taskbar, in device pixels.
+ */
+export function displayAreaOf({ appWindow, display }: {
+  appWindow: AppWindow;
+  display: DockDisplay;
+}) {
+  return DISPLAY_FINDERS[display](appWindow);
+}
+
+/** Where `dockWindow` puts a window. */
+export interface DockOptions {
+  /** The corner of the work area the window sits against. */
+  anchor: WindowAnchor;
+
+  /** Device pixels between the window and the two edges at that corner; 0 by default. */
+  inset?: number;
+
+  /** The display to dock to; the active one by default. */
+  display?: DockDisplay;
+}
+
+/**
+ * Moves the window against the `anchor` corner of a display's work area (the
+ * display minus the taskbar), `inset` device pixels in from both edges, with
+ * one `AppWindow.MoveAndResize`. The window keeps its size.
+ *
+ * A window moved to a display with another scale first goes there at its old
+ * size and is docked once Windows has rescaled it, so the corner it ends on is
+ * the one asked for at the size it really has.
+ *
+ * @param options - The window, the corner, the inset in device pixels (0 by
+ * default) and the display (the active one by default).
+ */
+export function dockWindow({ appWindow, anchor, inset = 0, display = DockDisplay.active }: DockOptions & {
+  appWindow: AppWindow;
+}) {
+  const area = displayAreaOf({
+    appWindow,
+    display
+  });
+  const { workArea } = area;
+  const currentArea = DisplayArea.getFromWindowId(appWindow.id, DisplayAreaFallback.Nearest);
+  const isOnOtherDisplay = currentArea.displayId.value !== area.displayId.value;
+  if (isOnOtherDisplay) {
+    appWindow.move({
+      x: workArea.x,
+      y: workArea.y
+    });
+  }
+
+  appWindow.moveAndResize(
+    dockedBounds({
+      area: workArea,
+      size: appWindow.size,
+      anchor,
+      inset
+    })
+  );
+}

package/src/window/index.ts

@@ -2,6 +2,10 @@ export type { RunWindowOptions } from "./application.ts";
 export { exitApplication, runWindow } from "./application.ts";
 export type { AppWindow, WindowOptions } from "./create-window.ts";
 export { Backdrop } from "./backdrop.ts";
+export type { WindowBounds, WindowSize } from "./anchor.ts";
+export { SizeToContent, WindowAnchor } from "./anchor.ts";
+export type { DockOptions } from "./dock.ts";
+export { displayAreaOf, DockDisplay, dockWindow } from "./dock.ts";
 export type { CaptionButtonColors, WindowRegion } from "./chrome.ts";
 export { TitleBarHeight, WindowPresentation, WindowTheme } from "./chrome.ts";
 export { createWindow } from "./create-window.ts";

package/src/window/native.ts

@@ -58,6 +58,18 @@ export function scaleOf(hwnd: bigint) {
   return dpi > 0 ? dpi / BASE_DPI : 1;
 }
 
+const getForegroundWindow = bind({
+  dll: "user32.dll",
+  entryPoint: "GetForegroundWindow",
+  parameters: [],
+  returnType: "pointer"
+});
+
+/** The handle of the window the user is working in; 0 when no window has the foreground. */
+export function foregroundWindowHandle() {
+  return addressOf(getForegroundWindow.invoke([]).returnValue);
+}
+
 /**
  * Makes the window `owner` own the window `hwnd`: the owned window stays above
  * its owner, and closes, minimizes and restores with it.

package/src/window/transparent-backdrop.ts

@@ -0,0 +1,38 @@
+import { write } from "#src/renderer/host/reflect.js";
+import type { Window } from "#src/winui.js";
+import { ICompositionSupportsSystemBackdrop, SystemCompositor } from "#src/winui.js";
+
+// The Windows App SDK's own Microsoft.UI.Xaml.Media.TransparentTintBackdrop is
+// not in the metadata of any release this package restores (2.2 and 2.3 have
+// DesktopAcrylicBackdrop, MicaBackdrop and the abstract SystemBackdrop only),
+// so it cannot be generated. What it does is what a window offers through
+// ICompositionSupportsSystemBackdrop: a composition brush placed behind the
+// content, one of the system's (Windows.UI.Composition) and not of the window's
+// own compositor (Microsoft.UI.Composition), which is what the interface takes.
+// A color brush with alpha 0 there makes the window show the desktop through
+// every pixel the content leaves clear, with per-pixel alpha.
+
+const CLEAR = {
+  a: 0,
+  r: 0,
+  g: 0,
+  b: 0
+};
+
+/**
+ * Puts a fully transparent system backdrop behind `window`'s content: the
+ * desktop shows through wherever the content paints nothing, and a partly
+ * transparent pixel blends with it. The window must have no XAML backdrop of
+ * its own (`applyBackdrop` takes it away first).
+ *
+ * @returns What takes the backdrop away again.
+ */
+export function attachTransparentBackdrop(window: Window) {
+  const target = window.as(ICompositionSupportsSystemBackdrop);
+  target.systemBackdrop = new SystemCompositor().createColorBrush(CLEAR);
+  return () => {
+    // The binding types the property as non-null, but null is how the target
+    // lets a backdrop go.
+    write(target, "systemBackdrop", null);
+  };
+}

package/src/window/window-handle.ts

@@ -1,7 +1,10 @@
 import { applyShownInSwitchers } from "./apply-chrome.ts";
+import type { DockOptions } from "./dock.ts";
+import { dockWindow } from "./dock.ts";
 import { scaleOf } from "./native.ts";
 import type { OpenFilePickerOptions, PickerOptions, SaveFilePickerOptions } from "./pickers.ts";
 import { pickFile, pickFilePaths, pickFolder, saveFile } from "./pickers.ts";
+import { WindowGeometry } from "#src/web-apis/window-geometry.js";
 import type { Window } from "#src/winui.js";
 import {
   FileOpenPicker,
@@ -18,11 +21,18 @@ import {
 export class WindowHandle {
   /** The native WinUI window. */
   readonly window: Window;
+
+  /**
+   * The window's size and place as the web has them: `outerWidth`,
+   * `screenX`, `resizeTo`, `moveBy` and the rest, in CSS pixels.
+   */
+  readonly geometry: WindowGeometry;
   private isClosed = false;
   private closeGuard = () => false;
 
   constructor(window: Window) {
     this.window = window;
+    this.geometry = new WindowGeometry(window.appWindow, () => this.scale);
     window.onClosed(() => {
       this.isClosed = true;
     });
@@ -59,6 +69,22 @@ export class WindowHandle {
     });
   }
 
+  /**
+   * Moves the window against a corner of a display's work area (the display
+   * minus the taskbar), `inset` device pixels in from both edges: an overlay
+   * that sits bottom-right above the taskbar of the display the user is on.
+   * With `sizeToContent` and the same `anchor` on the window, the corner stays
+   * as the content grows.
+   *
+   * @param options - The corner, the inset in device pixels and the display (the active one by default).
+   */
+  dock(options: DockOptions) {
+    dockWindow({
+      appWindow: this.appWindow,
+      ...options
+    });
+  }
+
   /** Shows the window and gives it focus. */
   activate() {
     this.window.activate();