@octane-xplat/ui 0.9.0 → 0.10.0

package/src/use-layer.mobile.test.tsrx

@@ -0,0 +1,132 @@
+/** @jsxImportSource @nativescript-community/octane */
+
+import { describe, expect, it, vi } from 'vitest'
+
+const state = vi.hoisted(() => ({
+	hosts: [] as any[],
+	roots: [] as any[],
+	owner: null as any,
+}))
+
+vi.mock('@nativescript/core', () => ({
+	Application: {
+		primaryWindow: undefined,
+		on: () => {},
+		off: () => {},
+	},
+	GridLayout: class {
+		className = ''
+		horizontalAlignment = ''
+		verticalAlignment = ''
+		style: Record<string, unknown> = {}
+		on() {}
+		off() {}
+		constructor() {
+			state.hosts.push(this)
+		}
+	},
+	isIOS: false,
+	isAndroid: true,
+	Screen: { mainScreen: { scale: 1 } },
+}))
+
+vi.mock('@nativescript-community/octane', async (importOriginal) => ({
+	...(await importOriginal<Record<string, unknown>>()),
+	createNativeScriptRoot: () => {
+		const root = { render: vi.fn(), unmount: vi.fn() }
+		state.roots.push(root)
+		return root
+	},
+}))
+
+vi.mock('./root-layout', () => ({ rootLayoutFor: () => state.owner }))
+vi.mock('./theme/theme-scheme', () => ({
+	useThemeScheme: () => 'light',
+	applyThemeClasses: (host: any, base: string) => {
+		host.className = base
+		return () => {}
+	},
+}))
+
+import {
+	createObjectContainer,
+	createObjectDriver,
+	createUniversalRoot,
+	flushUniversalSync,
+} from 'octane/universal/native'
+
+import { useLayer } from './use-layer.mobile.tsrx'
+
+let layer: any = null
+
+function Probe(props: { fixed?: boolean }) {
+	layer = useLayer({ mode: props.fixed ? 'fixed' : 'context' })
+	return (
+		<stacklayout>
+			{layer.render(
+				<gridlayout />,
+				props.fixed ? { x: 10, y: 20 } : { placement: 'below' },
+			)}
+		</stacklayout>
+	)
+}
+
+function freshOwner() {
+	state.hosts.length = 0
+	state.roots.length = 0
+	state.owner = {
+		open: vi.fn(async () => {}),
+		close: vi.fn(async () => {}),
+		hasChild: () => true,
+		getPopupIndex: () => 0,
+	}
+}
+
+describe('useLayer (mobile)', () => {
+	it('fixed mode mounts a positioned layer host on the RootLayout', async () => {
+		freshOwner()
+		const container = createObjectContainer('nativescript')
+		const root = createUniversalRoot(container, createObjectDriver('nativescript'))
+		root.render(Probe as any, { fixed: true })
+		flushUniversalSync(() => {})
+
+		expect(layer.ref).toBeUndefined()
+		expect(layer.isOpen).toBe(false)
+
+		layer.show()
+		await vi.waitFor(() => expect(layer.isOpen).toBe(true))
+		await vi.waitFor(() => expect(state.owner.open).toHaveBeenCalled())
+
+		const host = state.hosts.at(-1)
+		expect(host.className).toContain('vx-layer-host')
+		const surfaceProps = state.roots.at(-1).render.mock.calls.at(-1)[1]
+		expect(surfaceProps.x).toBe(10)
+		expect(surfaceProps.y).toBe(20)
+
+		layer.hide()
+		await vi.waitFor(() => expect(state.owner.close).toHaveBeenCalled())
+		await vi.waitFor(() => expect(layer.isOpen).toBe(false))
+		root.unmount()
+	})
+
+	it('context mode presents through Popover once the anchor binds', async () => {
+		freshOwner()
+		const container = createObjectContainer('nativescript')
+		const root = createUniversalRoot(container, createObjectDriver('nativescript'))
+		root.render(Probe as any, { fixed: false })
+		flushUniversalSync(() => {})
+
+		expect(typeof layer.ref).toBe('function')
+		layer.ref({})
+		layer.show()
+		await vi.waitFor(() => expect(layer.isOpen).toBe(true))
+		await vi.waitFor(() => expect(state.owner.open).toHaveBeenCalled())
+
+		const host = state.hosts.at(-1)
+		expect(host.className).toContain('vx-popover-host')
+
+		layer.hide()
+		await vi.waitFor(() => expect(layer.isOpen).toBe(false))
+		root.unmount()
+	})
+})

