@octane-xplat/pager 0.7.0

package/src/Pager.web.test.tsrx

@@ -0,0 +1,83 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { act, createRoot } from 'octane';
+import { Pager } from './Pager.web.tsrx';
+
+// jsdom has no layout — clientWidth is always 0 — so the leaf's scroll math
+// is exercised against a stubbed page width. scrollTo is unimplemented in
+// jsdom; the stub records controlled-page writes.
+
+const items = ['a', 'b', 'c'];
+const renderItem = (item: string) => <span class="pg">{item}</span>;
+
+function mount(extra: any = {}) {
+	const el = document.createElement('div');
+	document.body.appendChild(el);
+	const root = createRoot(el);
+	act(() => root.render(<Pager items={items} renderItem={renderItem} {...extra} />));
+	const pager = el.querySelector('.vx-pager') as any;
+	Object.defineProperty(pager, 'clientWidth', { value: 100, configurable: true });
+	pager.scrollTo = vi.fn((opts: any) => {
+		pager.scrollLeft = opts.left;
+		pager.dispatchEvent(new Event('scroll'));
+	});
+
+	return { el, root, pager };
+}
+
+describe('Pager (web leaf)', () => {
+	afterEach(() => {
+		vi.useRealTimers();
+	});
+
+	it('renders one snap page per item, plus renderEmpty', () => {
+		const { el, root, pager } = mount();
+		expect(pager.className).toContain('vx-pager');
+		expect(el.querySelectorAll('.vx-pager-page')).toHaveLength(3);
+		expect(el.querySelectorAll('.pg')).toHaveLength(3);
+		root.unmount();
+		el.remove();
+	});
+
+	it('fires onPageChange once the scroll settles', () => {
+		vi.useFakeTimers();
+		const onPageChange = vi.fn();
+		const { el, root, pager } = mount({ onPageChange });
+		pager.scrollLeft = 200;
+		pager.dispatchEvent(new Event('scroll'));
+		vi.advanceTimersByTime(200);
+		expect(onPageChange).toHaveBeenCalledTimes(1);
+		expect(onPageChange).toHaveBeenCalledWith(2);
+		root.unmount();
+		el.remove();
+	});
+
+	it('suppresses the echo of its own controlled writes', () => {
+		vi.useFakeTimers();
+		const onPageChange = vi.fn();
+		const el = document.createElement('div');
+		document.body.appendChild(el);
+		const root = createRoot(el);
+		const set = { page: 0 };
+		function Host() @{
+			<Pager items={items} renderItem={renderItem} page={set.page} onPageChange={onPageChange} />;
+		}
+
+		act(() => root.render(<Host />));
+		const pager = el.querySelector('.vx-pager') as any;
+		Object.defineProperty(pager, 'clientWidth', { value: 100, configurable: true });
+		pager.scrollTo = vi.fn((opts: any) => {
+			pager.scrollLeft = opts.left;
+			pager.dispatchEvent(new Event('scroll'));
+		});
+
+		set.page = 1;
+		act(() => root.render(<Host />));
+		expect(pager.scrollTo).toHaveBeenCalledWith({ left: 100, behavior: 'smooth' });
+		vi.advanceTimersByTime(200);
+		// The programmatic scroll must not report back as a user swipe.
+		expect(onPageChange).not.toHaveBeenCalled();
+		root.unmount();
+		el.remove();
+	});
+});

package/src/Pager.web.tsrx

@@ -0,0 +1,104 @@
+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 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);
+		};
+	}, []);
+
+	// Mount: 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 || current.current <= 0) return;
+		el.scrollLeft = current.current * el.clientWidth;
+	}, []);
+
+	// 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/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.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'
+
+export declare const Pager: UniversalComponent<PagerProps>
+export type { PagerProps } from './props'

package/types/index.macos.d.ts

@@ -0,0 +1,4 @@
+import type { PagerProps } from './props'
+
+export type { PagerProps } from './props'
+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>;
+}