@octane-xplat/ui 0.9.0 → 0.10.0

package/src/VirtualList.mobile.test.tsrx

@@ -2,7 +2,7 @@
 import { useState } from 'octane'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { createObjectContainer, createObjectDriver, createUniversalRoot } from 'octane/universal/native'
-import { VirtualList } from './VirtualList.tsrx'
+import { VirtualList } from './VirtualList'
 import { VirtualListSizeIndex } from './virtual-list-layout'
 
 vi.mock('@nativescript/core', () => ({ isAndroid: true, isIOS: false }))
@@ -32,7 +32,26 @@ async function mount(viewportWidth = 100, itemRenderer = renderItem) {
 	const prepare = driver.prepareBatch
 	driver.prepareBatch = (...args) => {
 		commits.push(args[1])
-		return prepare(...args)
+		const batch = prepare(...args)
+		const apply = batch.apply
+		batch.apply = () => {
+			apply()
+			for (const node of collect(container.children)) {
+				if (node.on) continue
+				const listeners = new Map<string, Set<(event: any) => void>>()
+				node.on = (name: string, listener: (event: any) => void) => {
+					const set = listeners.get(name) ?? new Set()
+					set.add(listener)
+					listeners.set(name, set)
+				}
+
+				node.off = (name: string, listener: (event: any) => void) => listeners.get(name)?.delete(listener)
+				node.notify = (event: any) => { for (const listener of listeners.get(event.eventName) ?? []) listener(event) }
+				node.layoutListeners = listeners
+			}
+		}
+
+		return batch
 	}
 
 	const root = createUniversalRoot(container, driver)
@@ -45,7 +64,7 @@ async function mount(viewportWidth = 100, itemRenderer = renderItem) {
 	container.dispatchEvent(scroll, 'loaded', { object: scroll })
 	const content = scroll.children[0]
 	content.getActualSize = () => ({ width: 100, height: 500 * 48 })
-	container.dispatchEvent(content, 'layoutchanged', { object: content })
+	content.notify({ eventName: 'layoutChanged', object: content })
 	await vi.advanceTimersByTimeAsync(32)
 	scroll.scrollToVerticalOffset.mockClear()
 	commits.length = 0
@@ -61,10 +80,10 @@ async function mount(viewportWidth = 100, itemRenderer = renderItem) {
 
 		if (!row) throw new Error('Missing row ' + id)
 		row.getActualSize = () => ({ width: 100, height })
-		if (emit) container.dispatchEvent(row, 'layoutchanged', { object: row })
+		if (emit) row.notify({ eventName: 'layoutChanged', object: row })
 	}
 
-	return { container, root, scroll, commits, move, measure }
+	return { container, root, scroll, commits, move, measure, content }
 }
 
 afterEach(() => {
@@ -75,6 +94,51 @@ afterEach(() => {
 })
 
 describe('native VirtualList scroll and measurement scheduling', () => {
+	it('ignores initial host-sized viewport geometry until real layout settles and detaches listeners', async () => {
+		const { root, container, scroll } = await mount()
+		scroll.isLayoutValid = false
+		scroll.getActualSize = () => ({ width: 402, height: 874 })
+		scroll.notify({ eventName: 'layoutChanged', object: scroll })
+		await vi.advanceTimersByTimeAsync(32)
+		const rows = () => collect(container.children).filter(node => node.props.id?.startsWith('row-'))
+		expect(rows().length).toBeLessThan(20)
+		scroll.isLayoutValid = true
+		scroll.getActualSize = () => ({ width: 100, height: 96 })
+		scroll.notify({ eventName: 'layoutChanged', object: scroll })
+		await vi.advanceTimersByTimeAsync(32)
+		expect(rows().length).toBeLessThan(10)
+		const nodes = collect(container.children)
+		root.unmount()
+		await vi.advanceTimersByTimeAsync(0)
+		for (const node of nodes) expect(node.layoutListeners?.get('layoutChanged')?.size ?? 0).toBe(0)
+	})
+
+	it('updates positioned rows and body height when all rows remain in the same visible range', async () => {
+		const { root, container, measure } = await mount()
+		root.render(VirtualList as any, { items: items.slice(0, 3), keyExtractor, renderItem })
+		for (let index = 0; index < 3; index++) measure('row-r' + index, 32)
+		await vi.advanceTimersByTimeAsync(32)
+		const nodes = collect(container.children)
+		const body = nodes.find(node => node.props.className === 'vx-virtual-list-body')
+		expect(body.props.style.height).toBe(96)
+		const cells = nodes.filter(node => String(node.props.className).split(' ').includes('vx-virtual-list-row'))
+		expect(cells.map(node => node.props.top)).toEqual([0, 32, 64])
+	})
+
+	it('re-reads row geometry after an invalid screen-sized layout event', async () => {
+		const { container, measure } = await mount()
+		measure('row-r0', 874, false)
+		const cell = collect(container.children).find(node => String(node.props.className).split(' ').includes('vx-virtual-list-row'))
+		cell.isLayoutValid = false
+		cell.notify({ eventName: 'layoutChanged', object: cell })
+		await vi.advanceTimersByTimeAsync(32)
+		cell.isLayoutValid = true
+		measure('row-r0', 32, false)
+		await vi.advanceTimersByTimeAsync(32)
+		const second = collect(container.children).find(node => node.props.top === 32)
+		expect(second).toBeDefined()
+	})
+
 	it('does not restore an obsolete anchor after the user advances during measurement', async () => {
 		const { scroll, move, measure } = await mount()
 		move(480)

package/src/VirtualList.tsrx

@@ -71,6 +71,7 @@ export function VirtualList<T = any>(props: VirtualListProps<T>) @{
 	const sizeIndexRef = useRef(new VirtualListSizeIndex())
 	const cellsRef = useRef(new VirtualListCellPool<T>())
 	const cellNodesRef = useRef(new Map<number, any>())
+	const layoutListenersRef = useRef(new Map<string, () => void>())
 	const cellCallbacksRef = useRef(new Map<number, (view: any) => void>())
 	const measuredAssignmentsRef = useRef(new Map<number, number>())
 	const sizeCacheRef = useRef(new Map<string, VirtualListSizeRecord>())
@@ -87,6 +88,7 @@ export function VirtualList<T = any>(props: VirtualListProps<T>) @{
 	const headerHeightRef = useRef(0)
 	const estimateTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
 	const frameCancelRef = useRef<(() => void) | null>(null)
+	const viewportFrameCancelRef = useRef<(() => void) | null>(null)
 	const disposedRef = useRef(false)
 	const pendingOffsetDeltaRef = useRef(0)
 	const measurementsRef = useRef(
@@ -94,6 +96,7 @@ export function VirtualList<T = any>(props: VirtualListProps<T>) @{
 	)
 
 	const rangeRef = useRef({ start: -1, end: -1, top: -1, bottom: -1 })
+	const geometryDirtyRef = useRef(false)
 	const pendingAnchorRef = useRef<VirtualListAnchor | null>(null)
 	const pendingAnchorRowsRef = useRef(new Set<string>())
 	const anchorRestoreScheduledRef = useRef(false)
@@ -189,12 +192,14 @@ export function VirtualList<T = any>(props: VirtualListProps<T>) @{
 		const next = currentRange()
 		const previous = rangeRef.current
 		if (
+			geometryDirtyRef.current ||
 			next.start !== previous.start ||
 			next.end !== previous.end ||
 			!sameSize(next.top, previous.top) ||
 			!sameSize(next.bottom, previous.bottom)
 		) {
 			rangeRef.current = next
+			geometryDirtyRef.current = false
 			setWindowVersion((version) => version + 1)
 		}
 	}
@@ -332,6 +337,7 @@ export function VirtualList<T = any>(props: VirtualListProps<T>) @{
 
 		const delta = sizeIndexRef.current.set(index, height)
 		if (Math.abs(delta) >= 0.5) {
+			geometryDirtyRef.current = true
 			const anchorIndex = anchor ? indexByRowKeyRef.current.get(anchor.rowKey) : undefined
 			if (anchor && anchorIndex !== undefined && index < anchorIndex) restoreAnchor(anchor)
 		}
@@ -356,7 +362,7 @@ export function VirtualList<T = any>(props: VirtualListProps<T>) @{
 	}
 
 	function syncViewport(view = scrollRef.current) {
-		if (!view) return
+		if (!view || view.isLoaded === false || view.isLayoutValid === false) return
 		const size = view.getActualSize?.()
 		if (!size) return
 
@@ -375,6 +381,14 @@ export function VirtualList<T = any>(props: VirtualListProps<T>) @{
 		else refreshWindow()
 	}
 
+	function scheduleViewport() {
+		if (disposedRef.current || viewportFrameCancelRef.current) return
+		viewportFrameCancelRef.current = scheduleListFrame(() => {
+			viewportFrameCancelRef.current = null
+			if (!disposedRef.current) syncViewport()
+		})
+	}
+
 	function onScroll(event: any) {
 		const view = event.object ?? scrollRef.current
 		const nextOffset = Number(view?.verticalOffset ?? 0)
@@ -411,15 +425,31 @@ export function VirtualList<T = any>(props: VirtualListProps<T>) @{
 		refreshWindow()
 	}
 
+	function observeLayout(slot: string, view: any, listener: (event: any) => void) {
+		layoutListenersRef.current.get(slot)?.()
+		layoutListenersRef.current.delete(slot)
+		if (!view) return
+		// NativeScript emits camel-case layoutChanged. The universal event
+		// binding lowercases JSX onLayoutChanged, so subscribe by exact name.
+		view.on?.('layoutChanged', listener)
+		layoutListenersRef.current.set(slot, () => view.off?.('layoutChanged', listener))
+	}
+
 	function cellCallback(id: number) {
 		let callback = cellCallbacksRef.current.get(id)
 		if (!callback) {
 			callback = (view: any) => {
 				if (view) {
+					observeLayout('cell:' + id, view, (event) => {
+						const cell = cellsRef.current.get(id)
+						if (cell) onRowLayout(cell, event)
+					})
+
 					// Preserve native widgets when the renderer moves a keyed host.
 					view.reusable = true
 					cellNodesRef.current.set(id, view)
 				} else {
+					observeLayout('cell:' + id, null, () => {})
 					cellNodesRef.current.get(id)?.destroyNode?.(true)
 					cellNodesRef.current.delete(id)
 					cellCallbacksRef.current.delete(id)
@@ -436,7 +466,7 @@ export function VirtualList<T = any>(props: VirtualListProps<T>) @{
 		const entry = cell.entry
 		const size = event.object?.getActualSize?.()
 		if (!entry || !size || disposedRef.current) return
-		measurementsRef.current.set(entry.rowKey, { entry, width: size.width, height: size.height, cellId: cell.id, generation: cell.generation })
+		measurementsRef.current.set(entry.rowKey, { entry, width: size.width, height: size.height, cellId: cell.id, generation: cell.generation, view: event.object })
 		refreshWindow()
 	}
 
@@ -445,10 +475,14 @@ export function VirtualList<T = any>(props: VirtualListProps<T>) @{
 		return () => {
 			disposedRef.current = true
 			frameCancelRef.current?.()
+			viewportFrameCancelRef.current?.()
+			viewportFrameCancelRef.current = null
 			if (estimateTimerRef.current != null) clearTimeout(estimateTimerRef.current)
 			frameCancelRef.current = null
 			estimateTimerRef.current = null
 			measurementsRef.current.clear()
+			for (const detach of layoutListenersRef.current.values()) detach()
+			layoutListenersRef.current.clear()
 			cellsRef.current.clear()
 			cellNodesRef.current.clear()
 			cellCallbacksRef.current.clear()
@@ -488,6 +522,8 @@ export function VirtualList<T = any>(props: VirtualListProps<T>) @{
 	<scrollview
 		ref={(view: any) => {
 			scrollRef.current = view
+			observeLayout('viewport', view, scheduleViewport)
+			if (view) scheduleViewport()
 			if (view) applyEscapeProps(view, props)
 		}}
 		id={props.id}
@@ -502,17 +538,16 @@ export function VirtualList<T = any>(props: VirtualListProps<T>) @{
 		accessibilityValue={props.accessibilityValue}
 		accessibilityState={nativeAccessibilityState(props.accessibilityState) as any}
 		accessibilityLiveRegion={props.accessibilityLiveRegion as any}
-		onLoaded={(event: any) => syncViewport(event.object)}
-		onLayoutChanged={(event: any) => syncViewport(event.object)}
+		onLoaded={scheduleViewport}
 		onScroll={onScroll}
 	>
-		<flexboxlayout flexDirection="column" className={cx('vx-virtual-list-content')} onLayoutChanged={onContentLayout}>
+		<flexboxlayout flexDirection="column" className={cx('vx-virtual-list-content')} ref={(view: any) => observeLayout('content', view, onContentLayout)}>
 			{props.renderHeader ? (
 				<flexboxlayout
 					flexDirection="column"
 					className="vx-virtual-list-header"
 					flexShrink={0}
-					onLayoutChanged={onHeaderLayout}
+					ref={(view: any) => observeLayout('header', view, onHeaderLayout)}
 				>
 					{props.renderHeader()}
 				</flexboxlayout>
@@ -534,7 +569,6 @@ export function VirtualList<T = any>(props: VirtualListProps<T>) @{
 							left={0}
 							top={cell.top}
 							width={contentWidthRef.current || viewportWidthRef.current || '100%'}
-							onLayoutChanged={(event: any) => onRowLayout(cell, event)}
 						>
 							@for (const entry of cell.rows; key entry.rowKey) {
 								<>

package/src/VirtualList.web.test.tsrx

@@ -0,0 +1,113 @@
+// @vitest-environment jsdom
+import { act, createRoot } from 'octane'
+import { afterEach, expect, it, vi } from 'vitest'
+import { VirtualList } from './VirtualList.web.tsrx'
+import { VirtualListSizeIndex } from './virtual-list-layout'
+
+const roots: ReturnType<typeof createRoot>[] = []
+afterEach(() => {
+	for (const root of roots.splice(0)) act(() => root.unmount())
+	document.body.innerHTML = ''
+	vi.restoreAllMocks()
+	vi.unstubAllGlobals()
+})
+
+it('keeps resize measurements immediate but defers estimate renders beyond microtasks', async () => {
+	let deliver: ResizeObserverCallback
+	const observed = new Set<Element>()
+	vi.stubGlobal('ResizeObserver', class {
+		constructor(callback: ResizeObserverCallback) { deliver = callback }
+		observe(node: Element) { observed.add(node) }
+		unobserve(node: Element) { observed.delete(node) }
+		disconnect() { observed.clear() }
+	})
+
+	let nextFrame = 0
+	const frames = new Map<number, FrameRequestCallback>()
+	vi.stubGlobal('requestAnimationFrame', (callback: FrameRequestCallback) => {
+		frames.set(++nextFrame, callback)
+		return nextFrame
+	})
+
+	const cancelFrame = vi.fn((id: number) => frames.delete(id))
+	vi.stubGlobal('cancelAnimationFrame', cancelFrame)
+	vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockImplementation(() => ({
+		x: 0, y: 0, width: 100, height: 60, top: 0, bottom: 60, left: 0, right: 100,
+		toJSON() {},
+	}))
+
+	const reset = vi.spyOn(VirtualListSizeIndex.prototype, 'reset')
+	const set = vi.spyOn(VirtualListSizeIndex.prototype, 'set')
+	const host = document.createElement('div')
+	document.body.append(host)
+	const root = createRoot(host)
+	roots.push(root)
+	act(() => root.render(<VirtualList items={Array.from({ length: 100 }, (_, i) => i)}
+		keyExtractor={(i) => i} renderItem={(i) => <div>{i}</div>} />))
+
+	const flushFrame = () => act(() => {
+		const pending = [...frames.values()]
+		frames.clear()
+		for (const callback of pending) callback(0)
+	})
+
+	// Establish the viewport and mounted rows before testing row delivery.
+	const viewport = host.firstElementChild as HTMLElement
+	Object.defineProperties(viewport, { clientWidth: { value: 100 }, clientHeight: { value: 200 } })
+	const record = (target: Element) => ({ target, contentRect: { width: 100, height: 60 } }) as ResizeObserverEntry
+	act(() => deliver!([record(viewport)], {} as ResizeObserver))
+	flushFrame()
+	flushFrame()
+	reset.mockClear()
+	set.mockClear()
+	act(() => deliver!([...observed].filter(node => node !== viewport).map(record), {} as ResizeObserver))
+	expect(set).toHaveBeenCalled()
+	const before = host.innerHTML
+	await Promise.resolve()
+	expect(reset).not.toHaveBeenCalled()
+	expect(host.innerHTML).toBe(before)
+	flushFrame()
+	expect(reset).toHaveBeenCalledTimes(1)
+	// Disposal must cancel both estimate and window work.
+	act(() => deliver!([...observed].filter(node => node !== viewport).map(record), {} as ResizeObserver))
+	expect(frames.size).toBeGreaterThan(0)
+	act(() => root.unmount())
+	await Promise.resolve()
+	expect(cancelFrame).toHaveBeenCalled()
+	const rebuilds = reset.mock.calls.length
+	flushFrame()
+	expect(reset).toHaveBeenCalledTimes(rebuilds)
+})
+
+it('repositions measured cells even when every row remains visible', () => {
+	let deliver: ResizeObserverCallback
+	vi.stubGlobal('ResizeObserver', class {
+		constructor(callback: ResizeObserverCallback) { deliver = callback }
+		observe() {}
+		unobserve() {}
+		disconnect() {}
+	})
+
+	const frames: FrameRequestCallback[] = []
+	vi.stubGlobal('requestAnimationFrame', (callback: FrameRequestCallback) => { frames.push(callback); return frames.length })
+	vi.stubGlobal('cancelAnimationFrame', () => {})
+	vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockImplementation(() => ({
+		x: 0, y: 0, width: 100, height: 32, top: 0, bottom: 32, left: 0, right: 100, toJSON() {},
+	}))
+
+	const host = document.createElement('div')
+	document.body.append(host)
+	const root = createRoot(host)
+	roots.push(root)
+	act(() => root.render(<VirtualList items={[0, 1, 2]} keyExtractor={i => i} renderItem={i => <div>{i}</div>} />))
+	const viewport = host.firstElementChild as HTMLElement
+	Object.defineProperties(viewport, { clientWidth: { value: 100 }, clientHeight: { value: 200 } })
+	act(() => deliver!([{ target: viewport, contentRect: { width: 100, height: 200 } } as ResizeObserverEntry], {} as ResizeObserver))
+	for (let i = 0; i < 4; i++) act(() => {
+		for (const callback of frames.splice(0)) callback(0)
+	})
+
+	const body = host.querySelector('.vx-virtual-list-body') as HTMLElement
+	expect(body.style.height).toBe('96px')
+	expect([...host.querySelectorAll<HTMLElement>('.vx-virtual-list-row')].map(node => node.style.top)).toEqual(['0px', '32px', '64px'])
+})

package/src/VirtualList.web.tsrx

@@ -50,11 +50,13 @@ export function VirtualList<T = any>(props: VirtualListProps<T>) @{
 	const footerHeightRef = useRef(0)
 	const observerRef = useRef<ResizeObserver | null>(null)
 	const estimateScheduledRef = useRef(false)
+	const estimateFrameRef = useRef<number | null>(null)
 	const resizeDeliveryRef = useRef(false)
 	const refreshAfterResizeRef = useRef(false)
 	const nodesBySlotRef = useRef(new Map<string, Element>())
 	const metaByNodeRef = useRef(new WeakMap<Element, NodeMeta>())
 	const rangeRef = useRef({ start: -1, end: -1, top: -1, bottom: -1 })
+	const geometryDirtyRef = useRef(false)
 	const handlersRef = useRef<(meta: NodeMeta, entry: ResizeObserverEntry) => void>(() => {})
 	const hasSeparator = Boolean(props.renderSeparator)
 	const hasSeparatorRef = useRef(hasSeparator)
@@ -111,12 +113,14 @@ export function VirtualList<T = any>(props: VirtualListProps<T>) @{
 		const next = currentRange()
 		const previous = rangeRef.current
 		if (
+			geometryDirtyRef.current ||
 			next.start !== previous.start ||
 			next.end !== previous.end ||
 			!sameSize(next.top, previous.top) ||
 			!sameSize(next.bottom, previous.bottom)
 		) {
 			rangeRef.current = next
+			geometryDirtyRef.current = false
 			setWindowVersion((version) => version + 1)
 		}
 	}
@@ -154,7 +158,10 @@ export function VirtualList<T = any>(props: VirtualListProps<T>) @{
 	function scheduleEstimateRebuild() {
 		if (estimateScheduledRef.current) return
 		estimateScheduledRef.current = true
-		Promise.resolve().then(() => {
+		// Measurements and anchor correction are immediate. Defer estimate-driven
+		// DOM writes until the next frame so they run after ResizeObserver delivery.
+		estimateFrameRef.current = requestAnimationFrame(() => {
+			estimateFrameRef.current = null
 			estimateScheduledRef.current = false
 			if (disposedRef.current) return
 			const anchor = captureAnchor()
@@ -177,6 +184,7 @@ export function VirtualList<T = any>(props: VirtualListProps<T>) @{
 		const anchor = captureAnchor()
 		const delta = sizeIndexRef.current.set(index, height)
 		if (Math.abs(delta) >= 0.5) {
+			geometryDirtyRef.current = true
 			if (anchor && index < anchor.index) restoreAnchor(anchor)
 			refreshWindow()
 		}
@@ -267,6 +275,9 @@ export function VirtualList<T = any>(props: VirtualListProps<T>) @{
 		disposedRef.current = false
 		return () => {
 			disposedRef.current = true
+			if (estimateFrameRef.current !== null) cancelAnimationFrame(estimateFrameRef.current)
+			estimateFrameRef.current = null
+			estimateScheduledRef.current = false
 			cellsRef.current.clear()
 			cellCallbacksRef.current.clear()
 			measuredAssignmentsRef.current.clear()

package/src/VisuallyHidden.macos.tsrx

@@ -0,0 +1,23 @@
+/** @jsxImportSource @octane-xplat/macos-renderer */
+import { useMemo } from 'octane'
+import { refList } from './ref-list'
+import type { VisuallyHiddenProps } from './props'
+import { applyEscapeProps } from './escape-props'
+
+/** VisuallyHidden — 1pt opacity-0 container; keeps content in the a11y
+ *  tree while rendering invisible (AppKit hidden views drop from
+ *  VoiceOver; transparent ones stay). */
+export function VisuallyHidden(props: VisuallyHiddenProps) @{
+	const forwardedRef = useMemo(() => refList((v: any) => { if (v) { applyEscapeProps(v, props); } }, props.ref), [props.ref, props.ios, props.android, props.web]);
+
+	<flexboxlayout
+		id={props.id}
+		ref={forwardedRef}
+		className="vx-visually-hidden"
+		accessibilityLabel={props.accessibilityLabel}
+		accessibilityRole={props.accessibilityRole}
+		accessibilityHint={props.accessibilityHint}
+	>
+		{props.children}
+	</flexboxlayout>
+}

package/src/VisuallyHidden.tsrx

@@ -0,0 +1,28 @@
+/** @jsxImportSource @nativescript-community/octane */
+import { useMemo } from 'octane'
+import { refList } from './ref-list'
+import type { VisuallyHiddenProps } from './props';
+import { applyEscapeProps } from './escape-props';
+
+/** VisuallyHidden — a 1dip, fully transparent container that keeps its
+ *  subtree in the native accessibility tree (opacity:0 views stay exposed
+ *  to TalkBack/VoiceOver, unlike visibility=hidden which drops them on
+ *  iOS). For screen-reader labels and live-region announcements. */
+export function VisuallyHidden(props: VisuallyHiddenProps) @{
+	const forwardedRef = useMemo(() => refList((v: any) => { if (v) { applyEscapeProps(v, props); } }, props.ref), [props.ref, props.ios, props.android, props.web]);
+
+	<flexboxlayout
+		id={props.id}
+		ref={forwardedRef}
+		className="vx-visually-hidden"
+		accessible={props.accessible}
+		accessibilityLabel={props.accessibilityLabel}
+		accessibilityRole={props.accessibilityRole as any}
+		accessibilityHint={props.accessibilityHint}
+		accessibilityValue={props.accessibilityValue}
+		accessibilityState={props.accessibilityState as any}
+		accessibilityLiveRegion={props.accessibilityLiveRegion as any}
+	>
+		{props.children}
+	</flexboxlayout>
+}

package/src/VisuallyHidden.web.tsrx

@@ -0,0 +1,32 @@
+import { useMemo } from 'octane'
+import { refList } from './ref-list'
+import type { VisuallyHiddenProps } from './props';
+import { applyEscapeProps } from './escape-props';
+import { applyWebProps } from './platformProps.web';
+
+/** VisuallyHidden — content stays in the a11y tree / DOM flow but renders
+ *  at a clipped 1px box. No style/className: restyling a hidden node is a
+ *  bug waiting to ship. `as` picks the tag ('span' inline default; 'div'
+ *  for live regions / block announcements). */
+export function VisuallyHidden(props: VisuallyHiddenProps) @{
+	const Tag: any = props.as ?? 'span';
+
+	const forwardedRef = useMemo(() => refList((e: any) => { if (e) { applyEscapeProps(e, props); applyWebProps(e, props.web); } }, props.ref), [props.ref, props.ios, props.android, props.web]);
+
+	<Tag
+		id={props.id}
+		ref={forwardedRef}
+		className="vx-visually-hidden"
+		role={props.accessibilityRole}
+		aria-label={props.accessibilityLabel}
+		aria-hidden={props.accessible === false ? true : undefined}
+		aria-description={props.accessibilityHint}
+		aria-valuetext={props.accessibilityValue}
+		aria-disabled={props.accessibilityState?.disabled}
+		aria-selected={props.accessibilityState?.selected}
+		aria-checked={props.accessibilityState?.checked}
+		aria-live={props.accessibilityLiveRegion === 'none' ? 'off' : props.accessibilityLiveRegion}
+	>
+		{props.children}
+	</Tag>
+}

package/src/WebView.macos.tsrx

@@ -1,6 +1,45 @@
-/** @jsxImportSource @xplat/macos/renderer */
+/** @jsxImportSource @octane-xplat/macos-renderer */
+import { useImperativeHandle, useRef } from 'octane'
 import type { WebViewProps } from './props'
+import { cx } from './cx'
+import { layoutChildProps } from './layout-child'
 
-export function WebView(_props: WebViewProps) @{
-	<label className="vx-unsupported">WebView is unsupported by the AppKit host</label>
+export function WebView(props: WebViewProps) @{
+	const view = useRef<any>(null)
+	const currentProps = useRef(props)
+	currentProps.current = props
+	useImperativeHandle(props.ref, () => ({
+		reload: () => {
+			if (currentProps.current.html !== undefined) {
+				view.current?.loadHTMLStringBaseURL(currentProps.current.html, null)
+			} else {
+				view.current?.reload()
+			}
+		},
+		goBack: () => view.current?.goBack(),
+		goForward: () => view.current?.goForward(),
+		stopLoading: () => view.current?.stopLoading(),
+		get native() { return view.current },
+	}), [])
+
+	<webview
+		ref={view}
+		id={props.id}
+		{...layoutChildProps(props)}
+		className={cx('vx-webview', props.className)}
+		style={props.style}
+		src={props.src}
+		html={props.html}
+		scrollEnabled={props.scrollEnabled}
+		matchContents={props.matchContents}
+		onLoad={props.onLoad}
+		onError={props.onError}
+		onLayoutContent={props.onLayoutContent}
+		accessible={props.accessible}
+		accessibilityLabel={props.accessibilityLabel}
+		accessibilityRole={props.accessibilityRole}
+		accessibilityHint={props.accessibilityHint}
+		accessibilityValue={props.accessibilityValue}
+		accessibilityState={props.accessibilityState}
+	/>
 }

package/src/WebView.tsrx

@@ -1,6 +1,6 @@
 /** @jsxImportSource @nativescript-community/octane */
 import { isAndroid, isIOS } from '@nativescript/core';
-import { useEffect, useRef } from 'octane';
+import { useImperativeHandle, useEffect, useRef } from 'octane';
 import type { WebViewProps } from "./props";
 import { cx } from "./cx";
 import { applyEscapeProps, nativeAccessibilityRole, nativeAccessibilityState } from "./escape-props";
@@ -60,18 +60,19 @@ export function WebView(props: WebViewProps) @{
 		if (props.matchContents && loaded.current) reportContentLayout(v, props);
 	}, [props.scrollEnabled, props.matchContents]);
 
+	useImperativeHandle(props.ref, () => ({
+				reload: () => el.current.reload(),
+				goBack: () => el.current.goBack(),
+				goForward: () => el.current.goForward(),
+				stopLoading: () => el.current.stopLoading(),
+				native: el.current,
+			}), []);
+
 	<webview
 		ref={(v: any) => {
-			el.current = v;
+				el.current = v;
 			if (!v) return;
 			applyEscapeProps(v, props);
-			props.bind?.({
-				reload: () => v.reload(),
-				goBack: () => v.goBack(),
-				goForward: () => v.goForward(),
-				stopLoading: () => v.stopLoading(),
-				native: v,
-			});
 		}}
 		id={props.id}
 		{...layoutChildProps(props)}

package/src/WebView.web.tsrx

@@ -1,4 +1,4 @@
-import { useEffect, useRef } from 'octane'
+import { useImperativeHandle, useEffect, useRef } from 'octane'
 import type { WebViewHandle, WebViewProps } from "./props";
 import { applyEscapeProps } from "./escape-props";
 import { layoutChildProps } from './layout-child.web';
@@ -73,12 +73,13 @@ export function WebView(props: WebViewProps) @{
 		};
 	}, [props.matchContents, props.onLayoutContent]);
 
+	useImperativeHandle(props.ref, () => handle(frame.current), []);
+
 	<iframe
 		ref={(el: any) => {
-			if (!el) return;
 			frame.current = el;
+			if (!el) return;
 			applyEscapeProps(el, props);
-			props.bind?.(handle(el));
 		}}
 		id={props.id}
 		className={['vx-webview', props.className]}

package/src/aliases.macos.tsrx

@@ -1,18 +1,13 @@
-/** @jsxImportSource @xplat/macos/renderer */
+/** @jsxImportSource @octane-xplat/macos-renderer */
 import { Select } from './Select.macos.tsrx'
-import type { SelectProps } from './props'
+import type { MultiSelectorProps } from './props'
 
 /** SelectMenu — multi-select anchored listbox (Select with `multiple`). */
-export function SelectMenu(props: SelectProps) @{
-	return <Select {...props} multiple={true} />
-}
-
-/** Combobox — searchable anchored listbox (Select with `searchable`). */
-export function Combobox(props: SelectProps) @{
-	return <Select {...props} searchable={true} />
-}
-
-/** InputMenu — alias of Combobox (searchable anchored listbox). */
-export function InputMenu(props: SelectProps) @{
-	return <Select {...props} searchable={true} />
+export function SelectMenu(props: MultiSelectorProps) @{
+	return <Select
+		{...props}
+		multiple={true}
+		onValueChange={(value) => props.onValueChange?.(Array.isArray(value) ? value : [])}
+		changeAction={props.changeAction ? (value) => props.changeAction?.(Array.isArray(value) ? value : []) : undefined}
+	/>
 }