@octane-xplat/ui 0.6.0 → 0.7.0

package/src/layout-child.ts

@@ -0,0 +1,57 @@
+import type { LayoutChildProps, FlexContainerProps } from './props'
+
+// start/end shorthand → flex-start/flex-end.
+const FLEX_JUSTIFY: Record<string, string> = { start: 'flex-start', end: 'flex-end' }
+const FLEX_ALIGN: Record<string, string> = { start: 'flex-start', end: 'flex-end' }
+
+/** NativeScript reads these attributes from each child view during parent
+ *  layout. Values are forwarded with NativeScript's own property names.
+ *  The flex-container props (justifyContent/alignItems/flexWrap/gap) land on
+ *  the host flexboxlayout itself — its own attributes, not child metadata. */
+export function layoutChildProps(props: LayoutChildProps & Partial<FlexContainerProps>) {
+	const result: Record<string, any> = {}
+	for (const key of [
+		'row',
+		'col',
+		'rowSpan',
+		'colSpan',
+		'dock',
+		'left',
+		'top',
+		'flexGrow',
+		'flexShrink',
+		'alignSelf',
+		'order',
+	] as const) {
+		if (props[key] !== undefined) {
+			result[key] = props[key]
+		}
+	}
+
+	if (props.justifyContent !== undefined) {
+		result.justifyContent = FLEX_JUSTIFY[props.justifyContent] ?? props.justifyContent
+	}
+
+	if (props.alignItems !== undefined) {
+		result.alignItems = FLEX_ALIGN[props.alignItems] ?? props.alignItems
+	}
+
+	if (props.flexWrap !== undefined) {
+		result.flexWrap =
+			props.flexWrap === true ? 'wrap' : props.flexWrap === false ? 'nowrap' : props.flexWrap
+	}
+
+	if (props.gap !== undefined) {
+		result.gap = props.gap
+	}
+
+	if (props.rowGap !== undefined) {
+		result.rowGap = props.rowGap
+	}
+
+	if (props.columnGap !== undefined) {
+		result.columnGap = props.columnGap
+	}
+
+	return result
+}

package/src/layout-child.web.ts

