@octane-xplat/ui 0.10.0 → 0.11.0

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

@@ -0,0 +1,158 @@
+import { describe, expect, it, vi } from 'vitest'
+import { createSizedImageBinding } from './image-sizing'
+
+function mockView(width = 0, height = 0) {
+	const handlers = new Map<string, Set<() => void>>()
+	const srcWrites: any[] = []
+	const view: any = {
+		measured: { w: width, h: height },
+		stretch: 'aspectFit',
+		decodeWidth: undefined as any,
+		decodeHeight: undefined as any,
+		srcWrites,
+		on: (event: string, callback: () => void) => {
+			const set = handlers.get(event) ?? new Set()
+			set.add(callback)
+			handlers.set(event, set)
+		},
+		off: (event: string, callback: () => void) => handlers.get(event)?.delete(callback),
+		getMeasuredWidth() {
+			return view.measured.w
+		},
+		getMeasuredHeight() {
+			return view.measured.h
+		},
+		emit(event: string) {
+			for (const callback of handlers.get(event) ?? []) callback()
+		},
+		handlerCount(event: string) {
+			return handlers.get(event)?.size ?? 0
+		},
+	}
+	let src: any
+	Object.defineProperty(view, 'src', {
+		get: () => src,
+		set: (value) => {
+			src = value
+			srcWrites.push(value)
+		},
+		configurable: true,
+	})
+	return view
+}
+
+describe('sized image decode binding', () => {
+	it('holds src until the first real layout, then issues decode dims in device px', () => {
+		const view = mockView(0, 0)
+		const binding = createSizedImageBinding()
+
+		binding.update(view, 'res://feed/photo.jpg')
+		expect(view.src).toBeUndefined()
+		expect(view.decodeWidth).toBeUndefined()
+		expect(view.handlerCount('layoutChanged')).toBe(1)
+
+		view.measured = { w: 300, h: 200 }
+		view.emit('layoutChanged')
+		expect(view.src).toBe('res://feed/photo.jpg')
+		expect(view.decodeWidth).toEqual({ value: 300, unit: 'px' })
+		expect(view.decodeHeight).toEqual({ value: 200, unit: 'px' })
+		expect(view.srcWrites).toHaveLength(1)
+	})
+
+	it('issues immediately when the view is already measured, and repeats are no-ops', () => {
+		const view = mockView(300, 200)
+		const binding = createSizedImageBinding()
+
+		binding.update(view, 'https://img.example/x.png')
+		expect(view.src).toBe('https://img.example/x.png')
+		expect(view.srcWrites).toHaveLength(1)
+
+		binding.update(view, 'https://img.example/x.png')
+		view.emit('layoutChanged')
+		expect(view.srcWrites).toHaveLength(1)
+	})
+
+	it('re-issues on a src change even when the size is unchanged', () => {
+		const view = mockView(300, 200)
+		const binding = createSizedImageBinding()
+
+		binding.update(view, 'res://a.jpg')
+		binding.update(view, 'res://b.jpg')
+		expect(view.src).toBe('res://b.jpg')
+		expect(view.srcWrites).toEqual(['res://a.jpg', 'res://b.jpg'])
+		expect(view.decodeWidth).toEqual({ value: 300, unit: 'px' })
+	})
+
+	it('re-issues at the new size on resize for aspect-fit stretches', () => {
+		const view = mockView(300, 200)
+		const binding = createSizedImageBinding()
+
+		binding.update(view, 'res://a.jpg')
+		view.measured = { w: 600, h: 400 }
+		view.emit('layoutChanged')
+		expect(view.srcWrites).toHaveLength(2)
+		expect(view.decodeWidth).toEqual({ value: 600, unit: 'px' })
+		expect(view.decodeHeight).toEqual({ value: 400, unit: 'px' })
+	})
+
+	it('does not reload on resize for fill or none — the expo-image gate', () => {
+		for (const stretch of ['fill', 'none']) {
+			const view = mockView(300, 200)
+			view.stretch = stretch
+			const binding = createSizedImageBinding()
+
+			binding.update(view, 'res://a.jpg')
+			view.measured = { w: 600, h: 400 }
+			view.emit('layoutChanged')
+			expect(view.srcWrites).toHaveLength(1)
+			expect(view.decodeWidth).toEqual({
+				value: stretch === 'fill' ? 300 : 0,
+				unit: 'px',
+			})
+		}
+	})
+
+	it('never downsamples for stretch none — source pixels are the contract', () => {
+		const view = mockView(300, 200)
+		view.stretch = 'none'
+		const binding = createSizedImageBinding()
+
+		binding.update(view, 'res://a.jpg')
+		expect(view.src).toBe('res://a.jpg')
+		expect(view.decodeWidth).toEqual({ value: 0, unit: 'px' })
+		expect(view.decodeHeight).toEqual({ value: 0, unit: 'px' })
+	})
+
+	it('moves the listener to a recreated view and re-issues at its size', () => {
+		const first = mockView(300, 200)
+		const second = mockView(0, 0)
+		const binding = createSizedImageBinding()
+
+		binding.update(first, 'res://a.jpg')
+		expect(first.src).toBe('res://a.jpg')
+
+		binding.update(second, 'res://a.jpg')
+		expect(first.handlerCount('layoutChanged')).toBe(0)
+		expect(second.handlerCount('layoutChanged')).toBe(1)
+		expect(second.src).toBeUndefined()
+
+		second.measured = { w: 100, h: 50 }
+		second.emit('layoutChanged')
+		expect(second.src).toBe('res://a.jpg')
+		expect(second.decodeWidth).toEqual({ value: 100, unit: 'px' })
+	})
+
+	it('keeps a held src pending until layout even across re-renders', () => {
+		const view = mockView(0, 0)
+		const binding = createSizedImageBinding()
+
+		binding.update(view, 'res://a.jpg')
+		binding.update(view, 'res://b.jpg')
+		expect(view.src).toBeUndefined()
+
+		view.measured = { w: 50, h: 50 }
+		view.emit('layoutChanged')
+		expect(view.src).toBe('res://b.jpg')
+		expect(view.srcWrites).toEqual(['res://b.jpg'])
+	})
+})

