node-gtk 2.1.0 → 3.0.0

package/lib/styles.d.ts

@@ -0,0 +1,81 @@
+/*
+ * Type declarations for node-gtk/styles (see lib/styles.js).
+ *
+ * The public surface deals only in strings, URLs, and plain handles, so these
+ * types are self-contained — they don't reference the GTK typings.
+ */
+
+/** Options shared by the style sheets. */
+export interface StyleOptions {
+  /** Provider priority; defaults to `Gtk.STYLE_PROVIDER_PRIORITY_APPLICATION`. */
+  priority?: number
+}
+
+/** Options for {@link StyleManager.add}. */
+export interface StyleAddOptions extends StyleOptions {
+  /**
+   * Watch the calling module for hot-reload (defaults to on in development).
+   * Pass `false` for a programmatic sheet whose source can't be re-imported
+   * safely (built inside a method, or owned by a stateful module); the handle
+   * still supports `update`/`refresh`/`remove`.
+   */
+  watch?: boolean
+}
+
+/** Options for {@link StyleManager.addFile}. */
+export interface StyleFileOptions extends StyleOptions {
+  /** Watch the file for hot-reload (defaults to on in development). */
+  watch?: boolean
+}
+
+/** A handle to an installed (or queued) stylesheet. */
+export interface StyleSheet {
+  /**
+   * Replace the CSS (or, for a file sheet, re-read the path) in place. For an
+   * inline sheet a string replaces any render function — it becomes fixed CSS.
+   */
+  update(next: string): void
+  /**
+   * Re-apply the sheet from its current source: re-run the render function
+   * (inline) or re-read the path (file). Call it when the state a render reads
+   * changes. A no-op for a queued sheet (not yet installed).
+   */
+  refresh(): void
+  /** Remove the sheet from the display. */
+  remove(): void
+}
+
+/**
+ * Applies CSS to a GTK app and, in development, hot-reloads it. The module
+ * exports a shared {@link styles} instance; constructing your own is rarely
+ * needed.
+ */
+export declare class StyleManager {
+  /**
+   * Queue (or, once the display exists, install) inline CSS. The source file it
+   * is called from is watched for hot-reload (unless `watch` is false).
+   *
+   * `css` may be a `() => string` *render* function instead of a string, for a
+   * dynamic stylesheet built from live state (theme, fonts, …). The render runs
+   * now and again on every hot-reload of its module, and on demand via the
+   * handle's {@link StyleSheet.refresh}. Keep such a module side-effect-free at
+   * its top level (a re-import re-runs it).
+   */
+  add(css: string | (() => string), options?: StyleAddOptions): StyleSheet
+
+  /**
+   * Queue (or install) a `.css` file. Unless `watch` is false, the file is
+   * watched and re-read into its provider on every edit. Idempotent per path.
+   * @param path A path, a `file://` URL string, or a `URL`.
+   */
+  addFile(path: string | URL, options?: StyleFileOptions): StyleSheet
+
+  /**
+   * Install everything queued before the display existed, and start the file
+   * watcher. Call once from your `activate` handler. Safe to call repeatedly.
+   */
+  install(): void
+}
+
+/** The application's shared StyleManager. */
+export declare const styles: StyleManager

package/lib/styles.js