@@ -0,0 +1,108 @@
+import type { LayoutChildProps, FlexContainerProps } from './props'
+
+/** The shared contract is "numbers are dips" (RN semantics), but octane's DOM
+ *  renderer keeps React's unitless list — lineHeight is unitless there, so
+ *  `style={{lineHeight: 40}}` would render a 40× multiplier instead of 40px.
+ *  lineHeight is the one unitless-in-React prop that is a length in the
+ *  shared vocabulary; force the px suffix. */
+export function normStyle(style: any) {
+	if (style && typeof style.lineHeight === 'number') {
+		return { ...style, lineHeight: style.lineHeight + 'px' }
+	}
+
+	return style
+}
+
+// start/end shorthand → flex-start/flex-end (valid in both engines).
+const FLEX_JUSTIFY: Record<string, string> = {
+	start: 'flex-start',
+	end: 'flex-end',
+}
+
+const FLEX_ALIGN: Record<string, string> = {
+	start: 'flex-start',
+	end: 'flex-end',
+}
+
+/** Convert parent-layout metadata to CSS on the web leaf. Native's `dock`
+ *  attribute has no CSS equivalent and is ignored on web. Grid indices are
+ *  zero-based in the shared API, matching NativeScript. */
+export function layoutChildProps(
+	props: LayoutChildProps & Partial<FlexContainerProps> & { style?: any },
+	baseStyle = props.style,
+) {
+	const style = { ...normStyle(baseStyle) }
+	if (props.row !== undefined) {
+		style.gridRow = `${props.row + 1} / span ${props.rowSpan ?? 1}`
+	} else if (props.rowSpan !== undefined) {
+		style.gridRow = `span ${props.rowSpan}`
+	}
+
+	if (props.col !== undefined) {
+		style.gridColumn = `${props.col + 1} / span ${props.colSpan ?? 1}`
+	} else if (props.colSpan !== undefined) {
+		style.gridColumn = `span ${props.colSpan}`
+	}
+
+	if (props.left !== undefined) {
+		style.left = props.left
+	}
+
+	if (props.top !== undefined) {
+		style.top = props.top
+	}
+
+	if (props.flexGrow !== undefined) {
+		style.flexGrow = props.flexGrow
+	}
+
+	if (props.flexShrink !== undefined) {
+		style.flexShrink = props.flexShrink
+	}
+
+	if (props.alignSelf !== undefined) {
+		style.alignSelf = props.alignSelf
+	}
+
+	if (props.order !== undefined) {
+		style.order = props.order
+	}
+
+	// Flex-container props (View/Row/Pressable hosts) — RN vocabulary on the
+	// element style. Numbers become px via octane's style normalization.
+	if (props.justifyContent !== undefined) {
+		style.justifyContent = FLEX_JUSTIFY[props.justifyContent] ?? props.justifyContent
+	}
+
+	if (props.alignItems !== undefined) {
+		style.alignItems = FLEX_ALIGN[props.alignItems] ?? props.alignItems
+	}
+
+	if (props.flexWrap !== undefined) {
+		style.flexWrap =
+			props.flexWrap === true ? 'wrap' : props.flexWrap === false ? 'nowrap' : props.flexWrap
+	}
+
+	if (props.gap !== undefined) {
+		style.gap = props.gap
+	}
+
+	if (props.rowGap !== undefined) {
+		style.rowGap = props.rowGap
+	}
+
+	if (props.columnGap !== undefined) {
+		style.columnGap = props.columnGap
+	}
+
+	// The shared contract is "numbers are dips" (RN semantics), but octane's
+	// DOM renderer keeps React's unitless list — lineHeight is unitless there,
+	// so `style={{lineHeight: 40}}` would render a 40× multiplier instead of
+	// 40px. lineHeight is the one unitless-in-React prop that is a length in
+	// the shared vocabulary; force the px suffix.
+	if (typeof style.lineHeight === 'number') {
+		style.lineHeight = style.lineHeight + 'px'
+	}
+
+	return { style }
+}

package/src/layout-shells.macos.tsrx

@@ -0,0 +1,10 @@
+/** @jsxImportSource @xplat/macos/renderer */
+import type { KeyboardAvoidingProps, SafeAreaProps } from './props'
+
+export function SafeArea(props: SafeAreaProps) @{
+	<flexboxlayout flexDirection="column" className={props.className} style={props.style}>{props.children}</flexboxlayout>
+}
+
+export function KeyboardAvoiding(props: KeyboardAvoidingProps) @{
+	<flexboxlayout flexDirection="column" className={props.className} style={props.style}>{props.children}</flexboxlayout>
+}

package/src/layout.macos.tsrx

@@ -0,0 +1,41 @@
+/** @jsxImportSource @xplat/macos/renderer */
+import type { AbsoluteProps, GridProps, SpacerProps, StackProps } from './props'
+import { cx } from './cx'
+import { applyEscapeProps, nativeAccessibilityRole, nativeAccessibilityState } from './escape-props'
+
+export function Grid(props: GridProps) @{
+	<gridlayout id={props.id} rows={props.rows} columns={props.columns} className={props.className} style={props.style}>
+		{props.children}
+	</gridlayout>
+}
+
+export function Stack(props: StackProps) @{
+	<gridlayout
+		id={props.id}
+		rows="*"
+		columns="*"
+		overlayChildren={true}
+		className={cx('vx-stack', props.className)}
+		style={props.style}
+		ref={(view: any) => applyEscapeProps(view, props)}
+		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}
+	>
+		{props.children}
+	</gridlayout>
+}
+
+export function Absolute(props: AbsoluteProps) @{
+	<absolutelayout id={props.id} className={props.className} style={props.style}>
+		{props.children}
+	</absolutelayout>
+}
+
+export function Spacer(props: SpacerProps) @{
+	<flexboxlayout className={cx('vx-spacer flex-1', props.className)} style={props.style} />
+}