package/src/image-sizing.ts

@@ -0,0 +1,117 @@
+/** View-sized decode for the native <image> leaf.
+ *
+ *  NS Android reads decodeWidth/decodeHeight only when `src` is written —
+ *  `srcProperty.setNative` → `_createImageSourceFromSrc` →
+ *  `imageView.setUri(value, decodeWidth, decodeHeight, …)` — and the
+ *  properties default to 0 → `Fetcher.calculateInSampleSize` maps
+ *  reqWidth ≤ 0 to the source dims → inSampleSize 1 → a full-resolution
+ *  decode (~48 MB ARGB_8888 per 12 MP photo; docs/notes/expo-image-study.md
+ *  L1). So the leaf holds `src` until the view's first real layout, writes
+ *  the decode dims in device pixels, then assigns src. A later resize
+ *  re-issues at the new size — the same reload expo-image runs from
+ *  onSizeChanged — under the same gate: 'fill'/'none' stretches keep the
+ *  existing decode because a resize can't change the ideal sample there
+ *  ('none' additionally never downsamples — its contract is source
+ *  pixels). iOS ignores the decode dims entirely; the deferred assignment
+ *  is behavior-identical there, so one path serves both platforms.
+ *
+ *  The ref callback re-fires on every render (identity change), so
+ *  `update` must be idempotent: same view + same src + same size is a
+ *  no-op. Null ref calls on detach are ignored by the leaf — re-attaching
+ *  the same view must not lose `applied`, or each render would re-issue
+ *  setUri. The dead-view listener left behind on real unmount is a
+ *  self-contained cycle the GC collects with the component record.
+ *
+ *  `afterIssue` runs right after every `src` write — including a same-src
+ *  resize re-issue mid-load, which fires no `isLoadingChange` (isLoading is
+ *  already true). The Image placeholder hooks this to re-apply its bitmap
+ *  after the write has nulled `imageSource` (L5, decision #103). */
+export function createSizedImageBinding(options: { afterIssue?: (view: any) => void } = {}) {
+	let view: any = null;
+	let listening = false;
+	let pendingSrc: any;
+	let pendingStretch: string | undefined;
+	let appliedSrc: any;
+	let applied = false;
+	let width = 0;
+	let height = 0;
+
+	const issue = (next: any) => {
+		// `pendingStretch` overrides view.stretch for the decode gates when the
+		// content-rect path draws stretch='fill' under a different semantic fit
+		// ('none' needs the full-resolution source to find the natural size).
+		const downscale = (pendingStretch ?? view.stretch) !== 'none';
+		view.decodeWidth = { value: downscale ? width : 0, unit: 'px' };
+		view.decodeHeight = { value: downscale ? height : 0, unit: 'px' };
+		view.src = next;
+		appliedSrc = next;
+		applied = true;
+		options.afterIssue?.(view);
+	};
+
+	const evaluate = () => {
+		if (!view) {
+			return;
+		}
+
+		const measuredWidth = view.getMeasuredWidth?.() ?? 0;
+		const measuredHeight = view.getMeasuredHeight?.() ?? 0;
+		// Hold the request until a real layout — writing src sooner decodes
+		// at the default 0 dims (full source resolution).
+		if (measuredWidth <= 0 || measuredHeight <= 0) {
+			return;
+		}
+
+		if (!applied || pendingSrc !== appliedSrc) {
+			width = measuredWidth;
+			height = measuredHeight;
+			issue(pendingSrc);
+			return;
+		}
+
+		if (measuredWidth === width && measuredHeight === height) {
+			return;
+		}
+
+		const stretch = pendingStretch ?? view.stretch;
+		if (stretch === 'fill' || stretch === 'none') {
+			return;
+		}
+
+		width = measuredWidth;
+		height = measuredHeight;
+		issue(appliedSrc);
+	};
+
+	const onLayout = () => evaluate();
+
+	return {
+		/** (Re)bind source → view; issues once the view reports a real layout.
+		 *  `stretchForDecode` overrides view.stretch for the decode/reload
+		 *  gates — see `issue`. */
+		update(next: any, source: any, stretchForDecode?: string): void {
+			if (next !== view) {
+				view?.off?.('layoutChanged', onLayout);
+				view = next;
+				listening = false;
+				applied = false;
+				appliedSrc = undefined;
+			}
+
+			pendingSrc = source;
+			pendingStretch = stretchForDecode;
+			if (view && !listening && typeof view.on === 'function') {
+				view.on('layoutChanged', onLayout);
+				listening = true;
+			}
+
+			evaluate();
+		},
+		dispose(): void {
+			view?.off?.('layoutChanged', onLayout);
+			view = null;
+			listening = false;
+			applied = false;
+		},
+	};
+}

