@octane-xplat/macos-renderer 0.11.0 → 0.12.0

package/src/appkit.d.ts

@@ -1,7 +1,9 @@
 // Ambient host globals injected by @nativescript/macos-node-api and the
 // embedding Node process. The prerelease ships no generated AppKit metadata
-// types, so bridge classes expose members loosely while the type names stay
-// usable in our own signatures.
+// types, so the declarations below cover the native surface the renderer
+// calls for event and control wiring (target/action, gesture recognizers,
+// tracking areas, notification observers, menus, pickers, sheets). Members
+// outside that surface still resolve to `any` through the index signatures.
 
 type NSClass<T> = {
 	new (...args: any[]): T
@@ -9,13 +11,32 @@ type NSClass<T> = {
 	[key: string]: any
 }
 
-// Objective-C classes. Instances expose bridged members as `any`; the type
-// name is real so parameters and node structs can reference them.
+// Core Graphics geometry, bridged as plain objects.
+interface NSPoint {
+	x: number
+	y: number
+}
+
+interface NSSize {
+	width: number
+	height: number
+}
+
+interface NSRect {
+	origin: NSPoint
+	size: NSSize
+}
+
+// Objective-C classes. Instances expose bridged members beyond the declared
+// surface as `any`; the type name is real so parameters and node structs can
+// reference them.
 declare class NSObject {
 	[key: string]: any
 	static alloc(): any
 	static new(): any
 	static extend(methods: object, options?: object): any
+	init(): this
+	isEqual?(other: any): boolean
 }
 
 interface NSAttributedString extends NSObject {}
@@ -31,16 +52,52 @@ interface NSURLRequest extends NSObject {}
 declare const NSURLRequest: NSClass<NSURLRequest>
 
 // WebKit is dlopen'd at runtime by the webview leaf.
-interface WKWebView extends NSView {}
+interface WKWebView extends NSView {
+	navigationDelegate: any
+	evaluateJavaScriptCompletionHandler(script: string, handler: any): void
+}
+
 declare const WKWebView: NSClass<WKWebView>
 
 interface WKWebViewConfiguration extends NSObject {}
 declare const WKWebViewConfiguration: NSClass<WKWebViewConfiguration>
 
-interface NSButton extends NSView {}
-declare const NSButton: NSClass<NSButton>
+// NSControl carries the target/action channel shared by buttons, sliders,
+// text fields, and date pickers.
+interface NSControl extends NSView {
+	target: any
+	action: string | null
+	enabled: boolean
+	doubleValue: number
+	font: any
+	textColor: any
+	cell: any
+}
+
+interface NSButton extends NSControl {
+	bezelStyle: number
+	state: number
+	setButtonType(type: number): void
+}
+
+interface NSButtonClass extends NSClass<NSButton> {
+	buttonWithTitleTargetAction(title: string, target: any, action: string): NSButton
+}
+
+declare const NSButton: NSButtonClass
+
+interface NSGestureRecognizer extends NSObject {
+	initWithTargetAction(target: any, action: string): this
+	readonly view: NSView
+	state: number
+	enabled: boolean
+}
+
+interface NSClickGestureRecognizer extends NSGestureRecognizer {
+	numberOfClicksRequired: number
+	buttonMask: number
+}
 
-interface NSClickGestureRecognizer extends NSObject {}
 declare const NSClickGestureRecognizer: NSClass<NSClickGestureRecognizer>
 
 interface NSColor extends NSObject {}
@@ -52,17 +109,51 @@ declare const NSColorSpace: NSClass<NSColorSpace>
 interface NSData extends NSObject {}
 declare const NSData: NSClass<NSData>
 
-interface NSDate extends NSObject {}
-declare const NSDate: NSClass<NSDate>
+interface NSDate extends NSObject {
+	readonly timeIntervalSince1970: number
+}
+
+interface NSDateClass extends NSClass<NSDate> {
+	dateWithTimeIntervalSince1970(seconds: number): NSDate
+}
+
+declare const NSDate: NSDateClass
+
+interface NSDatePicker extends NSControl {
+	datePickerElements: number
+	datePickerStyle: number
+	dateValue: NSDate | null
+	minDate: NSDate | null
+	maxDate: NSDate | null
+}
 
-interface NSDatePicker extends NSView {}
 declare const NSDatePicker: NSClass<NSDatePicker>
 
 interface NSEdgeInsets extends NSObject {}
 declare const NSEdgeInsets: NSClass<NSEdgeInsets>
 
-interface NSEvent extends NSObject {}
-declare const NSEvent: NSClass<NSEvent>
+interface NSEvent extends NSObject {
+	readonly type: number
+	readonly keyCode: number
+	readonly modifierFlags: number
+	readonly window: NSWindow | null
+	readonly locationInWindow: NSPoint
+	readonly trackingArea: NSTrackingArea
+}
+
+interface NSEventClass extends NSClass<NSEvent> {
+	addLocalMonitorForEventsMatchingMaskHandler(
+		mask: number,
+		handler: (event: NSEvent) => NSEvent | null,
+	): any
+	addGlobalMonitorForEventsMatchingMaskHandler(
+		mask: number,
+		handler: (event: NSEvent) => NSEvent | null,
+	): any
+	removeMonitor(monitor: any): void
+}
+
+declare const NSEvent: NSEventClass
 
 interface NSFont extends NSObject {}
 declare const NSFont: NSClass<NSFont>
@@ -76,63 +167,241 @@ declare const NSFontManager: NSClass<NSFontManager>
 interface NSImage extends NSObject {}
 declare const NSImage: NSClass<NSImage>
 
-interface NSImageView extends NSView {}
+interface NSImageView extends NSControl {
+	image: NSImage | null
+	imageScaling: number
+}
+
 declare const NSImageView: NSClass<NSImageView>
 
-interface NSMenu extends NSObject {}
+interface NSMenu extends NSObject {
+	autoenablesItems: boolean
+	addItem(item: NSMenuItem): void
+}
+
 declare const NSMenu: NSClass<NSMenu>
 
-interface NSMenuItem extends NSObject {}
-declare const NSMenuItem: NSClass<NSMenuItem>
+interface NSMenuItem extends NSObject {
+	initWithTitleActionKeyEquivalent(
+		title: string,
+		action: string | null,
+		keyEquivalent: string,
+	): this
+	target: any
+	action: string | null
+	enabled: boolean
+	tag?: number
+}
+
+interface NSMenuItemClass extends NSClass<NSMenuItem> {
+	separatorItem(): NSMenuItem
+}
+
+declare const NSMenuItem: NSMenuItemClass
+
+interface NSApplication extends NSObject {
+	readonly keyWindow: NSWindow | null
+}
+
+interface NSApplicationClass extends NSClass<NSApplication> {
+	readonly sharedApplication: NSApplication
+}
+
+declare const NSApplication: NSApplicationClass
+
+interface NSAppearance extends NSObject {}
+interface NSAppearanceClass extends NSClass<NSAppearance> {
+	appearanceNamed(name: string): NSAppearance
+}
+
+declare const NSAppearance: NSAppearanceClass
 
 interface NSMutableParagraphStyle extends NSObject {}
 declare const NSMutableParagraphStyle: NSClass<NSMutableParagraphStyle>
 
-interface NSNotification extends NSObject {}
+interface NSNotification extends NSObject {
+	readonly object: any
+}
+
 declare const NSNotification: NSClass<NSNotification>
 
-interface NSNotificationCenter extends NSObject {}
-declare const NSNotificationCenter: NSClass<NSNotificationCenter>
+interface NSNotificationCenter extends NSObject {
+	addObserverForNameObjectQueueUsingBlock(
+		name: string,
+		object: any,
+		queue: any,
+		block: () => void,
+	): any
+	removeObserver(observer: any): void
+}
+
+interface NSNotificationCenterClass extends NSClass<NSNotificationCenter> {
+	readonly defaultCenter: NSNotificationCenter
+}
+
+declare const NSNotificationCenter: NSNotificationCenterClass
 
 interface NSNumber extends NSObject {}
 declare const NSNumber: NSClass<NSNumber>
 
-interface NSPanGestureRecognizer extends NSObject {}
+interface NSPanGestureRecognizer extends NSGestureRecognizer {
+	translationInView(view: NSView | null): NSPoint
+	velocityInView(view: NSView | null): NSPoint
+}
+
 declare const NSPanGestureRecognizer: NSClass<NSPanGestureRecognizer>
 
-interface NSPopover extends NSObject {}
+interface NSPopover extends NSObject {
+	contentViewController: NSViewController
+	contentSize: NSSize
+	behavior: number
+	animates: boolean
+	showRelativeToRectOfViewPreferredEdge(rect: NSRect, view: NSView, preferredEdge: number): void
+	close(): void
+}
+
 declare const NSPopover: NSClass<NSPopover>
 
-interface NSScrollView extends NSView {}
+interface NSScrollView extends NSView {
+	documentView: NSView | null
+	contentView: any
+	borderType: number
+	drawsBackground: boolean
+	hasVerticalScroller: boolean
+	hasHorizontalScroller: boolean
+	reflectScrolledClipView(clipView: any): void
+}
+
 declare const NSScrollView: NSClass<NSScrollView>
 
-interface NSSlider extends NSView {}
+interface NSSlider extends NSControl {
+	minValue: number
+	maxValue: number
+}
+
 declare const NSSlider: NSClass<NSSlider>
 
 interface NSStackView extends NSView {}
 declare const NSStackView: NSClass<NSStackView>
 
-interface NSTextField extends NSView {}
+interface NSTextField extends NSControl {
+	stringValue: string
+	placeholderString?: string
+	placeholderAttributedString: any
+	bezeled: boolean
+	drawsBackground: boolean
+	editable: boolean
+	selectable: boolean
+	sendsActionOnEndEditing: boolean
+	alignment: number
+}
+
 declare const NSTextField: NSClass<NSTextField>
 
-interface NSTextView extends NSView {}
+interface NSSecureTextField extends NSTextField {}
+declare const NSSecureTextField: NSClass<NSSecureTextField>
+
+interface NSTextView extends NSView {
+	string: string
+	editable: boolean
+	selectable: boolean
+	drawsBackground: boolean
+	delegate: any
+	font: any
+	textColor: any
+	textContainer: any
+	textContainerInset: NSSize
+}
+
 declare const NSTextView: NSClass<NSTextView>
 
-interface NSTrackingArea extends NSObject {}
+interface NSTrackingArea extends NSObject {
+	initWithRectOptionsOwnerUserInfo(rect: NSRect, options: number, owner: any, userInfo: any): this
+}
+
 declare const NSTrackingArea: NSClass<NSTrackingArea>
 
 interface NSURL extends NSObject {}
 declare const NSURL: NSClass<NSURL>
 
-interface NSView extends NSObject {}
+interface NSView extends NSObject {
+	initWithFrame(frame: NSRect): this
+	addSubview(child: NSView): void
+	removeFromSuperview(): void
+	addGestureRecognizer(recognizer: NSGestureRecognizer): void
+	removeGestureRecognizer(recognizer: NSGestureRecognizer): void
+	addTrackingArea(area: NSTrackingArea): void
+	removeTrackingArea(area: NSTrackingArea): void
+	hitTest(point: NSPoint): NSView | null
+	acceptsFirstResponder(): boolean
+	keyDown(event: NSEvent): void
+	layout(): void
+	layoutSubtreeIfNeeded(): void
+	convertRectToView(rect: NSRect, view: NSView | null): NSRect
+	isFlipped(): boolean
+	frame: NSRect
+	bounds: NSRect
+	readonly fittingSize: NSSize
+	readonly superview: NSView | null
+	readonly window: NSWindow | null
+	hidden: boolean
+	tag?: number
+	menu: NSMenu | null
+	alphaValue: number
+	autoresizingMask?: number
+	translatesAutoresizingMaskIntoConstraints: boolean
+	wantsLayer: boolean
+	postsBoundsChangedNotifications: boolean
+	postsFrameChangedNotifications: boolean
+}
+
 declare const NSView: NSClass<NSView>
 
-interface NSViewController extends NSObject {}
+interface NSViewController extends NSObject {
+	view: NSView
+	preferredContentSize: NSSize
+}
+
 declare const NSViewController: NSClass<NSViewController>
 
-interface NSWindow extends NSObject {}
+interface NSWindow extends NSObject {
+	initWithContentRectStyleMaskBackingDefer(
+		contentRect: NSRect,
+		styleMask: number,
+		backing: number,
+		defer: boolean,
+	): this
+	contentView: NSView
+	contentViewController: NSViewController
+	frame: NSRect
+	firstResponder: any
+	delegate: any
+	effectiveAppearance: any
+	releasedWhenClosed: boolean
+	makeFirstResponder(responder: any): boolean
+	beginSheetCompletionHandler(sheet: NSWindow, handler: () => void): void
+	endSheet(sheet: NSWindow): void
+	orderOut(sender: any): void
+	center(): void
+	makeKeyAndOrderFront(sender: any): void
+}
+
 declare const NSWindow: NSClass<NSWindow>
 
+// QuartzCore, referenced lazily by the presentation bridge for sheet
+// transition fades.
+interface CABasicAnimation extends NSObject {
+	fromValue: any
+	toValue: any
+	duration: number
+}
+
+interface CABasicAnimationClass extends NSClass<CABasicAnimation> {
+	animationWithKeyPath(keyPath: string): CABasicAnimation
+}
+
+declare const CABasicAnimation: CABasicAnimationClass
+
 // Enum containers. Members resolve to `number`, so bitwise masks compose.
 declare const NSBackingStoreType: { [key: string]: number }
 declare const NSBezelStyle: { [key: string]: number }
@@ -145,6 +414,7 @@ declare const NSPopoverBehavior: { [key: string]: number }
 declare const NSRectEdge: { [key: string]: number }
 declare const NSStackViewDistribution: { [key: string]: number }
 declare const NSStackViewGravity: { [key: string]: number }
+declare const NSLineBreakMode: { [key: string]: number }
 declare const NSTextAlignment: { [key: string]: number }
 declare const NSTrackingAreaOptions: { [key: string]: number }
 declare const NSUserInterfaceLayoutOrientation: { [key: string]: number }
@@ -176,9 +446,12 @@ declare function dlopen(path: string, flags: number): unknown
 declare var __xplatAppKit: {
 	observeHover?: (view: NSView, handlers: any) => void
 	showAnchoredPopup?: (options: any) => void
+	showLayer?: (options: any) => any
 	attachContextMenu?: (view: NSView, options: any, onSelect: any) => void
 	attachDatePicker?: (view: NSView, options: any, onChange: any) => void
 	presentSheet?: (view: NSView, options: any) => void
+	presentSurface?: (options: any) => any
+	setSurfaceAppearance?: (view: NSView, dark: boolean) => void
 	[key: string]: any
 }
 

package/src/image.ts

@@ -21,3 +21,95 @@ export function loadImage(source: unknown): NSImage | null {
 
 	return null
 }
+
+/** Per-view load state. The generation invalidates in-flight decodes when the
+ *  source changes or `disposeImage` runs — the same guard the webview leaf
+ *  applies to async measurements. */
+interface ImageRequest {
+	source: string
+	generation: number
+}
+
+const requests = new WeakMap<object, ImageRequest>()
+
+/** Decoded images shared across views; bounded so galleries cannot retain
+ *  every source they have ever shown. Failures are not cached — a file that
+ *  appears later or a retry must still decode. */
+const cache = new Map<string, NSImage>()
+const pending = new Map<string, ((image: NSImage | null) => void)[]>()
+const IMAGE_CACHE_LIMIT = 64
+
+function decodeImage(source: string) {
+	const callbacks = pending.get(source) ?? []
+	pending.delete(source)
+
+	let image: NSImage | null = null
+	try {
+		image = loadImage(source)
+	} catch (error) {
+		console.error('[macos-image] decode failed', error)
+	}
+
+	if (image) {
+		cache.delete(source)
+		cache.set(source, image)
+		while (cache.size > IMAGE_CACHE_LIMIT) {
+			cache.delete(cache.keys().next().value!)
+		}
+	}
+
+	for (const callback of callbacks) {
+		callback(image)
+	}
+}
+
+/** Points `view` at `source`. Cached decodes assign immediately; anything else
+ *  decodes on a later run-loop turn so command batches never block on image
+ *  I/O. The previous image stays visible until its replacement resolves. */
+export function updateImage(view: NSImageView, source: unknown) {
+	const src = String(source ?? '')
+	let request = requests.get(view)
+	if (!request) {
+		request = { source: '', generation: 0 }
+		requests.set(view, request)
+	}
+
+	if (request.source === src) {
+		return
+	}
+
+	request.source = src
+	const generation = ++request.generation
+	const deliver = (image: NSImage | null) => {
+		if (requests.get(view) !== request || request.generation !== generation) {
+			return
+		}
+
+		view.image = image
+	}
+
+	if (!src) {
+		deliver(null)
+		return
+	}
+
+	const cached = cache.get(src)
+	if (cached) {
+		deliver(cached)
+		return
+	}
+
+	let waiters = pending.get(src)
+	if (!waiters) {
+		waiters = []
+		pending.set(src, waiters)
+		setTimeout(() => decodeImage(src), 0)
+	}
+
+	waiters.push(deliver)
+}
+
+/** Invalidates any in-flight decode for `view`; call when its node is destroyed. */
+export function disposeImage(view: NSImageView) {
+	requests.delete(view)
+}