@octane-xplat/video 0.0.0 → 0.7.1

package/package.json

@@ -1,6 +1,76 @@
 {
-	"name": "@octane-xplat/video",
-	"version": "0.0.0",
-	"description": "Stub reserving the name; real releases publish from CI via trusted publishing.",
-	"publishConfig": {"access": "public"}
-}
+  "name": "@octane-xplat/video",
+  "version": "0.7.1",
+  "description": "Embedded video player for Octane xplat — web <video> + @nstudio/nativescript-exoplayer (ExoPlayer / AVPlayerViewController) with self-drawn chrome",
+  "keywords": [
+    "octane",
+    "xplat",
+    "cross-platform",
+    "video",
+    "video-player",
+    "exoplayer",
+    "avplayer",
+    "media",
+    "nativescript",
+    "ios",
+    "android",
+    "web"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/octane-xplat/octane-xplat/tree/main/packages/video",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/octane-xplat/octane-xplat.git",
+    "directory": "packages/video"
+  },
+  "files": [
+    "dist",
+    "types",
+    "src"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "macos": {
+        "types": "./types/index.macos.d.ts",
+        "default": "./src/index.macos.ts"
+      },
+      "types": "./types/index.d.ts",
+      "web": "./dist/web/index.js",
+      "native": "./dist/native/index.js",
+      "default": "./dist/native/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@nstudio/nativescript-exoplayer": "6.2.0"
+  },
+  "devDependencies": {
+    "@nativescript-community/octane": "0.2.1",
+    "@nativescript/core": "9.1.2",
+    "@octane-xplat/ui": "0.7.1",
+    "@octanejs/vite-plugin": "0.1.61",
+    "octane": "0.6.3",
+    "typescript": "5.9.3",
+    "vite": "8.3.0"
+  },
+  "peerDependencies": {
+    "@nativescript-community/octane": ">=0.2.1 <1",
+    "@nativescript/core": ">=9.1.0 <10",
+    "@octane-xplat/ui": ">=0.6.0 <1",
+    "octane": ">=0.6.3 <1"
+  },
+  "peerDependenciesMeta": {
+    "@nativescript-community/octane": {
+      "optional": true
+    },
+    "@nativescript/core": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "vite build && vite build --mode native && tsc -p tsconfig.types.json && node ../../scripts/check-native-dist.mjs"
+  }
+}

package/src/Video.macos.tsrx

@@ -0,0 +1,7 @@
+/** @jsxImportSource @xplat/macos/renderer */
+import type { VideoProps } from './props'
+
+/** Explicit placeholder until the AppKit host has a video surface. */
+export function Video(_props: VideoProps) @{
+	<label className="vx-unsupported">Video playback is unsupported by the AppKit host</label>
+}

package/src/Video.tsrx

