@octane-xplat/ui 0.10.0 → 0.11.1

package/src/image-content.ts

@@ -0,0 +1,309 @@
+import type {
+	ImageContentFit,
+	ImageContentPosition,
+	ImageContentPositionObject,
+	ImageContentPositionValue,
+	ImageSourceLike,
+} from './props'
+
+/** Shared `contentFit`/`contentPosition` + multi-source math for `Image` —
+ *  pure functions used by every leaf (docs/notes/expo-image-study.md L7/L8).
+ *  Semantics mirror CSS `object-fit`/`object-position`, which is also
+ *  expo-image's contract: the leaves compute the drawn-content rect
+ *  themselves instead of delegating to platform scaleType/contentMode,
+ *  so all platforms get the same answer.
+ *
+ *  The default fit is 'cover' everywhere (the expo/RN default). Today's
+ *  platform defaults disagree — web <img> is 'fill' and NS stretch is
+ *  'aspectFit' — so an un-propped Image was silently divergent. */
+
+export const DEFAULT_CONTENT_FIT: ImageContentFit = 'cover'
+
+export function resolveContentFit(fit?: ImageContentFit): ImageContentFit {
+	return fit ?? DEFAULT_CONTENT_FIT
+}
+
+/** expo-image's keyword shorthands; the object form positions relative to
+ *  any corner pair ({top,left}, {top,right}, {bottom,left}, {bottom,right}). */
+const POSITION_KEYWORDS: Record<string, ImageContentPositionObject> = {
+	center: { top: '50%', left: '50%' },
+	top: { top: 0, left: '50%' },
+	right: { top: '50%', right: 0 },
+	bottom: { bottom: 0, left: '50%' },
+	left: { top: '50%', left: 0 },
+	'top center': { top: 0, left: '50%' },
+	'top right': { top: 0, right: 0 },
+	'top left': { top: 0, left: 0 },
+	'right center': { top: '50%', right: 0 },
+	'right top': { top: 0, right: 0 },
+	'right bottom': { bottom: 0, right: 0 },
+	'bottom center': { bottom: 0, left: '50%' },
+	'bottom right': { bottom: 0, right: 0 },
+	'bottom left': { bottom: 0, left: 0 },
+	'left center': { top: '50%', left: 0 },
+	'left top': { top: 0, left: 0 },
+	'left bottom': { bottom: 0, left: 0 },
+}
+
+export function resolveContentPosition(
+	position?: ImageContentPosition,
+): ImageContentPositionObject {
+	if (typeof position === 'string') {
+		return POSITION_KEYWORDS[position] ?? POSITION_KEYWORDS.center
+	}
+
+	return position ?? POSITION_KEYWORDS.center
+}
+
+type AxisValue = { percent: number } | { dips: number }
+
+function parseAxisValue(value: ImageContentPositionValue | undefined): AxisValue | null {
+	if (value == null) {
+		return null
+	}
+
+	if (typeof value === 'number') {
+		return { dips: value }
+	}
+
+	const text = String(value).trim()
+	if (text === 'center') {
+		return { percent: 50 }
+	}
+
+	if (text.endsWith('%')) {
+		const parsed = Number.parseFloat(text)
+		return Number.isNaN(parsed) ? null : { percent: parsed }
+	}
+
+	const parsed = Number.parseFloat(text)
+	return Number.isNaN(parsed) ? null : { dips: parsed }
+}
+
+/** Offset of the drawn content's start edge inside the view along one axis.
+ *  expo-image `calcTranslation`: percentages run over the free space
+ *  (view − content), absolute dips measure from the named edge, and the
+ *  reverse edge (right/bottom) counts back from the far side. */
+export function contentAxisOffset(
+	viewSize: number,
+	contentSize: number,
+	start: ImageContentPositionValue | undefined,
+	end: ImageContentPositionValue | undefined,
+): number {
+	const from = parseAxisValue(start)
+	if (from) {
+		return 'percent' in from ? (from.percent / 100) * (viewSize - contentSize) : from.dips
+	}
+
+	const to = parseAxisValue(end)
+	if (to) {
+		return 'percent' in to
+			? (1 - to.percent / 100) * (viewSize - contentSize)
+			: viewSize - contentSize - to.dips
+	}
+
+	return (viewSize - contentSize) / 2
+}
+
+function centeredAxis(
+	start: ImageContentPositionValue | undefined,
+	end: ImageContentPositionValue | undefined,
+): boolean {
+	const from = parseAxisValue(start)
+	if (from) {
+		return 'percent' in from && from.percent === 50
+	}
+
+	const to = parseAxisValue(end)
+	if (to) {
+		return 'percent' in to && to.percent === 50
+	}
+
+	return true
+}
+
+export function isCenteredContentPosition(position: ImageContentPositionObject): boolean {
+	return (
+		centeredAxis(position.left, position.right) && centeredAxis(position.top, position.bottom)
+	)
+}
+
+/** The rect the bitmap occupies inside the view box, in the same units the
+ *  caller measures with (native: dips; web: CSS px via object-fit anyway —
+ *  only the native leaf calls this). Every length unit is dips except the
+ *  intrinsic size, which the leaf must supply in dips too. */
+export function contentRect(
+	fit: ImageContentFit,
+	position: ImageContentPositionObject,
+	viewWidth: number,
+	viewHeight: number,
+	imageWidth: number,
+	imageHeight: number,
+): { x: number; y: number; width: number; height: number } {
+	let width: number
+	let height: number
+	switch (fit) {
+		case 'fill':
+			width = viewWidth
+			height = viewHeight
+			break
+		case 'cover': {
+			const scale = Math.max(viewWidth / imageWidth, viewHeight / imageHeight)
+			width = imageWidth * scale
+			height = imageHeight * scale
+			break
+		}
+		case 'scale-down': {
+			const scale = Math.min(1, Math.min(viewWidth / imageWidth, viewHeight / imageHeight))
+			width = imageWidth * scale
+			height = imageHeight * scale
+			break
+		}
+		case 'none':
+			width = imageWidth
+			height = imageHeight
+			break
+		default: {
+			// 'contain'
+			const scale = Math.min(viewWidth / imageWidth, viewHeight / imageHeight)
+			width = imageWidth * scale
+			height = imageHeight * scale
+		}
+	}
+
+	return {
+		x: contentAxisOffset(viewWidth, width, position.left, position.right),
+		y: contentAxisOffset(viewHeight, height, position.top, position.bottom),
+		width,
+		height,
+	}
+}
+
+/** True when no platform stretch/scaleType can express the request and the
+ *  leaf must measure + lay out the image itself: 'none' (iOS maps NS
+ *  stretch='none' to TopLeft, not CSS centered), 'scale-down' (needs the
+ *  intrinsic-vs-view compare), or any non-center position. 'fill' is
+ *  exempt — its rect is always the whole box, so position can't matter. */
+export function needsContentRect(
+	fit: ImageContentFit,
+	position: ImageContentPositionObject,
+): boolean {
+	if (fit === 'none' || fit === 'scale-down') {
+		return true
+	}
+
+	return fit !== 'fill' && !isCenteredContentPosition(position)
+}
+
+/** NS `stretch` for the fast path — only reached for fits the platform
+ *  vocabulary expresses identically (contain/cover/fill centered). */
+export function contentFitToStretch(fit: ImageContentFit): 'aspectFit' | 'aspectFill' | 'fill' {
+	switch (fit) {
+		case 'contain':
+			return 'aspectFit'
+		case 'fill':
+			return 'fill'
+		default:
+			return 'aspectFill'
+	}
+}
+
+/** L8 — expo `getBestSource`: the source whose declared pixel count
+ *  (`width·height·scale²`, dips × density) is closest to the view's pixel
+ *  count. Needs a real measured size; one source or no size picks nothing
+ *  to decide. Unsized sources score worst and are skipped when any sized
+ *  candidate exists. */
+export function bestImageSource(
+	sources: readonly ImageSourceLike[],
+	viewWidth: number,
+	viewHeight: number,
+	screenScale: number,
+): ImageSourceLike | null {
+	if (sources.length === 0 || viewWidth <= 0 || viewHeight <= 0) {
+		return null
+	}
+
+	if (sources.length === 1) {
+		return sources[0]
+	}
+
+	const target = viewWidth * viewHeight * screenScale * screenScale
+	let best: ImageSourceLike | null = null
+	let bestFit = Infinity
+	for (const source of sources) {
+		const pixelCount = (source.width ?? 0) * (source.height ?? 0) * (source.scale ?? 1) ** 2
+		const fit = Math.abs(1 - pixelCount / target)
+		if (fit < bestFit) {
+			best = source
+			bestFit = fit
+		}
+	}
+
+	return best
+}
+
+function ensureWebUnits(value: ImageContentPositionValue): string {
+	const text = String(value).trim()
+	return text.endsWith('%') ? text : `${text}px`
+}
+
+/** Browser `object-position` for a resolved position — mirrors expo-image
+ *  web's `getObjectPositionFromContentPositionObject`. */
+export function objectPositionCSSValue(position: ImageContentPositionObject): string {
+	const resolved: ImageContentPositionObject = { ...position }
+	if (resolved.top == null && resolved.bottom == null) {
+		resolved.top = '50%'
+	}
+
+	if (resolved.left == null && resolved.right == null) {
+		resolved.left = '50%'
+	}
+
+	return (
+		(['top', 'bottom', 'left', 'right'] as const)
+			.map((edge) => (resolved[edge] != null ? `${edge} ${ensureWebUnits(resolved[edge]!)}` : ''))
+			.filter((part) => part !== '')
+			.join(' ') || '50% 50%'
+	)
+}
+
+/** Browser `srcset` candidates for a source array: `w` descriptors (real
+ *  file px = width·scale) when every source is sized, `x` descriptors when
+ *  every source only carries density. `src` falls back to the largest
+ *  declared pixel count — guaranteed coverage where srcset is ignored. */
+export function imageSrcSet(sources: readonly ImageSourceLike[]): {
+	src: string
+	srcSet?: string
+} {
+	if (sources.length === 0) {
+		return { src: '' }
+	}
+
+	const everyWidth = sources.every(
+		(source) => typeof source.width === 'number' && source.width > 0,
+	)
+
+	const everyScale =
+		!everyWidth &&
+		sources.every((source) => typeof source.scale === 'number' && source.scale > 0)
+
+	const srcSet = everyWidth
+		? sources
+				.map((source) => `${source.uri} ${Math.round(source.width! * (source.scale ?? 1))}w`)
+				.join(', ')
+		: everyScale
+			? sources.map((source) => `${source.uri} ${source.scale}x`).join(', ')
+			: undefined
+
+	let fallback = sources[0]
+	let bestCount = -Infinity
+	for (const source of sources) {
+		const count = (source.width ?? 0) * (source.height ?? 0) * (source.scale ?? 1) ** 2
+		if (count > bestCount) {
+			bestCount = count
+			fallback = source
+		}
+	}
+
+	return { src: fallback.uri, srcSet }
+}

