@octane-xplat/ui 0.6.0 → 0.7.1

package/src/FormField.tsrx

@@ -0,0 +1,25 @@
+/** @jsxImportSource @nativescript-community/octane */
+import type { FormFieldProps } from "./props";
+import { cx } from "./cx";
+import { applyEscapeProps } from "./escape-props";
+
+/** FormField — label + control + hint/error stack. The error replaces the
+ *  hint when present; `required` appends a marker to the label. */
+export function FormField(props: FormFieldProps) @{
+	const message = props.error ?? props.hint;
+
+	<flexboxlayout
+		ref={(v: any) => applyEscapeProps(v, props)}
+		id={props.id}
+		className={cx('vx-field', props.error && 'vx-field--error', props.className)}
+		style={props.style}
+	>
+		{props.label != null
+			? <label className="vx-field-label" text={props.required ? props.label + ' *' : props.label} />
+			: null}
+		{props.children}
+		{message != null
+			? <label className={cx('vx-field-msg', props.error && 'vx-field-msg--error')} text={message} />
+			: null}
+	</flexboxlayout>
+}

package/src/FormField.web.tsrx

@@ -0,0 +1,24 @@
+import type { FormFieldProps } from "./props";
+import { applyEscapeProps } from "./escape-props";
+
+/** FormField — label + control + hint/error stack. The error replaces the
+ *  hint when present; `required` appends a marker to the label. */
+export function FormField(props: FormFieldProps) @{
+	const message = props.error ?? props.hint;
+
+	<div
+		ref={(e: any) => applyEscapeProps(e, props)}
+		id={props.id}
+		className={['vx-field', props.error ? 'vx-field--error' : undefined, props.className]}
+		style={props.style}
+		role="group"
+	>
+		{props.label != null
+			? <span className="vx-field-label">{props.label}{props.required ? <span className="vx-field-required" aria-hidden="true"> *</span> : null}</span>
+			: null}
+		{props.children}
+		{message != null
+			? <span className={['vx-field-msg', props.error ? 'vx-field-msg--error' : undefined]} role={props.error ? 'alert' : undefined}>{message}</span>
+			: null}
+	</div>
+}

package/src/Grid.tsrx

@@ -0,0 +1,32 @@
+/** @jsxImportSource @nativescript-community/octane */
+import type { GridProps } from './props';
+import { cx } from './cx';
+import { applyEscapeProps, nativeAccessibilityRole, nativeAccessibilityState } from './escape-props';
+
+let warnedAboutGap = false;
+
+export function Grid(props: GridProps) @{
+	const deprecatedGap = (props as GridProps & { gap?: number | string }).gap;
+	if (deprecatedGap != null && !warnedAboutGap) {
+		warnedAboutGap = true;
+		console.warn('[Grid] gap was removed; use child margins');
+	}
+
+	<gridlayout
+		id={props.id}
+		ref={(view: any) => applyEscapeProps(view, props)}
+		rows={props.rows}
+		columns={props.columns}
+		className={cx('vx-grid', props.className)}
+		style={props.style}
+		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>
+}

package/src/Grid.web.tsrx

@@ -0,0 +1,43 @@
+import type { GridProps } from './props';
+import { applyEscapeProps } from './escape-props';
+
+function parseTracks(spec?: string) {
+	return spec?.split(',').map((part) => {
+		const track = part.trim();
+		if (track === 'auto') return 'auto';
+		if (track.endsWith('*')) return `${track.slice(0, -1) || '1'}fr`;
+		return /^\d+(?:\.\d+)?$/.test(track) ? `${track}px` : track;
+	}).join(' ');
+}
+
+let warnedAboutGap = false;
+
+export function Grid(props: GridProps) @{
+	const deprecatedGap = (props as GridProps & { gap?: number | string }).gap;
+	if (deprecatedGap != null && !warnedAboutGap) {
+		warnedAboutGap = true;
+		console.warn('[Grid] gap was removed; use child margins');
+	}
+
+	<div
+		id={props.id}
+		className={['vx-grid', props.className]}
+		style={{
+			...props.style,
+			...(props.rows ? { gridTemplateRows: parseTracks(props.rows) } : {}),
+			...(props.columns ? { gridTemplateColumns: parseTracks(props.columns) } : {}),
+		}}
+		ref={(el: any) => applyEscapeProps(el, props)}
+		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}
+	</div>
+}

package/src/Heading.macos.tsrx