package/src/use-layer.mobile.tsrx

@@ -0,0 +1,228 @@
+/** @jsxImportSource @nativescript-community/octane */
+import { LayerDepthProvider, useLayerDismissal } from './layer-dismissal.tsrx';
+import { useCallback, useEffect, useId, useRef, useState } from 'octane';
+import { GridLayout } from '@nativescript/core';
+import { createNativeScriptRoot } from '@nativescript-community/octane';
+import type { UniversalComponent } from 'octane/universal';
+import type {
+	ContextLayerReturn,
+	ContextRenderProps,
+	FixedLayerOptions,
+	FixedLayerReturn,
+	FixedRenderProps,
+	LayerOptions,
+} from './props';
+
+import { Popover } from './Popover';
+import { applyNativeProps } from './platformProps';
+import { applyThemeClasses, useThemeScheme } from './theme/theme-scheme';
+import { cx } from './cx';
+import { rootLayoutFor } from './root-layout';
+import { createOverlayLifetime } from './overlay-lifetime';
+import { layerOffset } from './popover-position';
+
+interface FixedSurfaceProps {
+	layerDepth?: number
+	/** Page-coordinate position in dips; consumer-authored styles carry it
+	 *  under `positioning: 'custom'`. */
+	x?: number
+	y?: number
+	lightDismiss?: boolean
+	dismissOnEscape?: boolean
+	onDismiss?: () => void
+	className?: any
+	style?: any
+	accessibilityLabel?: string
+	ios?: Record<string, any>
+	android?: Record<string, any>
+	children?: any
+}
+
+/** Layer surface inside the overlay root — the Popover layout without
+ *  anchor measurement. */
+function FixedLayerSurface(props: FixedSurfaceProps) @{
+	const panelRef = useRef<any>(null);
+	useEffect(() => {
+		applyNativeProps(panelRef.current, props);
+	}, [props.ios, props.android]);
+
+	<absolutelayout
+		width="100%"
+		height="100%"
+		className={cx('vx-popover-layer', useThemeScheme() === 'dark' && 'ns-dark')}
+	>
+		{(props.lightDismiss ?? false) && <gridlayout
+			width="100%"
+			height="100%"
+			backgroundColor={"transparent" as any}
+			className="vx-popover-backdrop"
+			onTap={() => props.onDismiss?.()}
+		/>}
+		<gridlayout
+			ref={panelRef}
+			left={props.x ?? 0}
+			top={props.y ?? 0}
+			accessibilityLabel={props.accessibilityLabel}
+			className={cx('vx-popover', props.className)}
+			style={props.style}
+		>
+			<LayerDepthProvider value={props.layerDepth ?? 0}>{props.children}</LayerDepthProvider>
+		</gridlayout>
+	</absolutelayout>
+}
+
+/** Mounts the fixed-position layer on the enclosing RootLayout — the
+ *  zero-size sentinel locates the root; the layer renders in its own root
+ *  above the page, the same machinery as `Overlay`/`Popover`. */
+function FixedLayerMount(props: FixedSurfaceProps & { open?: boolean }) @{
+	const dismissal = useLayerDismissal({ get active() { return !!props.open }, isPresent: () => !!shown.current, dismiss: () => props.onDismiss?.(), get behavior() { return (props.dismissOnEscape ?? props.lightDismiss) ? 'close' : 'block' } });
+	const sentinel = useRef<any>(null);
+	const shown = useRef<{ host: any; root: any; lifetime: ReturnType<typeof createOverlayLifetime> } | null>(null);
+	const dismiss = useRef(props.onDismiss);
+	dismiss.current = props.onDismiss;
+
+	useEffect(() => {
+		const current = shown.current;
+		if (!props.open) {
+			current?.lifetime.close();
+			return;
+		}
+
+		const rl = rootLayoutFor(sentinel.current);
+		if (!rl) return;
+
+		const surface = { ...props, layerDepth: dismissal.depth, onDismiss: () => { if (dismissal.shouldClose()) dismiss.current?.(); } };
+		if (current) {
+			current.root.render(FixedLayerSurface as unknown as UniversalComponent, surface);
+			return;
+		}
+
+		const host = new GridLayout();
+		const unbindTheme = applyThemeClasses(host, 'vx-layer-host');
+		host.horizontalAlignment = 'stretch';
+		host.verticalAlignment = 'stretch';
+		const root = createNativeScriptRoot(host);
+		const lifetime = createOverlayLifetime(rl, host, root, 'Layer', (dismissed) => {
+			if (shown.current?.host === host) shown.current = null;
+			if (dismissed) dismiss.current?.();
+		});
+
+		lifetime.own(unbindTheme);
+		shown.current = { host, root, lifetime };
+		root.render(FixedLayerSurface as unknown as UniversalComponent, surface);
+		lifetime.open();
+	}, [props.open, props.children, props.x, props.y, props.lightDismiss, props.className, props.style, props.ios, props.android]);
+
+	useEffect(() => () => shown.current?.lifetime.close(), []);
+
+	<stacklayout ref={(v: any) => { sentinel.current = v; }} style={{ width: 0, height: 0 }} />
+}
+
+/**
+ * Anchored-layer primitive (Astryx `useLayer`), iOS/Android leaf. Context
+ * mode delegates to `Popover` — JS measure/flip placement on the page's
+ * RootLayout, not CSS anchor positioning. Logical sides and horizontal alignment use the anchor's effective OS direction. Fixed mode positions at page-coordinate x/y. The
+ * layer is a separate Octane root: pass data as props, not context.
+ */
+export function useLayer<O extends LayerOptions>(
+	options: O,
+): O extends FixedLayerOptions ? FixedLayerReturn : ContextLayerReturn @{
+	const fixed = options.mode === 'fixed';
+	const id = useId();
+	const [uncontrolled, setIsOpen] = useState(false);
+	const isOpen = options.isOpen ?? uncontrolled;
+	const controlled = options.isOpen !== undefined;
+	const openRef = useRef(false);
+	const anchor = useRef<{ current: any }>({ current: null });
+	openRef.current = isOpen;
+	const onShow = useRef(options.onShow);
+	onShow.current = options.onShow;
+	const onHide = useRef(options.onHide);
+	onHide.current = options.onHide;
+
+	const show = useCallback(() => {
+		if (openRef.current) return;
+		if (!controlled) { openRef.current = true; setIsOpen(true); }
+		onShow.current?.();
+	}, [controlled]);
+
+	const hide = useCallback(() => {
+		if (!openRef.current) return;
+		if (!controlled) { openRef.current = false; setIsOpen(false); }
+		onHide.current?.();
+	}, [controlled]);
+
+	const ref = useCallback((el: any) => {
+		anchor.current.current = el;
+	}, []);
+
+	const render = useCallback(
+		(children: any, props?: ContextRenderProps | FixedRenderProps) => {
+			if (fixed) {
+				const p = (props ?? {}) as FixedRenderProps;
+				return (
+					<FixedLayerMount
+						open={isOpen}
+						x={p.x}
+						y={p.y}
+						lightDismiss={options.lightDismiss}
+						dismissOnEscape={options.dismissOnEscape}
+						onDismiss={hide}
+						className={p.className}
+						style={p.style}
+						accessibilityLabel={p.accessibilityLabel}
+						ios={p.ios}
+						android={p.android}
+					>
+						{children}
+					</FixedLayerMount>
+				);
+			}
+
+			const p = (props ?? {}) as ContextRenderProps;
+			if (p.positioning === 'custom') {
+				return (
+					<FixedLayerMount
+						open={isOpen}
+						lightDismiss={options.lightDismiss}
+						dismissOnEscape={options.dismissOnEscape}
+						onDismiss={hide}
+						className={p.className}
+						style={p.style}
+						accessibilityLabel={p.accessibilityLabel}
+						ios={p.ios}
+						android={p.android}
+					>
+						{children}
+					</FixedLayerMount>
+				);
+			}
+
+			return (
+				<Popover
+					open={isOpen}
+					layerPosition={p}
+					anchor={anchor.current}
+					offset={layerOffset(p.offset)}
+					dismissOnOutsideTap={options.lightDismiss === true}
+					dismissOnEscape={options.dismissOnEscape ?? options.lightDismiss === true}
+					onDismiss={hide}
+					finalFocusRef={p.finalFocusRef}
+					className={p.className}
+					style={p.style}
+					ios={{ accessibilityLabel: p.accessibilityLabel, ...p.ios }}
+					android={{ accessibilityLabel: p.accessibilityLabel, ...p.android }}
+				>
+					{children}
+				</Popover>
+			);
+		},
+		[fixed, isOpen, options.lightDismiss, options.dismissOnEscape, hide],
+	);
+
+	return (fixed
+		? { ref: undefined, id, isOpen, show, hide, render }
+		: { ref, anchorId: id, id, isOpen, show, hide, render }) as O extends FixedLayerOptions
+		? FixedLayerReturn
+		: ContextLayerReturn;
+}

