@octane-xplat/ui 0.10.0 → 0.11.1

package/src/Image.tsrx

@@ -1,30 +1,182 @@
 /** @jsxImportSource @nativescript-community/octane */
-import { ImageSource } from '@nativescript/core';
-import { useMemo } from 'octane';
-import type { ImageProps } from './props';
+import { isAndroid, isIOS, ImageSource, knownFolders, Screen } from '@nativescript/core';
+import { useLayoutEffect, useMemo, useRef } from 'octane';
+import type { ImageProps, ImageSourceLike } from './props';
 import { cx } from './cx';
 import { applyEscapeProps } from './escape-props';
+import { rememberGridChildPlacement } from './grid-placement';
 import { layoutChildProps } from './layout-child';
 import { isSvgSrc, svgSource } from './svg';
+import { createSizedImageBinding } from './image-sizing';
+import { contentFitToStretch, needsContentRect, resolveContentFit, resolveContentPosition } from './image-content';
+import { createImageContentBinding } from './image-content-binding';
+import { hashToPngBase64 } from './hash-image';
+
+/** Resolves `placeholder` to an ImageSource synchronously — a placeholder
+ *  that must fetch first defeats its purpose, so remote URLs are ignored.
+ *  Accepts `blurhash:`/`thumbhash:` (decoded to PNG bytes in JS — see
+ *  ./hash-image), `data:` base64, `res://`, `~/`, and plain file paths. */
+function placeholderSource(placeholder: string): ImageSource | null {
+	const png = hashToPngBase64(placeholder);
+	if (png) {
+		return ImageSource.fromBase64Sync(png);
+	}
+
+	const comma = placeholder.indexOf(',');
+	if (
+		placeholder.startsWith('data:') &&
+		comma > 0 &&
+		placeholder.slice(0, comma).endsWith(';base64')
+	) {
+		return ImageSource.fromBase64Sync(placeholder.slice(comma + 1));
+	}
+
+	if (placeholder.startsWith('res://')) {
+		return ImageSource.fromResourceSync(placeholder.slice('res://'.length));
+	}
+
+	if (placeholder.startsWith('~/')) {
+		return ImageSource.fromFileSync(
+			knownFolders.currentApp().path + '/' + placeholder.slice(2),
+		);
+	}
+
+	if (!/^https?:\/\//.test(placeholder)) {
+		return ImageSource.fromFileSync(placeholder);
+	}
+
+	return null;
+}
+
+/** Re-resolves on every call — iOS disposes the previous ImageSource's
+ *  native image each time `src` is assigned. Only writes when a load is
+ *  pending (or nothing is showing), so a completed final image is never
+ *  clobbered. */
+function applyPlaceholder(view: any, placeholder: string | undefined): void {
+	if (!placeholder || !(view.isLoading || !view.imageSource)) {
+		return;
+	}
+
+	const ph = placeholderSource(placeholder);
+	if (ph) {
+		view.imageSource = ph;
+	}
+}
+
 /** Image — NS <image>. `src` accepts the NS ImageSource grammar:
- *  res://name, ~/bundle-path, file path, remote URL, or data: URI. SVG srcs
- *  (inline markup, svg data URIs, .svg paths/URLs) route to <svgview> —
- *  remote .svg URLs fetch to markup since SVGView has no fetch of its own.
- *  `alt` maps to accessibilityLabel (RN calls it `alt` on web parity). */
+ *  res://name, ~/bundle-path, file path, remote URL, or data: URI; an
+ *  ImageSourceLike[] picks the closest pixel count to the laid-out view
+ *  (srcset for native — study L8). SVG srcs (inline markup, svg data URIs,
+ *  .svg paths/URLs) route to <svgview> — remote .svg URLs fetch to markup
+ *  since SVGView has no fetch of its own. `alt` maps to accessibilityLabel
+ *  (RN calls it `alt` on web parity).
+ *  `contentFit` maps to stretch for the centered contain/cover/fill cases.
+ *  'none'/'scale-down'/positioned content takes the computed path: the
+ *  binding measures the host box, computes the CSS content rect, and lays
+ *  out an inner fill-stretched <image> inside a clipped absolutelayout —
+ *  the view-level equivalent of expo's matrix (the stock NS widget owns
+ *  its own draw matrix; see image-content-binding.ts).
+ *  `src` never goes through JSX: the content binding resolves WHICH source
+ *  (the array pick, or the prop as-is) and hands it to the sized binding,
+ *  which holds it until first layout then sets decodeWidth/decodeHeight in
+ *  device px before assigning — an eager src would decode at full source
+ *  resolution on Android (study L1).
+ *  `placeholder` rides the same view: NS nulls `imageSource` whenever a new
+ *  `src` is applied, so the leaf (re)assigns the placeholder bitmap whenever
+ *  the pipeline reports a pending load (`isLoadingChange`) and after every
+ *  binding src write (`afterIssue` — a same-src re-issue mid-load fires no
+ *  event). Placeholder → final inside one view; on the computed-rect path
+ *  the inner stretch='fill' image scales it with the same content math, so
+ *  fit/position match the final (expo-image study L5). A failed load leaves
+ *  the placeholder standing — failure-image semantics for free.
+ *  `decoding` maps to NS `loadMode` (default 'async' — the binding defers
+ *  src to first layout, so loadMode is always on the view before src is
+ *  issued); 'sync' blocks the UI thread at decode for must-paint-now
+ *  bitmaps. Remote URLs decode async and font-icon srcs sync regardless —
+ *  NS honors loadMode only on the file/resource/data paths. */
+function clipImageHost(host: any): void {
+	host?.on?.('loaded', () => {
+		// iOS UIView clipsToBounds defaults false (DOM/NS overflow:visible);
+		// cover/positioned rects must clip at the component box. Android
+		// ViewGroups clip children by default — and the host never receives
+		// escape props, which would unclip it.
+		if (isIOS && host.ios) {
+			host.ios.clipsToBounds = true;
+		}
+	});
+}
+
 export function Image(props: ImageProps) @{
-	const svg = useMemo(() => (isSvgSrc(props.src) ? svgSource(props.src) : null), [props.src]);
+	const sources = Array.isArray(props.src) ? (props.src as ImageSourceLike[]) : null;
+	const srcString = sources ? '' : (props.src as string);
+	const fit = resolveContentFit(props.contentFit);
+	const position = resolveContentPosition(props.contentPosition);
+	const computed = needsContentRect(fit, position);
+	const imageRef = useRef<any>(null);
+	const placeholderRef = useRef(props.placeholder);
+	placeholderRef.current = props.placeholder;
+	const sizing = useMemo(
+		() =>
+			createSizedImageBinding({
+				afterIssue: (v: any) => applyPlaceholder(v, placeholderRef.current),
+			}),
+		[],
+	);
+
+	const binding = useMemo(
+		() =>
+			createImageContentBinding({
+				isAndroid,
+				screenScale: () => Screen.mainScreen?.scale ?? 1,
+				issue: (view: any, src: any, gate?: string) => sizing.update(view, src, gate),
+			}),
+		[],
+	);
+
+	const boundRef = useRef({ key: props.recyclingKey, src: props.src });
+	const bound = boundRef.current;
+	boundRef.current = { key: props.recyclingKey, src: props.src };
+	// expo-image `recyclingKey`: platform-list cells rebind the same view, and
+	// Android's setUri keeps drawing the previous bitmap until the new fetch
+	// resolves. Clear it before the ref re-binds the next src — only when
+	// identity AND source both changed (same src = same bitmap).
+	if (
+		bound.key != null &&
+		props.recyclingKey != null &&
+		bound.key !== props.recyclingKey &&
+		bound.src !== props.src &&
+		imageRef.current
+	) {
+		imageRef.current.imageSource = null;
+	}
+
+	const svg = useMemo(() => (srcString && isSvgSrc(srcString) ? svgSource(srcString) : null), [srcString]);
 	const source = useMemo(() => {
-		const comma = props.src.indexOf(',');
+		const comma = srcString.indexOf(',');
 		if (
-			props.src.startsWith('data:') &&
+			srcString.startsWith('data:') &&
 			comma > 0 &&
-			props.src.slice(0, comma).endsWith(';base64')
+			srcString.slice(0, comma).endsWith(';base64')
 		) {
-			return ImageSource.fromBase64Sync(props.src.slice(comma + 1));
+			return ImageSource.fromBase64Sync(srcString.slice(comma + 1));
 		}
 
-		return props.src;
-	}, [props.src]);
+		return srcString;
+	}, [srcString]);
+
+	const update = { source: sources ? null : source, sources, fit, position, computed };
+
+	useLayoutEffect(() => {
+		const view = imageRef.current;
+		if (!view || !props.placeholder || svg != null) {
+			return;
+		}
+
+		const show = () => applyPlaceholder(view, props.placeholder);
+		show();
+		view.on?.('isLoadingChange', show);
+		return () => view.off?.('isLoadingChange', show);
+	}, [props.src, props.placeholder, svg]);
 
 	@if (svg != null) {
 		<svgview
@@ -34,17 +186,51 @@ export function Image(props: ImageProps) @{
 			className={cx(props.className)}
 			style={props.style}
 			src={svg}
-			stretch="aspectFit"
+			stretch={fit === 'none' ? 'none' : contentFitToStretch(fit === 'scale-down' ? 'contain' : fit)}
 			accessibilityLabel={props.alt}
 		/>
+	} @else if (computed) {
+		<absolutelayout
+			ref={(v: any) => {
+				clipImageHost(v);
+				rememberGridChildPlacement(v, props);
+				if (v) {
+					binding.update(v, null, update);
+				}
+			}}
+			id={props.id}
+			{...layoutChildProps(props)}
+			className={cx(props.className)}
+			style={props.style}
+		>
+			<image
+				ref={(v: any) => {
+					imageRef.current = v;
+					applyEscapeProps(v, props);
+					if (v) {
+						binding.update(null, v, update);
+					}
+				}}
+				stretch="fill"
+				loadMode={props.decoding ?? 'async'}
+				accessibilityLabel={props.alt}
+			/>
+		</absolutelayout>
 	} @else {
 		<image
-			ref={(v: any) => applyEscapeProps(v, props)}
+			ref={(v: any) => {
+				imageRef.current = v;
+				applyEscapeProps(v, props);
+				if (v) {
+					binding.update(v, v, update);
+				}
+			}}
 			id={props.id}
 			{...layoutChildProps(props)}
 			className={cx(props.className)}
 			style={props.style}
-			src={source}
+			stretch={contentFitToStretch(fit)}
+			loadMode={props.decoding ?? 'async'}
 			accessibilityLabel={props.alt}
 		/>
 	}

package/src/Image.web.tsrx

@@ -1,14 +1,100 @@
-import type { ImageProps } from "./props";
+import type { ImageProps, ImageSourceLike } from "./props";
 import { applyEscapeProps } from "./escape-props";
-import { layoutChildProps } from './layout-child.web';
-/** Image — a plain <img>. `src` takes any URL or data: URI. */
+import { layoutChildProps, normStyle } from './layout-child.web';
+import { useLayoutEffect, useRef } from 'octane'
+import { imageSrcSet, objectPositionCSSValue, resolveContentFit, resolveContentPosition } from './image-content';
+import { hashToPngBase64 } from './hash-image'
+
+/** `blurhash:`/`thumbhash:` decode to a data: PNG (./hash-image); every
+ *  other value passes through as an ordinary <img> URL (a low-res source
+ *  URL is a fine placeholder on web). */
+function placeholderUrl(placeholder: string): string {
+	const png = hashToPngBase64(placeholder)
+	return png ? `data:image/png;base64,${png}` : placeholder
+}
+
+/** Image — a plain <img>. `src` takes any URL or data: URI; a source array
+ *  becomes a real `srcset` (w descriptors from width·scale, x from scale —
+ *  the browser owns selection, the same role bestImageSource plays on
+ *  native). `contentFit`/`contentPosition` map 1:1 to object-fit/
+ *  object-position; explicit props win over style, style wins over the
+ *  'cover'/'50% 50%' defaults. `placeholder` rides the same element: the
+ *  img keeps showing its last decoded image while a new src fetches, so
+ *  assigning placeholder → src swaps placeholder → final in one view —
+ *  never a blank frame and no parallel loader (expo-image study L5). A
+ *  hidden prefetch keeps the final fetch running while the placeholder
+ *  paints. `decoding` writes the HTML `decoding` attribute 1:1 (default
+ *  'async' — the shared contract's default, not the browser's 'auto'). */
 export function Image(props: ImageProps) @{
+	const imgRef = useRef<HTMLImageElement | null>(null)
+	const sources = Array.isArray(props.src) ? (props.src as ImageSourceLike[]) : null;
+	const selected = sources
+		? imageSrcSet(sources)
+		: { src: props.src as string, srcSet: undefined };
+
+	useLayoutEffect(() => {
+		const img = imgRef.current
+		// complete = the current src already resolved (cache/sync data URI) —
+		// showing the placeholder would flash backwards.
+		if (!img || !props.placeholder || img.complete) return
+		const placeholder = placeholderUrl(props.placeholder)
+		const { src: final, srcSet: finalSrcSet } = selected
+		// (document.createElement — `Image` here is this component, not the
+		// global HTMLImageElement constructor)
+		const warm = document.createElement('img')
+		warm.src = final
+		if (finalSrcSet) {
+			warm.srcset = finalSrcSet
+		}
+
+		const swap = () => {
+			img.src = final
+			if (finalSrcSet) {
+				// srcset overrides src while present — restore it after the
+				// src write so both point at the final selection.
+				img.srcset = finalSrcSet
+			}
+		}
+
+		img.addEventListener('load', swap, { once: true })
+		img.addEventListener('error', swap, { once: true })
+		if (finalSrcSet) {
+			// While srcset is set it wins over src — clear it or the
+			// placeholder assignment below is inert.
+			img.srcset = ''
+		}
+
+		img.src = placeholder
+		return () => {
+			img.removeEventListener('load', swap)
+			img.removeEventListener('error', swap)
+		}
+	}, [props.src, props.placeholder])
+
+	const style = {
+		objectFit: 'cover',
+		objectPosition: '50% 50%',
+		...normStyle(props.style),
+		...(props.contentFit !== undefined
+			? { objectFit: resolveContentFit(props.contentFit) }
+			: null),
+		...(props.contentPosition !== undefined
+			? { objectPosition: objectPositionCSSValue(resolveContentPosition(props.contentPosition)) }
+			: null),
+	};
+
 	<img
-		ref={(e: any) => applyEscapeProps(e, props)}
+		ref={(e: any) => {
+			imgRef.current = e
+			applyEscapeProps(e, props)
+		}}
 		id={props.id}
 		className={props.className}
 		{...layoutChildProps(props)}
-		src={props.src}
+		src={selected.src}
+		srcSet={selected.srcSet}
+		decoding={props.decoding ?? 'async'}
 		alt={props.alt}
+		style={style}
 	/>
 }

package/src/Tabs.macos.tsrx

@@ -6,6 +6,8 @@ import { TabList, Tab } from './TabList.macos.tsrx'
 import { RouteHost } from './RouteHost.macos.tsrx'
 import { errorBoundaryFor, layoutsFor, useRoute, screenFor } from './route.macos'
 
+export type { TabSpec } from './props'
+
 function screenParams(route: NonNullable<ReturnType<typeof useRoute>>) {
 	const params: Record<string, unknown> = { ...route.params, ...(route.context ?? {}), _stack: route.stack, _pushed: true }
 	if (Object.prototype.hasOwnProperty.call(route, 'loaderData')) {params.data = route.loaderData}

package/src/Timestamp.macos.tsrx

@@ -105,7 +105,7 @@ export function Timestamp(props: TimestampProps) @{
 					))}
 				</flexboxlayout>
 			}