package/src/macos-extras.macos.tsrx

@@ -0,0 +1,40 @@
+/** @jsxImportSource @xplat/macos/renderer */
+import type { HeadingProps, MeterProps } from './props'
+import { cx } from './cx'
+
+export function Meter(props: MeterProps) @{
+	const size = props.size ?? 24
+	const strokeWidth = Math.max(0, Math.min(props.strokeWidth ?? 3, size))
+	// Track ring via layer chrome; the progress arc itself needs a stroked
+	// CAShapeLayer — not bridged yet, so the ring renders unfilled.
+	<flexboxlayout
+		id={props.id}
+		className={cx('vx-meter', props.className)}
+		style={{
+			width: size,
+			height: size,
+			borderWidth: strokeWidth,
+			borderColor: props.trackColor ?? '#e1ecf7',
+			borderRadius: size / 2,
+			...props.style,
+		}}
+		accessible={true}
+		accessibilityRole="progressbar"
+		accessibilityValue={String(props.value ?? 0) + ' of ' + String(props.max ?? 100)}
+	>
+		{props.children}
+	</flexboxlayout>
+}
+
+export function Heading(props: HeadingProps) @{
+	const level = props.level ?? 2
+	<label
+		id={props.id}
+		className={cx('vx-heading', `vx-h${level}`, props.className)}
+		style={props.style}
+		accessibilityRole="heading"
+	>
+		{props.children}
+	</label>
+}
+

package/src/meter-math.ts

@@ -0,0 +1,6 @@
+/** Clamp a progress value to its declared range for drawing and accessibility. */
+export function meterRange(value: number, max: number) {
+	const safeMax = Number.isFinite(max) && max > 0 ? max : 100
+	const safeValue = Number.isFinite(value) ? Math.min(safeMax, Math.max(0, value)) : 0
+	return { max: safeMax, value: safeValue, ratio: safeValue / safeMax }
+}

package/src/modal-presenter.mobile.ts

@@ -0,0 +1,24 @@
+/** Resolve the view `showModal` should present from: the frame's current
+ *  page while it's live, else the frame itself. During push/pop churn
+ *  `currentPage` can still point at a page that already left the window —
+ *  presenting on a detached iOS VC silently drops the modal and its
+ *  closeCallback never runs, hanging `openModal`/`Modal` forever. A page
+ *  is a valid presenter only while it is loaded and still owned by the
+ *  frame (`page.frame` is the page's parent link, cleared on detach).
+ *  Returns null when nothing live can present — callers must surface that
+ *  rather than presenting blind. `frame` is structural: `Frame.topmost()`
+ *  types as FrameBase while stack registration hands over Frame. */
+export function modalPresenter(
+	frame: { currentPage?: any; isLoaded?: boolean } | undefined | null,
+): any {
+	if (!frame) {
+		return null
+	}
+
+	const page = frame.currentPage as any
+	if (page && page.isLoaded && page.frame === frame) {
+		return page
+	}
+
+	return (frame as any).isLoaded ? frame : null
+}

package/src/modifier-factories.ts

@@ -0,0 +1,20 @@
+import type { NativeModifier, NativeModifierValue } from './props'
+
+type StyleValues = Extract<NativeModifier, { type: 'style' }>['values']
+
+const style = (values: StyleValues): NativeModifier => ({ type: 'style', values })
+
+/** Serializable modifier factories for the platform-authentic UI subpaths. */
+export const modifier = {
+	background: (color: string) => style({ backgroundColor: color }),
+	cornerRadius: (radius: number) => style({ borderRadius: radius }),
+	opacity: (value: number) => style({ opacity: value }),
+	padding: (value: number | string) => style({ padding: value }),
+	frame: (width: number | string, height: number | string) => style({ width, height }),
+	style,
+	nativeProperty: (name: string, value: NativeModifierValue): NativeModifier => ({
+		type: 'property',
+		name,
+		value,
+	}),
+}

package/src/native/index.ts

