@octane-xplat/ui 0.10.0 → 0.11.1

package/src/image-content-binding.ts

@@ -0,0 +1,231 @@
+import { bestImageSource, contentRect } from './image-content';
+import type {
+	ImageContentFit,
+	ImageContentPositionObject,
+	ImageSourceLike,
+} from './props';
+
+export interface ImageContentEnv {
+	/** Platform gate for the intrinsic-size unit conversion — the leaf
+	 *  supplies it so this module stays free of '@nativescript/core'. */
+	isAndroid: boolean;
+	/** Device pixel ratio for the L8 pixel-count target. */
+	screenScale: () => number;
+	/** Src write seam — the sized-decode binding (image-sizing.ts) owns WHEN
+	 *  a source lands on the view: first-layout gate, decode dims, resize
+	 *  reload. `stretchForDecode` overrides the view's stretch for those
+	 *  gates on the computed path, whose inner image draws stretch='fill'
+	 *  under a different semantic fit ('none' needs the full-resolution
+	 *  source to find the natural size). */
+	issue: (view: any, source: any, stretchForDecode?: string) => void;
+}
+
+export interface ImageContentUpdate {
+	/** The resolved single source (string or ImageSource), null when
+	 *  `sources` carries the request. */
+	source: any;
+	/** Resolution-qualified sources (L8) — the binding defers selection
+	 *  until a real layout exists, picks the closest pixel count, then
+	 *  hands the winner to `issue`. */
+	sources: readonly ImageSourceLike[] | null;
+	/** Resolved CSS fit/position for the computed path. */
+	fit: ImageContentFit;
+	position: ImageContentPositionObject;
+	/** True when the image view lives in a clip host and is laid out by the
+	 *  binding (width/height/left/top in dips) — needed for 'none',
+	 *  'scale-down', and non-center positions no platform scaleType has. */
+	computed: boolean;
+}
+
+/** Intrinsic size in dips. iOS `UIImage.size` is already points; Android
+ *  `Bitmap` reports raw pixels — density-bucketed resource bitmaps convert
+ *  through their bucket (a 300px xxxhdpi asset = 75 dips), while decoded
+ *  remote/file bitmaps carry no density and treat px as dips, which is the
+ *  CSS 'none' natural size on every platform. */
+function intrinsicDipSize(
+	imageSource: any,
+	android: boolean,
+): { w: number; h: number } | null {
+	const width = imageSource?.width;
+	const height = imageSource?.height;
+	if (!width || !height) {
+		return null;
+	}
+
+	if (android) {
+		const density = imageSource.android?.getDensity?.() ?? 0;
+		if (density > 0) {
+			return { w: (width * 160) / density, h: (height * 160) / density };
+		}
+	}
+
+	return { w: width, h: height };
+}
+
+/** Measure → compute → apply for Image's content contract (study L7).
+ *  NS's stock widget owns its draw path — the widgets ImageView computes
+ *  its own matrix in onDraw and honors only the four stretch scaleTypes —
+ *  so the drawable-level matrix expo-image uses is engine internals. What
+ *  the leaf can own is the view-level equivalent: measure the box
+ *  (`layoutChanged` → `getActualSize`, dips), compute the content rect
+ *  with the same math as object-fit/object-position, and lay out the
+ *  inner <image stretch="fill"> to that rect inside a clipped host. One
+ *  code path produces identical rects on iOS and Android.
+ *
+ *  This binding never writes `src` itself — it resolves WHICH source the
+ *  view should load and hands it to `env.issue`, the sized-decode binding
+ *  (study L1). That seam composes both contracts: the L8 array pick waits
+ *  on the same first real layout the decode gate needs, and the computed
+ *  path passes the semantic fit as the decode gate so 'none' still
+ *  decodes at source resolution while 'fill' would have been
+ *  view-sampled.
+ *
+ *  Before the bitmap's intrinsic size is known the computed path sizes
+ *  the inner image to the host box: a real rect is what lets the decode
+ *  gate's first-layout check pass, and the placeholder is the CSS 'fill'
+ *  answer until imageSourceChange refines it.
+ *
+ *  `update` re-runs on every render (ref identity churn); all writes are
+ *  idempotent. Null refs on detach are ignored — a dead listener is a
+ *  self-contained cycle GC collects with the view. */
+export function createImageContentBinding(env: ImageContentEnv) {
+	let sizeView: any = null;
+	let imageView: any = null;
+	let update: ImageContentUpdate = {
+		source: null,
+		sources: null,
+		fit: 'cover',
+		position: {},
+		computed: false,
+	};
+
+	let appliedW = 0;
+	let appliedH = 0;
+	let appliedX = 0;
+	let appliedY = 0;
+	let listening = false;
+	let sourceListening = false;
+
+	const screenScale = () => {
+		try {
+			return env.screenScale();
+		} catch {
+			return 1;
+		}
+	};
+
+	// 'none' decodes at source resolution — its contract is natural size and
+	// the rect math needs the true intrinsic. Everything else decodes at
+	// view size: for 'scale-down' the intrinsic-vs-view comparison survives
+	// downsampling (a bigger source still reads >= view), though a source
+	// barely larger than the view can sample to just under it and resolve
+	// as 'none' — a small undersize vs CSS, accepted for one decode pass.
+	const decodeGate = () => (update.fit === 'none' ? 'none' : 'aspectFit');
+
+	const evaluate = () => {
+		if (!sizeView) {
+			return;
+		}
+
+		const needsViewSize = update.computed || update.sources != null;
+		let viewWidth = 0;
+		let viewHeight = 0;
+		if (needsViewSize) {
+			const actual = sizeView.getActualSize?.();
+			viewWidth = actual?.width ?? 0;
+			viewHeight = actual?.height ?? 0;
+			if (viewWidth <= 0 || viewHeight <= 0) {
+				return;
+			}
+		}
+
+		if (imageView) {
+			let resolved: any = update.source;
+			if (update.sources?.length) {
+				resolved = bestImageSource(update.sources, viewWidth, viewHeight, screenScale())?.uri;
+			}
+
+			if (resolved != null && resolved !== '') {
+				env.issue(imageView, resolved, update.computed ? decodeGate() : undefined);
+			}
+		}
+
+		if (!update.computed || !imageView) {
+			return;
+		}
+
+		const intrinsic = intrinsicDipSize(imageView.imageSource, env.isAndroid);
+		const rect = intrinsic
+			? contentRect(update.fit, update.position, viewWidth, viewHeight, intrinsic.w, intrinsic.h)
+			: { x: 0, y: 0, width: viewWidth, height: viewHeight };
+
+		if (
+			rect.width !== appliedW ||
+			rect.height !== appliedH ||
+			rect.x !== appliedX ||
+			rect.y !== appliedY
+		) {
+			appliedW = rect.width;
+			appliedH = rect.height;
+			appliedX = rect.x;
+			appliedY = rect.y;
+			imageView.width = rect.width;
+			imageView.height = rect.height;
+			imageView.left = rect.x;
+			imageView.top = rect.y;
+		}
+	};
+
+	const onLayout = () => evaluate();
+	const onImageSource = () => evaluate();
+
+	const listen = () => {
+		const wantsMeasure = update.computed || update.sources != null;
+		if (wantsMeasure && !listening && typeof sizeView?.on === 'function') {
+			sizeView.on('layoutChanged', onLayout);
+			listening = true;
+		} else if (!wantsMeasure && listening) {
+			sizeView?.off?.('layoutChanged', onLayout);
+			listening = false;
+		}
+
+		if (update.computed && !sourceListening && typeof imageView?.on === 'function') {
+			imageView.on('imageSourceChange', onImageSource);
+			sourceListening = true;
+		} else if (!update.computed && sourceListening) {
+			imageView?.off?.('imageSourceChange', onImageSource);
+			sourceListening = false;
+		}
+	};
+
+	return {
+		/** (Re)bind views + intent. `sizeView` is the measured box (the image
+		 *  itself on the stretch path, the clip host on the computed path);
+		 *  `imageView` is the <image> that draws. */
+		update(nextSizeView: any, nextImageView: any, next: ImageContentUpdate): void {
+			if (nextSizeView && nextSizeView !== sizeView) {
+				sizeView?.off?.('layoutChanged', onLayout);
+				sizeView = nextSizeView;
+				listening = false;
+			}
+
+			if (nextImageView && nextImageView !== imageView) {
+				imageView?.off?.('imageSourceChange', onImageSource);
+				imageView = nextImageView;
+				sourceListening = false;
+			}
+
+			update = next;
+			listen();
+			evaluate();
+		},
+		dispose(): void {
+			sizeView?.off?.('layoutChanged', onLayout);
+			imageView?.off?.('imageSourceChange', onImageSource);
+			sizeView = null;
+			imageView = null;
+			listening = false;
+			sourceListening = false;
+		},
+	};
+}

