@octane-xplat/pager 0.0.0-nightly.g2e22171

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Alec Larson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,56 @@
+# `@octane-xplat/pager`
+
+A paged horizontal swipe container for Octane Xplat apps — onboarding flows,
+media galleries. Each page fills the host; the user swipes between pages.
+
+```sh
+pnpm add @octane-xplat/pager
+```
+
+```tsx
+import { useState } from 'octane'
+import { Text } from '@octane-xplat/ui'
+import { Pager } from '@octane-xplat/pager'
+
+export function Onboarding() {
+	const [page, setPage] = useState(0)
+	return (
+		<Pager
+			items={['Pack', 'Travel']}
+			page={page}
+			onPageChange={setPage}
+			renderItem={(title) => <Text>{title}</Text>}
+			renderEmpty={() => <Text>No pages</Text>}
+		/>
+	)
+}
+```
+
+It follows the platform-list contract — `items` + `renderItem`, no children;
+each page is a full-host-size cell. `onPageChange` fires on settled user
+swipes; programmatic `page` writes don't echo back. `renderEmpty` covers the
+empty list.
+
+There is no built-in page indicator. Compose one from `HStack` + `Text`
+driven by the `page` state:
+
+```tsx
+import { HStack, Text } from '@octane-xplat/ui'
+
+;<HStack>
+	{titles.map((title, index) => (
+		<Text>{index === page ? '●' : '○'}</Text>
+	))}
+</HStack>
+```
+
+## Platform support
+
+- **iOS/Android** — `@nativescript-community/ui-pager` (ViewPager2 on Android,
+  a paging `UICollectionView` on iOS)
+- **Web** — a scroll-snap scroller
+- **macOS** — an entry exists
+
+Per-target limits are recorded in
+[known limits](../../docs/verify/known-limits.md). Exercised by
+[`PagerDemo`](../demos/src/PagerDemo.tsrx).

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@octane-xplat/pager",
+  "version": "0.0.0-nightly.g2e22171",
+  "description": "Paged swipe container for Octane xplat — web scroll-snap row + @nativescript-community/ui-pager (ViewPager2 / paging UICollectionView)",
+  "keywords": [
+    "android",
+    "carousel",
+    "cross-platform",
+    "ios",
+    "nativescript",
+    "octane",
+    "pager",
+    "paging",
+    "swipe",
+    "viewpager",
+    "web",
+    "xplat"
+  ],
+  "homepage": "https://github.com/octane-xplat/octane-xplat/tree/main/packages/pager",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/octane-xplat/octane-xplat",
+    "directory": "packages/pager"
+  },
+  "files": [
+    "types",
+    "src",
+    "!src/**/*.test.*",
+    "!src/**/*.spec.*"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "macos": {
+        "types": "./types/index.macos.d.ts",
+        "default": "./src/index.macos.ts"
+      },
+      "types": "./types/index.d.ts",
+      "web": "./src/index.web.ts",
+      "native": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@nativescript-community/ui-pager": "14.1.42"
+  },
+  "devDependencies": {
+    "@nativescript-community/octane": "0.2.5",
+    "@nativescript/core": "9.1.3",
+    "@octane-xplat/macos-renderer": "0.0.0-nightly.g2e22171",
+    "@octane-xplat/ui": "0.0.0-nightly.g2e22171",
+    "@octanejs/vite-plugin": "0.1.61",
+    "octane": "0.11.0",
+    "tsrx-typegen": "0.3.0",
+    "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": {
+    "test:native": "vitest run --config vitest.native.config.mts",
+    "typegen": "tsc -p tsconfig.types.json",
+    "test:packed": "node tests/packed-consumer.mjs",
+    "pack:check": "tsrx-typegen --pack-check"
+  }
+}

package/src/Pager.macos.tsrx

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

package/src/Pager.parity.check.ts

@@ -0,0 +1,19 @@
+import type { ParityCheck } from '@octane-xplat/ui/parity/check-helpers'
+import { dims } from '@octane-xplat/ui/parity/check-helpers'
+
+export const CHECKS: ParityCheck[] = [
+
+	{
+		fixture: 'pager-two-pages',
+		targets: ['web', 'ios', 'android'],
+		elements: { pager: 'parity-pager-root', page: 'parity-pager-page' },
+		equal: [
+			'pager.box.w',
+			'pager.box.h',
+			'pager.style.backgroundColor',
+			'page.box.w',
+			'page.box.h',
+		],
+		check: (m) => [dims(m('pager'), 220, 96), dims(m('page'), 220, 96)],
+	}
+]