@@ -0,0 +1,6 @@
+// @octane-xplat/ui/native — NativeScript integration plumbing shared by iOS
+// and Android. This is not part of the cross-platform component barrel.
+
+export { rootLayoutFor, topRootLayout, findInRootLayouts } from '../root-layout.mobile'
+export { layoutsForRoute } from '../route'
+export { sheetHost } from '../sheet-service'

package/src/pan.tsrx

@@ -0,0 +1,64 @@
+/** @jsxImportSource @nativescript-community/octane */
+import { useCallback, useRef } from 'octane';
+import { Utils } from '@nativescript/core';
+import type { PanEvent } from './props';
+
+/** Shared pan normalization for native leaves — NS pan payloads
+ *  ({deltaX,deltaY,state:int}) map to the shared gesture shape. Velocity:
+ *  iOS reads velocityInView, Android feeds MotionEvents to VelocityTracker
+ *  (dip/sec both). Returns undefined when no callback is set so leaves can
+ *  spread it straight into the gesture prop. */
+const PAN_STATE = ['cancelled', 'began', 'moved', 'ended'] as const;
+
+function panVelocity(e: any, state: number, trackerRef: { current: any }): { vx: number; vy: number } {
+	const recognizer = e.ios;
+	const nativeView = e.view?.nativeViewProtected;
+	if (recognizer?.velocityInView && nativeView) {
+		const velocity = recognizer.velocityInView(nativeView);
+		return { vx: velocity.x, vy: velocity.y };
+	}
+
+	// NativeScript's Android pan facade exposes the current MotionEvent but no
+	// velocity. Feed those events to the platform tracker and convert px/sec to
+	// the dip/sec units used by deltaX/deltaY.
+	const motionEvent = e.android?.current;
+	const velocityTrackerClass = (globalThis as any).android?.view?.VelocityTracker;
+	if (!motionEvent || !velocityTrackerClass) {
+		return { vx: 0, vy: 0 };
+	}
+
+	if (state === 1 || !trackerRef.current) {
+		trackerRef.current?.recycle?.();
+		trackerRef.current = velocityTrackerClass.obtain();
+	}
+
+	const tracker = trackerRef.current;
+	tracker.addMovement(motionEvent);
+	tracker.computeCurrentVelocity(1000);
+	const density = Utils.layout.getDisplayDensity();
+	const velocity = { vx: tracker.getXVelocity() / density, vy: tracker.getYVelocity() / density };
+	if (state === 0 || state === 3) {
+		tracker.recycle?.();
+		trackerRef.current = null;
+	}
+
+	return velocity;
+}
+
+export function usePan(cb?: (e: PanEvent) => void): ((e: any) => void) | undefined {
+	const velocityTracker = useRef<any>(null);
+	// Memoized so the driver's observer doesn't churn per render — each
+	// re-subscribe would re-attach a UIPanGestureRecognizer.
+	const handler = useCallback((e: any) => {
+		const state = PAN_STATE[e.state] ?? 'moved';
+		const velocity = panVelocity(e, e.state, velocityTracker);
+		cb?.({
+			x: e.deltaX, y: e.deltaY, dx: e.deltaX, dy: e.deltaY,
+			vx: velocity.vx, vy: velocity.vy,
+			state,
+			target: e.view ?? e.object,
+		});
+	}, [cb]);
+
+	return cb ? handler : undefined;
+}

package/src/pan.web.tsrx

