@quickgui/native 0.0.1

package/dialog.ts

@@ -0,0 +1,176 @@
+import { statSync } from "node:fs";
+import { basename, dirname, resolve, sep } from "node:path";
+import * as binding from "./binding.js";
+
+export type AlertDialogLevel = "info" | "warning" | "critical";
+export type AlertDialogButtonRole = "default" | "cancel" | "other";
+
+export interface AlertDialogButton {
+  label: string;
+  role?: AlertDialogButtonRole;
+}
+
+export interface AlertDialogOptions {
+  level?: AlertDialogLevel;
+  message: string;
+  detail?: string;
+  /**
+   * Defaults to one system-styled OK button. macOS accepts up to 16 buttons; the portable
+   * Windows/Linux/BSD backend accepts up to three uniquely labelled buttons.
+   */
+  buttons?: readonly (string | AlertDialogButton)[];
+}
+
+export type OpenDialogProperty =
+  | "openFile"
+  | "openDirectory"
+  | "multiSelections"
+  | "showHiddenFiles";
+
+export interface FileDialogFilter {
+  name: string;
+  /** File extensions without a leading dot. Use `*` to match every file. */
+  extensions: readonly string[];
+}
+
+export interface OpenDialogOptions {
+  title?: string;
+  /** Initial file or directory. */
+  defaultPath?: string;
+  filters?: readonly FileDialogFilter[];
+  /** Custom open-button text. Currently supported by the macOS backend. */
+  buttonLabel?: string;
+  /**
+   * Defaults to `["openFile"]`. `showHiddenFiles` can currently be forced only on macOS;
+   * Windows/Linux otherwise follow the user's file-picker preference.
+   */
+  properties?: readonly OpenDialogProperty[];
+}
+
+export interface OpenDialogResult {
+  canceled: boolean;
+  filePaths: string[];
+}
+
+export interface SaveDialogOptions {
+  title?: string;
+  /** Initial directory or complete suggested file path. */
+  defaultPath?: string;
+  filters?: readonly FileDialogFilter[];
+  /** Custom save-button text. Currently supported by the macOS backend. */
+  buttonLabel?: string;
+  /** Currently supported by the macOS backend. */
+  showHiddenFiles?: boolean;
+}
+
+export interface SaveDialogResult {
+  canceled: boolean;
+  filePath?: string;
+}
+
+export function normalizeAlertDialogOptions(
+  options: AlertDialogOptions,
+): binding.NativeDialogOptions {
+  const normalized: binding.NativeDialogOptions = {
+    message: options.message,
+    buttons: (options.buttons ?? [{ label: "OK", role: "default" }]).map((button) => {
+      if (typeof button === "string") return { label: button };
+      const normalizedButton: binding.NativeDialogButton = { label: button.label };
+      if (button.role !== undefined) normalizedButton.role = button.role;
+      return normalizedButton;
+    }),
+  };
+  if (options.level !== undefined) normalized.level = options.level;
+  if (options.detail !== undefined) normalized.detail = options.detail;
+  return normalized;
+}
+
+export function normalizeOpenDialogOptions(
+  options: OpenDialogOptions,
+): binding.NativeOpenDialogOptions {
+  const properties = new Set(options.properties ?? ["openFile"]);
+  const files = properties.has("openFile");
+  const directories = properties.has("openDirectory");
+  if (!files && !directories) {
+    throw new TypeError("showOpenDialog properties must include openFile or openDirectory");
+  }
+  if (files && directories && process.platform !== "darwin") {
+    throw new TypeError(
+      "showOpenDialog cannot combine openFile and openDirectory on this platform",
+    );
+  }
+  const normalized: binding.NativeOpenDialogOptions = {
+    files,
+    directories,
+    multiple: properties.has("multiSelections"),
+    filters: normalizeFileDialogFilters(options.filters),
+    showsHiddenFiles: properties.has("showHiddenFiles"),
+  };
+  if (options.title !== undefined) normalized.title = options.title;
+  if (options.buttonLabel !== undefined) normalized.prompt = options.buttonLabel;
+  if (options.defaultPath !== undefined) {
+    const defaultPath = resolve(options.defaultPath);
+    if (options.defaultPath.endsWith(sep) || isExistingDirectory(defaultPath)) {
+      normalized.directory = defaultPath;
+    } else {
+      normalized.directory = dirname(defaultPath);
+      normalized.suggestedName = basename(defaultPath);
+    }
+  }
+  return normalized;
+}
+
+export function normalizeSaveDialogOptions(
+  options: SaveDialogOptions,
+): binding.NativeSaveDialogOptions {
+  const normalized: binding.NativeSaveDialogOptions = {
+    directory: process.cwd(),
+    filters: normalizeFileDialogFilters(options.filters),
+    showsHiddenFiles: options.showHiddenFiles ?? false,
+  };
+  if (options.title !== undefined) normalized.title = options.title;
+  if (options.buttonLabel !== undefined) normalized.prompt = options.buttonLabel;
+  if (options.defaultPath !== undefined) {
+    const defaultPath = resolve(options.defaultPath);
+    if (options.defaultPath.endsWith(sep) || isExistingDirectory(defaultPath)) {
+      normalized.directory = defaultPath;
+    } else {
+      normalized.directory = dirname(defaultPath);
+      normalized.suggestedName = basename(defaultPath);
+    }
+  }
+  return normalized;
+}
+
+function normalizeFileDialogFilters(
+  filters: readonly FileDialogFilter[] | undefined,
+): binding.NativeFileDialogFilter[] {
+  return (filters ?? []).map((filter) => {
+    if (filter.name.length === 0 || filter.extensions.length === 0) {
+      throw new TypeError("file dialog filters require a name and at least one extension");
+    }
+    const extensions = filter.extensions.map((extension) => {
+      if (
+        extension.length === 0 ||
+        extension.startsWith(".") ||
+        extension.includes("\0") ||
+        extension.includes("/") ||
+        extension.includes("\\")
+      ) {
+        throw new TypeError(
+          "file dialog filter extensions must be nonempty and omit dots and path separators",
+        );
+      }
+      return extension;
+    });
+    return { name: filter.name, extensions };
+  });
+}
+
+function isExistingDirectory(path: string): boolean {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}