package/src/image-content.mobile.test.tsrx

@@ -0,0 +1,84 @@
+/** @jsxImportSource @nativescript-community/octane */
+import { describe, expect, it, vi } from 'vitest'
+import { createObjectContainer, createObjectDriver, createUniversalRoot } from 'octane/universal/native'
+
+vi.mock('@nativescript/core', () => ({
+	isIOS: false,
+	isAndroid: true,
+	Screen: { mainScreen: { scale: 3 } },
+	ScrollView: class {},
+	ImageSource: class {
+		static fromBase64Sync() {
+			return { mocked: true }
+		}
+	},
+}))
+
+// The raster path is under test; ./svg resolves to svg.mobile.ts, which
+// registers SVGView from the vendored submodule (needs real NS core).
+vi.mock('./svg', () => ({
+	isSvgSrc: () => false,
+	svgSource: (s: string) => s,
+}))
+
+import { Image } from './Image.tsrx'
+
+function render(props: any) {
+	const container = createObjectContainer('nativescript')
+	const root = createUniversalRoot(container, createObjectDriver('nativescript'))
+	root.render(Image as any, props)
+	return { container, root, host: container.children[0] as any }
+}
+
+describe('native Image — contentFit fast path (L7)', () => {
+	it('defaults to cover → aspectFill (the web/img fill and NS aspectFit defaults diverged)', () => {
+		const { host } = render({ src: 'https://img.example/x.png' })
+		expect(host.type).toBe('image')
+		expect(host.props.stretch).toBe('aspectFill')
+	})
+
+	it('maps contain/cover/fill onto stretch', () => {
+		expect(render({ src: 'x', contentFit: 'contain' }).host.props.stretch).toBe('aspectFit')
+		expect(render({ src: 'x', contentFit: 'cover' }).host.props.stretch).toBe('aspectFill')
+		expect(render({ src: 'x', contentFit: 'fill' }).host.props.stretch).toBe('fill')
+	})
+
+	it('routes none/scale-down/positioned content through the computed wrapper', () => {
+		const none = render({ src: 'x', contentFit: 'none' }).host
+		expect(none.type).toBe('absolutelayout')
+		const inner = none.children[0] as any
+		expect(inner.type).toBe('image')
+		expect(inner.props.stretch).toBe('fill')
+
+		const scaleDown = render({ src: 'x', contentFit: 'scale-down' }).host
+		expect(scaleDown.type).toBe('absolutelayout')
+		const positioned = render({ src: 'x', contentFit: 'cover', contentPosition: 'top left' }).host
+		expect(positioned.type).toBe('absolutelayout')
+		// fill ignores position — the rect is always the whole box
+		const filled = render({ src: 'x', contentFit: 'fill', contentPosition: 'top left' }).host
+		expect(filled.type).toBe('image')
+	})
+})
+
+describe('native Image — multi-source selection (L8)', () => {
+	const sources = [
+		{ uri: 'https://img.example/p-200.jpg', width: 200, height: 200 },
+		{ uri: 'https://img.example/p-800.jpg', width: 800, height: 800 },
+	]
+
+	it('defers src until a real layout, then assigns the closest source', () => {
+		const { root, host } = render({ src: sources })
+		expect(host.type).toBe('image')
+		expect(host.src).toBeUndefined()
+
+		// re-render re-fires the ref → binding.update → content binding picks
+		// (200x200 dips at scale 3 → 600² px → 800² wins) and hands it to the
+		// sized binding, whose measured-width gate lands the src + decode dims
+		host.getActualSize = () => ({ width: 200, height: 200 })
+		host.getMeasuredWidth = () => 600
+		host.getMeasuredHeight = () => 600
+		root.render(Image as any, { src: sources })
+		expect(host.src).toBe('https://img.example/p-800.jpg')
+		expect(host.decodeWidth).toEqual({ value: 600, unit: 'px' })
+	})
+})