@@ -0,0 +1,428 @@
+/*
+ * styles.js — a small StyleManager for node-gtk apps. Applies CSS (inline via
+ * styles.add, a `.css` file via styles.addFile) and hot-reloads it in
+ * development. Adapted from zym's style-manager; see doc/styles.md.
+ */
+
+const Path = require('node:path')
+const { pathToFileURL, fileURLToPath } = require('node:url')
+
+const internal = require('./native.js')
+const Module = require('./module.js')
+
+// Lazily resolved: the app loads Gtk/Gdk/GLib/Gio, not this module. GLib/Gio
+// drive hot-reload (watchDir) and arrive with Gtk.
+const moduleCache = internal.GetModuleCache()
+const gtk = () => Module.require('Gtk')
+const gdk = () => Module.require('Gdk')
+const glib = () => Module.require('GLib')
+const gio = () => Module.require('Gio')
+
+// Dev-only; opt out with a falsy NODE_GTK_STYLE_HOT_RELOAD (0/false/no/off).
+const HOT_RELOAD =
+  process.env.NODE_ENV === 'development' &&
+  !/^(0|false|no|off)$/i.test(process.env.NODE_GTK_STYLE_HOT_RELOAD ?? '')
+
+const OWN_FILE = __filename // skipped during caller detection
+
+const DEBOUNCE_MS = 40 // coalesce the burst an editor's atomic save emits
+
+function defaultPriority() {
+  return gtk().STYLE_PROVIDER_PRIORITY_APPLICATION ?? 600
+}
+
+/** The default display, or null before it exists (e.g. before app activation). */
+function defaultDisplay() {
+  if (!moduleCache['Gdk']) return null // don't force-load Gdk just to ask
+  return gdk().Display.getDefault()
+}
+
+/** Normalise a path / `file:` URL string / URL to an absolute path. */
+function toPath(p) {
+  if (p instanceof URL) return fileURLToPath(p)
+  if (typeof p === 'string' && p.startsWith('file:')) return fileURLToPath(p)
+  return Path.resolve(p)
+}
+
+function loadCss(provider, css) {
+  // loadFromString is GTK 4.12+; fall back on older 4.x.
+  if (typeof provider.loadFromString === 'function') provider.loadFromString(css)
+  else provider.loadFromData(css)
+}
+
+/** Local path of a GFile from a monitor event, or null. GFile is a GInterface,
+ *  so its methods live on the prototype, not the instance. */
+function gioPath(file) {
+  if (!file) return null
+  try { return gio().File.prototype.getPath.call(file) } catch { return null }
+}
+
+/** Absolute path of the first source file above this module on the stack. */
+function callerFile() {
+  const stack = new Error().stack
+  if (!stack) return null
+  for (const line of stack.split('\n').slice(1)) {
+    const file = frameFile(line)
+    if (file && file !== OWN_FILE) return file
+  }
+  return null
+}
+
+/** Pull the absolute file path out of one V8 stack frame, or null. */
+function frameFile(frame) {
+  // Matches "(file:line:col)", bare "at file:line:col", and the "at async
+  // file:..." form V8 uses for top-level ESM code.
+  const m = frame.match(/\(([^()]+):\d+:\d+\)\s*$/) || frame.match(/\bat\s+(?:async\s+)?([^()\s]+):\d+:\d+\s*$/)
+  if (!m) return null
+  let loc = m[1]
+  const q = loc.indexOf('?') // drop the cache-buster query, if any
+  if (q !== -1) loc = loc.slice(0, q)
+  if (loc.startsWith('file://')) {
+    try { return Path.resolve(fileURLToPath(loc)) } catch { return null }
+  }
+  if (loc.startsWith('node:') || loc.includes('node_modules')) return null
+  return Path.resolve(loc)
+}
+
+/**
+ * A handle to an installed (or queued) stylesheet.
+ * @typedef {object} StyleSheet
+ * @property {(next: string) => void} update   Replace with fixed CSS (drops any render fn).
+ * @property {() => void} refresh              Re-apply from source (re-run render / re-read file).
+ * @property {() => void} remove               Remove the sheet from the display.
+ */
+
+class StyleManager {
+  constructor() {
+    this.ready = false
+    this.queued = [] // entries awaiting the display
+
+    // File sheets by path, for per-path dedup and reload. path -> Set<entry>.
+    this.cssEntries = new Map()
+
+    // ---- Hot-reload state (only used when HOT_RELOAD is on) ----
+    this.fileProviders = new Map() // srcFile -> Set<provider>, so a reload drops the old
+    this.watchedFiles = new Set()
+    this.dirWatchers = new Map() // dir -> Gio.FileMonitor
+    this.reloadSeq = 0
+    this.reloadTimers = new Map()
+    this.reloading = new Set()
+    this.reloadPending = new Set()
+  }
+
+  /**
+   * Inline CSS, hot-reloaded by re-importing its source module. Queued until the
+   * display exists.
+   *
+   * `css` may be a `() => string` *render* function instead of a string, for
+   * dynamic stylesheets built from live state (theme, fonts, …). The render runs
+   * now and again on every hot-reload of its module (so editing the
+   * CSS-generating code re-applies it), and on demand via the handle's
+   * `refresh()` — call it whenever the state it reads changes. Keep such a module
+   * side-effect-free at its top level (a re-import re-runs it); a stateful
+   * singleton it owns must survive re-import (e.g. guarded on `globalThis`).
+   *
+   * Pass `watch: false` to install without watching the caller for hot-reload —
+   * for programmatic sheets whose source can't be re-imported safely (created
+   * inside a method, owned by a stateful module). The handle still supports
+   * `update`/`refresh`/`remove`.
+   * @param {string | (() => string)} css  Inline CSS, or a render function.
+   * @param {{ priority?: number, watch?: boolean }} [options]
+   * @returns {StyleSheet}
+   */
+  add(css, options = {}) {
+    const render = typeof css === 'function' ? css : null
+    const watch = HOT_RELOAD && (options.watch ?? true)
+    const file = watch ? callerFile() : null
+    const entry = {
+      kind: 'inline',
+      render,
+      css: render ? null : css,
+      file,
+      priority: options.priority,
+      provider: null,
+      cancelled: false,
+    }
+    this.place(entry)
+    if (file) this.watch(file)
+    return this.handle(entry)
+  }
+
+  /**
+   * A `.css` file, hot-reloaded by re-reading it (unless `watch` is false).
+   * Idempotent per path.
+   * @param {string|URL} path  A path, a `file://` URL string, or a URL.
+   * @param {{ priority?: number, watch?: boolean }} [options]
+   * @returns {StyleSheet}
+   */
+  addFile(path, options = {}) {
+    const file = toPath(path)
+    const existing = this.cssEntries.get(file)
+    if (existing && existing.size) {
+      // Refresh the existing sheet rather than stacking a second provider.
+      const entry = existing.values().next().value
+      if (entry.provider) entry.provider.loadFromPath(file)
+      return this.handle(entry)
+    }
+    const watch = options.watch ?? HOT_RELOAD
+    const entry = { kind: 'file', path: file, priority: options.priority, provider: null, cancelled: false, watch }
+    this.trackCssEntry(entry) // register by path now, so re-adds dedup even in production
+    this.place(entry)
+    if (watch) this.watch(file)
+    return this.handle(entry)
+  }
+
+  /**
+   * Install everything queued before the display existed, and start watching.
+   * Call once from your `activate` handler. Safe to call more than once.
+   */
+  install() {
+    if (this.ready) return
+    // Before the display exists, providers would never be shown — fail loudly
+    // rather than silently drop them. (place()'s auto-flush only runs once a
+    // display exists, so it never trips this.)
+    if (!defaultDisplay())
+      throw new Error('styles.install() called before the display exists — call it from your app\'s "activate" handler')
+    this.ready = true
+    const pending = this.queued
+    this.queued = []
+    for (const entry of pending) this.installEntry(entry)
+    if (HOT_RELOAD) this.startWatcher()
+  }
+
+  // -------------------------------------------------------------------------
+  // installation
+  // -------------------------------------------------------------------------
+
+  place(entry) {
+    if (!this.ready && defaultDisplay()) this.install() // auto-flush on first post-display call
+    if (this.ready) this.installEntry(entry)
+    else this.queued.push(entry)
+  }
+
+  installEntry(entry) {
+    if (entry.cancelled) return
+    if (entry.kind === 'file') {
+      const provider = this.newProvider()
+      provider.loadFromPath(entry.path)
+      this.addProvider(provider, entry.priority)
+      entry.provider = provider
+    } else {
+      const provider = this.newProvider()
+      loadCss(provider, entry.render ? entry.render() : entry.css)
+      this.addProvider(provider, entry.priority)
+      entry.provider = provider
+      if (entry.file) this.trackFileProvider(entry.file, provider)
+    }
+  }
+
+  newProvider() {
+    const provider = new (gtk().CssProvider)()
+    // Surface parse errors with a friendly line instead of a bare GTK critical.
+    try {
+      provider.on('parsing-error', (section, error) => {
+        let message = 'CSS parse error'
+        try { if (error && error.message) message += `: ${error.message}` } catch {}
+        console.warn(`[node-gtk:styles] ${message}`)
+      })
+    } catch {}
+    return provider
+  }
+
+  addProvider(provider, priority) {
+    const display = defaultDisplay()
+    if (display) gtk().StyleContext.addProviderForDisplay(display, provider, priority ?? defaultPriority())
+  }
+
+  removeProvider(provider) {
+    const display = defaultDisplay()
+    if (display) gtk().StyleContext.removeProviderForDisplay(display, provider)
+  }
+
+  // -------------------------------------------------------------------------
+  // handles
+  // -------------------------------------------------------------------------
+
+  handle(entry) {
+    return {
+      update: (next) => {
+        if (entry.kind === 'file') {
+          const nextPath = toPath(next)
+          if (nextPath !== entry.path) {
+            // Re-key tracking + watching to the new path.
+            this.untrackCssEntry(entry)
+            entry.path = nextPath
+            this.trackCssEntry(entry)
+            if (entry.watch) this.watch(nextPath)
+          }
+          if (entry.provider) entry.provider.loadFromPath(entry.path)
+        } else {
+          // A literal replaces a render function: from now on this is fixed CSS.
+          entry.render = null
+          entry.css = next
+          if (entry.provider) loadCss(entry.provider, next)
+        }
+      },
+      // Re-apply the sheet from its current source: re-run the render function
+      // (inline) or re-read the path (file). For a fixed-string inline sheet this
+      // just re-loads the same CSS. Use it when the state a render reads changes.
+      refresh: () => {
+        if (!entry.provider) return
+        if (entry.kind === 'file') entry.provider.loadFromPath(entry.path)
+        else loadCss(entry.provider, entry.render ? entry.render() : entry.css)
+      },
+      remove: () => {
+        if (entry.cancelled) return
+        entry.cancelled = true
+        if (entry.provider) this.removeProvider(entry.provider)
+        if (entry.kind === 'file') this.untrackCssEntry(entry)
+        else this.untrackFileProvider(entry)
+      },
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // hot-reload (dev only)
+  // -------------------------------------------------------------------------
+
+  trackFileProvider(file, provider) {
+    let set = this.fileProviders.get(file)
+    if (!set) this.fileProviders.set(file, (set = new Set()))
+    set.add(provider)
+  }
+
+  trackCssEntry(entry) {
+    let set = this.cssEntries.get(entry.path)
+    if (!set) this.cssEntries.set(entry.path, (set = new Set()))
+    set.add(entry)
+  }
+
+  // When the last sheet for a path is removed, stop watching it — otherwise a
+  // later edit would be misrouted through reloadModule and import() the .css.
+  untrackCssEntry(entry) {
+    const set = this.cssEntries.get(entry.path)
+    if (!set) return
+    set.delete(entry)
+    if (set.size === 0) {
+      this.cssEntries.delete(entry.path)
+      this.unwatch(entry.path)
+    }
+  }
+
+  // Drop the provider so the next module reload doesn't re-remove it. Keep
+  // watching: re-running the module re-installs its add() calls.
+  untrackFileProvider(entry) {
+    if (!entry.file || !entry.provider) return
+    this.fileProviders.get(entry.file)?.delete(entry.provider)
+  }
+
+  watch(file) {
+    if (this.watchedFiles.has(file)) return
+    this.watchedFiles.add(file)
+    if (this.ready) this.watchDir(Path.dirname(file)) // else startWatcher picks it up
+  }
+
+  // Stop watching a file; cancel the directory monitor once its last file goes.
+  unwatch(file) {
+    if (!this.watchedFiles.delete(file)) return
+    const timer = this.reloadTimers.get(file)
+    if (timer) { glib().sourceRemove(timer); this.reloadTimers.delete(file) }
+    const dir = Path.dirname(file)
+    for (const f of this.watchedFiles) if (Path.dirname(f) === dir) return
+    const monitor = this.dirWatchers.get(dir)
+    if (monitor) { try { monitor.cancel() } catch {} ; this.dirWatchers.delete(dir) }
+  }
+
+  startWatcher() {
+    for (const file of this.watchedFiles) this.watchDir(Path.dirname(file))
+  }
+
+  // Watch with a GLib GFileMonitor, not node's fs.watch: it is driven by the
+  // GLib loop the app already runs (an fs.watch, a libuv handle, silently stops
+  // firing once that loop is the only one running) and it does not keep Node
+  // alive on exit. We watch the directory, not the file, so atomic-save renames
+  // survive — WATCH_MOVES surfaces them.
+  watchDir(dir) {
+    if (this.dirWatchers.has(dir)) return
+    let monitor
+    try {
+      const Gio = gio()
+      const gfile = Gio.File.newForPath(dir)
+      // GFile is a GInterface: its methods live on the prototype, not the instance.
+      monitor = Gio.File.prototype.monitorDirectory.call(gfile, Gio.FileMonitorFlags.WATCH_MOVES, null)
+    } catch {
+      return // Gio unavailable / monitor failed — hot-reload just won't fire
+    }
+    monitor.on('changed', (file, otherFile) => {
+      // Map the event back to a watched file (a rename's target is in otherFile);
+      // if neither matches, re-check the dir's files — the debounce coalesces.
+      const a = gioPath(file)
+      const b = gioPath(otherFile)
+      if (a && this.watchedFiles.has(a)) this.onFileChanged(a)
+      else if (b && this.watchedFiles.has(b)) this.onFileChanged(b)
+      else for (const f of this.watchedFiles) if (Path.dirname(f) === dir) this.onFileChanged(f)
+    })
+    this.dirWatchers.set(dir, monitor)
+  }
+
+  // GLib timeout, not setTimeout, so the debounce is loop-driven too.
+  onFileChanged(file) {
+    const pending = this.reloadTimers.get(file)
+    if (pending) glib().sourceRemove(pending)
+    this.reloadTimers.set(file, glib().timeoutAdd(0, DEBOUNCE_MS, () => {
+      this.reloadTimers.delete(file)
+      void this.reloadFile(file)
+      return false // GLib.SOURCE_REMOVE
+    }))
+  }
+
+  async reloadFile(file) {
+    // Dispatch by which registry the file is in; one in neither (e.g. its sheets
+    // were removed) is ignored, so a stray .css edit is never import()ed.
+    const cssEntries = this.cssEntries.get(file)
+    if (cssEntries && cssEntries.size) {
+      for (const entry of cssEntries) {
+        if (entry.provider) {
+          try { entry.provider.loadFromPath(file) } catch {}
+        }
+      }
+      console.info(`[node-gtk:styles] reloaded ${Path.relative(process.cwd(), file)}`)
+      return
+    }
+    if (this.fileProviders.has(file)) await this.reloadModule(file)
+  }
+
+  /**
+   * Re-import a source module (cache-busted) so its add() calls reinstall the
+   * new CSS, then drop the previous run's providers — new sheets up before old
+   * come down. A load error rolls back to the previously working sheets.
+   */
+  async reloadModule(file) {
+    if (this.reloading.has(file)) { this.reloadPending.add(file); return }
+    this.reloading.add(file)
+
+    const previous = this.fileProviders.get(file) ?? new Set()
+    const fresh = new Set()
+    this.fileProviders.set(file, fresh) // the re-run's tracking collects into here
+    try {
+      await import(`${pathToFileURL(file).href}?node-gtk-style=${++this.reloadSeq}`)
+      for (const provider of previous) this.removeProvider(provider)
+      console.info(`[node-gtk:styles] reloaded ${Path.relative(process.cwd(), file)}`)
+    } catch (error) {
+      for (const provider of fresh) this.removeProvider(provider)
+      this.fileProviders.set(file, previous) // keep the working sheets installed
+      const message = error instanceof Error ? error.message : String(error)
+      console.warn(`[node-gtk:styles] hot-reload failed for ${Path.relative(process.cwd(), file)}: ${message}`)
+    } finally {
+      this.reloading.delete(file)
+      if (this.reloadPending.delete(file)) void this.reloadModule(file)
+    }
+  }
+}
+
+const styles = new StyleManager()
+
+module.exports = {
+  StyleManager,
+  styles,
+}

package/package.json

@@ -1,8 +1,22 @@
 {
   "name": "node-gtk",
-  "version": "2.1.0",
+  "version": "3.0.0",
   "description": "GNOME Gtk+ bindings for NodeJS",
   "main": "lib/index.js",
+  "exports": {
+    ".": {
+      "import": "./lib/index.mjs",
+      "require": "./lib/index.js"
+    },
+    "./register": "./lib/esm/register.mjs",
+    "./hooks": "./lib/esm/hooks.mjs",
+    "./styles": {
+      "types": "./lib/styles.d.ts",
+      "default": "./lib/styles.js"
+    },
+    "./package.json": "./package.json",
+    "./*": "./*"
+  },
   "bin": {
     "node-gtk": "bin/node-gtk.js"
   },