package/src/Pager.parity.tsrx

@@ -0,0 +1,19 @@
+// Measured parity fixtures — assertions live in Pager.parity.check.ts.
+import { Pager } from './Pager'
+import { View } from '@octane-xplat/ui'
+import type { ParityFixture } from '@octane-xplat/ui/parity'
+
+function PagerFixture() @{
+	<Pager
+		className="parity-pager-root"
+		style={{ width: 220, height: 96, backgroundColor: '#f5f5f5' }}
+		items={[{ key: 'first' }, { key: 'second' }]}
+		renderItem={() => (
+			<View className="parity-pager-page" style={{ width: 220, height: 96 }} />
+		)}
+	/>
+}
+
+export const PARITY: ParityFixture[] = [
+	{ name: 'pager-two-pages', component: 'Pager', renderer: PagerFixture, props: {} },
+]

package/src/Pager.tsrx

@@ -0,0 +1,255 @@
+/** @jsxImportSource @nativescript-community/octane */
+import { memo, useCallback, useEffect, useRef, useState } from 'octane';
+import {
+	registerElement,
+} from '@nativescript-community/octane';
+
+import type { Attributes } from '@nativescript-community/octane/intrinsics';
+import { createPortal as createUniversalPortal, type UniversalRenderable } from 'octane/universal/native';
+import { Pager as NSPager } from '@nativescript-community/ui-pager';
+import { GridLayout } from '@nativescript/core';
+import type { PagerProps } from './props';
+import { applyEscapeProps, nativeAccessibilityRole, nativeAccessibilityState } from './escape-props.mobile';
+import { layoutChildProps } from './layout-child';
+
+declare module '@nativescript-community/octane/intrinsics' {
+	interface NativeScriptElements {
+		pager: Attributes<typeof NSPager>;
+	}
+}
+
+// @nativescript-community/ui-pager — ViewPager2 on Android, a paging
+// UICollectionView on iOS. 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('pager', NSPager);
+
+function createPortal(children: unknown, target: unknown) {
+	return createUniversalPortal(children as UniversalRenderable, target);
+}
+
+/** One recycled page: the adapter-owned host plus the current render data.
+	 *  Its content is a portal from Pager's declaring tree. */
+interface PagerCell {
+	host: any;
+	pager: any;
+	renderItem: any;
+	item: any;
+	index: number;
+}
+
+const cellsByHost = new WeakMap<object, PagerCell>();
+const cellsByPager = new WeakMap<object, Set<PagerCell>>();
+
+function cellFor(host: any): PagerCell {
+	let cell = cellsByHost.get(host);
+	if (!cell) {
+		cell = { host, pager: null, renderItem: null, item: undefined, index: -1 };
+		cellsByHost.set(host, cell);
+	}
+
+	return cell;
+}
+
+/** `createView` runs inside the plugin's adapter — no pager instance in
+ *  scope, so the cell is only linked to its pager at `itemLoading` (where
+ *  `args.object` is the owner). */
+function createPageHost() {
+	const host = new GridLayout();
+	cellFor(host);
+	return host;
+}
+
+const PAGER_TEMPLATES = [{ key: 'xplat-page', createView: createPageHost }];
+// The built-in 'default' template stays first in the plugin's internal
+// list, so the selector must name our key — a 'default' entry would match
+// the built-in (an XML string parse, which yields nothing here).
+const selectPageTemplate = () => 'xplat-page';
+
+function releasePagerCells(pager: any) {
+	const cells = cellsByPager.get(pager);
+	if (!cells) return;
+	for (const cell of cells) {
+		cellsByHost.delete(cell.host);
+	}
+
+	cellsByPager.delete(pager);
+}
+
+function PagerInner(props: PagerProps) @{
+	const host = useRef<any>(null);
+	const [portalCells, setPortalCells] = useState<PagerCell[]>([]);
+	// Track selectedIndex writes across synchronous and delayed echoes.
+	// The plugin raises
+	// 'selectedIndexChange' for script writes exactly as for swipes, and
+	// the driver's auto-mute only covers JSX prop writes, not ours.
+	const current = useRef(props.page ?? props.defaultPage ?? 0);
+	const pageSeeded = useRef(false);
+
+	// Stable ref 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 bindCell = (args: any) => {
+		const cell = cellFor(args.view);
+		cell.pager = args.object;
+		let owned = cellsByPager.get(cell.pager);
+		if (!owned) {
+			owned = new Set();
+			cellsByPager.set(cell.pager, owned);
+		}
+
+		owned.add(cell);
+		const item = args.bindingContext ?? props.items?.[args.index];
+		if (cell.renderItem === props.renderItem && cell.index === args.index && Object.is(cell.item, item)) {
+			return;
+		}
+
+		cell.renderItem = props.renderItem;
+		cell.item = item;
+		cell.index = args.index;
+		setPortalCells((current) => {
+			const existing = current.some((entry) => entry === cell);
+			return existing ? [...current] : [...current, cell];
+		});
+	};
+
+	const disposeCell = (args: any) => {
+		const cell = args.view && cellsByHost.get(args.view);
+		if (cell) {
+			cellsByHost.delete(args.view);
+			if (cell.pager) cellsByPager.get(cell.pager)?.delete(cell);
+			setPortalCells((current) => current.filter((entry) => entry !== cell));
+		}
+	};
+
+	// One-time wiring (mount): the template set + selector are imperative —
+	// as JSX props they would be re-applied on every render. The cleanup
+	// captures the pager so cell roots release after the ref detaches.
+	useEffect(() => {
+		const pager = host.current;
+		if (!pager) return;
+		pager.itemTemplates = PAGER_TEMPLATES;
+		pager.itemTemplateSelector = selectPageTemplate;
+		return () => releasePagerCells(pager);
+	}, []);
+
+	// Items and the index are imperative writes, not JSX props: `items` must
+	// land before `selectedIndex` (the plugin coerces the index against the
+	// page count — a write ahead of items clamps to -1), and a re-assert
+	// after an items change repairs the plugin's own re-coercion.
+	useEffect(() => {
+		const pager = host.current;
+		if (!pager) return;
+		applyEscapeProps(pager, props);
+		if (pager.items !== props.items) pager.items = props.items;
+		const target = props.page ?? (pageSeeded.current ? undefined : props.defaultPage);
+		if (target !== undefined && pager.selectedIndex !== target) {
+			// Track the coerced target before writing: Android may echo later.
+			current.current = Math.max(0, Math.min(props.items.length - 1, target));
+			pager.selectedIndex = target;
+		}
+
+		pageSeeded.current = true;
+	});
+
+	<>
+	<pager
+		ref={bindHost}
+		id={props.id}
+		{...layoutChildProps(props)}
+		className={['vx-pager', props.className]}
+		style={props.style}
+		onItemLoading={bindCell}
+		onItemDisposing={disposeCell}
+		onSelectedIndexChange={(args: any) => {
+			if (args.value !== current.current) {
+				current.current = args.value;
+				props.onPageChange?.(args.value);
+			}
+		}}
+		accessibilityRole={nativeAccessibilityRole(props.accessibilityRole) as any}
+		accessibilityLabel={props.accessibilityLabel}
+		accessibilityHint={props.accessibilityHint}
+		accessibilityValue={props.accessibilityValue}
+		accessibilityState={nativeAccessibilityState(props.accessibilityState) as any}
+		accessible={props.accessible}
+		accessibilityLiveRegion={props.accessibilityLiveRegion as any}
+	/>
+	{portalCells.map((cell) =>
+		createPortal(
+			<gridlayout>{cell.renderItem?.(cell.item, cell.index)}</gridlayout>,
+			cell.host,
+		),
+	)}
+	</>
+}
+
+// The pager subtree is memoized on `items` and configuration: the universal
+// driver re-applies props on every render (no value diffing) and a stray
+// `items` write would refresh the whole adapter. Constraint matches
+// UITableView: `renderItem` should be identity-stable — a fresh closure per
+// render is deliberately not part of the compare. (`PagerInner` must precede
+// this — compiled components are consts, not hoisted functions.)
+const MemoPager = memo(PagerInner, (a, b) =>
+	a.items === b.items &&
+	a.className === b.className &&
+	a.style === b.style &&
+	a.id === b.id &&
+	a.page === b.page &&
+	a.onPageChange === b.onPageChange &&
+	a.ios === b.ios &&
+	a.android === b.android &&
+	a.row === b.row &&
+	a.col === b.col &&
+	a.rowSpan === b.rowSpan &&
+	a.colSpan === b.colSpan &&
+	a.dock === b.dock &&
+	a.left === b.left &&
+	a.top === b.top &&
+	a.flexGrow === b.flexGrow &&
+	a.flexShrink === b.flexShrink &&
+	a.alignSelf === b.alignSelf &&
+	a.order === b.order &&
+	a.accessible === b.accessible &&
+	a.accessibilityRole === b.accessibilityRole &&
+	a.accessibilityLabel === b.accessibilityLabel &&
+	a.accessibilityHint === b.accessibilityHint &&
+	a.accessibilityValue === b.accessibilityValue &&
+	a.accessibilityState === b.accessibilityState &&
+	a.accessibilityLiveRegion === b.accessibilityLiveRegion
+);
+
+/** Pager — paged horizontal swiping via @nativescript-community/ui-pager
+ *  (ViewPager2 / paging UICollectionView), chrome-reset: one full-size cell
+ *  per item, no indicator. Pages recycle through `itemTemplates` +
+ *  `itemLoading`; active cell hosts are portals from the Pager's declaring
+ *  tree, so provider context follows each cell. */
+export function Pager(props: PagerProps) @{
+	@if (props.items.length > 0) {
+		<MemoPager
+			accessible={props.accessible}
+			accessibilityRole={props.accessibilityRole}
+			accessibilityLabel={props.accessibilityLabel}
+			accessibilityHint={props.accessibilityHint}
+			accessibilityValue={props.accessibilityValue}
+			accessibilityState={props.accessibilityState}
+			accessibilityLiveRegion={props.accessibilityLiveRegion}
+			id={props.id}
+			className={props.className}
+			style={props.style}
+			items={props.items}
+			renderItem={props.renderItem}
+			page={props.page}
+			defaultPage={props.defaultPage}
+			onPageChange={props.onPageChange}
+			ios={props.ios}
+			android={props.android}
+			{...layoutChildProps(props)}
+		/>
+	} @else {
+		<>{props.renderEmpty?.()}</>
+	}
+}