@@ -0,0 +1,8 @@
+/** @jsxImportSource @xplat/macos/renderer */
+import type { HeadingProps } from './props'
+
+export function Heading(props: HeadingProps) @{
+	<label id={props.id} className={props.className} style={props.style} accessibilityRole="heading">
+		{props.children}
+	</label>
+}

package/src/Heading.tsrx

@@ -0,0 +1,17 @@
+/** @jsxImportSource @nativescript-community/octane */
+import { AccessibilityRole } from '@nativescript/core';
+import type { HeadingProps } from './props';
+import { cx } from './cx';
+import { applyNativeProps } from './platformProps';
+
+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={AccessibilityRole.Header}
+		ref={(el: any) => applyNativeProps(el, props)}
+	>{props.children}</label>
+}

package/src/Heading.web.tsrx

@@ -0,0 +1,15 @@
+import type { HeadingProps } from './props';
+import { normStyle } from './layout-child.web';
+import { applyWebProps } from './platformProps.web';
+
+export function Heading(props: HeadingProps) @{
+	const level = props.level ?? 2;
+	const tag = `h${level}`;
+
+	<{tag}
+		id={props.id}
+		className={['vx-heading', `vx-h${level}`, props.className]}
+		style={normStyle(props.style)}
+		ref={(el: any) => applyWebProps(el, props.web)}
+	>{props.children}</{tag}>
+}

package/src/Hoverable.mobile.tsrx

@@ -0,0 +1,21 @@
+/** @jsxImportSource @nativescript-community/octane */
+import type { HoverableProps } from './props';
+import { cx } from './cx';
+import { View } from './View.tsrx';
+
+/** Touch-target leaf: renders the children unchanged and never mounts the
+ *  hover card — pointer intent has no touch semantic. A long-press stand-in
+ *  is deliberately not provided (the fake-parity trap from decision #44).
+ *  Keep essential information out of `card`; the pointer platforms (web,
+ *  macOS) carry the real hover surface. */
+export function Hoverable(props: HoverableProps) @{
+	<View
+		id={props.id}
+		className={cx(props.className)}
+		style={props.style}
+		ios={props.ios}
+		android={props.android}
+	>
+		{props.children}
+	</View>
+}

package/src/Hoverable.tsrx

@@ -0,0 +1,113 @@
+/** @jsxImportSource @nativescript-community/octane */
+import { useEffect, useRef } from 'octane'
+import type { HoverableProps } from './props'
+import { cx } from './cx'
+import { View } from './View.tsrx'
+
+const host = () => (globalThis as any).__xplatAppKit ?? {}
+
+function HoverablePanel(props: { body?: any; className?: any; style?: any }) @{
+	<View className={cx('vx-hoverable-card', props.className)} style={props.style}>
+		{props.body}
+	</View>
+}
+
+/** Native-default leaf — the implementation, not a stub. On macOS the
+ *  `__xplatAppKit` bridge supplies real pointer intent: an NSTrackingArea
+ *  drives the same open/close delays as web and the card is an anchored
+ *  NSPopover that stays open while the pointer crosses to the panel (the
+ *  panel gets its own tracking area), matching the web leaf's pointer
+ *  bridge. iOS/Android take the `.mobile` passthrough; bridge-absent
+ *  targets (Windows) render the children only. The card renders once at
+ *  open in a separate Octane root — no shared context. */
+export function Hoverable(props: HoverableProps) @{
+	const anchor = useRef<any>(null)
+	const popup = useRef<any>(null)
+	const detachHover = useRef<(() => void) | null>(null)
+	const detachCardHover = useRef<(() => void) | null>(null)
+	const openTimer = useRef<ReturnType<typeof setTimeout> | null>(null)
+	const closeTimer = useRef<ReturnType<typeof setTimeout> | null>(null)
+
+	const clearOpen = () => {
+		if (openTimer.current !== null) clearTimeout(openTimer.current)
+		openTimer.current = null
+	}
+
+	const clearClose = () => {
+		if (closeTimer.current !== null) clearTimeout(closeTimer.current)
+		closeTimer.current = null
+	}
+
+	const closeNow = () => {
+		clearOpen()
+		clearClose()
+		detachCardHover.current?.()
+		detachCardHover.current = null
+		popup.current?.close()
+		popup.current = null
+	}
+
+	const openNow = () => {
+		if (popup.current) return
+		const view = anchor.current
+		const show = host().showAnchoredPopup
+		if (!view || typeof show !== 'function') return
+		popup.current = show({
+			anchor: view,
+			placement: props.placement ?? 'bottom',
+			component: HoverablePanel,
+			props: { body: props.card, className: props.cardClassName, style: props.cardStyle },
+		})
+
+		if (popup.current?.contentView && typeof host().observeHover === 'function') {
+			detachCardHover.current = host().observeHover(popup.current.contentView, {
+				enter: clearClose,
+				exit: scheduleClose,
+			})
+		}
+	}
+
+	const startOpen = () => {
+		clearClose()
+		clearOpen()
+		openTimer.current = setTimeout(() => {
+			openTimer.current = null
+			openNow()
+		}, Math.max(0, props.openDelay ?? 500))
+	}
+
+	const scheduleClose = () => {
+		clearClose()
+		closeTimer.current = setTimeout(() => {
+			closeTimer.current = null
+			closeNow()
+		}, Math.max(0, props.closeDelay ?? 120))
+	}
+
+	const bindAnchor = (view: any) => {
+		if (view && view === anchor.current && detachHover.current) return
+		anchor.current = view
+		detachHover.current?.()
+		detachHover.current = null
+		if (!view) return
+		const observe = host().observeHover
+		if (typeof observe !== 'function') return
+		detachHover.current = observe(view, {
+			enter: startOpen,
+			exit: () => { clearOpen(); scheduleClose() },
+		})
+	}
+
+	useEffect(() => () => {
+		clearOpen()
+		clearClose()
+		detachHover.current?.()
+		detachCardHover.current?.()
+		popup.current?.close()
+		popup.current = null
+	}, [])
+
+	<View id={props.id} className={props.className} style={props.style} bind={bindAnchor}>
+		{props.children}
+	</View>
+}