@@ -0,0 +1,38 @@
+import { useEffect } from 'octane';
+import type { PanEvent } from './props';
+
+/** Shared pan plumbing for web leaves — pointerdown/move/up/cancel with
+ *  pointer capture, normalized to the shared gesture shape
+ *  {x,y,dx,dy,vx,vy,state,target}. `pointermove` isn't in octane's
+ *  delegated-event set, so listeners attach to the element directly —
+ *  that's why callers pass the bound-element ref. */
+export function usePan(el: { current: HTMLElement | null }, cb?: (e: PanEvent) => void): void {
+	useEffect(() => {
+		const node = el.current;
+		if (!node || !cb) return;
+		let sx = 0, sy = 0, active = false, last = 0, lx = 0, t0 = 0;
+		const emit = (e: PointerEvent, state: string) => {
+			const now = performance.now();
+			const dt = Math.max(now - t0, 1) / 1000;
+			const vx = (e.clientX - lx) / dt;
+			const vy = (e.clientY - last) / dt;
+			lx = e.clientX; last = e.clientY; t0 = now;
+			cb({ x: e.clientX - sx, y: e.clientY - sy, dx: e.clientX - sx, dy: e.clientY - sy, vx, vy, state, target: node });
+		};
+
+		const down = (e: PointerEvent) => { active = true; sx = e.clientX; sy = e.clientY; t0 = performance.now(); lx = sx; last = sy; node.setPointerCapture?.(e.pointerId); emit(e, 'began'); };
+		const move = (e: PointerEvent) => { if (active) emit(e, 'moved'); };
+		const up = (e: PointerEvent) => { if (active) { active = false; emit(e, 'ended'); } };
+		const cancel = (e: PointerEvent) => { if (active) { active = false; emit(e, 'cancelled'); } };
+		node.addEventListener('pointerdown', down);
+		node.addEventListener('pointermove', move);
+		node.addEventListener('pointerup', up);
+		node.addEventListener('pointercancel', cancel);
+		return () => {
+			node.removeEventListener('pointerdown', down);
+			node.removeEventListener('pointermove', move);
+			node.removeEventListener('pointerup', up);
+			node.removeEventListener('pointercancel', cancel);
+		};
+	}, [el, cb]);
+}

package/src/platform.macos.ts

@@ -0,0 +1 @@
+export const isNative = true as const

package/src/platform.ts

@@ -0,0 +1,7 @@
+/** Compile-time platform flag — `true` in every NativeScript build.
+ *  Prefer `.web`/unsuffixed native defaults leaves for real divergence; `isNative` covers
+ *  the render-time cases (conditional JSX, prop selection) where a whole
+ *  leaf file is heavier than the difference. For OS-level splits use
+ *  `.ios`/`.android` leaves or `isIOS`/`isAndroid` from @nativescript/core
+ *  inside native-default code. */
+export const isNative = true

package/src/platform.web.ts

@@ -0,0 +1,6 @@
+/** Compile-time platform flag — `false` in every web build. Prefer
+ *  `.web`/unsuffixed native defaults leaves for real divergence; `isNative` covers the
+ *  render-time cases (conditional JSX, prop selection) where a whole
+ *  leaf file is heavier than the difference. Bundlers constant-fold it,
+ *  so `!isNative` branches tree-shake out of web output. */
+export const isNative = false

package/src/platformProps.ts

@@ -0,0 +1,23 @@
+import { isAndroid, isIOS } from '@nativescript/core'
+import type { NativeModifier } from './props'
+import { applyNativeModifiers } from './apply-native-modifiers.native'
+
+/** Apply the matching native escape-hatch bag after the primitive's props. */
+export function applyNativeProps(
+	el: any,
+	props: {
+		ios?: Record<string, any>
+		android?: Record<string, any>
+		modifiers?: readonly NativeModifier[]
+	},
+): void {
+	if (!el) {
+		return
+	}
+
+	const bag = isIOS ? props.ios : isAndroid ? props.android : undefined
+	if (bag) {
+		Object.assign(el, bag)
+	}
+	applyNativeModifiers(el, props.modifiers)
+}

package/src/platformProps.web.ts

@@ -0,0 +1,14 @@
+/** Apply a web escape-hatch bag after the primitive's standard props. */
+export function applyWebProps(el: any, props: Record<string, any> | undefined) {
+	if (!el || !props) {
+		return
+	}
+
+	for (const [name, value] of Object.entries(props)) {
+		if (name.includes('-')) {
+			el.setAttribute(name, String(value))
+		} else {
+			el[name] = value
+		}
+	}
+}

package/src/popover-position.ts