package/src/Pager.web.tsrx

@@ -0,0 +1,107 @@
+import { useEffect, useRef } from 'octane';
+import type { PagerProps } from './props';
+import { applyWebProps } from './platformProps.web';
+import { layoutChildProps } from './layout-child.web';
+
+/** Paged horizontal container — web leaf: a mandatory scroll-snap row, one
+ *  page per item at 100% host width. `onPageChange` fires on the settled
+ *  snap page (a scroll-idle debounce reads scrollLeft after the snap lands),
+ *  matching the native widget's selected-index event. Programmatic `page`
+ *  writes are tracked in `current` so their own scroll never echoes back
+ *  through `onPageChange` — same contract as the muted property echo on
+ *  native. No indicator — compose dots from Row + View outside. */
+export function Pager(props: PagerProps) @{
+	const host = useRef<HTMLElement | null>(null);
+	const latest = useRef(props);
+	// The page the leaf believes it is on: seeded by `page`/`defaultPage`,
+	// updated by controlled writes and settled swipes. A scroll that lands
+	// on `current` is programmatic — the settle never reports it.
+	const current = useRef(props.page ?? props.defaultPage ?? 0);
+	const hasItems = props.items.length > 0;
+	const settle = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+	useEffect(() => {
+		latest.current = props;
+	});
+
+	useEffect(() => {
+		const el = host.current;
+		if (!el) return;
+		const onScroll = () => {
+			if (settle.current !== null) clearTimeout(settle.current);
+			settle.current = setTimeout(() => {
+				settle.current = null;
+				const el2 = host.current;
+				if (!el2 || el2.clientWidth === 0) return;
+				const max = Math.max(latest.current.items.length - 1, 0);
+				const next = Math.max(0, Math.min(max, Math.round(el2.scrollLeft / el2.clientWidth)));
+				if (next !== current.current) {
+					current.current = next;
+					latest.current.onPageChange?.(next);
+				}
+			}, 90);
+		};
+
+		el.addEventListener('scroll', onScroll, { passive: true });
+		return () => {
+			el.removeEventListener('scroll', onScroll);
+			if (settle.current !== null) clearTimeout(settle.current);
+			settle.current = null;
+		};
+	}, [hasItems]);
+
+	// Each new host: jump (no animation) to the starting page — an initial position
+	// is not a scroll. Runs after the scroll listener attaches so the write
+	// still flows through the tracked-index path.
+	useEffect(() => {
+		const el = host.current;
+		if (!el) return;
+		current.current = props.page ?? current.current;
+		el.scrollLeft = current.current * el.clientWidth;
+	}, [hasItems]);
+
+	// Controlled writes scroll smoothly. Skipped when the page already
+	// matches `current` — a user swipe that the parent echoes back unchanged
+	// must not scroll again.
+	useEffect(() => {
+		const el = host.current;
+		if (!el || props.page === undefined || props.page === current.current) return;
+		current.current = props.page;
+		el.scrollTo({ left: props.page * el.clientWidth, behavior: 'smooth' });
+	}, [props.page]);
+
+	@if (props.items.length > 0) {
+		<div
+			ref={(el: any) => {
+				host.current = el;
+				applyWebProps(el, props.web);
+			}}
+			id={props.id}
+			className={['vx-pager', props.className]}
+			{...layoutChildProps(props)}
+			role={props.accessibilityRole ?? 'group'}
+			aria-roledescription="carousel"
+			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}
+		>
+			@for (const item of props.items; index i; key i) {
+				<div
+					className="vx-pager-page"
+					role="group"
+					aria-roledescription="slide"
+					aria-label={`${i + 1} of ${props.items.length}`}
+				>
+					{props.renderItem(item, i)}
+				</div>
+			}
+		</div>
+	} @else {
+		<>{props.renderEmpty?.()}</>
+	}
+}