package/src/Hoverable.web.tsrx

@@ -0,0 +1,98 @@
+import { useEffect, useRef, useState } from 'octane';
+import { Popover } from './Popover.web.tsrx';
+import { View } from './View.web.tsrx';
+import type { HoverableProps } from './props';
+
+type Binding = { node: HTMLElement; enter: () => void; leave: () => void };
+
+/**
+ * Delayed hover intent with a card that remains open while the pointer moves
+ * through the body portal to the card. `bind` is used instead of delegated
+ * events so the anchor and portaled card can be tracked independently.
+ *
+ * Web-only (the `ui/web` subpath) — hover has no touch-platform semantic and
+ * the old native leaf's long-press→popover stand-in was fake parity.
+ */
+export function Hoverable(props: HoverableProps) @{
+	const [open, setOpen] = useState(false);
+	const anchor = useRef<any>(null);
+	const anchorBinding = useRef<Binding | null>(null);
+	const cardBinding = useRef<Binding | null>(null);
+	const openTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+	const closeTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+	const clearOpen = () => {
+		if (openTimer.current !== null) clearTimeout(openTimer.current);
+		openTimer.current = null;
+	};
+
+	const clearClose = () => {
+		if (closeTimer.current !== null) clearTimeout(closeTimer.current);
+		closeTimer.current = null;
+	};
+
+	const scheduleClose = () => {
+		clearClose();
+		closeTimer.current = setTimeout(() => {
+			closeTimer.current = null;
+			setOpen(false);
+		}, Math.max(0, props.closeDelay ?? 120));
+	};
+
+	const startOpen = () => {
+		clearClose();
+		clearOpen();
+		openTimer.current = setTimeout(() => {
+			openTimer.current = null;
+			setOpen(true);
+		}, Math.max(0, props.openDelay ?? 500));
+	};
+
+	const unbind = (binding: Binding | null) => {
+		if (!binding) return;
+		binding.node.removeEventListener('mouseenter', binding.enter);
+		binding.node.removeEventListener('mouseleave', binding.leave);
+	};
+
+	const bindAnchor = (node: HTMLElement | null) => {
+		anchor.current = node;
+		if (anchorBinding.current?.node === node) return;
+		unbind(anchorBinding.current);
+		anchorBinding.current = null;
+		if (!node) return;
+		const binding = { node, enter: startOpen, leave: () => { clearOpen(); scheduleClose(); } };
+		node.addEventListener('mouseenter', binding.enter);
+		node.addEventListener('mouseleave', binding.leave);
+		anchorBinding.current = binding;
+	};
+
+	const bindCard = (node: HTMLElement | null) => {
+		if (cardBinding.current?.node === node) return;
+		unbind(cardBinding.current);
+		cardBinding.current = null;
+		if (!node) return;
+		const binding = { node, enter: clearClose, leave: scheduleClose };
+		node.addEventListener('mouseenter', binding.enter);
+		node.addEventListener('mouseleave', binding.leave);
+		cardBinding.current = binding;
+	};
+
+	useEffect(() => () => {
+		clearOpen();
+		clearClose();
+		unbind(anchorBinding.current);
+		unbind(cardBinding.current);
+	}, []);
+
+	<View id={props.id} className={props.className} style={props.style} bind={bindAnchor} web={props.web}>
+		{props.children}
+		<Popover
+			open={open}
+			anchor={anchor}
+			placement={props.placement ?? 'bottom'}
+			dismissOnOutsideTap={false}
+		>
+			<View bind={bindCard} className={props.cardClassName} style={props.cardStyle}>{props.card}</View>
+		</Popover>
+	</View>
+}