package/src/image.mobile.test.tsrx

@@ -0,0 +1,81 @@
+/** @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,
+	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'
+
+describe('native Image sized decode', () => {
+	it('defers src until first layout, issues decode dims in device px, and re-issues per the stretch gate', () => {
+		const container = createObjectContainer('nativescript')
+		const root = createUniversalRoot(container, createObjectDriver('nativescript'))
+		root.render(Image as any, { src: 'res://feed/photo.jpg' })
+		const host = container.children[0] as any
+		expect(host.type).toBe('image')
+		// The leaf owns src imperatively — the driver never saw it.
+		expect(host.props.src).toBeUndefined()
+		expect(host.src).toBeUndefined()
+
+		let layoutCb: (() => void) | null = null
+		host.on = (event: string, cb: () => void) => {
+			if (event === 'layoutChanged') layoutCb = cb
+		}
+
+		host.off = () => {}
+		host.getMeasuredWidth = () => 300
+		host.getMeasuredHeight = () => 200
+		host.stretch = 'aspectFit'
+
+		root.render(Image as any, { src: 'res://feed/photo.jpg', id: 'rebind' })
+		expect(host.src).toBe('res://feed/photo.jpg')
+		expect(host.decodeWidth).toEqual({ value: 300, unit: 'px' })
+		expect(host.decodeHeight).toEqual({ value: 200, unit: 'px' })
+
+		host.getMeasuredWidth = () => 600
+		layoutCb!()
+		expect(host.decodeWidth).toEqual({ value: 600, unit: 'px' })
+		expect(host.src).toBe('res://feed/photo.jpg')
+
+		host.stretch = 'fill'
+		host.getMeasuredWidth = () => 900
+		layoutCb!()
+		expect(host.decodeWidth).toEqual({ value: 600, unit: 'px' })
+
+		root.render(Image as any, { src: 'res://feed/other.jpg' })
+		expect(host.src).toBe('res://feed/other.jpg')
+		expect(host.decodeWidth).toEqual({ value: 900, unit: 'px' })
+		root.unmount()
+	})
+
+	it('maps decoding to NS loadMode — async by default, sync when requested', () => {
+		const container = createObjectContainer('nativescript')
+		const root = createUniversalRoot(container, createObjectDriver('nativescript'))
+
+		root.render(Image as any, { src: 'res://feed/photo.jpg' })
+		expect((container.children[0] as any).props.loadMode).toBe('async')
+
+		root.render(Image as any, { src: 'res://feed/photo.jpg', decoding: 'sync' })
+		expect((container.children[0] as any).props.loadMode).toBe('sync')
+
+		root.render(Image as any, { src: 'res://feed/photo.jpg', decoding: 'async' })
+		expect((container.children[0] as any).props.loadMode).toBe('async')
+		root.unmount()
+	})
+})

package/src/index.macos.ts

@@ -272,6 +272,7 @@ export { SafeArea } from './layout-shells.macos.tsrx'
 export { KeyboardAvoiding } from './KeyboardAvoiding.macos.tsrx'
 export type { KeyboardAvoidingProps } from './props'
 export { useSafeAreaInsets } from './safeAreaInsets.macos.tsrx'
+export type { SafeAreaInsets } from './safeAreaInsets.macos.tsrx'
 export { useMeasure } from './useMeasure.macos.tsrx'
 export { Meter, Heading } from './macos-extras.macos.tsrx'
 export { Icon } from './Icon.macos.tsrx'

package/src/index.shared.ts

@@ -837,6 +837,13 @@ export type {
 	DrawerProps,
 	GridProps,
 	ImageProps,
+	ImageContentFit,
+	ImageContentPosition,
+	ImageContentPositionObject,
+	ImageContentPositionString,
+	ImageContentPositionValue,
+	ImageDecoding,
+	ImageSourceLike,
 	KeyboardAvoidingProps,
 	LayoutChildProps,
 	PressableProps,

package/src/index.shared.web.ts

@@ -838,6 +838,13 @@ export type {
 	DrawerProps,
 	GridProps,
 	ImageProps,
+	ImageContentFit,
+	ImageContentPosition,
+	ImageContentPositionObject,
+	ImageContentPositionString,
+	ImageContentPositionValue,
+	ImageDecoding,
+	ImageSourceLike,
 	KeyboardAvoidingProps,
 	LayoutChildProps,
 	PressableProps,

package/src/list-viewability-observer.ios.ts

@@ -42,6 +42,7 @@ export function observeListViewability(
 					const top = offset + Number(insets?.top ?? 0)
 					const bottom =
 						offset + Number(table.bounds?.size?.height ?? 0) - Number(insets?.bottom ?? 0)
+
 					const rows: VisibleListRow[] = []
 					const paths = Array.from(table.indexPathsForVisibleRows ?? []) as NSIndexPath[]
 					for (const path of paths) {

package/src/list-viewability.mobile.test.ts

@@ -101,6 +101,7 @@ describe('platform list viewability', () => {
 			{ minimumViewTime: 0 },
 			onChange,
 		)
+
 		tracker.update([{ index: 1, visiblePercent: 100 }], ['active', 'pending'], undefined, onChange)
 		tracker.reset()
 		vi.advanceTimersByTime(250)

package/src/props.ts

@@ -390,6 +390,8 @@ export interface RichTextProps extends LayoutChildProps {
 	style?: any
 	children?: any
 	id?: string
+	/** Optional explicit accessible name override for the text block. */
+	accessibilityLabel?: string
 	/** Platform-specific properties are applied after shared props. */
 	ios?: any
 	android?: any