package/src/escape-props.mobile.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/index.macos.ts

@@ -0,0 +1,2 @@
+export { Pager } from './Pager.macos.tsrx'
+export type { PagerProps } from './props'

package/src/index.ts

@@ -0,0 +1,2 @@
+export { Pager } from './Pager.tsrx'
+export type { PagerProps } from './props'

package/src/index.web.ts

@@ -0,0 +1,2 @@
+export { Pager } from './Pager.web.tsrx'
+export type { PagerProps } 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 }
+}

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/props.ts

@@ -0,0 +1,84 @@
+export interface LayoutChildProps {
+	row?: number
+	col?: number
+	rowSpan?: number
+	colSpan?: number
+	dock?: 'left' | 'top' | 'right' | 'bottom'
+	left?: number
+	top?: number
+	flexGrow?: number
+	flexShrink?: number
+	alignSelf?: string
+	order?: number
+}
+
+/** Flex-container props shared by View/Row/Pressable — RN vocabulary, applied
+ *  to the host flexboxlayout natively and the element's style on web.
+ *  `gap` is a dip number (px on web); NS supports it on FlexboxLayout only
+ *  (GridLayout has no gap). */
+export interface FlexContainerProps {
+	justifyContent?: 'start' | 'center' | 'end' | 'space-between' | 'space-around' | 'space-evenly'
+	alignItems?: 'start' | 'center' | 'end' | 'stretch' | 'baseline'
+	flexWrap?: boolean | 'wrap' | 'nowrap' | 'wrap-reverse'
+	gap?: number | string
+	rowGap?: number | string
+	columnGap?: number | string
+}
+
+export type Role =
+	| 'button'
+	| 'link'
+	| 'search'
+	| 'image'
+	| 'heading'
+	| 'adjustable'
+	| 'summary'
+	| 'text'
+	| 'none'
+	| 'progressbar'
+	| 'checkbox'
+	| 'switch'
+	| 'radio'
+	| 'spinbutton'
+	| 'tab'
+
+export interface AccessibilityProps {
+	accessible?: boolean
+	accessibilityLabel?: string
+	accessibilityRole?: Role
+	accessibilityHint?: string
+	accessibilityValue?: string
+	accessibilityState?: {
+		disabled?: boolean
+		selected?: boolean
+		checked?: boolean
+	}
+	accessibilityLiveRegion?: 'none' | 'polite' | 'assertive'
+}
+
+/** Paged horizontal swipe container — onboarding flows, media galleries.
+ *  Chrome-reset OS paging on native (ViewPager2 / UICollectionView paging via
+ *  @nativescript-community/ui-pager), a scroll-snap scroller on web. Follows
+ *  the platform-list contract: `items` + `renderItem`, no children — each
+ *  page is a full-host-size cell. No indicator is built in; compose dots
+ *  from `Row` + `View` driven by `page`/`onPageChange`. */
+export interface PagerProps extends LayoutChildProps, AccessibilityProps {
+	className?: any
+	style?: any
+	id?: string
+	items: any[]
+	renderItem: (item: any, index: number) => any
+	renderEmpty?: () => any
+	/** Controlled page index — pass with `onPageChange` to own the page.
+	 *  Writes scroll/settle to the page; user swipes call `onPageChange`. */
+	page?: number
+	/** Starting page for uncontrolled use (default 0). */
+	defaultPage?: number
+	/** Fires when the settled page changes — a completed swipe on both
+	 *  targets. Programmatic `page` writes do not echo back through it. */
+	onPageChange?: (index: number) => void
+	/** Platform escape hatches, applied after the shared props. */
+	ios?: Record<string, any>
+	android?: Record<string, any>
+	web?: Record<string, any>
+}