@@ -0,0 +1,162 @@
+/** @jsxImportSource @nativescript-community/octane */
+import { useCallback, useEffect, useRef, useState } from 'octane';
+import { registerElement } from '@nativescript-community/octane';
+import type { Attributes } from '@nativescript-community/octane/intrinsics';
+import { Video as NSVideo, VideoFill } from '@nstudio/nativescript-exoplayer';
+import type { VideoHandle, VideoProps } from './props';
+import { cx } from './cx.mobile';
+import { applyEscapeProps, nativeAccessibilityRole, nativeAccessibilityState } from './escape-props';
+import { layoutChildProps } from './layout-child';
+import { VideoChrome } from './video-chrome.tsrx';
+
+declare module '@nativescript-community/octane/intrinsics' {
+	interface NativeScriptElements {
+		xplatvideo: Attributes<typeof NSVideo>;
+	}
+}
+
+// @nstudio/nativescript-exoplayer — AVPlayerViewController on iOS,
+// ExoPlayer2 on Android. It is a required peer: this leaf sits in the
+// shared native barrel, so every native app must declare the plugin for
+// the /ns/m dev bridge to resolve it under the app root.
+registerElement('xplatvideo', NSVideo);
+
+const FILLS: Record<string, any> = {
+	contain: VideoFill.aspect,
+	cover: VideoFill.aspectFill,
+	fill: VideoFill.fill,
+};
+
+/** Video — surface-hosted: the plugin supplies the engine surface
+ *  (`controls={false}` strips AVPlayerViewController/PlayerView chrome) and
+ *  the shared `VideoChrome` draws the transport on top. Times are ms —
+ *  the plugin's native unit on both platforms. One-time wiring (escape
+ *  props, `src`) lands in effects: the driver doesn't diff props, and
+ *  `src` must arrive after the flags (the plugin opens the clip when the
+ *  src property lands). The plugin emits `finished` even while looping —
+ *  `onEnded` suppresses it under `loop` to match the web leaf. */
+export function Video(props: VideoProps) @{
+	const host = useRef<any>(null);
+	const [playing, setPlaying] = useState(props.playing ?? props.autoPlay ?? false);
+	const [started, setStarted] = useState(false);
+	const [position, setPosition] = useState(0);
+	const [duration, setDuration] = useState(0);
+	const [internalMuted, setInternalMuted] = useState(false);
+	const muted = props.muted ?? internalMuted;
+	const appliedSrc = useRef<string | undefined>(undefined);
+
+	// Stable identity — an inline closure re-fires ref(null)/ref(v) per
+	// render, which would bounce host.current around the effects below.
+	const bindHost = useCallback((v: any) => {
+		host.current = v;
+	}, []);
+
+	const drive = (v: any, next: boolean) => {
+		if (!v) return;
+		if (next) v.play();
+		else v.pause();
+	};
+
+	// src + escape props land in effects: the driver doesn't diff props, and
+	// `src` must arrive after the flags (the plugin opens the clip when the
+	// src property lands).
+	useEffect(() => {
+		const v = host.current;
+		if (!v) return;
+		applyEscapeProps(v, props);
+		props.bind?.(handle(v));
+	}, []);
+
+	useEffect(() => {
+		const v = host.current;
+		if (!v || props.src === appliedSrc.current) return;
+		appliedSrc.current = props.src;
+		v.src = props.src;
+	}, [props.src]);
+
+	// Controlled `playing` writes — play state is a method call, not a prop.
+	useEffect(() => {
+		if (props.playing === undefined) return;
+		setPlaying(props.playing);
+		drive(host.current, props.playing);
+	}, [props.playing]);
+
+	const togglePlay = () => {
+		const next = !playing;
+		setPlaying(next);
+		drive(host.current, next);
+		props.onPlayingChange?.(next);
+	};
+
+	const handle = (v: any): VideoHandle => ({
+		play: () => v.play(),
+		pause: () => v.pause(),
+		seekTo: (ms: number) => v.seekToTime(ms / 1000),
+		currentTime: () => v.getCurrentTime(),
+		duration: () => v.getDuration(),
+		native: v,
+	});
+
+	<gridlayout
+		id={props.id}
+		rows="*"
+		columns="*"
+		className={cx('vx-stack', 'vx-video', props.className)}
+		style={props.style}
+		{...layoutChildProps(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}
+	>
+		<xplatvideo
+			ref={bindHost}
+			autoplay={props.playing ?? props.autoPlay ?? false}
+			controls={false}
+			loop={props.loop}
+			muted={muted}
+			fill={FILLS[props.fit ?? 'contain']}
+			observeCurrentTime={props.controls !== false}
+			onFinished={() => {
+				if (!props.loop) {
+					setPlaying(false);
+					props.onEnded?.();
+				}
+			}}
+			onPlaybackReady={() => {
+				const v = host.current;
+				const ms = v?.getDuration?.() ?? 0;
+				setDuration(ms);
+				props.onReady?.({ duration: ms });
+			}}
+			onPlaybackStart={() => setStarted(true)}
+			onCurrentTimeUpdated={(e: any) => setPosition(e.position ?? 0)}
+		/>
+		@if (props.controls !== false) {
+			<VideoChrome
+				poster={props.poster}
+				started={started}
+				playing={playing}
+				position={position}
+				duration={duration}
+				muted={muted}
+				onTogglePlay={togglePlay}
+				onToggleMute={() => {
+					const next = !muted;
+					setInternalMuted(next);
+					if (host.current) host.current.muted = next;
+					props.onMutedChange?.(next);
+				}}
+				onSeek={(ms: number) => {
+					if (host.current) {
+						host.current.seekToTime(ms / 1000);
+						setPosition(ms);
+					}
+				}}
+			/>
+		}
+	</gridlayout>
+}

package/src/Video.web.tsrx

@@ -0,0 +1,147 @@
+import { useEffect, useRef, useState } from 'octane';
+import type { VideoHandle, VideoProps } from './props';
+import { applyEscapeProps } from './escape-props';
+import { layoutChildProps } from './layout-child.web';
+import { VideoChrome } from './video-chrome.web.tsrx';
+
+const MEDIA_ERR: Record<number, string> = {
+	1: 'aborted',
+	2: 'network',
+	3: 'decode',
+	4: 'source-not-supported',
+};
+
+/** Video — chrome-reset surface + self-drawn transport. The `<video>`
+ *  element runs chrome-free (`controls` never set); the transport is the
+ *  shared `VideoChrome` overlay, identical source on every target. Times
+ *  are milliseconds — converted from the element's seconds at the
+ *  boundary. */
+export function Video(props: VideoProps) @{
+	const el = useRef<HTMLVideoElement | null>(null);
+	const [playing, setPlaying] = useState(props.playing ?? props.autoPlay ?? false);
+	const [started, setStarted] = useState(false);
+	const [position, setPosition] = useState(0);
+	const [duration, setDuration] = useState(0);
+	const [internalMuted, setInternalMuted] = useState(false);
+	const muted = props.muted ?? internalMuted;
+
+	const drive = (v: HTMLVideoElement | null, next: boolean) => {
+		if (!v) return;
+		if (next) {
+			// Autoplay-with-sound rejection parks the leaf back in paused.
+			v.play()?.catch(() => setPlaying(false));
+		} else {
+			v.pause();
+		}
+	};
+
+	// Controlled `playing` writes land imperatively — the DOM renderer
+	// diffs props, but play state is a method call, not an attribute.
+	useEffect(() => {
+		if (props.playing === undefined) return;
+		setPlaying(props.playing);
+		drive(el.current, props.playing);
+	}, [props.playing]);
+
+	// Uncontrolled autoplay start + controlled-prop mute echo.
+	useEffect(() => {
+		const v = el.current;
+		if (!v) return;
+		v.muted = muted;
+		if (props.autoPlay || props.playing) {
+			v.play()?.catch(() => setPlaying(false));
+		}
+	}, [muted]);
+
+	const togglePlay = () => {
+		const next = !playing;
+		setPlaying(next);
+		drive(el.current, next);
+		props.onPlayingChange?.(next);
+	};
+
+	const handle = (v: HTMLVideoElement): VideoHandle => ({
+		play: () => v.play(),
+		pause: () => v.pause(),
+		seekTo: (ms: number) => {
+			v.currentTime = ms / 1000;
+		},
+		currentTime: () => v.currentTime * 1000,
+		duration: () => (Number.isFinite(v.duration) ? v.duration * 1000 : 0),
+		native: v,
+	});
+
+	<div
+		id={props.id}
+		className={['vx-stack', 'vx-video', props.className]}
+		{...layoutChildProps(props, 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}
+	>
+		<video
+			ref={(v: HTMLVideoElement | null) => {
+				el.current = v;
+				if (!v) return;
+				v.muted = muted;
+				applyEscapeProps(v, props);
+				props.bind?.(handle(v));
+			}}
+			className="vx-video-surface"
+			src={props.src}
+			poster={props.poster}
+			muted={muted}
+			loop={props.loop}
+			playsInline={true}
+			preload="metadata"
+			style={{ objectFit: props.fit ?? 'contain' }}
+			onPlay={() => setPlaying(true)}
+			onPause={() => setPlaying(false)}
+			onPlaying={() => setStarted(true)}
+			onLoadedMetadata={(e: any) => {
+				const ms = e.currentTarget.duration * 1000;
+				setDuration(Number.isFinite(ms) ? ms : 0);
+				props.onReady?.({ duration: Number.isFinite(ms) ? ms : 0 });
+			}}
+			onTimeUpdate={(e: any) => setPosition(e.currentTarget.currentTime * 1000)}
+			onEnded={() => {
+				if (props.loop) return;
+				setPlaying(false);
+				props.onEnded?.();
+			}}
+			onError={(e: any) => {
+				const code = e.currentTarget?.error?.code ?? 0;
+				props.onError?.({ message: MEDIA_ERR[code] ?? 'unknown' });
+			}}
+		/>
+		@if (props.controls !== false) {
+			<VideoChrome
+				poster={props.poster}
+				started={started}
+				playing={playing}
+				position={position}
+				duration={duration}
+				muted={muted}
+				onTogglePlay={togglePlay}
+				onToggleMute={() => {
+					const next = !muted;
+					setInternalMuted(next);
+					if (el.current) el.current.muted = next;
+					props.onMutedChange?.(next);
+				}}
+				onSeek={(ms: number) => {
+					if (el.current) {
+						el.current.currentTime = ms / 1000;
+						setPosition(ms);
+					}
+				}}
+			/>
+		}
+	</div>
+}

package/src/cx.mobile.ts

@@ -0,0 +1,8 @@
+/** NS `className` splits on ' ' only, and the universal driver applies the
+ *  prop via `String(value)` — an array would arrive comma-joined and match
+ *  no class at all. Native leaves normalize through cx() before handing
+ *  className to an intrinsic. (The DOM renderer already flattens arrays,
+ *  so web leaves don't need this.) */
+export function cx(...parts: any[]): string {
+	return parts.flat(Infinity).filter(Boolean).join(' ')
+}

package/src/escape-props.ts

@@ -0,0 +1,65 @@
+import { isAndroid, isIOS } from '@nativescript/core'
+import type { Role } from './props'
+
+/** Apply only the active device's escape bag after the primitive's own props. */
+export function applyEscapeProps(view: any, props: { ios?: any; android?: any }): void {
+	if (!view) {
+		return
+	}
+
+	const bag = isIOS ? props.ios : isAndroid ? props.android : undefined
+	if (bag) {
+		Object.assign(view, bag)
+	}
+}
+
+const NATIVE_ACCESSIBILITY_ROLES: Record<Role, string> = {
+	button: 'button',
+	link: 'link',
+	search: 'search',
+	image: 'image',
+	heading: 'header',
+	adjustable: 'adjustable',
+	summary: 'summary',
+	text: 'text',
+	none: 'none',
+	progressbar: 'progressBar',
+	checkbox: 'checkbox',
+	switch: 'switch',
+	radio: 'radioButton',
+	spinbutton: 'spinButton',
+	// NativeScript has no tab role; a tab is still an actionable button and
+	// its selected state is carried separately by accessibilityState.
+	tab: 'button',
+}
+
+/** Translate the shared/ARIA spelling to NativeScript's narrower role enum. */
+export function nativeAccessibilityRole(role?: Role): string | undefined {
+	return role ? NATIVE_ACCESSIBILITY_ROLES[role] : undefined
+}
+
+/** NativeScript's AccessibilityState is a single enum value, unlike the
+ *  web's independent ARIA booleans. Priority follows the strongest state. */
+export function nativeAccessibilityState(state?: {
+	disabled?: boolean
+	selected?: boolean
+	checked?: boolean
+}): string | undefined {
+	if (state?.disabled) {
+		return 'disabled'
+	}
+
+	if (state?.selected) {
+		return 'selected'
+	}
+
+	if (state?.checked === true) {
+		return 'checked'
+	}
+
+	if (state?.checked === false) {
+		return 'unchecked'
+	}
+
+	return undefined
+}

package/src/escape-props.web.ts

@@ -0,0 +1,25 @@
+/** Apply DOM escape props after the primitive's own props. Dash-named keys
+ *  are attributes; other keys use the DOM property where available. */
+export function applyEscapeProps(element: any, props: { web?: any }): void {
+	if (!element || !props.web) {
+		return
+	}
+
+	for (const [key, value] of Object.entries(props.web)) {
+		if (key.includes('-')) {
+			if (value == null || value === false) {
+				element.removeAttribute(key)
+			} else {
+				element.setAttribute(key, value === true ? '' : String(value))
+			}
+		} else if (key in element) {
+			try {
+				element[key] = value
+			} catch {
+				element.setAttribute(key, String(value))
+			}
+		} else if (value != null) {
+			element.setAttribute(key, String(value))
+		}
+	}
+}

package/src/index.macos.ts

@@ -0,0 +1,2 @@
+export { Video } from './Video.macos.tsrx'
+export type { VideoEvent, VideoFit, VideoHandle, VideoProps } from './props'

package/src/index.ts

@@ -0,0 +1,2 @@
+export { Video } from './Video.tsrx'
+export type { VideoEvent, VideoFit, VideoHandle, VideoProps } from './props'

package/src/index.web.ts

@@ -0,0 +1,2 @@
+export { Video } from './Video.web.tsrx'
+export type { VideoEvent, VideoFit, VideoHandle, VideoProps } from './props'

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 }
+}