winui-svelte 0.0.3 → 0.0.4

package/src/components/convert.ts

@@ -1,4 +1,4 @@
-import type { FluentGlyphName } from "./fluent-glyph.ts";
+import type { FluentGlyphCode, FluentGlyphValue } from "./fluent-glyph.ts";
 import type { FontFamilyName } from "./font-family-name.ts";
 import {
   Application,
@@ -203,8 +203,8 @@ export type GeometryInput = string | Geometry;
 /** A font family name or a font family. */
 export type FontFamilyInput = FontFamilyName | (string & Record<never, never>) | FontFamily;
 
-/** An icon glyph: a name of Segoe Fluent Icons ("Save"), a code point (`0xE74E`), code points to compose, or text. */
-export type GlyphInput = FluentGlyphName | (string & Record<never, never>) | number | readonly number[];
+/** An icon glyph: a Fluent name ("Save"), its code point (`FluentGlyph.Save`), code points to compose, or text. */
+export type GlyphInput = FluentGlyphValue | (string & Record<never, never>) | readonly FluentGlyphCode[];
 
 /** A URI string or a URI. */
 export type UriInput = string | Uri;

package/src/components/fluent-glyph.ts

@@ -1545,3 +1545,9 @@ export const FluentGlyph = {
 
 /** The name of an icon of Segoe Fluent Icons. */
 export type FluentGlyphName = keyof typeof FluentGlyph;
+
+/** The code point of an icon of Segoe Fluent Icons: the only numbers a `glyph` takes. */
+export type FluentGlyphCode = (typeof FluentGlyph)[FluentGlyphName];
+
+/** An icon of Segoe Fluent Icons by its name or its code point. */
+export type FluentGlyphValue = FluentGlyphName | FluentGlyphCode;

package/src/components/generated/controls/FontIcon.svelte.ts

@@ -59,7 +59,7 @@ export interface FontIconProps extends IconElementProps {
   /**
    * Gets or sets the character code that identifies the icon glyph. The hexadecimal character code for the icon glyph.
    *
-   * Accepts an icon glyph: a name of Segoe Fluent Icons ("Save"), a code point (`0xE74E`), code points to compose, or text.
+   * Accepts an icon glyph: a Fluent name ("Save"), its code point (`FluentGlyph.Save`), code points to compose, or text.
    *
    * @see https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.fonticon.glyph
    */

package/src/components/generated/controls/FontIconSource.svelte.ts

@@ -59,7 +59,7 @@ export interface FontIconSourceProps extends IconSourceProps {
   /**
    * Gets or sets the character code that identifies the icon glyph. The hexadecimal character code for the icon glyph.
    *
-   * Accepts an icon glyph: a name of Segoe Fluent Icons ("Save"), a code point (`0xE74E`), code points to compose, or text.
+   * Accepts an icon glyph: a Fluent name ("Save"), its code point (`FluentGlyph.Save`), code points to compose, or text.
    *
    * @see https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.fonticonsource.glyph
    */

package/src/components/generated/controls/UIElement.svelte.ts

@@ -761,7 +761,7 @@ export interface UIElementProps {
   /**
    * Gets or sets the visibility of a UIElement. A UIElement that is not visible is not rendered and does not communicate its desired size to layout. A value of the enumeration. The default value is Visible.
    *
-   * Also settable in CSS as `visibility`
+   * Also settable in CSS as `display`
    *
    * @see https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.visibility
    */

package/src/components/index.ts

@@ -22,7 +22,7 @@ export type {
 export { NavigationCacheMode, NavigationMode } from "./hand-written/navigation/navigation-stack.ts";
 export { MoveDirection } from "./hand-written/items/reorder.ts";
 export { FluentGlyph } from "./fluent-glyph.ts";
-export type { FluentGlyphName } from "./fluent-glyph.ts";
+export type { FluentGlyphCode, FluentGlyphName, FluentGlyphValue } from "./fluent-glyph.ts";
 export type { FontFamilyName } from "./font-family-name.ts";
 export { isColorText, ticksDate, ticksMilliseconds } from "./values.ts";
 export type { ColorInput, ColorKeyword, ColorText, GridLengthText, HexColor } from "./values.ts";
@@ -42,5 +42,7 @@ export { goToState, installXaml, resourceDictionaryOf, xamlOf } from "./xaml.ts"
 export type { XamlSource } from "./xaml-source.ts";
 export { XamlKind } from "./xaml-source.ts";
 export type { CaptionButtonColors, TitleBarHeight, WindowPresentation, WindowRegion, WindowTheme } from "#src/window/chrome.js";
+export type { DockDisplay, DockOptions } from "#src/window/dock.js";
+export type { SizeToContent, WindowAnchor } from "#src/window/anchor.js";
 export type { WindowHandle } from "#src/window/window-handle.js";
 export type { WindowBounds, WindowPlacement } from "#src/window/window-host.svelte.js";

package/src/dev/dev-window.ts

@@ -0,0 +1,63 @@
+import type { Json } from "#src/messaging/json.js";
+import type * as StateModule from "#src/state/index.js";
+import { createWindowModuleRunner } from "#src/vite/runner.js";
+import type { WindowOptions } from "#src/window/create-window.js";
+import type * as WindowModule from "#src/window/index.js";
+import { runOnUiThread } from "#src/window/thread.js";
+import type { MessagePort } from "node:worker_threads";
+
+/** The window's chrome `startDev` takes: what `createWindow` takes besides the content and the owner. */
+export type DevWindowChrome = Omit<Extract<WindowOptions<object>, { component: unknown }>, "component" | "owner" | "props">;
+
+/** What the dev window's thread is started with. */
+export interface DevWindowData {
+  modules: MessagePort;
+  /** The host's end of the link, when the app has one: the component then gets a `channel` prop. */
+  link: MessagePort | null;
+  component: string;
+  props: Record<string, Json>;
+  window: DevWindowChrome;
+}
+
+/**
+ * The window's side of `startDev`: enters the apartment, loads the component
+ * through the module server (so a saved file updates the open window) and
+ * opens it in a window.
+ */
+export async function runDevWindow(data: DevWindowData) {
+  await runOnUiThread(async () => {
+    const { runner } = createWindowModuleRunner(data.modules);
+    const { createWindow, exitWhenHostEnds, runWindow } = await runner.import<typeof WindowModule>("winui-svelte/window");
+    const { default: component } = await runner.import(data.component);
+    const { createHostChannel, createMessagePortTransport } = await runner.import<typeof StateModule>(
+      "winui-svelte/state"
+    );
+    const { link } = data;
+    await runWindow({
+      onStart() {
+        const hasLink = link !== null;
+        if (!hasLink) {
+          createWindow({
+            ...data.window,
+            component,
+            props: data.props
+          });
+          return;
+        }
+
+        const channel = createHostChannel({
+          transport: createMessagePortTransport({ port: link })
+        });
+        exitWhenHostEnds({ link: channel });
+        createWindow({
+          ...data.window,
+          component,
+          props: {
+            ...data.props,
+            channel
+          }
+        });
+      }
+    });
+  });
+}

package/src/dev/index.ts

@@ -0,0 +1,2 @@
+export type { DevOptions } from "./start-dev.ts";
+export { startDev } from "./start-dev.ts";

package/src/dev/start-dev.ts

@@ -0,0 +1,120 @@
+import type { DevWindowChrome, DevWindowData } from "./dev-window.ts";
+import type { Json } from "#src/messaging/json.js";
+import type { Transport } from "#src/state/host.js";
+import { createStdioTransport, reserveStdout } from "#src/state/host.js";
+import { startModuleServer } from "#src/vite/server.js";
+import { initWindowsAppSdk } from "#src/window/bootstrap.js";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { MessageChannel, Worker } from "node:worker_threads";
+
+/** What `startDev` opens and where its modules come from. */
+export interface DevOptions {
+  /** The folder of the app's sources, which the dev server serves and watches. */
+  root: string;
+
+  /** The window's root component, as a path under `root` that starts with a slash (`"/App.svelte"`). */
+  component: string;
+
+  /** The component's props: JSON, since they cross to the window's thread. */
+  props?: Record<string, Json>;
+
+  /** The window's title, size, backdrop and the other chrome `createWindow` takes, besides its content and owner. */
+  window?: DevWindowChrome;
+
+  /**
+   * The app's link to the framework that starts it (a Tauri core, an Electron
+   * main process, a script): `"stdio"` when it started this process as a
+   * sidecar and speaks JSON lines on its pipes, or a transport of its own
+   * (`utilityProcess`'s parent port, say). The component then gets a
+   * `channel` prop (`hostState`, `channel.send`), and the window closes when
+   * the link ends.
+   */
+  host?: "stdio" | Transport;
+
+  /** The app's Vite config, whose plugins should include `winuiSvelte()`; the plugin's defaults serve without one. */
+  configFile?: string;
+
+  /** Modules Node loads itself rather than Vite: an app's own native modules. */
+  isNative?: (file: string) => boolean;
+}
+
+// The window's thread is a worker that loads this package's dev-window module,
+// from source (.ts) or from the published package (.js).
+const WINDOW_MODULE = path.join(import.meta.dirname, `dev-window${path.extname(import.meta.filename)}`);
+const WORKER_SOURCE = `const { workerData } = require("node:worker_threads");
+import(workerData.moduleUrl).then(module => module.runDevWindow(workerData.data));`;
+
+// The host's transport and the window's end of a MessageChannel, joined: what
+// the host sends reaches the window, what the window sends reaches the host.
+function linkTo(host: "stdio" | Transport) {
+  const isStdio = host === "stdio";
+  if (isStdio) {
+    reserveStdout();
+  }
+
+  const transport = isStdio ? createStdioTransport() : host;
+  const link = new MessageChannel();
+  transport.listen({
+    message: frame => link.port1.postMessage(frame),
+    malformed: reason => process.stderr.write(
+      `host: malformed message: ${reason}
+`
+    ),
+    closed: () => link.port1.close()
+  });
+  link.port1.on("message", frame => transport.send(frame));
+  return link;
+}
+
+/**
+ * Opens the app in a window and keeps it live: a saved `.svelte` or `.ts`
+ * file updates the open window without a restart. It starts the Windows App
+ * SDK, a Vite dev server for the app's modules and the window's thread, so the
+ * host is one call:
+ *
+ * ```ts
+ * import { startDev } from "winui-svelte/dev";
+ *
+ * process.exitCode = await startDev({
+ *   root: import.meta.dirname,
+ *   component: "/App.svelte",
+ *   window: { title: "My app" }
+ * });
+ * ```
+ *
+ * @returns The exit code, once the window has closed and the dev server has stopped.
+ */
+export async function startDev({ component, props = {}, window = {}, host, ...serverOptions }: DevOptions) {
+  const link = host === undefined ? null : linkTo(host);
+  initWindowsAppSdk();
+  const modules = new MessageChannel();
+  const server = await startModuleServer({
+    ...serverOptions,
+    port: modules.port1
+  });
+  const data: DevWindowData = {
+    modules: modules.port2,
+    link: link?.port2 ?? null,
+    component,
+    props,
+    window
+  };
+  const worker = new Worker(WORKER_SOURCE, {
+    eval: true,
+    workerData: {
+      moduleUrl: pathToFileURL(WINDOW_MODULE).href,
+      data
+    },
+    transferList: link === null ? [modules.port2] : [modules.port2, link.port2]
+  });
+  worker.on("error", error => {
+    process.stderr.write(`${error.stack ?? String(error)}\n`);
+    process.exitCode = 1;
+  });
+  const code = await new Promise<number>(resolve => {
+    worker.on("exit", resolve);
+  });
+  await server.close();
+  return process.exitCode ?? code;
+}

package/src/enums.ts

@@ -12,6 +12,8 @@ export { XamlKind } from "./components/xaml-source.ts";
 export { FocusKind } from "./renderer/host/focus-element.ts";
 export { TrayGesture } from "./tray/click-detector.ts";
 export { TrayBalloonIcon } from "./tray/tray-core.ts";
+export { SizeToContent, WindowAnchor } from "./window/anchor.ts";
 export { Backdrop } from "./window/backdrop.ts";
 export { TitleBarHeight, WindowPresentation, WindowTheme } from "./window/chrome.ts";
+export { DockDisplay } from "./window/dock.ts";
 export { PickerLocation } from "./window/pickers.ts";

package/src/web-apis/window-geometry.ts

@@ -0,0 +1,106 @@
+import { toCssPixels, toDevicePixels } from "#src/window/css-pixels.js";
+import type { AppWindow } from "#src/winui.js";
+
+/**
+ * One window's size and place as the web's `window` has them (`outerWidth`,
+ * `outerHeight`, `screenX`, `screenY`, `devicePixelRatio`, `resizeTo`,
+ * `resizeBy`, `moveTo`, `moveBy`), in CSS pixels, over its `AppWindow`. A
+ * process holds many windows, so there is no `window` global for it; a
+ * `WindowHandle` gives each window its own (`handle.geometry`).
+ *
+ * CSS pixels are WinUI's device-independent pixels, at the window's scale.
+ */
+export class WindowGeometry {
+  private readonly appWindow: AppWindow;
+  private readonly readScale: () => number;
+
+  /** Made by `WindowHandle`. */
+  constructor(appWindow: AppWindow, readScale: () => number) {
+    this.appWindow = appWindow;
+    this.readScale = readScale;
+  }
+
+  /** Device pixels per CSS pixel. */
+  // fallow-ignore-next-line unused-class-member
+  get devicePixelRatio() {
+    return this.readScale();
+  }
+
+  /** The window's width with its frame, in CSS pixels. */
+  get outerWidth() {
+    return toCssPixels({
+      value: this.appWindow.size.width,
+      scale: this.readScale()
+    });
+  }
+
+  /** The window's height with its frame, in CSS pixels. */
+  get outerHeight() {
+    return toCssPixels({
+      value: this.appWindow.size.height,
+      scale: this.readScale()
+    });
+  }
+
+  /** The window's left edge on the desktop, in CSS pixels at this window's scale. */
+  get screenX() {
+    return toCssPixels({
+      value: this.appWindow.position.x,
+      scale: this.readScale()
+    });
+  }
+
+  /** The window's top edge on the desktop, in CSS pixels at this window's scale. */
+  get screenY() {
+    return toCssPixels({
+      value: this.appWindow.position.y,
+      scale: this.readScale()
+    });
+  }
+
+  /**
+   * Resizes the window (frame included) to `width` by `height` CSS pixels,
+   * keeping its top-left corner: `AppWindow.Resize`. A side that
+   * `sizeToContent` sets is set again by the content.
+   */
+  resizeTo(width: number, height: number) {
+    const scale = this.readScale();
+    this.appWindow.resize({
+      width: toDevicePixels({
+        value: width,
+        scale
+      }),
+      height: toDevicePixels({
+        value: height,
+        scale
+      })
+    });
+  }
+
+  /** Grows (or shrinks) the window by `width` and `height` CSS pixels. */
+  // fallow-ignore-next-line unused-class-member
+  resizeBy(width: number, height: number) {
+    this.resizeTo(this.outerWidth + width, this.outerHeight + height);
+  }
+
+  /** Puts the window's top-left corner at `x`, `y` CSS pixels on the desktop: `AppWindow.Move`. */
+  moveTo(x: number, y: number) {
+    const scale = this.readScale();
+    this.appWindow.move({
+      x: toDevicePixels({
+        value: x,
+        scale
+      }),
+      y: toDevicePixels({
+        value: y,
+        scale
+      })
+    });
+  }
+
+  /** Moves the window by `x` and `y` CSS pixels. */
+  // fallow-ignore-next-line unused-class-member
+  moveBy(x: number, y: number) {
+    this.moveTo(this.screenX + x, this.screenY + y);
+  }
+}

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);
+}