package/src/image-decoding.web.test.tsrx

@@ -0,0 +1,26 @@
+// @vitest-environment jsdom
+import { afterEach, expect, it } from 'vitest'
+import { act, createRoot } from 'octane'
+import { Image } from './Image.web.tsrx'
+
+const roots: any[] = []
+
+function mount(props: any = {}) {
+	const el = document.createElement('div')
+	document.body.append(el)
+	const root = createRoot(el)
+	roots.push(root)
+	act(() => root.render(<Image {...props} />))
+	return el.firstElementChild as HTMLImageElement
+}
+
+afterEach(() => {
+	for (const root of roots.splice(0)) act(() => root.unmount())
+	document.body.innerHTML = ''
+})
+
+it('writes the HTML decoding attribute — async by default, 1:1 when set', () => {
+	expect(mount({ src: 'https://x/a.png' }).getAttribute('decoding')).toBe('async')
+	expect(mount({ src: 'https://x/a.png', decoding: 'sync' }).getAttribute('decoding')).toBe('sync')
+	expect(mount({ src: 'https://x/a.png', decoding: 'async' }).getAttribute('decoding')).toBe('async')
+})

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

@@ -0,0 +1,113 @@
+/** @jsxImportSource @nativescript-community/octane */
+import { describe, expect, it, vi } from 'vitest'
+import {
+	createObjectContainer,
+	createObjectDriver,
+	createUniversalRoot,
+	flushUniversalSync,
+} from 'octane/universal/native'
+
+vi.mock('@nativescript/core', () => ({
+	isIOS: false,
+	isAndroid: true,
+	Screen: { mainScreen: { scale: 2 } },
+	ImageSource: class {
+		static fromBase64Sync() {
+			return { mocked: 'png' }
+		}
+		static fromResourceSync() {
+			return { mocked: 'res' }
+		}
+		static fromFileSync() {
+			return { mocked: 'file' }
+		}
+	},
+	knownFolders: { currentApp: () => ({ path: '/app' }) },
+}))
+
+// 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'
+
+const BLURHASH = 'blurhash:LEHV6nWB2yk8pyo0adR*.7kCMdnj'
+
+function mount(props: any) {
+	const container = createObjectContainer('nativescript')
+	const root = createUniversalRoot(container, createObjectDriver('nativescript'))
+	root.render(Image as any, props)
+	flushUniversalSync(() => {})
+	return { container, root, host: container.children[0] as any }
+}
+
+function sized(host: any) {
+	host.on = (event: string, fn: () => void) => {
+		if (event === 'layoutChanged') host._layoutCb = fn
+		if (event === 'isLoadingChange') host._loadCb = fn
+	}
+
+	host.off = () => {}
+	host.getMeasuredWidth = () => 300
+	host.getMeasuredHeight = () => 200
+	host.stretch = 'aspectFit'
+}
+
+describe('native Image placeholder (study L5)', () => {
+	it('paints the placeholder bitmap while the binding still holds src', () => {
+		const { host } = mount({ src: 'https://x/photo.png', placeholder: BLURHASH })
+		expect(host.type).toBe('image')
+		// L1 binding: src stays unissued until first layout.
+		expect(host.src).toBeUndefined()
+		expect(host.imageSource).toEqual({ mocked: 'png' })
+	})
+
+	it('re-applies after each src issue and leaves the final bitmap alone on completion', () => {
+		const { root, host } = mount({ src: 'https://x/a.png', placeholder: BLURHASH })
+		expect(host.imageSource).toEqual({ mocked: 'png' })
+		sized(host)
+
+		// Emulate the iOS sequence for a pending load: the previous bitmap was
+		// cleared and isLoading is already true when src is written again.
+		host.imageSource = null
+		host.isLoading = true
+		root.render(Image as any, { src: 'https://x/b.png', placeholder: BLURHASH })
+		flushUniversalSync(() => {})
+
+		// The binding issued the new src and its afterIssue hook repainted the
+		// placeholder — this is the same-src/mid-load gap that fires no
+		// isLoadingChange.
+		expect(host.src).toBe('https://x/b.png')
+		expect(host.decodeWidth).toEqual({ value: 300, unit: 'px' })
+		expect(host.imageSource).toEqual({ mocked: 'png' })
+		expect(host._loadCb).toBeTypeOf('function')
+
+		// Load completes: final bitmap arrives before isLoading goes false →
+		// the placeholder must not clobber it.
+		host.imageSource = { mocked: 'final' }
+		host.isLoading = false
+		host._loadCb()
+		expect(host.imageSource).toEqual({ mocked: 'final' })
+
+		// Failure path: Android clears imageSource on error → the listener
+		// puts the placeholder back (failure-image semantics).
+		host.imageSource = null
+		host._loadCb()
+		expect(host.imageSource).toEqual({ mocked: 'png' })
+	})
+
+	it('ignores a remote placeholder URL and no-ops without placeholder', () => {
+		const { host } = mount({
+			src: 'https://x/photo.png',
+			placeholder: 'https://x/placeholder.png',
+		})
+
+		expect(host.imageSource).toBeUndefined()
+
+		const { host: plain } = mount({ src: 'https://x/photo.png' })
+		expect(plain.imageSource).toBeUndefined()
+	})
+})