@@ -0,0 +1,62 @@
+import type { PopoverPlacement } from './props'
+
+export interface PopoverRect {
+	left: number
+	top: number
+	width: number
+	height: number
+}
+
+export interface PopoverPosition {
+	left: number
+	top: number
+	placement: PopoverPlacement
+}
+
+const opposite: Record<PopoverPlacement, PopoverPlacement> = {
+	top: 'bottom',
+	bottom: 'top',
+	left: 'right',
+	right: 'left',
+}
+
+/** Place beside the anchor, flip once when the requested side overflows, then clamp. */
+export function positionPopover(
+	anchor: PopoverRect,
+	panel: Pick<PopoverRect, 'width' | 'height'>,
+	viewport: PopoverRect,
+	requested: PopoverPlacement = 'bottom',
+	gap = 8,
+): PopoverPosition {
+	const at = (placement: PopoverPlacement): { left: number; top: number } => {
+		switch (placement) {
+			case 'top':
+				return { left: anchor.left, top: anchor.top - panel.height - gap }
+			case 'bottom':
+				return { left: anchor.left, top: anchor.top + anchor.height + gap }
+			case 'left':
+				return { left: anchor.left - panel.width - gap, top: anchor.top }
+			case 'right':
+				return { left: anchor.left + anchor.width + gap, top: anchor.top }
+		}
+
+		throw new Error(`Unknown popover placement: ${placement}`)
+	}
+
+	const fits = (position: { left: number; top: number }) =>
+		position.left >= viewport.left &&
+		position.top >= viewport.top &&
+		position.left + panel.width <= viewport.left + viewport.width &&
+		position.top + panel.height <= viewport.top + viewport.height
+
+	const preferred = at(requested)
+	const placement = fits(preferred) ? requested : opposite[requested]
+	const raw = placement === requested ? preferred : at(placement)
+	const maxLeft = Math.max(viewport.left, viewport.left + viewport.width - panel.width)
+	const maxTop = Math.max(viewport.top, viewport.top + viewport.height - panel.height)
+	return {
+		left: Math.min(maxLeft, Math.max(viewport.left, raw.left)),
+		top: Math.min(maxTop, Math.max(viewport.top, raw.top)),
+		placement,
+	}
+}

package/src/popover.mobile.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it, vi } from 'vitest'
+
+const hosts: any[] = []
+
+vi.mock('@nativescript/core', () => ({
+	Application: {
+		primaryWindow: undefined,
+		on: () => {},
+		off: () => {},
+	},
+	GridLayout: class {
+		className = ''
+		horizontalAlignment = ''
+		verticalAlignment = ''
+		style: Record<string, unknown> = {}
+		constructor() {
+			hosts.push(this)
+		}
+	},
+}))
+
+vi.mock('@nativescript-community/octane', async (importOriginal) => ({
+	...(await importOriginal<Record<string, unknown>>()),
+	createNativeScriptRoot: () => ({ render() {}, unmount() {} }),
+}))
+
+vi.mock('./root-layout.mobile', () => ({
+	rootLayoutFor: () => ({
+		open: async () => {},
+		hasChild: () => false,
+		close: async () => {},
+	}),
+}))
+
+import { createObjectContainer, createObjectDriver, createUniversalRoot, flushUniversalSync } from 'octane/universal/native'
+import { Popover } from './Popover.tsrx'
+
+// The full-screen host must not wear the caller's className — a backgrounded
+// class like vx-menu would paint the whole screen (0.4.0–0.6.0 regression).
+describe('native Popover host', () => {
+	it('stamps only vx-popover-host on the overlay host', async () => {
+		const container = createObjectContainer('nativescript')
+		const root = createUniversalRoot(container, createObjectDriver('nativescript'))
+		const anchor = { current: {} }
+		root.render(Popover as any, { open: true, anchor, className: 'vx-menu' })
+		flushUniversalSync(() => {})
+		await vi.waitFor(() => expect(hosts.length).toBe(1))
+
+		expect(hosts).toHaveLength(1)
+		expect(hosts[0].className).toContain('vx-popover-host')
+		expect(hosts[0].className).not.toContain('vx-menu')
+		root.unmount()
+	})
+})