package/src/image-content.test.ts

@@ -0,0 +1,219 @@
+import { describe, expect, it } from 'vitest'
+import {
+	bestImageSource,
+	contentAxisOffset,
+	contentFitToStretch,
+	contentRect,
+	imageSrcSet,
+	isCenteredContentPosition,
+	needsContentRect,
+	objectPositionCSSValue,
+	resolveContentFit,
+	resolveContentPosition,
+} from './image-content'
+
+const CENTER = { top: '50%', left: '50%' } as const
+
+describe('resolveContentFit / resolveContentPosition', () => {
+	it('defaults to cover and 50%/50%', () => {
+		expect(resolveContentFit(undefined)).toBe('cover')
+		expect(resolveContentPosition(undefined)).toEqual(CENTER)
+	})
+
+	it('maps keyword shorthands like expo-image', () => {
+		expect(resolveContentPosition('top right')).toEqual({ top: 0, right: 0 })
+		expect(resolveContentPosition('bottom')).toEqual({ bottom: 0, left: '50%' })
+		expect(resolveContentPosition('left center')).toEqual({ top: '50%', left: 0 })
+	})
+
+	it('falls back to center for invalid keywords', () => {
+		expect(resolveContentPosition('diagonal' as any)).toEqual(CENTER)
+	})
+
+	it('detects centered positions including explicit 50% edges', () => {
+		expect(isCenteredContentPosition({})).toBe(true)
+		expect(isCenteredContentPosition({ left: '50%' })).toBe(true)
+		expect(isCenteredContentPosition({ right: '50%' })).toBe(true)
+		expect(isCenteredContentPosition({ left: 'center' })).toBe(true)
+		expect(isCenteredContentPosition({ top: 0 })).toBe(false)
+		expect(isCenteredContentPosition({ left: 10 })).toBe(false)
+		expect(isCenteredContentPosition({ right: '25%' })).toBe(false)
+	})
+})
+
+describe('contentAxisOffset', () => {
+	const img = 200
+	const view = 400
+
+	it('centers by default and honors percentages over the free space', () => {
+		expect(contentAxisOffset(view, img, undefined, undefined)).toBe(100)
+		expect(contentAxisOffset(view, img, '0%', undefined)).toBe(0)
+		expect(contentAxisOffset(view, img, '25%', undefined)).toBe(50)
+		expect(contentAxisOffset(view, img, 'center', undefined)).toBe(100)
+	})
+
+	it('measures absolute dips from the named edge', () => {
+		expect(contentAxisOffset(view, img, 10, undefined)).toBe(10)
+		expect(contentAxisOffset(view, img, undefined, 10)).toBe(view - img - 10)
+		expect(contentAxisOffset(view, img, undefined, '75%')).toBe(50)
+	})
+})
+
+describe('contentRect', () => {
+	// 200x100 image inside a 400x300 box
+	it('contain letterboxes centered', () => {
+		expect(contentRect('contain', CENTER, 400, 300, 200, 100)).toEqual({
+			x: 0,
+			y: 50,
+			width: 400,
+			height: 200,
+		})
+	})
+
+	it('cover overflows evenly with negative offset', () => {
+		expect(contentRect('cover', CENTER, 400, 300, 200, 100)).toEqual({
+			x: -100,
+			y: 0,
+			width: 600,
+			height: 300,
+		})
+	})
+
+	it('cover + top left anchors the crop', () => {
+		expect(contentRect('cover', { top: 0, left: 0 }, 400, 300, 200, 100)).toEqual({
+			x: 0,
+			y: 0,
+			width: 600,
+			height: 300,
+		})
+	})
+
+	it('cover + right 25% shifts into the overflow', () => {
+		expect(contentRect('cover', { right: '25%', top: '50%' }, 400, 300, 200, 100).x).toBe(-150)
+	})
+
+	it('fill ignores position entirely', () => {
+		expect(contentRect('fill', { top: 0, left: 0 }, 400, 300, 200, 100)).toEqual({
+			x: 0,
+			y: 0,
+			width: 400,
+			height: 300,
+		})
+	})
+
+	it('none keeps the intrinsic size, centered', () => {
+		expect(contentRect('none', CENTER, 400, 300, 200, 100)).toEqual({
+			x: 100,
+			y: 100,
+			width: 200,
+			height: 100,
+		})
+	})
+
+	it('scale-down shrinks to contain when the image is bigger, else none', () => {
+		expect(contentRect('scale-down', CENTER, 400, 300, 800, 600)).toEqual({
+			x: 0,
+			y: 0,
+			width: 400,
+			height: 300,
+		})
+
+		expect(contentRect('scale-down', CENTER, 400, 300, 200, 100)).toEqual({
+			x: 100,
+			y: 100,
+			width: 200,
+			height: 100,
+		})
+	})
+
+	it('absolute dip positions pin to the named edge', () => {
+		const rect = contentRect('contain', { bottom: 10, right: 20 }, 400, 300, 200, 100)
+		// content is 400x200 → bottom-edge offset = 300-200-10, right = 400-400-20
+		expect(rect.y).toBe(90)
+		expect(rect.x).toBe(-20)
+	})
+})
+
+describe('needsContentRect / contentFitToStretch', () => {
+	it('uses the fast path for expressible fits', () => {
+		expect(needsContentRect('cover', CENTER)).toBe(false)
+		expect(needsContentRect('contain', CENTER)).toBe(false)
+		expect(needsContentRect('fill', CENTER)).toBe(false)
+		// fill's rect is the whole box — position can't change it
+		expect(needsContentRect('fill', { top: 0, left: 0 })).toBe(false)
+	})
+
+	it('needs the computed path for none, scale-down, and positioned content', () => {
+		expect(needsContentRect('none', CENTER)).toBe(true)
+		expect(needsContentRect('scale-down', CENTER)).toBe(true)
+		expect(needsContentRect('cover', { top: 0 })).toBe(true)
+		expect(needsContentRect('contain', { left: '25%' })).toBe(true)
+	})
+
+	it('maps fits onto the stretch vocabulary', () => {
+		expect(contentFitToStretch('contain')).toBe('aspectFit')
+		expect(contentFitToStretch('cover')).toBe('aspectFill')
+		expect(contentFitToStretch('fill')).toBe('fill')
+	})
+})
+
+describe('bestImageSource', () => {
+	const sources = [
+		{ uri: 'https://img.example/photo-100.jpg', width: 100, height: 100 },
+		{ uri: 'https://img.example/photo-400.jpg', width: 400, height: 400 },
+		{ uri: 'https://img.example/photo-1600.jpg', width: 1600, height: 1600 },
+	]
+
+	it('picks the closest pixel count to the view', () => {
+		// 200x200 dips at scale 3 → 600x600 device px → closest is 400²
+		const best = bestImageSource(sources, 200, 200, 3)
+		expect(best?.uri).toBe('https://img.example/photo-400.jpg')
+	})
+
+	it('weighs the source scale multiplier', () => {
+		const dense = [
+			{ uri: 'a', width: 100, height: 100, scale: 1 },
+			{ uri: 'b', width: 100, height: 100, scale: 3 },
+		]
+
+		// 100 dips at scale 3 → 300px target; b is 300px-worth, a is 100
+		expect(bestImageSource(dense, 100, 100, 3)?.uri).toBe('b')
+	})
+
+	it('returns the only source, and nothing before a real layout', () => {
+		expect(bestImageSource(sources, 0, 0, 3)).toBeNull()
+		expect(bestImageSource([sources[0]], 100, 100, 1)?.uri).toBe(sources[0].uri)
+	})
+
+	it('skips unsized sources when sized candidates exist', () => {
+		const mixed = [{ uri: 'unsized' }, sources[1]]
+		expect(bestImageSource(mixed, 100, 100, 3)?.uri).toBe(sources[1].uri)
+	})
+})
+
+describe('objectPositionCSSValue / imageSrcSet', () => {
+	it('emits edge-value object-position', () => {
+		expect(objectPositionCSSValue({ top: 0, right: '25%' })).toBe('top 0px right 25%')
+		expect(objectPositionCSSValue({ bottom: 10, left: '50%' })).toBe('bottom 10px left 50%')
+		expect(objectPositionCSSValue({})).toBe('top 50% left 50%')
+	})
+
+	it('builds w-descriptor srcset from width·scale', () => {
+		const { src, srcSet } = imageSrcSet([
+			{ uri: 'a.jpg', width: 100, height: 100 },
+			{ uri: 'b.jpg', width: 200, height: 200, scale: 2 },
+		])
+
+		expect(srcSet).toBe('a.jpg 100w, b.jpg 400w')
+		expect(src).toBe('b.jpg')
+	})
+
+	it('builds x-descriptor srcset when only density is known', () => {
+		const { srcSet } = imageSrcSet([
+			{ uri: 'a.png', scale: 1 },
+			{ uri: 'a@2x.png', scale: 2 },
+		])
+
+		expect(srcSet).toBe('a.png 1x, a@2x.png 2x')
+	})
+})