package/src/use-layer.tsrx

@@ -0,0 +1,132 @@
+/** @jsxImportSource @nativescript-community/octane */
+import { LayerDepthProvider, useLayerDismissal } from './layer-dismissal.tsrx';
+import { useCallback, useEffect, useId, useRef, useState } from 'octane';
+import type {
+	ContextLayerReturn,
+	ContextRenderProps,
+	FixedLayerOptions,
+	FixedLayerReturn,
+	FixedRenderProps,
+	LayerOptions,
+} from './props';
+
+import { cx } from './cx';
+import { layerOffset, nativeLayerRTL, positionPopover, resolveLayerAlignment, resolveLayerSide } from './popover-position';
+
+const host = () => (globalThis as any).__xplatAppKit ?? {};
+
+function LayerPanel(props: { body?: any; className?: any; style?: any; label?: string; layerDepth?: number }) @{
+	<flexboxlayout
+		flexDirection="column"
+		className={cx('vx-popover', props.className)}
+		style={props.style}
+		accessibilityLabel={props.label}
+	>
+		<LayerDepthProvider value={props.layerDepth ?? 0}>{props.body}</LayerDepthProvider>
+	</flexboxlayout>
+}
+
+function LayerContentUpdate(props: { sync: () => void; body: any; surface?: ContextRenderProps | FixedRenderProps; open: boolean }) @{
+	useEffect(() => { props.sync(); }, [props.sync, props.open, props.body, props.surface]);
+	return null;
+}
+
+/**
+ * Anchored-layer primitive (Astryx `useLayer`), native-default/macOS leaf.
+ * The AppKit host bridge presents a self-drawn in-window view (`showLayer`).
+ * Context mode measures the ref view; fixed/custom use top-left window points. The panel is a separate
+ * Octane root; `render` passes updated content and surface props to that root
+ * while the layer is open. Context from the declaring tree is not shared.
+ */
+export function useLayer<O extends LayerOptions>(
+	options: O,
+): O extends FixedLayerOptions ? FixedLayerReturn : ContextLayerReturn @{
+	const fixed = options.mode === 'fixed';
+	const id = useId();
+	const [isOpen, setIsOpen] = useState(false);
+	const openRef = useRef(false);
+	const anchorEl = useRef<any>(null);
+	const markerEl = useRef<any>(null);
+	const content = useRef<any>(null);
+	const renderProps = useRef<ContextRenderProps | FixedRenderProps | undefined>(undefined);
+	const popup = useRef<any>(null);
+	const onShow = useRef(options.onShow);
+	onShow.current = options.onShow;
+	const onHide = useRef(options.onHide);
+	onHide.current = options.onHide;
+
+	const dismissal = useLayerDismissal({ get active() { return (options.isOpen ?? isOpen) && typeof host().showLayer === 'function' }, isPresent: () => !!popup.current && !popup.current.closed, dismiss: () => hide(), get behavior() { return (options.dismissOnEscape ?? options.lightDismiss) ? 'close' : 'block' } });
+
+	const controlled = options.isOpen !== undefined;
+	const visible = options.isOpen ?? isOpen;
+	const controlledOpen = useRef(options.isOpen);
+	controlledOpen.current = options.isOpen;
+	const position = (surface: ContextRenderProps | FixedRenderProps | undefined) => (anchor: any, panel: any, viewport: any) => {
+		const p = (surface ?? {}) as ContextRenderProps;
+		if (fixed || p.positioning === 'custom') {
+			const fx = surface as FixedRenderProps | undefined;
+			const x = fixed ? fx?.x ?? 0 : p.style?.left ?? 0;
+			const y = fixed ? fx?.y ?? 0 : p.style?.top ?? 0;
+			if (!Number.isFinite(x) || !Number.isFinite(y)) throw new TypeError('macOS custom layer left/top require finite window points');
+			return { left: x, top: y };
+		}
+
+		const rtl = nativeLayerRTL(anchorEl.current);
+		const side = resolveLayerSide(p.placement, rtl);
+		return positionPopover(anchor, panel, viewport, side, layerOffset(p.offset), resolveLayerAlignment(p.alignment, side, rtl));
+	};
+
+	const sync = (present = controlledOpen.current ?? openRef.current) => {
+		const p = renderProps.current;
+		if (!present) { popup.current?.close(); popup.current = null; return; }
+		const surface = { body: content.current, layerDepth: dismissal.depth, className: p?.className, style: p?.style, label: p?.accessibilityLabel };
+		if (popup.current) { popup.current.update(surface, { position: position(p), lightDismiss: options.lightDismiss === true }); return popup.current; }
+		const showLayer = host().showLayer;
+		if (typeof showLayer !== 'function') return;
+		const anchor = fixed ? markerEl.current : anchorEl.current;
+		if (!anchor) return;
+		popup.current = showLayer({ anchor, position: position(p), lightDismiss: options.lightDismiss === true,
+			onClose: () => { if (dismissal.shouldClose()) hide(); }, component: LayerPanel, props: surface });
+
+		return popup.current;
+	};
+
+	const show = useCallback(() => {
+		if (visible || openRef.current || typeof host().showLayer !== 'function') return;
+		if (!controlled) { if (!sync(true)) return; openRef.current = true; setIsOpen(true); }
+		onShow.current?.();
+	}, [visible, controlled, sync]);
+
+	const hide = useCallback(() => {
+		if (!(controlledOpen.current ?? openRef.current)) return;
+		if (!controlled) { openRef.current = false; setIsOpen(false); }
+		onHide.current?.();
+	}, [visible, controlled]);
+
+	useEffect(() => () => { openRef.current = false; popup.current?.close(); popup.current = null; }, []);
+
+	const ref = useCallback((el: any) => {
+		anchorEl.current = el;
+	}, []);
+
+	const render = useCallback(
+		(children: any, props?: ContextRenderProps | FixedRenderProps) => {
+			content.current = children;
+			renderProps.current = props;
+			// The layer mounts imperatively through the host bridge. The update
+			// component adds no view; the fixed-mode marker
+			// locates the owning AppKit view for the point anchor.
+			return <>
+				<LayerContentUpdate sync={sync} body={children} surface={props} open={visible} />
+				{fixed && <flexboxlayout ref={(v: any) => { markerEl.current = v; }} style={{ width: 0, height: 0 }} />}
+			</>;
+		},
+		[fixed, visible, sync],
+	);
+
+	return (fixed
+		? { ref: undefined, id, isOpen: visible, show, hide, render }
+		: { ref, anchorId: id, id, isOpen: visible, show, hide, render }) as O extends FixedLayerOptions
+		? FixedLayerReturn
+		: ContextLayerReturn;
+}