package/src/image-placeholder.web.test.tsrx

@@ -0,0 +1,48 @@
+// @vitest-environment jsdom
+import { afterEach, expect, it, vi } from 'vitest'
+import { act, createRoot } from 'octane'
+import { Image } from './Image.web.tsrx'
+
+const roots: any[] = []
+
+function mount(props: any = {}) {
+	vi.useFakeTimers()
+	const el = document.createElement('div')
+	document.body.append(el)
+	const root = createRoot(el)
+	roots.push(root)
+	const render = (next: any = {}) => act(() => root.render(<Image {...props} {...next} />))
+	render()
+	return { root, render, el, img: el.firstElementChild as HTMLImageElement }
+}
+
+afterEach(() => {
+	for (const root of roots.splice(0)) act(() => root.unmount())
+	document.body.innerHTML = ''
+	vi.useRealTimers()
+})
+
+it('serves the placeholder through the same <img>, then swaps to src on placeholder load', () => {
+	const { img } = mount({ src: 'https://x/photo.png', placeholder: 'blurhash:LEHV6nWB2yk8pyo0adR*.7kCMdnj' })
+	expect(img.getAttribute('src')).toMatch(/^data:image\/png;base64,iVBORw0KGgo/)
+	act(() => img.dispatchEvent(new Event('load')))
+	expect(img.getAttribute('src')).toBe('https://x/photo.png')
+})
+
+it('swaps to src when the placeholder errors', () => {
+	const { img } = mount({ src: 'https://x/photo.png', placeholder: 'blurhash:LEHV6nWB2yk8pyo0adR*.7kCMdnj' })
+	act(() => img.dispatchEvent(new Event('error')))
+	expect(img.getAttribute('src')).toBe('https://x/photo.png')
+})
+
+it('passes non-hash placeholders through as plain URLs', () => {
+	const { img } = mount({ src: 'https://x/photo.png', placeholder: 'https://x/tiny.jpg' })
+	expect(img.getAttribute('src')).toBe('https://x/tiny.jpg')
+	act(() => img.dispatchEvent(new Event('load')))
+	expect(img.getAttribute('src')).toBe('https://x/photo.png')
+})
+
+it('does not re-run the placeholder when src is already complete', () => {
+	const { img } = mount({ src: 'https://x/photo.png' })
+	expect(img.getAttribute('src')).toBe('https://x/photo.png')
+})

