@octane-xplat/ui 0.6.0 → 0.7.0

package/src/VirtualList.web.tsrx

@@ -0,0 +1,313 @@
+import { useEffect, useMemo, useRef, useState } from 'octane'
+import type { VirtualListProps } from './props'
+import {
+	createVirtualListEntries,
+	estimateVirtualListSizes,
+	virtualListMeasurementKey,
+	virtualListRange,
+	VirtualListSizeIndex,
+	type VirtualListEntry,
+	type VirtualListSizeRecord,
+} from './virtual-list-layout'
+import { applyEscapeProps } from './escape-props'
+import { layoutChildProps } from './layout-child.web'
+
+type NodeMeta =
+	| { kind: 'viewport' }
+	| { kind: 'row'; rowKey: string }
+	| { kind: 'header' }
+	| { kind: 'footer' }
+
+function sameSize(a: number, b: number) {
+	return Math.abs(a - b) < 0.5
+}
+
+/** Shared vertical virtualization over a DOM scroll container. Rows outside
+ *  the viewport plus one viewport of overscan are unmounted. */
+export function VirtualList<T = any>(props: VirtualListProps<T>) @{
+	const entries = useMemo(
+		() => createVirtualListEntries(props.items, props.keyExtractor, props.getItemType),
+		[props.items, props.keyExtractor, props.getItemType],
+	)
+	const [windowVersion, setWindowVersion] = useState(0)
+	const sizeIndexRef = useRef(new VirtualListSizeIndex())
+	const sizeCacheRef = useRef(new Map<string, VirtualListSizeRecord>())
+	const entriesRef = useRef<VirtualListEntry<T>[]>([])
+	const indexByRowKeyRef = useRef(new Map<string, number>())
+	const scrollRef = useRef<HTMLElement | null>(null)
+	const scrollOffsetRef = useRef(0)
+	const viewportHeightRef = useRef(0)
+	const viewportWidthRef = useRef(0)
+	const headerHeightRef = useRef(0)
+	const footerHeightRef = useRef(0)
+	const observerRef = useRef<ResizeObserver | null>(null)
+	const estimateScheduledRef = 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 handlersRef = useRef<(meta: NodeMeta, entry: ResizeObserverEntry) => void>(() => {})
+	const hasSeparator = Boolean(props.renderSeparator)
+	const hasSeparatorRef = useRef(hasSeparator)
+	hasSeparatorRef.current = hasSeparator
+
+	function rebuildLayout(nextEntries: VirtualListEntry<T>[], width: number) {
+		entriesRef.current = nextEntries
+		const indexByKey = new Map<string, number>()
+		const activeMeasurements = new Set<string>()
+
+		for (const entry of nextEntries) {
+			indexByKey.set(entry.rowKey, entry.index)
+			const cacheKey = virtualListMeasurementKey(
+				entry.rowKey,
+				hasSeparatorRef.current && entry.index < nextEntries.length - 1,
+			)
+			activeMeasurements.add(cacheKey)
+		}
+
+		for (const cacheKey of sizeCacheRef.current.keys()) {
+			if (!activeMeasurements.has(cacheKey)) sizeCacheRef.current.delete(cacheKey)
+		}
+
+		indexByRowKeyRef.current = indexByKey
+		sizeIndexRef.current.reset(
+			estimateVirtualListSizes(nextEntries, hasSeparatorRef.current, width, sizeCacheRef.current),
+		)
+	}
+
+	if (entries !== entriesRef.current) rebuildLayout(entries, viewportWidthRef.current)
+
+	function currentRange() {
+		const listOffset = Math.max(0, scrollOffsetRef.current - headerHeightRef.current)
+		return virtualListRange(
+			sizeIndexRef.current,
+			listOffset,
+			viewportHeightRef.current,
+			viewportHeightRef.current,
+		)
+	}
+
+	function refreshWindow() {
+		const next = currentRange()
+		const previous = rangeRef.current
+		if (
+			next.start !== previous.start ||
+			next.end !== previous.end ||
+			!sameSize(next.top, previous.top) ||
+			!sameSize(next.bottom, previous.bottom)
+		) {
+			rangeRef.current = next
+			setWindowVersion((version) => version + 1)
+		}
+	}
+
+	function captureAnchor() {
+		const listOffset = scrollOffsetRef.current - headerHeightRef.current
+		if (listOffset < 0 || entriesRef.current.length === 0) return null
+
+		const index = sizeIndexRef.current.indexAt(listOffset)
+		const entry = entriesRef.current[index]
+		if (!entry) return null
+		return {
+			rowKey: entry.rowKey,
+			index,
+			within: listOffset - sizeIndexRef.current.prefix(index),
+		}
+	}
+
+	function restoreAnchor(anchor: ReturnType<typeof captureAnchor>) {
+		if (!anchor) return
+		const index = indexByRowKeyRef.current.get(anchor.rowKey)
+		if (index === undefined) return
+		const nextOffset = Math.max(
+			0,
+			headerHeightRef.current + sizeIndexRef.current.prefix(index) + anchor.within,
+		)
+		if (sameSize(nextOffset, scrollOffsetRef.current)) return
+
+		scrollOffsetRef.current = nextOffset
+		if (scrollRef.current) scrollRef.current.scrollTop = nextOffset
+	}
+
+	function scheduleEstimateRebuild() {
+		if (estimateScheduledRef.current) return
+		estimateScheduledRef.current = true
+		Promise.resolve().then(() => {
+			estimateScheduledRef.current = false
+			const anchor = captureAnchor()
+			rebuildLayout(entriesRef.current, viewportWidthRef.current)
+			restoreAnchor(anchor)
+			refreshWindow()
+		})
+	}
+
+	function recordRowSize(rowKey: string, width: number, height: number) {
+		if (!Number.isFinite(height) || height < 0) return
+		const index = indexByRowKeyRef.current.get(rowKey)
+		if (index === undefined) return
+		const entry = entriesRef.current[index]
+		if (!entry) return
+
+		const hasRowSeparator = hasSeparatorRef.current && index < entriesRef.current.length - 1
+		const cacheKey = virtualListMeasurementKey(rowKey, hasRowSeparator)
+		sizeCacheRef.current.set(cacheKey, { width, height })
+		const anchor = captureAnchor()
+		const delta = sizeIndexRef.current.set(index, height)
+		if (Math.abs(delta) >= 0.5) {
+			if (anchor && index < anchor.index) restoreAnchor(anchor)
+			refreshWindow()
+		}
+		scheduleEstimateRebuild()
+	}
+
+	function bindObservedNode(slot: string, node: Element | null, meta: NodeMeta) {
+		const previous = nodesBySlotRef.current.get(slot)
+		if (previous && previous !== node) {
+			observerRef.current?.unobserve(previous)
+			metaByNodeRef.current.delete(previous)
+			nodesBySlotRef.current.delete(slot)
+		}
+		if (!node) {
+			if (previous) {
+				observerRef.current?.unobserve(previous)
+				metaByNodeRef.current.delete(previous)
+				nodesBySlotRef.current.delete(slot)
+			}
+			return
+		}
+
+		nodesBySlotRef.current.set(slot, node)
+		metaByNodeRef.current.set(node, meta)
+		observerRef.current?.observe(node)
+	}
+
+	handlersRef.current = (meta, entry) => {
+		if (meta.kind === 'viewport') {
+			const width = scrollRef.current?.clientWidth ?? entry.contentRect.width
+			const height = scrollRef.current?.clientHeight ?? entry.contentRect.height
+			const widthChanged = !sameSize(width, viewportWidthRef.current)
+			viewportHeightRef.current = height
+			if (widthChanged) {
+				const anchor = captureAnchor()
+				viewportWidthRef.current = width
+				rebuildLayout(entriesRef.current, width)
+				restoreAnchor(anchor)
+			}
+			refreshWindow()
+			return
+		}
+
+		const height = entry.contentRect.height
+		if (meta.kind === 'row') {
+			recordRowSize(meta.rowKey, entry.contentRect.width, height)
+			return
+		}
+
+		if (meta.kind === 'header' && !sameSize(height, headerHeightRef.current)) {
+			const anchor = captureAnchor()
+			headerHeightRef.current = height
+			restoreAnchor(anchor)
+			refreshWindow()
+		} else if (meta.kind === 'footer' && !sameSize(height, footerHeightRef.current)) {
+			footerHeightRef.current = height
+			refreshWindow()
+		}
+	}
+
+	useEffect(() => {
+		if (typeof ResizeObserver === 'undefined') return
+
+		const observer = new ResizeObserver((records) => {
+			for (const record of records) {
+				const meta = metaByNodeRef.current.get(record.target)
+				if (meta) handlersRef.current(meta, record)
+			}
+		})
+		observerRef.current = observer
+		for (const node of nodesBySlotRef.current.values()) observer.observe(node)
+
+		return () => {
+			observer.disconnect()
+			observerRef.current = null
+		}
+	}, [])
+
+	function onScroll(event: any) {
+		const root = event.currentTarget as HTMLElement
+		scrollOffsetRef.current = root.scrollTop
+		refreshWindow()
+	}
+
+	const range = currentRange()
+	rangeRef.current = range
+	void windowVersion
+	const visibleEntries = entries.slice(range.start, range.end)
+	const style = {
+		...props.style,
+		minHeight: props.style?.minHeight ?? 0,
+		overflowY: 'auto',
+		overflowX: 'hidden',
+		overflowAnchor: 'none',
+	}
+
+	<div
+		ref={(node: any) => {
+			scrollRef.current = node
+			if (node) applyEscapeProps(node, props)
+			bindObservedNode('viewport', node, { kind: 'viewport' })
+		}}
+		id={props.id}
+		className={['vx-virtual-list', props.className]}
+		{...layoutChildProps(props, style)}
+		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}
+		onScroll={onScroll}
+	>
+		{props.renderHeader ? (
+			<div
+				className="vx-virtual-list-header"
+				ref={(node: any) => bindObservedNode('header', node, { kind: 'header' })}
+			>
+				{props.renderHeader()}
+			</div>
+		) : null}
+		{entries.length === 0 ? (
+			props.renderEmpty ? <div className="vx-virtual-list-empty">{props.renderEmpty()}</div> : null
+		) : (
+			<>
+				<div className="vx-virtual-list-spacer" style={{ height: range.top }} aria-hidden="true" />
+				@for (const entry of visibleEntries; key entry.rowKey) {
+					<div
+						className="vx-virtual-list-row"
+						data-vx-row="true"
+						ref={(node: any) => bindObservedNode(
+							'row:' + virtualListMeasurementKey(entry.rowKey, hasSeparator && entry.index < entries.length - 1),
+							node,
+							{ kind: 'row', rowKey: entry.rowKey },
+						)}
+					>
+						<div className="vx-virtual-list-item">{props.renderItem(entry.item, entry.index)}</div>
+						{hasSeparator && entry.index < entries.length - 1 ? (
+							<div className="vx-virtual-list-separator">{props.renderSeparator?.()}</div>
+						) : null}
+					</div>
+				}
+				<div className="vx-virtual-list-spacer" style={{ height: range.bottom }} aria-hidden="true" />
+			</>
+		)}
+		{props.renderFooter ? (
+			<div
+				className="vx-virtual-list-footer"
+				ref={(node: any) => bindObservedNode('footer', node, { kind: 'footer' })}
+			>
+				{props.renderFooter()}
+			</div>
+		) : null}
+	</div>
+}

