quicklook-kit 0.5.0 → 0.7.0

package/dist/config.d.mts

@@ -1,5 +1,4 @@
 import { Plugin } from "vite";
-//#region src/config.d.ts
 /** An existing type id such as "public.json", or a new type the app declares. */
 export type FileType = string | DeclaredType;
 /** A file type the app declares itself, as a UTExportedTypeDeclaration. */
@@ -13,6 +12,41 @@ export interface DeclaredType {
 export type Csp = Partial<Record<string, string[]>>;
 /** The xcodegen project spec, written as project.yml. */
 export type XcodeSpec = Record<string, any>;
+/** An `enum` entry: a plain value, or one with a label for the picker. */
+export type EnumEntry<T> = T | {
+  value: T;
+  description?: string;
+};
+interface BaseSetting {
+  /** Defaults to the key, turned into words (`fontSize` → "Font Size"). */
+  title?: string;
+  /** Inline Markdown. */
+  description?: string;
+  order?: number;
+}
+/**
+ * A user-editable setting. The type decides the control the app shows; the
+ * page gets the resolved values from `settings()`.
+ */
+export type Setting = (BaseSetting & {
+  type: 'boolean';
+  default: boolean;
+}) | (BaseSetting & {
+  type: 'string';
+  default: string;
+  enum?: EnumEntry<string>[];
+  radio?: boolean;
+}) | (BaseSetting & {
+  type: 'integer' | 'number';
+  default: number;
+  enum?: EnumEntry<number>[];
+  radio?: boolean;
+  minimum?: number;
+  maximum?: number;
+}) | (BaseSetting & {
+  type: 'object';
+  properties: Record<string, Setting>;
+});
 export interface Integration {
   name: string;
   /** Set by frameworks only: how to run and build the page, and where it lands. */
@@ -41,15 +75,27 @@ export interface Integration {
  * either an integration or a function that takes the options and returns one.
  */
 export type IntegrationRef = Integration | string | [name: string, options?: unknown];
-export interface QuickLookConfig {
-  /** App name, shown in Finder and System Settings. */
-  name: string;
+/** Builds a Quick Look extension for macOS. */
+export interface MacosConfig {
   bundleId: string;
   /** Path to the app's .icns icon, relative to the project root. */
   icon?: string;
-  /** Minimum macOS version. Defaults to 14.0. */
-  macOS?: string;
+  /** Defaults to 14.0. */
+  minimumVersion?: string;
   types: FileType[];
+}
+/** Builds a plugin for QuickLook on Windows. */
+export interface WindowsConfig {
+  /** The plugin's namespace and assembly name, e.g. `QuickLook.Plugin.Example`. */
+  id: string;
+  /** Extensions to preview, without the dot. */
+  extensions: string[];
+}
+export interface QuickLookConfig {
+  /** App name, shown in Finder and System Settings. */
+  name: string;
+  macos?: MacosConfig;
+  windows?: WindowsConfig;
   /** `sveltekit`, `astro`, `solid-start`, `nuxt`, `analog`, or any integration that sets `build`. */
   framework: IntegrationRef;
   integrations?: IntegrationRef[];
@@ -59,11 +105,20 @@ export interface QuickLookConfig {
   maxFileSize?: number;
   /** Exposed to the page as `config.public` from `virtual:quicklook`. */
   public?: Record<string, unknown>;
+  /** Settings the user edits in the app, read on the page with `settings()`. */
+  settings?: Record<string, Setting>;
+  /** A file the dev server previews until one is dropped, relative to the project root. */
+  devFile?: string;
 }
 /** What the page sees as `config` from `virtual:quicklook`. */
-export type PageConfig = Pick<ResolvedConfig, 'name' | 'bundleId' | 'types' | 'public'>;
-export interface ResolvedConfig extends Required<Omit<QuickLookConfig, 'framework' | 'integrations' | 'icon'>>, Pick<QuickLookConfig, 'icon'> {
+export type PageConfig = Pick<ResolvedConfig, 'name' | 'public'> & {
+  macos?: Pick<MacosConfig, 'bundleId' | 'types'>;
+};
+export interface ResolvedConfig extends Required<Omit<QuickLookConfig, 'framework' | 'integrations' | 'macos' | 'windows' | 'devFile'>>, Pick<QuickLookConfig, 'windows' | 'devFile'> {
   root: string;
+  macos?: MacosConfig & {
+    minimumVersion: string;
+  };
   framework: Integration & {
     build: NonNullable<Integration['build']>;
   };
@@ -77,4 +132,4 @@ export declare const serializeCsp: (csp: Csp) => string;
 /** `csp` with `sources` appended to `directive`. */
 export declare const addSources: (csp: Csp, directive: string, ...sources: string[]) => Csp;
 export declare function loadConfig(root?: string): Promise<ResolvedConfig>;
-//#endregion
+export {};

package/dist/config.mjs

@@ -1 +1 @@
-export { t as addSources, n as defaultCsp, r as defineConfig, i as loadConfig, a as serializeCsp } from "./config-BQ-9qYNV.mjs";
+export { t as addSources, n as defaultCsp, r as defineConfig, i as loadConfig, a as serializeCsp } from "./config-qdxXRvMf.mjs";

package/dist/runtime.d.mts

@@ -1,4 +1,3 @@
-//#region src/runtime.d.ts
 /** The file Quick Look asked to preview. */
 export interface QuickLookFile {
   name: string;
@@ -13,11 +12,12 @@ declare global {
       name: string;
       extension: string;
       base64: string;
+      /** Present when the config declares `settings`. */
+      settings?: Record<string, unknown>;
     };
   }
 }
 /** The previewed file inside Quick Look; `undefined` in the browser. */
 export declare function nativeFile(): QuickLookFile | undefined;
 /** The same shape from a file picked or dropped in the browser, for the dev server. */
-export declare function browserFile(file: File): Promise<QuickLookFile>;
-//#endregion
+export declare function browserFile(file: File): Promise<QuickLookFile>;

package/dist/runtime.mjs

@@ -1,4 +1,4 @@
-//#region src/runtime.ts
+// src/runtime.ts
 /** The previewed file inside Quick Look; `undefined` in the browser. */
 function nativeFile() {
 	const injected = window.quicklook;
@@ -17,5 +17,4 @@ async function browserFile(file) {
 		bytes: new Uint8Array(await file.arrayBuffer())
 	};
 }
-//#endregion
 export { browserFile, nativeFile };

package/dist/vite.d.mts

@@ -1,8 +1,6 @@
 import { Plugin } from "vite";
-//#region src/vite.d.ts
 /**
  * Provides `virtual:quicklook`, adds the integrations' Vite plugins, and makes
  * the dev server report what the extension's CSP would block.
  */
-export declare function quicklook(): Promise<Plugin[]>;
-//#endregion
+export declare function quicklook(): Promise<Plugin[]>;

package/dist/vite.mjs

@@ -1,26 +1,50 @@
-import { a as serializeCsp, i as loadConfig, t as addSources } from "./config-BQ-9qYNV.mjs";
-//#region src/vite.ts
+import { a as serializeCsp, i as loadConfig, t as addSources } from "./config-qdxXRvMf.mjs";
+import { readFile } from "node:fs/promises";
+import { basename, extname, resolve } from "node:path";
+// src/vite.ts
 const virtualId = "virtual:quicklook";
+/** The schema's defaults as nested objects, the shape the extension injects. */
+function settingDefaults(settings) {
+	return Object.fromEntries(Object.entries(settings).map(([key, setting]) => [key, setting.type === "object" ? settingDefaults(setting.properties) : setting.default]));
+}
 /**
 * Provides `virtual:quicklook`, adds the integrations' Vite plugins, and makes
 * the dev server report what the extension's CSP would block.
 */
 async function quicklook() {
 	const config = await loadConfig();
-	const { name, bundleId, types } = config;
+	const { name, macos } = config;
 	const pageConfig = {
 		name,
-		bundleId,
-		types,
-		public: config.public
+		public: config.public,
+		...macos && { macos: {
+			bundleId: macos.bundleId,
+			types: macos.types
+		} }
 	};
 	const virtualSource = `export const config = ${JSON.stringify(pageConfig)};
-export { browserFile, nativeFile } from 'quicklook-kit/runtime';`;
+export { browserFile, nativeFile } from 'quicklook-kit/runtime';
+// The injected values in Quick Look, the defaults in the dev server and when prerendering.
+export const settings = () => globalThis.window?.quicklook?.settings ?? ${JSON.stringify(settingDefaults(config.settings))};`;
 	const devCsp = serializeCsp(addSources(addSources(config.csp, "script-src", "'unsafe-inline'"), "connect-src", "'self'", "ws:"));
+	let serve = false;
 	return [{
 		name: "quicklook",
+		config: (_, { command }) => {
+			serve = command === "serve";
+		},
 		resolveId: (source) => source === virtualId ? `\0${virtualId}` : void 0,
-		load: (source) => source === `\0${virtualId}` ? virtualSource : void 0,
+		async load(source) {
+			if (source !== `\0${virtualId}`) return;
+			if (!(serve && config.devFile)) return virtualSource;
+			const path = resolve(config.root, config.devFile);
+			const file = {
+				name: basename(path),
+				extension: extname(path).slice(1).toLowerCase(),
+				base64: (await readFile(path)).toString("base64")
+			};
+			return `if (globalThis.window && !window.quicklook) window.quicklook = ${JSON.stringify(file)};\n${virtualSource}`;
+		},
 		configureServer(server) {
 			server.middlewares.use((_request, response, next) => {
 				response.setHeader("Content-Security-Policy-Report-Only", devCsp);
@@ -29,5 +53,4 @@ export { browserFile, nativeFile } from 'quicklook-kit/runtime';`;
 		}
 	}, ...config.integrations.flatMap((integration) => integration.hooks?.vite?.() ?? [])];
 }
-//#endregion
 export { quicklook };

package/native/App/HostApp.swift

@@ -8,16 +8,237 @@ import UniformTypeIdentifiers
 struct HostApp: App {
   private let name = Bundle.main.object(forInfoDictionaryKey: "CFBundleName") as? String ?? ""
 
+  private let specs = SettingSpec.load()
+
   var body: some Scene {
     Window(name, id: "main") {
-      ContentView(name: name)
-        .padding(32)
+      if specs.isEmpty {
+        ContentView(name: name)
+          .padding([.horizontal, .top], 32)
+          // Matches the gap above the footer.
+          .padding(.bottom, 16)
+          .fixedSize()
+      } else {
+        TabView {
+          ContentView(name: name)
+            .padding([.horizontal, .top], 32)
+            // Matches the gap above the footer.
+            .padding(.bottom, 16)
+            .tabItem { Text("General") }
+          VStack(spacing: 16) {
+            ScrollView {
+              VStack(alignment: .leading, spacing: 20) {
+                ForEach(specs, id: \.key) { SettingRow(spec: $0) }
+              }
+              .frame(width: 360, alignment: .leading)
+            }
+            // Caps the window height; longer forms scroll.
+            .frame(maxHeight: 420)
+            Footer()
+          }
+          .frame(width: 360)
+          .padding([.horizontal, .top], 32)
+          // Matches the gap above the footer.
+          .padding(.bottom, 16)
+          .tabItem { Text("Settings") }
+        }
+        .padding([.horizontal, .top], 20)
         .fixedSize()
+      }
     }
     .windowResizability(.contentSize)
   }
 }
 
+/// Shown at the bottom of every tab.
+private struct Footer: View {
+  var body: some View {
+    Divider()
+    HStack(spacing: 3) {
+      Text("Made with").foregroundStyle(.tertiary)
+      Link("quicklook-kit", destination: URL(string: "https://github.com/idleberg/quicklook-kit")!)
+        .foregroundStyle(.secondary)
+        // A separate view, so only the link gets the pointer.
+        .onHover { $0 ? NSCursor.pointingHand.push() : NSCursor.pop() }
+    }
+    .font(.caption)
+  }
+}
+
+/// One entry of the settings form, in a single column: title, description, control.
+/// Values live in `UserDefaults.standard` under the dotted key, where the extension reads them.
+private struct SettingRow: View {
+  let spec: SettingSpec
+
+  var body: some View {
+    VStack(alignment: .leading, spacing: 6) {
+      if spec.type == "boolean" {
+        CheckboxSetting(spec: spec)
+        SettingDescription(spec: spec)
+      } else {
+        Text(spec.title).font(spec.type == "object" ? .headline : .body).bold()
+        SettingDescription(spec: spec)
+        if spec.type == "object" {
+          VStack(alignment: .leading, spacing: 16) {
+            ForEach(spec.children, id: \.key) { SettingRow(spec: $0) }
+          }
+          .padding(.leading, 16)
+          .padding(.top, 6)
+        } else if !spec.options.isEmpty {
+          PickerSetting(spec: spec)
+        } else {
+          FieldSetting(spec: spec)
+        }
+      }
+    }
+  }
+}
+
+private struct SettingDescription: View {
+  let spec: SettingSpec
+
+  var body: some View {
+    if let description = spec.description {
+      let options = AttributedString.MarkdownParsingOptions(
+        interpretedSyntax: .inlineOnlyPreservingWhitespace)
+      Text(
+        (try? AttributedString(markdown: description, options: options))
+          ?? AttributedString(description)
+      )
+      .foregroundStyle(.secondary)
+      .fixedSize(horizontal: false, vertical: true)
+    }
+  }
+}
+
+private struct CheckboxSetting: View {
+  let spec: SettingSpec
+  @State private var isOn: Bool
+
+  init(spec: SettingSpec) {
+    self.spec = spec
+    _isOn = State(initialValue: (storedValue(spec) ?? spec.defaultValue) as? Bool ?? false)
+  }
+
+  var body: some View {
+    Toggle(isOn: $isOn) { Text(spec.title).bold() }
+      .toggleStyle(.checkbox)
+      .onChange(of: isOn) { save(isOn, for: spec) }
+  }
+}
+
+private struct PickerSetting: View {
+  let spec: SettingSpec
+  @State private var selection: Int
+
+  init(spec: SettingSpec) {
+    self.spec = spec
+    let current = storedValue(spec) ?? spec.defaultValue
+    _selection = State(
+      initialValue: spec.options.firstIndex { option in
+        current.map { same(option.value, $0) } ?? false
+      } ?? 0)
+  }
+
+  var body: some View {
+    let picker = Picker(spec.title, selection: $selection) {
+      ForEach(spec.options.indices, id: \.self) { Text(spec.options[$0].label).tag($0) }
+    }
+    .labelsHidden()
+    .fixedSize()
+    .onChange(of: selection) { save(spec.options[selection].value, for: spec) }
+
+    if spec.radio {
+      picker.pickerStyle(.radioGroup)
+    } else {
+      picker.pickerStyle(.menu)
+    }
+  }
+}
+
+/// Saves on Return or focus loss. Empty removes the stored value, so the default
+/// (shown as placeholder) applies again.
+private struct FieldSetting: View {
+  let spec: SettingSpec
+  @State private var text: String
+  @FocusState private var isFocused: Bool
+
+  init(spec: SettingSpec) {
+    self.spec = spec
+    _text = State(initialValue: storedValue(spec).map { "\($0)" } ?? "")
+  }
+
+  var body: some View {
+    TextField(spec.defaultValue.map { String(describing: $0) } ?? "", text: $text)
+      .focused($isFocused)
+      .onSubmit(commit)
+      .onChange(of: isFocused) { if !isFocused { commit() } }
+  }
+
+  private func commit() {
+    let input = spec.type == "string" ? text : text.trimmingCharacters(in: .whitespaces)
+    if input.isEmpty {
+      text = ""
+      save(nil, for: spec)
+      return
+    }
+
+    let clamp = { (raw: Double) in
+      min(max(raw, spec.minimum ?? -.infinity), spec.maximum ?? .infinity)
+    }
+    var value: Any?
+    switch spec.type {
+    // Int() rejects fractions, so "2.5" never saves for an integer.
+    case "integer":
+      value = Int(input).map { clamp(Double($0)) == Double($0) ? $0 : Int(clamp(Double($0))) }
+    case "number": value = Double(input).map(clamp)
+    default: value = input
+    }
+
+    // Invalid input isn't saved; the field goes back to what's stored.
+    guard let value, spec.isValid(value) else {
+      text = storedValue(spec).map { "\($0)" } ?? ""
+      return
+    }
+    text = "\(value)"
+    save(value, for: spec)
+  }
+}
+
+/// The stored value, or nil when there is none or it no longer fits the schema.
+private func storedValue(_ spec: SettingSpec) -> Any? {
+  guard let value = UserDefaults.standard.object(forKey: spec.key), spec.isValid(value) else {
+    return nil
+  }
+  return value
+}
+
+/// Compares through NSObject, so an Int option matches the NSNumber UserDefaults returns,
+/// and 2 matches 2.0.
+private func same(_ lhs: Any, _ rhs: Any) -> Bool {
+  (lhs as AnyObject).isEqual(rhs as AnyObject)
+}
+
+/// Writes or removes (nil) the value, then resets Quick Look's cache so the next
+/// preview picks it up. Open previews don't update.
+private func save(_ value: Any?, for spec: SettingSpec) {
+  let defaults = UserDefaults.standard
+  let old = defaults.object(forKey: spec.key)
+  if let value {
+    if let old, same(old, value) { return }
+    defaults.set(value, forKey: spec.key)
+  } else {
+    if old == nil { return }
+    defaults.removeObject(forKey: spec.key)
+  }
+
+  let process = Process()
+  process.executableURL = URL(fileURLWithPath: "/usr/bin/qlmanage")
+  process.arguments = ["-r", "cache"]
+  process.standardOutput = FileHandle.nullDevice
+  try? process.run()
+}
+
 private struct ContentView: View {
   let name: String
 
@@ -60,12 +281,7 @@ private struct ContentView: View {
         .frame(maxWidth: .infinity, alignment: .leading)
       }
 
-      Divider()
-
-      Text("Made with [quicklook-kit](https://github.com/idleberg/quicklook-kit)")
-        .font(.caption)
-        .foregroundStyle(.tertiary)
-        .tint(.secondary)
+      Footer()
     }
     // Fixed so the window only grows in height as text comes and goes.
     .frame(width: 360)

package/native/Extension/PreviewViewController.swift

@@ -29,11 +29,18 @@ final class PreviewViewController: NSViewController, QLPreviewingController {
     let size = try url.resourceValues(forKeys: [.fileSizeKey]).fileSize ?? 0
     guard size <= Self.maxFileSize else { throw CocoaError(.fileReadTooLarge) }
 
-    let file = [
+    var file: [String: Any] = [
       "name": url.lastPathComponent,
       "extension": url.pathExtension.lowercased(),
       "base64": try Data(contentsOf: url).base64EncodedString(),
     ]
+    // The host app saves settings to its own defaults; the extension's bundle id
+    // is the app's plus `.Extension`, and its entitlements allow reading them.
+    let specs = SettingSpec.load()
+    let suite = Bundle.main.bundleIdentifier.map { String($0.dropLast(".Extension".count)) }
+    if !specs.isEmpty, let suite, let defaults = UserDefaults(suiteName: suite) {
+      file["settings"] = resolveSettings(specs, from: defaults)
+    }
     // JSON is a valid JavaScript expression, so this needs no escaping of its own.
     let json = String(decoding: try JSONSerialization.data(withJSONObject: file), as: UTF8.self)
     let scripts = webView.configuration.userContentController

package/native/Shared/Settings.swift

@@ -0,0 +1,129 @@
+import Foundation
+
+/// One entry of the `QLSettings` schema the build writes into Info.plist.
+/// Compiled into both the app, which edits the values, and the extension,
+/// which hands them to the page. See packages/quicklook-kit/src/config.ts.
+struct SettingSpec {
+  let key: String
+  let type: String
+  let title: String
+  let description: String?
+  let defaultValue: Any?
+  let options: [(value: Any, label: String)]
+  let radio: Bool
+  let minimum: Double?
+  let maximum: Double?
+  let children: [SettingSpec]
+
+  private init(_ entry: [String: Any], prefix: String) {
+    let name = entry["key"] as? String ?? ""
+    let type = entry["type"] as? String ?? ""
+    key = prefix + name
+    self.type = type
+    title = entry["title"] as? String ?? words(name)
+    description = entry["description"] as? String
+    radio = bool(entry["radio"] as Any) ?? false
+    minimum = number(entry["minimum"] as Any)?.doubleValue
+    maximum = number(entry["maximum"] as Any)?.doubleValue
+    children = Self.sorted(entry["properties"] as? [[String: Any]] ?? [], prefix: key + ".")
+    defaultValue = entry["default"].flatMap { Self.cast($0, as: type) }
+    options = (entry["enum"] as? [Any] ?? []).compactMap { option in
+      let object = option as? [String: Any]
+      guard let value = Self.cast(object?["value"] ?? option, as: type) else { return nil }
+      return (value, object?["description"] as? String ?? "\(value)")
+    }
+  }
+
+  /// Whether a stored value fits this entry: right type, in `options` if any, within bounds, integers whole.
+  func isValid(_ value: Any) -> Bool { validated(value) != nil }
+
+  /// `value` as this entry's Swift type if it fits, so a stored 3.0 comes back as integer 3.
+  func validated(_ value: Any) -> Any? {
+    guard let cast = Self.cast(value, as: type) else { return nil }
+    if !options.isEmpty, !options.contains(where: { ($0.value as AnyObject).isEqual(cast) }) {
+      return nil
+    }
+    if let num = number(cast)?.doubleValue {
+      if let minimum, num < minimum { return nil }
+      if let maximum, num > maximum { return nil }
+    }
+    return cast
+  }
+
+  /// `value` as Bool, String, Int or Double per `type`, or nil if it's the wrong type.
+  private static func cast(_ value: Any, as type: String) -> Any? {
+    switch type {
+    case "boolean": bool(value)
+    case "string": value as? String
+    case "integer": number(value).flatMap { Int(exactly: $0.doubleValue) }
+    case "number": number(value)?.doubleValue
+    default: nil
+    }
+  }
+
+  /// Top-level entries from the bundle's `QLSettings`, sorted; empty if absent.
+  static func load(from bundle: Bundle = .main) -> [SettingSpec] {
+    decode(bundle.object(forInfoDictionaryKey: "QLSettings") as? String ?? "[]")
+  }
+
+  /// Entries from a `QLSettings` JSON string, sorted; empty if it doesn't parse.
+  static func decode(_ json: String) -> [SettingSpec] {
+    let entries = (try? JSONSerialization.jsonObject(with: Data(json.utf8))) as? [[String: Any]]
+    return sorted(entries ?? [], prefix: "")
+  }
+
+  /// By `order`, unordered entries last, then in declaration order.
+  private static func sorted(_ entries: [[String: Any]], prefix: String) -> [SettingSpec] {
+    entries.enumerated()
+      .sorted {
+        let lhs = number($0.element["order"] as Any)?.doubleValue ?? .infinity
+        let rhs = number($1.element["order"] as Any)?.doubleValue ?? .infinity
+        return (lhs, $0.offset) < (rhs, $1.offset)
+      }
+      .map { SettingSpec($0.element, prefix: prefix) }
+  }
+}
+
+/// Defaults overridden by valid values from `defaults` (read by dotted key), as nested dictionaries.
+func resolveSettings(_ specs: [SettingSpec], from defaults: UserDefaults) -> [String: Any] {
+  var values: [String: Any] = [:]
+  for spec in specs {
+    let name = spec.key.split(separator: ".").last.map(String.init) ?? spec.key
+    values[name] =
+      spec.type == "object"
+      ? resolveSettings(spec.children, from: defaults)
+      : defaults.object(forKey: spec.key).flatMap(spec.validated) ?? spec.defaultValue
+  }
+  return values
+}
+
+// UserDefaults and JSONSerialization hand back NSNumber for booleans and numbers
+// alike; only the CFBoolean ones are booleans.
+private func bool(_ value: Any) -> Bool? {
+  guard let num = value as? NSNumber, CFGetTypeID(num) == CFBooleanGetTypeID() else { return nil }
+  return num.boolValue
+}
+
+private func number(_ value: Any) -> NSNumber? {
+  guard let num = value as? NSNumber, CFGetTypeID(num) != CFBooleanGetTypeID() else { return nil }
+  return num
+}
+
+/// "fontSize" → "Font Size"; dashes and underscores become spaces too.
+private func words(_ key: String) -> String {
+  var spaced = ""
+  var previous: Character?
+  for char in key {
+    if char == "_" || char == "-" {
+      spaced.append(" ")
+    } else {
+      if char.isUppercase, previous?.isLowercase == true || previous?.isNumber == true {
+        spaced.append(" ")
+      }
+      spaced.append(char)
+    }
+    previous = char
+  }
+  return spaced.split(separator: " ").map { $0.prefix(1).uppercased() + $0.dropFirst() }
+    .joined(separator: " ")
+}