package/src/use-layer.web.test.tsrx

@@ -0,0 +1,77 @@
+// @vitest-environment jsdom
+import { act, createRoot } from 'octane'
+import { describe, expect, it, vi } from 'vitest'
+vi.mock('./theme/theme-scheme', () => ({ useThemeScheme: () => 'light' }))
+import { useLayer } from './use-layer'
+import { ownAnchorName } from './layer-position.web'
+
+let layer: any
+function Probe(props: { open?: boolean; hide?: () => void; custom?: boolean }) @{
+	layer = useLayer({ mode: 'context', isOpen: props.open, dismissOnEscape: true, onHide: props.hide })
+
+	<><button ref={layer.ref}>Anchor</button>{layer.render('Body', props.custom ? { positioning: 'custom', style: { right: 12, bottom: 18 }, accessibilityRole: 'dialog' } : { placement: 'below', accessibilityRole: 'dialog' })}</>
+}
+
+describe('useLayer ownership', () => {
+	it('keeps other anchor tokens during replacement, consumer edits and release', () => {
+		const a = document.createElement('div'), b = document.createElement('div')
+		a.style.setProperty('anchor-name', '--consumer')
+		const releaseFirst = ownAnchorName(a, '--first'), releaseSecond = ownAnchorName(a, '--second')
+		expect(a.style.getPropertyValue('anchor-name')).toBe('--consumer, --first, --second')
+		a.style.setProperty('anchor-name', a.style.getPropertyValue('anchor-name') + ', --later')
+		releaseFirst()
+		expect(a.style.getPropertyValue('anchor-name')).toBe('--consumer, --second, --later')
+		const releaseB = ownAnchorName(b, '--first')
+		releaseSecond(); releaseB()
+		expect(a.style.getPropertyValue('anchor-name')).toBe('--consumer, --later')
+		expect(b.style.getPropertyValue('anchor-name')).toBe('')
+	})
+
+	it('cleans its anchor on unmount and keeps rejected controlled dismissal mounted', () => {
+		const container = document.createElement('div'); document.body.append(container)
+		const root = createRoot(container), hide = vi.fn()
+		act(() => root.render(Probe, { open: true, hide, custom: true }))
+		const anchor = container.querySelector('button')!, panel = document.querySelector('[role="dialog"]') as HTMLElement
+		expect(panel.style.getPropertyValue('position-anchor')).toBe(layer.anchorId)
+		expect(panel.style.left).toBe('')
+		expect(panel.style.top).toBe('')
+		expect(panel.style.right).toBe('12px')
+		act(() => document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true, cancelable: true })))
+		expect(hide).toHaveBeenCalledTimes(1)
+		expect(document.querySelector('[role="dialog"]')).toBe(panel)
+		act(() => root.render(Probe, { open: false, hide }))
+		expect(document.querySelector('[role="dialog"]')).toBeNull()
+		expect(hide).toHaveBeenCalledTimes(1)
+		act(() => root.unmount())
+		expect(anchor.style.getPropertyValue('anchor-name')).toBe('')
+		container.remove()
+	})
+})
+
+
+function ExternalProbe() @{
+	layer = useLayer({ mode: 'context' })
+
+	<>{layer.render('Body', { placement: 'below', accessibilityRole: 'dialog' })}</>
+}
+
+describe('useLayer anchor replacement ownership', () => {
+	it('releases the previous element without deleting consumer names and cleans the current ref on unmount', () => {
+		const container = document.createElement('div'), next = document.createElement('div')
+		next.style.setProperty('anchor-name', '--consumer')
+		document.body.append(container, next)
+		const root = createRoot(container)
+		try {
+			act(() => root.render(ExternalProbe, {}))
+			const previous = document.createElement('button')
+			container.append(previous)
+			act(() => layer.ref(previous))
+			act(() => layer.ref(next))
+			expect(previous.style.getPropertyValue('anchor-name')).toBe('')
+			expect(next.style.getPropertyValue('anchor-name')).toContain('--consumer, --xplat-layer-')
+		} finally { act(() => root.unmount()); container.remove() }
+
+		expect(next.style.getPropertyValue('anchor-name')).toBe('--consumer')
+		next.remove()
+	})
+})