package/src/WebView.macos.tsrx

@@ -0,0 +1,6 @@
+/** @jsxImportSource @xplat/macos/renderer */
+import type { WebViewProps } from './props'
+
+export function WebView(_props: WebViewProps) @{
+	<label className="vx-unsupported">WebView is unsupported by the AppKit host</label>
+}

package/src/WebView.tsrx

@@ -0,0 +1,89 @@
+/** @jsxImportSource @nativescript-community/octane */
+import { isAndroid, isIOS } from '@nativescript/core';
+import { useEffect, useRef } from 'octane';
+import type { WebViewProps } from "./props";
+import { cx } from "./cx";
+import { applyEscapeProps, nativeAccessibilityRole, nativeAccessibilityState } from "./escape-props";
+import { layoutChildProps } from './layout-child';
+
+function reportContentLayout(view: any, props: WebViewProps) {
+	let width = Number(view?.getActualSize?.()?.width ?? 0)
+	let height = 0
+	if (isIOS) {
+		const size = view?.ios?.scrollView?.contentSize
+		width = Number(size?.width ?? width)
+		height = Number(size?.height ?? 0)
+	} else if (isAndroid) {
+		height = Number(view?.android?.getContentHeight?.() ?? 0) * Number(view?.android?.getScale?.() ?? 1)
+	}
+	if (!Number.isFinite(width) || !Number.isFinite(height) || height <= 0) return
+	props.onLayoutContent?.({ width, height })
+	if (props.matchContents) {
+		view.height = height
+		view.style.height = height
+	}
+}
+
+/** Embedded web document — NS <webview> (WKWebView / android.webkit.WebView).
+ *  `html` flows through the `src` property: values that aren't http/file
+ *  URLs take its `_loadData` path. NS reports failures as `loadFinished`
+ *  with an `error` field — there is no separate error event, so the leaf
+ *  splits it into onLoad/onError.
+ *  `scrollEnabled={false}` is leaf-applied, not an NS prop: iOS clears the
+ *  WKWebView scrollView's scrollEnabled; Android has no settings flag, so
+ *  a touch listener eats ACTION_MOVE (DOWN/UP still reach the page, so
+ *  link taps work but drag text selection inside the frame does not). */
+export function WebView(props: WebViewProps) @{
+	const el = useRef<any>(null);
+	const loaded = useRef(false);
+	useEffect(() => {
+		const v = el.current;
+		if (!v) return;
+		if (isIOS) {
+			v.ios.scrollView.scrollEnabled = props.scrollEnabled !== false;
+		} else if (isAndroid) {
+			v.android.setOnTouchListener(props.scrollEnabled === false
+				? new android.view.View.OnTouchListener({
+						onTouch: (_view: any, event: any) =>
+							event.getActionMasked() === android.view.MotionEvent.ACTION_MOVE,
+					})
+				: null);
+		}
+		if (props.matchContents && loaded.current) reportContentLayout(v, props);
+	}, [props.scrollEnabled, props.matchContents]);
+
+	<webview
+		ref={(v: any) => {
+			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)}
+		className={cx('vx-webview', props.className)}
+		style={props.style}
+		src={props.html !== undefined ? props.html : props.src}
+		onLoadFinished={(e: any) => {
+			if (e.error) props.onError?.({ url: e.url, error: e.error });
+			else {
+				loaded.current = true;
+				reportContentLayout(e.object ?? el.current, props);
+				props.onLoad?.({ url: e.url });
+			}
+		}}
+		accessible={props.accessible}
+		accessibilityLabel={props.accessibilityLabel}
+		accessibilityRole={nativeAccessibilityRole(props.accessibilityRole) as any}
+		accessibilityHint={props.accessibilityHint}
+		accessibilityValue={props.accessibilityValue}
+		accessibilityState={nativeAccessibilityState(props.accessibilityState) as any}
+		accessibilityLiveRegion={props.accessibilityLiveRegion as any}
+	/>
+}