package/src/Icon.macos.tsrx

@@ -0,0 +1,18 @@
+/** @jsxImportSource @xplat/macos/renderer */
+import type { IconProps } from './props'
+import { getIcon } from './icons'
+
+/** Icon — no svgview/NSImage glyph path on the AppKit host yet, so the
+ *  registered glyph name renders as text. `size` still sizes the frame so
+ *  layouts and the parity sweep measure the declared box. */
+export function Icon(props: IconProps) @{
+	const size = props.size ?? 24
+	const glyph = getIcon(props.name)
+	<label
+		className={props.className}
+		style={{ width: size, height: size, fontSize: size * 0.75, ...props.style }}
+		accessibilityLabel={props.accessibilityLabel ?? props.name}
+	>
+		{glyph?.font?.glyph ?? props.name}
+	</label>
+}

package/src/Icon.tsrx

@@ -0,0 +1,65 @@
+/** @jsxImportSource @nativescript-community/octane */
+import type { IconProps } from './props';
+import { getIcon } from './icons';
+import { cx } from './cx';
+import { applyNativeProps } from './platformProps';
+import { glyphSvgMarkup, isSvgSrc, svgSource } from './svg.mobile';
+
+export function Icon(props: IconProps) @{
+	const glyph = getIcon(props.name);
+	if (!glyph) return null;
+	const size = props.size ?? 24;
+	const markup = glyphSvgMarkup(glyph, props.color);
+
+	@if (markup) {
+		<svgview
+			id={props.id}
+			className={cx(props.className)}
+			src={markup}
+			stretch="aspectFit"
+			style={{ width: size, height: size }}
+			ref={(el: any) => applyNativeProps(el, props)}
+		/>
+	} @else {
+		@if (glyph.font) {
+			<label
+				id={props.id}
+				className={cx(props.className)}
+				text={glyph.font.glyph}
+				style={{ fontFamily: glyph.font.family, fontSize: size, color: props.color as any }}
+				ref={(el: any) => applyNativeProps(el, props)}
+			/>
+		} @else {
+			@if (glyph.src) {
+				@if (isSvgSrc(glyph.src)) {
+					<svgview
+						id={props.id}
+						className={cx(props.className)}
+						src={svgSource(glyph.src)}
+						stretch="aspectFit"
+						style={{ width: size, height: size }}
+						ref={(el: any) => applyNativeProps(el, props)}
+					/>
+				} @else {
+					<image
+						id={props.id}
+						className={cx(props.className)}
+						src={glyph.src}
+						style={{ width: size, height: size }}
+						ref={(el: any) => applyNativeProps(el, props)}
+					/>
+				}
+			} @else {
+				@if (glyph.text) {
+					<label
+						id={props.id}
+						className={cx(props.className)}
+						text={glyph.text}
+						style={{ fontSize: size, color: props.color as any }}
+						ref={(el: any) => applyNativeProps(el, props)}
+					/>
+				}
+			}
+		}
+	}
+}

package/src/Icon.web.tsrx