-			placement="top"
+			placement="above"
 		>
 			{labelNode}
 		</HoverCard>

package/src/colorScheme.macos.ts

@@ -1,7 +1,7 @@
 import { useSyncExternalStore } from 'octane'
 import type { ColorScheme } from './props'
 
-let appearanceListener: (() => void) | undefined
+let unsubscribeAppearance: (() => void) | undefined
 const listeners = new Set<() => void>()
 const host = () => (globalThis as any).__xplatAppKit
 
@@ -15,12 +15,25 @@ export function getColorScheme(): ColorScheme {
 
 export function subscribeSystemScheme(callback: () => void): () => void {
 	listeners.add(callback)
-	if (!appearanceListener) {
-		appearanceListener = () => listeners.forEach((listener) => listener())
-		host()?.onAppearanceChange?.(appearanceListener)
+	if (!unsubscribeAppearance) {
+		unsubscribeAppearance = host()?.onAppearanceChange?.(() => {
+			listeners.forEach((listener) => listener())
+		})
 	}
 
-	return () => listeners.delete(callback)
+	let active = true
+	return () => {
+		if (!active) {
+			return
+		}
+
+		active = false
+		listeners.delete(callback)
+		if (listeners.size === 0) {
+			unsubscribeAppearance?.()
+			unsubscribeAppearance = undefined
+		}
+	}
 }
 
 export function useColorScheme(): ColorScheme {

package/src/hash-image.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, it } from 'vitest'
+import { hashToPngBase64, isHashPlaceholder } from './hash-image'
+
+const PNG_MAGIC = 'iVBORw0KGgo'
+
+function pngBytes(base64: string) {
+	return Buffer.from(base64, 'base64')
+}
+
+function pngSize(base64: string) {
+	const bytes = pngBytes(base64)
+	return {
+		width: bytes.readUInt32BE(16),
+		height: bytes.readUInt32BE(20),
+		bitDepth: bytes[24],
+		colorType: bytes[25],
+	}
+}
+
+describe('isHashPlaceholder', () => {
+	it('accepts blurhash: and thumbhash: schemes only', () => {
+		expect(isHashPlaceholder('blurhash:LEHV6nWB2yk8pyo0adR*.7kCMdnj')).toBe(true)
+		expect(isHashPlaceholder('thumbhash:1QcSHQRnh493V4dIh4eXh1h4kJUI')).toBe(true)
+		expect(isHashPlaceholder('https://x/y.png')).toBe(false)
+		expect(isHashPlaceholder('res://icon')).toBe(false)
+	})
+})
+
+describe('hashToPngBase64', () => {
+	it('decodes a blurhash to a 32x32 RGBA PNG', () => {
+		const png = hashToPngBase64('blurhash:LEHV6nWB2yk8pyo0adR*.7kCMdnj')
+		expect(png).not.toBeNull()
+		expect(png!.startsWith(PNG_MAGIC)).toBe(true)
+		expect(pngSize(png!)).toEqual({ width: 32, height: 32, bitDepth: 8, colorType: 6 })
+	})
+
+	it('decodes a thumbhash to a bounded PNG', () => {
+		const png = hashToPngBase64('thumbhash:1QcSHQRnh493V4dIh4eXh1h4kJUI')
+		expect(png).not.toBeNull()
+		expect(png!.startsWith(PNG_MAGIC)).toBe(true)
+		const size = pngSize(png!)
+		expect(size.width).toBeGreaterThan(0)
+		expect(size.width).toBeLessThanOrEqual(32)
+		expect(size.height).toBeGreaterThan(0)
+		expect(size.height).toBeLessThanOrEqual(32)
+	})
+
+	it('produces non-uniform pixel data (real decode, not a flat fill)', () => {
+		const png = hashToPngBase64('blurhash:LGF5]+Yk^6#M@-5c,1J5@[or[Q6.')
+		const bytes = pngBytes(png!)
+		const unique = new Set(bytes.subarray(60))
+		expect(unique.size).toBeGreaterThan(8)
+	})
+
+	it('is deterministic', () => {
+		const src = 'blurhash:LEHV6nWB2yk8pyo0adR*.7kCMdnj'
+		expect(hashToPngBase64(src)).toBe(hashToPngBase64(src))
+	})
+
+	it.each([
+		'blurhash:',
+		'blurhash:abc',
+		'blurhash:!!!!!!!!!!!!!!!!!',
+		'thumbhash:',
+		'thumbhash:%%%',
+		'thumbhash:AAAA',
+		'https://x/y.png',
+		'plain string',
+	])('returns null for %s', (src) => {
+		expect(hashToPngBase64(src)).toBeNull()
+	})
+})