package/src/WebView.web.tsrx

@@ -0,0 +1,92 @@
+import { useEffect, useRef } from 'octane'
+import type { WebViewHandle, WebViewProps } from "./props";
+import { applyEscapeProps } from "./escape-props";
+import { layoutChildProps } from './layout-child.web';
+
+/** Matches what NS WebView content can already do — scripts, forms, modal
+ *  dialogs, its own origin — while top navigation, popups, and downloads
+ *  stay contained. `sandbox`/`web.sandbox` override. */
+const DEFAULT_SANDBOX = 'allow-scripts allow-same-origin allow-forms allow-modals';
+
+/** Embedded web document — a sandboxed <iframe>. `html` renders through
+ *  `srcdoc` and wins over `src` when both are set. The iframe `error`
+ *  event is unreliable cross-browser, so `onError` is best-effort here. */
+export function WebView(props: WebViewProps) @{
+	const frame = useRef<HTMLIFrameElement | null>(null);
+	const handle = (el: any): WebViewHandle => ({
+		reload: () => {
+			try {
+				// Same-origin and srcdoc frames reload in place.
+				el.contentWindow.location.reload();
+			} catch {
+				// Cross-origin frame — re-request the document instead.
+				if (el.src) el.src = el.src;
+			}
+		},
+		// history navigation is allowed cross-origin; location/stop are not.
+		goBack: () => el.contentWindow?.history.back(),
+		goForward: () => el.contentWindow?.history.forward(),
+		stopLoading: () => {
+			try {
+				el.contentWindow?.stop();
+			} catch { /* cross-origin frames can't be stopped */ }
+		},
+		native: el,
+	});
+	useEffect(() => {
+		const el = frame.current;
+		if (!el) return;
+		let observer: ResizeObserver | undefined;
+		let observedDocument: Document | undefined;
+		const measure = () => {
+			try {
+				const doc = el.contentDocument;
+				const body = doc?.body;
+				const root = doc?.documentElement;
+				if (!doc || !body || !root) return;
+				const size = {
+					width: Math.max(body.scrollWidth, root.scrollWidth),
+					height: Math.max(body.scrollHeight, root.scrollHeight),
+				};
+				if (size.width <= 0 || size.height <= 0) return;
+				if (props.matchContents) el.style.height = `${size.height}px`;
+				props.onLayoutContent?.(size);
+				if (observedDocument !== doc && typeof ResizeObserver !== 'undefined') {
+					observer?.disconnect();
+					observer = new ResizeObserver(measure);
+					observer.observe(body);
+					observer.observe(root);
+					observedDocument = doc;
+				}
+			} catch {
+				// Cross-origin documents cannot be inspected by the embedding page.
+			}
+		};
+		el.addEventListener('load', measure);
+		measure();
+		return () => {
+			el.removeEventListener('load', measure);
+			observer?.disconnect();
+		};
+	}, [props.matchContents, props.onLayoutContent]);
+
+	<iframe
+		ref={(el: any) => {
+			if (!el) return;
+			frame.current = el;
+			applyEscapeProps(el, props);
+			props.bind?.(handle(el));
+		}}
+		id={props.id}
+		className={['vx-webview', props.className]}
+		{...layoutChildProps(props)}
+		srcDoc={props.html}
+		src={props.html === undefined ? props.src : undefined}
+		sandbox={props.sandbox === false ? undefined : props.sandbox ?? DEFAULT_SANDBOX}
+		scrolling={props.scrollEnabled === false ? 'no' : undefined}
+		title={props.accessibilityLabel}
+		aria-hidden={props.accessible === false ? true : undefined}
+		onLoad={(e: any) => props.onLoad?.({ url: props.html === undefined ? e.currentTarget?.src : undefined })}
+		onError={(e: any) => props.onError?.({ url: props.html === undefined ? e.currentTarget?.src : undefined, error: 'iframe failed to load' })}
+	/>
+}

package/src/aliases.macos.tsrx

@@ -0,0 +1,18 @@
+/** @jsxImportSource @xplat/macos/renderer */
+import { Select } from './Select.macos.tsrx'
+import type { SelectProps } 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} />
+}

package/src/aliases.tsrx

@@ -0,0 +1,18 @@
+/** @jsxImportSource @nativescript-community/octane */
+import { Select } from './Select.tsrx'
+import type { SelectProps } 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} />
+}

package/src/aliases.web.tsrx

@@ -0,0 +1,17 @@
+import { Select } from './Select.web.tsrx'
+import type { SelectProps } 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} />
+}