package/src/image-recycling.mobile.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it, vi } from 'vitest'
+import {
+	createObjectContainer,
+	createObjectDriver,
+	createUniversalRoot,
+} from 'octane/universal/native'
+
+vi.mock('@nativescript/core', () => ({
+	isIOS: false,
+	isAndroid: true,
+	ScrollView: class ScrollView {},
+	ImageSource: { fromBase64Sync: (data: string) => ({ base64: data }) },
+}))
+
+// The svg leaf registers <svgview> via a vendored submodule; raster srcs
+// never consult it, so the test stubs the router out.
+vi.mock('./svg', () => ({
+	isSvgSrc: () => false,
+	svgSource: (src: string) => src,
+}))
+
+import { Image } from './Image'
+
+describe('Image recyclingKey', () => {
+	it('clears the previous bitmap only when a recycled cell binds a new identity', () => {
+		const container = createObjectContainer('nativescript')
+		const root = createUniversalRoot(container, createObjectDriver('nativescript'))
+
+		root.render(Image as any, { src: 'https://img/1.png', recyclingKey: 'a' })
+		const host = container.children[0] as any
+		// The sized binding holds src until the view reports a real layout.
+		host.getMeasuredWidth = () => 800
+		host.getMeasuredHeight = () => 600
+
+		// Simulate a completed load: the native view holds a decoded bitmap.
+		host.imageSource = { bitmap: 'first' }
+
+		// Same identity, new src — the bitmap is still this item's predecessor;
+		// it stays while the sized binding issues the replacement.
+		root.render(Image as any, { src: 'https://img/2.png', recyclingKey: 'a' })
+		expect(host.imageSource).toEqual({ bitmap: 'first' })
+		expect(host.src).toBe('https://img/2.png')
+
+		// Recycled cell rebound to a different item — blank before the new load.
+		root.render(Image as any, { src: 'https://img/3.png', recyclingKey: 'b' })
+		expect(host.imageSource).toBeNull()
+		expect(host.src).toBe('https://img/3.png')
+
+		// New identity but identical src — the bitmap is already correct.
+		host.imageSource = { bitmap: 'third' }
+		root.render(Image as any, { src: 'https://img/3.png', recyclingKey: 'c' })
+		expect(host.imageSource).toEqual({ bitmap: 'third' })
+
+		// No key at all — never blanks on src change.
+		root.render(Image as any, { src: 'https://img/4.png' })
+		expect(host.imageSource).toEqual({ bitmap: 'third' })
+		expect(host.src).toBe('https://img/4.png')
+
+		root.unmount()
+	})
+})