package/host.ts

@@ -0,0 +1,58 @@
+import * as binding from "./binding.js";
+
+const WORKER_ENV = "QUICKGUI_APP_WORKER";
+const WORKER_READY = "quickgui:worker-ready";
+
+/**
+ * Start the application Bun isolate, then permanently hand the process main thread to AppKit.
+ * Application code stays on Bun's supported Worker event loop; the native host sleeps until either
+ * Winit or the worker posts bounded work.
+ */
+export async function runApplicationWorker(entrypoint: string): Promise<number> {
+  if (!Bun.isMainThread) {
+    throw new Error("the QuickGUI native host must run on Bun's process main thread");
+  }
+
+  const worker = new Worker(entrypoint, {
+    name: "quickgui-app",
+    env: { ...process.env, [WORKER_ENV]: "1" },
+  });
+  await waitForWorkerReady(worker);
+  const onReady = developmentReadyCallback();
+  return binding.runAppHost(onReady);
+}
+
+/** Report an application-worker startup failure while the main thread is blocked in AppKit. */
+export function reportWorkerFailure(error: unknown): void {
+  const message =
+    error instanceof Error ? (error.stack ?? error.message) : `QuickGUI worker failed: ${String(error)}`;
+  binding.abortAppHost(message);
+}
+
+function waitForWorkerReady(worker: Worker): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const ready = (event: MessageEvent): void => {
+      if (event.data !== WORKER_READY) return;
+      worker.removeEventListener("error", failed);
+      worker.removeEventListener("message", ready);
+      resolve();
+    };
+    const failed = (event: ErrorEvent): void => {
+      worker.removeEventListener("message", ready);
+      reject(new Error(event.message || "QuickGUI application worker failed to start"));
+    };
+    worker.addEventListener("message", ready);
+    worker.addEventListener("error", failed, { once: true });
+  });
+}
+
+function developmentReadyCallback(): (() => void) | undefined {
+  if (process.env.QUICKGUI_DEV !== "1" || typeof process.send !== "function") return undefined;
+  return () => {
+    try {
+      process.send?.({ type: "quickgui-ready" });
+    } catch {
+      // The CLI may have exited while the native window was being presented.
+    }
+  };
+}