@@ -0,0 +1,75 @@
+import type { IconProps } from './props';
+import { getIcon } from './icons';
+import { applyWebProps } from './platformProps.web';
+
+export function Icon(props: IconProps) @{
+	const glyph = getIcon(props.name);
+	if (!glyph) return null;
+	const size = props.size ?? 24;
+
+	@if (glyph.markup) {
+		<svg
+			id={props.id}
+			className={['vx-icon', props.className]}
+			viewBox={glyph.viewBox ?? '0 0 24 24'}
+			width={size}
+			height={size}
+			aria-hidden="true"
+			style={props.color ? { color: props.color } : undefined}
+			ref={(el: any) => {
+				if (el) el.innerHTML = glyph.markup;
+				applyWebProps(el, props.web);
+			}}
+		></svg>
+	} @else {
+		@if (glyph.svg) {
+			<svg
+				id={props.id}
+				className={['vx-icon', props.className]}
+				viewBox={glyph.viewBox ?? '0 0 24 24'}
+				width={size}
+				height={size}
+				aria-hidden="true"
+				ref={(el: any) => applyWebProps(el, props.web)}
+			>
+				<path d={glyph.svg} fill={props.color ?? 'currentColor'} />
+			</svg>
+		} @else {
+			@if (glyph.font) {
+				<span
+					id={props.id}
+					className={['vx-icon', props.className]}
+					aria-hidden="true"
+					style={{ fontFamily: glyph.font.family, fontSize: size, color: props.color }}
+					ref={(el: any) => applyWebProps(el, props.web)}
+				>
+					{glyph.font.glyph}
+				</span>
+			} @else {
+				@if (glyph.src) {
+					<img
+						id={props.id}
+						className={['vx-icon', props.className]}
+						src={glyph.src}
+						width={size}
+						height={size}
+						alt={props.name}
+						ref={(el: any) => applyWebProps(el, props.web)}
+					/>
+				} @else {
+					@if (glyph.text) {
+						<span
+							id={props.id}
+							className={['vx-icon', props.className]}
+							aria-hidden="true"
+							style={{ fontSize: size, color: props.color }}
+							ref={(el: any) => applyWebProps(el, props.web)}
+						>
+							{glyph.text}
+						</span>
+					}
+				}
+			}
+		}
+	}
+}

package/src/Image.macos.tsrx

@@ -0,0 +1,12 @@
+/** @jsxImportSource @xplat/macos/renderer */
+import type { ImageProps } from './props'
+
+export function Image(props: ImageProps) @{
+	<image
+		id={props.id}
+		src={props.src}
+		className={props.className}
+		style={props.style}
+		accessibilityLabel={props.accessibilityLabel}
+	/>
+}

package/src/Image.tsrx

@@ -0,0 +1,51 @@
+/** @jsxImportSource @nativescript-community/octane */
+import { ImageSource } from '@nativescript/core';
+import { useMemo } from 'octane';
+import type { ImageProps } from './props';
+import { cx } from './cx';
+import { applyEscapeProps } from './escape-props';
+import { layoutChildProps } from './layout-child';
+import { isSvgSrc, svgSource } from './svg.mobile';
+/** Image — NS <image>. `src` accepts the NS ImageSource grammar:
+ *  res://name, ~/bundle-path, file path, remote URL, or data: URI. SVG srcs
+ *  (inline markup, svg data URIs, .svg paths/URLs) route to <svgview> —
+ *  remote .svg URLs fetch to markup since SVGView has no fetch of its own.
+ *  `alt` maps to accessibilityLabel (RN calls it `alt` on web parity). */
+export function Image(props: ImageProps) @{
+	const svg = useMemo(() => (isSvgSrc(props.src) ? svgSource(props.src) : null), [props.src]);
+	const source = useMemo(() => {
+		const comma = props.src.indexOf(',');
+		if (
+			props.src.startsWith('data:') &&
+			comma > 0 &&
+			props.src.slice(0, comma).endsWith(';base64')
+		) {
+			return ImageSource.fromBase64Sync(props.src.slice(comma + 1));
+		}
+
+		return props.src;
+	}, [props.src]);
+
+	@if (svg != null) {
+		<svgview
+			ref={(v: any) => applyEscapeProps(v, props)}
+			id={props.id}
+			{...layoutChildProps(props)}
+			className={cx(props.className)}
+			style={props.style}
+			src={svg}
+			stretch="aspectFit"
+			accessibilityLabel={props.alt}
+		/>
+	} @else {
+		<image
+			ref={(v: any) => applyEscapeProps(v, props)}
+			id={props.id}
+			{...layoutChildProps(props)}
+			className={cx(props.className)}
+			style={props.style}
+			src={source}
+			accessibilityLabel={props.alt}
+		/>
+	}
+}

package/src/Image.web.tsrx

@@ -0,0 +1,14 @@
+import type { ImageProps } from "./props";
+import { applyEscapeProps } from "./escape-props";
+import { layoutChildProps } from './layout-child.web';
+/** Image — a plain <img>. `src` takes any URL or data: URI. */
+export function Image(props: ImageProps) @{
+	<img
+		ref={(e: any) => applyEscapeProps(e, props)}
+		id={props.id}
+		className={props.className}
+		{...layoutChildProps(props)}
+		src={props.src}
+		alt={props.alt}
+	/>
+}