package/types/index.d.ts

@@ -0,0 +1,5 @@
+import type { UniversalComponent } from 'octane/universal'
+import type { PagerProps } from './props.js'
+
+export declare const Pager: UniversalComponent<PagerProps>
+export type { PagerProps } from './props.js'

package/types/index.macos.d.ts

@@ -0,0 +1,4 @@
+import type { PagerProps } from './props.js'
+
+export type { PagerProps } from './props.js'
+export declare function Pager(props: PagerProps): unknown

package/types/props.d.ts

@@ -0,0 +1,65 @@
+export interface LayoutChildProps {
+    row?: number;
+    col?: number;
+    rowSpan?: number;
+    colSpan?: number;
+    dock?: 'left' | 'top' | 'right' | 'bottom';
+    left?: number;
+    top?: number;
+    flexGrow?: number;
+    flexShrink?: number;
+    alignSelf?: string;
+    order?: number;
+}
+/** Flex-container props shared by View/Row/Pressable — RN vocabulary, applied
+ *  to the host flexboxlayout natively and the element's style on web.
+ *  `gap` is a dip number (px on web); NS supports it on FlexboxLayout only
+ *  (GridLayout has no gap). */
+export interface FlexContainerProps {
+    justifyContent?: 'start' | 'center' | 'end' | 'space-between' | 'space-around' | 'space-evenly';
+    alignItems?: 'start' | 'center' | 'end' | 'stretch' | 'baseline';
+    flexWrap?: boolean | 'wrap' | 'nowrap' | 'wrap-reverse';
+    gap?: number | string;
+    rowGap?: number | string;
+    columnGap?: number | string;
+}
+export type Role = 'button' | 'link' | 'search' | 'image' | 'heading' | 'adjustable' | 'summary' | 'text' | 'none' | 'progressbar' | 'checkbox' | 'switch' | 'radio' | 'spinbutton' | 'tab';
+export interface AccessibilityProps {
+    accessible?: boolean;
+    accessibilityLabel?: string;
+    accessibilityRole?: Role;
+    accessibilityHint?: string;
+    accessibilityValue?: string;
+    accessibilityState?: {
+        disabled?: boolean;
+        selected?: boolean;
+        checked?: boolean;
+    };
+    accessibilityLiveRegion?: 'none' | 'polite' | 'assertive';
+}
+/** Paged horizontal swipe container — onboarding flows, media galleries.
+ *  Chrome-reset OS paging on native (ViewPager2 / UICollectionView paging via
+ *  @nativescript-community/ui-pager), a scroll-snap scroller on web. Follows
+ *  the platform-list contract: `items` + `renderItem`, no children — each
+ *  page is a full-host-size cell. No indicator is built in; compose dots
+ *  from `Row` + `View` driven by `page`/`onPageChange`. */
+export interface PagerProps extends LayoutChildProps, AccessibilityProps {
+    className?: any;
+    style?: any;
+    id?: string;
+    items: any[];
+    renderItem: (item: any, index: number) => any;
+    renderEmpty?: () => any;
+    /** Controlled page index — pass with `onPageChange` to own the page.
+     *  Writes scroll/settle to the page; user swipes call `onPageChange`. */
+    page?: number;
+    /** Starting page for uncontrolled use (default 0). */
+    defaultPage?: number;
+    /** Fires when the settled page changes — a completed swipe on both
+     *  targets. Programmatic `page` writes do not echo back through it. */
+    onPageChange?: (index: number) => void;
+    /** Platform escape hatches, applied after the shared props. */
+    ios?: Record<string, any>;
+    android?: Record<string, any>;
+    web?: Record<string, any>;
+}