@@ -1196,12 +1198,105 @@ export interface WebViewProps extends LayoutChildProps, AccessibilityProps {
 	web?: any
 }
 
+/** A density/size-qualified entry in a multi-resolution `Image.src` array —
+ *  the native `srcset` analog. `uri` takes the same grammar as a string
+ *  `src`. `width`/`height` declare the source's display size (dips) and
+ *  `scale` its density multiplier, so file pixels are `width·scale`: the
+ *  selector compares `width·height·scale²` against the view's pixel count
+ *  and loads the closest match once a real layout exists. */
+export interface ImageSourceLike {
+	uri: string
+	width?: number
+	height?: number
+	scale?: number
+}
+
+/** How the bitmap is sized inside the element's box — the CSS `object-fit`
+ *  vocabulary (same contract as expo-image `contentFit`). Default 'cover'. */
+export type ImageContentFit = 'cover' | 'contain' | 'fill' | 'none' | 'scale-down'
+
+/** One edge value in a `contentPosition`: dips from the named edge, a
+ *  percentage of the free space along that axis, or 'center' (= '50%'). */
+export type ImageContentPositionValue = number | `${number}%` | 'center'
+
+export interface ImageContentPositionObject {
+	top?: ImageContentPositionValue
+	right?: ImageContentPositionValue
+	bottom?: ImageContentPositionValue
+	left?: ImageContentPositionValue
+}
+
+export type ImageContentPositionString =
+	| 'center'
+	| 'top'
+	| 'right'
+	| 'bottom'
+	| 'left'
+	| 'top center'
+	| 'top right'
+	| 'top left'
+	| 'right center'
+	| 'right top'
+	| 'right bottom'
+	| 'bottom center'
+	| 'bottom right'
+	| 'bottom left'
+	| 'left center'
+	| 'left top'
+	| 'left bottom'
+
+/** Where the drawn bitmap sits inside the element's box — CSS
+ *  `object-position`. A keyword string, or an object naming one horizontal
+ *  and one vertical edge. Default centered on every platform. */
+export type ImageContentPosition = ImageContentPositionObject | ImageContentPositionString
+
+/** When the bitmap is decoded — the HTML `decoding` attribute's vocabulary.
+ *  'async' decodes off the UI thread, 'sync' decodes during the `src`
+ *  assignment. */
+export type ImageDecoding = 'async' | 'sync'
+
 export interface ImageProps extends LayoutChildProps {
 	className?: any
 	style?: any
 	id?: string
-	src: string
+	/** A single source — `res://name`, `~/bundle-path`, file path, remote
+	 *  URL, or data:/inline-SVG URI — or a resolution-qualified array
+	 *  (closest pixel count wins; the `srcset` model). */
+	src: string | ImageSourceLike[]
 	alt?: string
+	/** Placeholder shown while `src` loads — painted inside the same image
+	 *  view so the swap can't blank or mismatch fit (expo-image study L5).
+	 *  Accepts `blurhash:<hash>` / `thumbhash:<base64>` (decoded to a small
+	 *  PNG in JS) plus any synchronously resolvable `src` grammar (`data:`
+	 *  base64, `res://name`, `~/`, file path). Remote URLs are ignored on
+	 *  native — a placeholder that must fetch first is pointless. On web any
+	 *  `img.src` URL works (e.g. a low-res image). No-op on macOS, where
+	 *  image loads are synchronous. Ignored for SVG srcs. */
+	placeholder?: string
+	/** Item identity for recycled platform-list cells (RecyclerView/UITableView
+	 *  rebind the same view). When the key changes between binds, the previous
+	 *  bitmap is cleared before the new `src` load starts, so the cell never
+	 *  flashes the prior item's image (expo-image's `recyclingKey`). Web and
+	 *  macOS leaves ignore it: their lists remount keyed rows rather than
+	 *  rebinding a reused host. */
+	recyclingKey?: string
+	/** Bitmap sizing inside the box — CSS `object-fit`. Default 'cover' on
+	 *  every platform (the platform-native defaults disagree: web `img` is
+	 *  `fill`, NS stretch is `aspectFit`). */
+	contentFit?: ImageContentFit
+	/** Bitmap alignment inside the box — CSS `object-position`. Native
+	 *  honors it by laying out the image itself (measured path), so
+	 *  arbitrary positions match web pixel-for-pixel. */
+	contentPosition?: ImageContentPosition
+	/** Decode scheduling hint — the HTML `decoding` attribute. 'async'
+	 *  (default): the bitmap decodes off the UI thread and may paint a frame
+	 *  late. 'sync': decoded during the `src` assignment, blocking the UI
+	 *  thread — for small bitmaps that must appear without a flicker.
+	 *  Native maps to NS `loadMode` for file/resource/data srcs; remote URLs
+	 *  always decode async and font-icon srcs are always sync regardless.
+	 *  Web writes the `decoding` attribute. macOS ignores it — AppKit image
+	 *  loads are synchronous. */
+	decoding?: ImageDecoding
 	/** Platform-specific properties are applied after shared props. */
 	ios?: any
 	android?: any
@@ -1262,6 +1357,8 @@ export interface SwitchProps extends FieldControlProps {
 	className?: any
 	style?: any
 	id?: string
+	/** Optional explicit accessible name override for the switch. */
+	accessibilityLabel?: string
 	checked?: boolean
 	onCheckedChange?: (checked: boolean) => void
 	/** Platform-specific properties are applied after shared props. */
@@ -2289,6 +2386,7 @@ export interface LinkProps {
 	href: string
 	target?: string
 	className?: any
+	style?: any
 	children?: any
 }
 
@@ -2296,6 +2394,7 @@ export interface NavLinkProps {
 	route: Route
 	activeClassName?: string
 	className?: any
+	style?: any
 	children?: any
 }
 

package/src/safeAreaInsets.macos.tsrx

@@ -1,4 +1,9 @@
-import type { SafeAreaInsets } from './props'
+export interface SafeAreaInsets {
+	top: number
+	right: number
+	bottom: number
+	left: number
+}
 
 /** The AppKit root view begins below the title bar; there are no additional
  * safe-area insets in this window-hosted renderer. */

package/src/styled.macos.tsrx

@@ -5,7 +5,7 @@ import { cx } from './cx'
 export function styled<P extends { className?: any }, V extends Record<string, any>>(
 	Base: (props: P) => any,
 	def: { base?: any; variants?: V },
-) {
+): (props: P & { [K in keyof V]?: boolean }, context: any) => any {
 	function Styled(props: P & { [K in keyof V]?: boolean }) {
 		const classes: any[] = [def.base]
 		const rest: any = { ...props }

package/src/vendor/ui-svg/src/index.android.ts

@@ -55,7 +55,11 @@ class SVGExternalFileResolver extends com.caverock.androidsvg.SVGExternalFileRes
 		if (fontFamily) {
 			fontFamily = fontFamily.replace(/\\\//, '/')
 		}
-		return new Font(fontFamily, undefined as any, fontStyle.toLowerCase() as any, (fontWeight + '') as any).getAndroidTypeface()
+		return Font.default
+			.withFontFamily(fontFamily)
+			.withFontStyle(fontStyle.toLowerCase() as any)
+			.withFontWeight((fontWeight + '') as any)
+			.getAndroidTypeface()
 	}
 
 	override resolveImage(filename: string): globalAndroid.graphics.Bitmap {